Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,14 @@ MacMCP is in early development, so tools and policy keys may change before 1.0.

### Added

- A kill switch for the person at the Mac: ⌃⇧⌘\ (or the menu bar item's "Stop and pause agents", or `mac-mcp pause`)
stops the running action and pauses agents. Only `mac-mcp resume` in Terminal resumes. A menu bar item shows when
an agent is driving; `--hide-indicator` hides it. The pause state survives restarts.
- `mac-mcp setup`: a guided first run that opens the right System Settings panes and waits for the grants.
- `mac-mcp install --client` and `uninstall --client` for Claude Code, Claude Desktop, Codex, Cursor and VS Code. They
edit only MacMCP's entry, keep a backup in MacMCP's protected support folder, and refuse files they can't parse.
- A Claude Code plugin with a driving-macos skill: `/plugin marketplace add Playback-Software/mac-mcp`.
- `scripts/measure-actions.py` and `MAC_MCP_DEBUG_ACTIONS=1` for per-action walk counts and timings.
- `CONTRIBUTING.md` and this changelog.
- A `VERSION` file at the repo root. `scripts/build.sh` reads it, and a unit test fails if the CLI's version differs.
- A GitHub Actions workflow that builds, runs the unit tests and runs `scripts/lint-blocking.sh` on a macOS 26
Expand All @@ -15,13 +23,33 @@ MacMCP is in early development, so tools and policy keys may change before 1.0.

### Changed

- `mac_snapshot` output over its budget keeps controls ahead of text, keeps the focused and selected rows and the
window's bottom controls, collapses runs of similar list rows, and marks each gap.
- Actions refuse a ref that was never shown (a guessed one); find it with `query=` or a new snapshot.
- Tool descriptions and server instructions are about 27% shorter, and say to trust an action's diff rather than
snapshot again.
- Actions reuse settle's final walk for the report: clicks and menu commands are about 16% faster.
- Protected-path checks resolve the protected locations once per check, so a 5,000-file Finder selection is checked
in about 1 s instead of 13–26 s.
- OCR hands frames to Vision directly and, within one `mac_wait`, skips frames that haven't changed.
- VS Code's, VS Code Insiders' and Cursor's user folders are protected like other AI clients' settings.
- `scripts/build.sh` and `scripts/setup-signing.sh` stop with a fix when full Xcode or Swift 6.1+ is missing, and
`build.sh` ends with a hint when `~/.local/bin` isn't on `PATH`.
- `swift test` prints a notice when it skips the integration tests, pointing at `scripts/integration.sh`.
- `scripts/soak.py` fails, rather than passing, when MacMCPTestHost isn't installed or never launched, and counts a
skipped hang phase as a problem unless `--no-chaos` was passed.
- `scripts/protocol-probe.py` has a shebang and is executable.

### Fixed

- `mac_script` refused every allowed app that had a window on macOS 27: its open-documents check required the window
server and Accessibility to list the same number of windows, and macOS 27 adds offscreen helper windows to every
app. The check now matches each window to its Accessibility element by window ID, and skips only offscreen helper
windows whose title is present and empty (read with Screen Recording); a document window always has a title.
- `mac_script` refused every reference to an app's documents or Safari's tabs: the document gate's own inventory
query encoded "every" with the wrong descriptor type, so apps rejected it. The gate now works as documented.
- `mac_menu` accepts a path sent as a JSON array inside a string (`"[\"File\", \"Save As…\"]"`).

### Documentation

- The policy reference describes `shortcuts.timeout_seconds` and `alert_cooldown_minutes`.
Expand Down
10 changes: 9 additions & 1 deletion Sources/MacMCPCore/Act/ScriptHost.swift
Original file line number Diff line number Diff line change
Expand Up @@ -292,6 +292,12 @@ public enum ScriptHost {
if let reply {
let response: NSAppleEventDescriptor
if ScriptHost.propertyCode(descriptor.paramDescriptor(forKeyword: AEKeyword(keyDirectObject))) == "ppth", let ref {
// Model Cocoa's collection selector validation, not just its path reply.
let paths = descriptor.paramDescriptor(forKeyword: AEKeyword(keyDirectObject))
let documents = paths?.forKeyword(AEKeyword(keyAEContainer))
guard let ordinal = documents?.forKeyword(AEKeyword(keyAEKeyData)),
ordinal.descriptorType == typeAbsoluteOrdinal,
ordinal.data == NSAppleEventDescriptor(enumCode: OSType(kAEAll)).data else { return OSErr(errAEWrongDataType) }
let gate = Unmanaged<Gate>.fromOpaque(ref).takeUnretainedValue()
response = NSAppleEventDescriptor(eventClass: ScriptHost.codeValue("aevt"), eventID: ScriptHost.codeValue("ansr"), targetDescriptor: nil,
returnID: AEReturnID(kAutoGenerateReturnID), transactionID: AETransactionID(kAnyTransactionID))
Expand Down Expand Up @@ -738,7 +744,9 @@ public enum ScriptHost {
record.setDescriptor(container, forKeyword: AEKeyword(keyAEContainer))
return record.coerce(toDescriptorType: typeObjectSpecifier)
}
let all = NSAppleEventDescriptor(enumCode: OSType(kAEAll))
// Cocoa rejects enum/all as an absolute-position selector. AppleScript uses abso/all for `every`.
guard let all = NSAppleEventDescriptor(descriptorType: typeAbsoluteOrdinal,
data: NSAppleEventDescriptor(enumCode: OSType(kAEAll)).data) else { return nil }
var container = NSAppleEventDescriptor.null()
if tabs {
guard let windows = object("cwin", form: OSType(formAbsolutePosition), key: all, container: container) else { return nil }
Expand Down
91 changes: 85 additions & 6 deletions Sources/MacMCPCore/Act/Scripts.swift
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@ import ApplicationServices
import Foundation
import MachO

// Accessibility has no public window-ID attribute. Never substitute a coincident frame when this lookup fails.
@_silgen_name("_AXUIElementGetWindow")
private func scriptAXWindowID(_ element: AXUIElement, _ id: UnsafeMutablePointer<CGWindowID>) -> AXError

/// App automation with a source preflight and an Apple-event gate in a disposable signed host.
public enum Scripts {
public enum Language: String, Sendable, CaseIterable {
Expand Down Expand Up @@ -499,25 +503,75 @@ enum ScriptDocuments {
static func snapshot(bundleID: String) -> Snapshot {
snapshot(bundleID: bundleID, source: Source<AXElement>(
applications: { Scripts.runningApplications(bundleID: $0) }, trusted: AXIsProcessTrusted,
windowCount: { pid in
serverWindows: { pid in
guard let windows = CGWindowListCopyWindowInfo(.optionAll, kCGNullWindowID) as? [[String: Any]] else { return nil }
return windows.filter { ($0[kCGWindowOwnerPID as String] as? pid_t) == pid }.count
// Preflight can cache a denial: keep exemptions disabled in that case. A cached grant alone
// is insufficient; exemptions also require an empty CGWindowName in this fresh, live inventory.
return windowInventory(pid: pid, info: windows, displays: WindowServer.activeDisplays(),
screenRecording: CGPreflightScreenCaptureAccess())
}, windows: { pid in
let read = AXElement.application(pid: pid, timeout: 0.2).attribute(reporting: kAXWindowsAttribute)
guard read.error == nil, let windows = read.value as? [AXUIElement] else { return nil }
return windows.map(AXElement.init)
}, read: { element in
AXUIElementSetMessagingTimeout(element.raw, 0.2)
return element.read(reporting: [kAXDocumentAttribute, kAXURLAttribute, kAXRoleAttribute, kAXChildrenAttribute, kAXTabsAttribute])
return element.read(reporting: [kAXDocumentAttribute, kAXURLAttribute, kAXRoleAttribute, kAXPositionAttribute,
kAXSizeAttribute, kAXChildrenAttribute, kAXTabsAttribute])
}, windowID: { element in
var id = kCGNullWindowID
guard scriptAXWindowID(element.raw, &id) == .success, id != kCGNullWindowID else { return nil }
return id
}, elements: { ($0 as? [AXUIElement])?.map(AXElement.init) }))
}

struct Window: Equatable {
let id: CGWindowID
let bounds: CGRect
let onscreen: Bool
}

/// Unordered windows are not necessarily backing windows: minimized windows and windows on other Spaces
/// must remain in this inventory. A document window always has a title (its file's name), so only an offscreen
/// window whose name is present and empty, read with Screen Recording live, and with the backing traits measured
/// below is exempt. Its size isn't: apps' helper windows vary (64×64 and 500×500 icon windows, 100×132, menu-bar
/// strips). An absent name (including redaction without Screen Recording) is unknown, and onscreen windows are
/// always checked.
static func windowInventory(pid: pid_t, info: [[String: Any]], displays: [CGRect], screenRecording: Bool) -> [Window]? {
var windows: [Window] = [], ids: Set<CGWindowID> = []
for entry in info {
guard let owner = entry[kCGWindowOwnerPID as String] as? pid_t else { return nil }
guard owner == pid else { continue }
guard let layer = entry[kCGWindowLayer as String] as? Int else { return nil }
guard layer == 0 else { continue } // Includes neither Finder's desktop nor elevated system chrome.
guard let id = entry[kCGWindowNumber as String] as? CGWindowID, ids.insert(id).inserted,
let dictionary = entry[kCGWindowBounds as String] as? [String: Any],
let bounds = CGRect(dictionaryRepresentation: dictionary as CFDictionary),
bounds.origin.x.isFinite, bounds.origin.y.isFinite, bounds.width.isFinite, bounds.height.isFinite,
bounds.width >= 0, bounds.height >= 0 else { return nil }
guard bounds.width > 0, bounds.height > 0 else { continue }
if let title = entry[kCGWindowName as String], !(title is String) { return nil }
if let onscreen = entry[kCGWindowIsOnscreen as String], !(onscreen is Bool) { return nil }
let onscreen = entry[kCGWindowIsOnscreen as String] as? Bool ?? false
// Finder/TextEdit backing windows measured on macOS 27.2: sharing=read-only, store=nonretained, alpha=1.
// All three must be present and exact; window movement/resizing cannot establish these traits.
if screenRecording, entry[kCGWindowName as String] as? String == "", !onscreen,
entry[kCGWindowSharingState as String] as? Int == Int(CGWindowSharingType.readOnly.rawValue),
entry[kCGWindowStoreType as String] as? Int == Int(CGWindowBackingType.backingStoreNonretained.rawValue),
entry[kCGWindowAlpha as String] as? Double == 1 {
continue
}
windows.append(Window(id: id, bounds: bounds, onscreen: onscreen))
}
return windows.sorted { $0.id < $1.id }
}

struct Source<Element: Hashable> {
let applications: (String) -> [Scripts.RunningApplication]
let trusted: () -> Bool
let windowCount: (pid_t) -> Int?
let serverWindows: (pid_t) -> [Window]?
let windows: (pid_t) -> [Element]?
let read: (Element) -> AXElement.Read?
let windowID: (Element) -> CGWindowID?
let elements: (Any) -> [Element]?
}

Expand All @@ -531,8 +585,10 @@ enum ScriptDocuments {
let deadline = ContinuousClock.now.advanced(by: .seconds(2))
var tabsPerWindow: [Int] = []
for app in apps {
guard let serverWindows = source.serverWindows(app.pid), serverWindows.count <= 512 else { return Snapshot(.unavailable) }
guard let windows = source.windows(app.pid), windows.count <= 128,
source.windowCount(app.pid) == windows.count else { return Snapshot(.unavailable) }
Set(windows).count == windows.count else { return Snapshot(.unavailable) }
var checkedIDs: [Element: CGWindowID] = [:], checkedFrames: [CGWindowID: CGRect] = [:]
for window in windows {
var queue = [(window, false)], seen: Set<Element> = [], tabs: Set<Element> = [], visited = 0
while !queue.isEmpty {
Expand All @@ -542,6 +598,20 @@ enum ScriptDocuments {
// A tab may also occur in AXChildren. Recheck it in tab context rather than losing its URL requirement.
if !seen.insert(element).inserted, !tab { continue }
guard let read = source.read(element), read.errors.isEmpty else { return Snapshot(.unavailable) }
if let role = read.values[kAXRoleAttribute] as? String,
[kAXWindowRole, kAXSheetRole, kAXDrawerRole, "AXPopover"].contains(role) {
guard let bounds = frame(position: read.values[kAXPositionAttribute], size: read.values[kAXSizeAttribute]),
let id = source.windowID(element), id != kCGNullWindowID else {
return Snapshot(.unavailable)
}
if let previous = checkedIDs[element] {
guard previous == id, checkedFrames[id] == bounds else { return Snapshot(.unavailable) }
} else {
guard checkedFrames[id] == nil else { return Snapshot(.unavailable) }
checkedIDs[element] = id
checkedFrames[id] = bounds
}
}
var values: [String] = []
for key in [kAXDocumentAttribute, kAXURLAttribute] {
guard let value = read.values[key] else { continue }
Expand All @@ -564,7 +634,16 @@ enum ScriptDocuments {
if bundleID.lowercased() == "com.apple.safari", tabs.isEmpty { return Snapshot(.unavailable) }
tabsPerWindow.append(tabs.count)
}
guard ContinuousClock.now < deadline, source.windowCount(app.pid) == windows.count else { return Snapshot(.unavailable) }
// Sheets/popovers have CG windows of their own but occur under their parent in AX. Conversely Finder
// includes its desktop scroll area in AXWindows. Require coverage, not equality of those two counts.
// Bind coverage to window identity as well as frame: an AXWindow panel on layer 3 cannot cover a
// missing layer-0 document at the same frame. A failed private ID lookup never falls back to frames.
for window in serverWindows {
guard checkedFrames[window.id] == window.bounds else { return Snapshot(.unavailable) }
}
guard ContinuousClock.now < deadline, source.serverWindows(app.pid) == serverWindows,
let currentWindows = source.windows(app.pid), Set(currentWindows) == Set(windows),
currentWindows.count == windows.count else { return Snapshot(.unavailable) }
}
return Snapshot(.safe, inventory: Inventory(pid: apps[0].pid, tabsPerWindow: tabsPerWindow))
}
Expand Down
9 changes: 6 additions & 3 deletions Sources/MacMCPServer/Tools/ActionTools.swift
Original file line number Diff line number Diff line change
Expand Up @@ -107,15 +107,18 @@ enum ActionTools {
""",
properties: [
"app": Prop.string(),
"path": Prop.string("\"Format > Make Plain Text\" or [\"File\", \"Save As…\"]; ignores case and ellipses."),
"path": Prop.string("Steps separated by \" > \", e.g. \"File > Save As…\"; ignores case and ellipses."),
],
required: ["path"],
annotations: .action,
deadline: { _ in lockedDeadline(actionDeadline) }
) { args, _ in
let raw = args.raw["path"]
let path: [String] = raw?.arrayValue?.compactMap(\.stringValue)
?? (args.string("path") ?? "").components(separatedBy: ">").map { $0.trimmingCharacters(in: .whitespaces) }.filter { !$0.isEmpty }
let text = (args.string("path") ?? "").trimmingCharacters(in: .whitespaces)
// Some clients send the array form as a JSON string: '["File", "Save As…"]'.
let encoded = text.hasPrefix("[") ? (try? JSONDecoder().decode([String].self, from: Data(text.utf8))) : nil
let path: [String] = raw?.arrayValue?.compactMap(\.stringValue) ?? encoded
?? text.components(separatedBy: ">").map { $0.trimmingCharacters(in: .whitespaces) }.filter { !$0.isEmpty }
guard !path.isEmpty else { return .error("path is required, e.g. \"File > Save As…\".") }
if let refusal = SessionSafety.refusal(menuPath: path) { return .error(refusal) }
if let refused = await RouteGuards.menu(path, app: args.string("app")) { return refused }
Expand Down
9 changes: 6 additions & 3 deletions Tests/IntegrationTests/ScriptEnforcementTests.swift
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,8 @@ extension Integration {
let scripts = [
("Mail", "tell application \"Mail\"\nif (count of messages of inbox) > 0 then\nget read status of message 1 of inbox\nelse\nreturn true\nend if\nend tell"),
("TextEdit", "tell application \"TextEdit\" to get name of every document"),
("Finder", "tell application \"Finder\" to get name of every file of desktop"),
// Finder's desktop container cannot be mapped to a file path, so file enumeration fails closed.
("Finder", "tell application \"Finder\" to count of windows"),
]
for (app, script) in scripts {
try withPolicy(#"{"script":{"allowed_apps":["\#(app)"],"timeout_seconds":30}}"#) {
Expand All @@ -81,13 +82,15 @@ extension Integration {
}

@Test func additionsAddressedToAnAllowedAppAreStillRefused() async throws {
for command in ["system info", "path to home folder", "list disks"] {
// Bypass parent AX preflight so this verifies the addition's event-code refusal even when the runner
// lacks Accessibility. An absent document-gate socket must not be the reason these commands are refused.
for (command, refusal) in [("system info", "system info"), ("path to home folder", "path to"), ("list disks", "list disks")] {
// Use a variable to avoid app terminology: the addition is still addressed to TextEdit at runtime.
let source = "use scripting additions\nset target to application \"TextEdit\"\ntell target to " + command
#expect(Scripts.refusal(source: source, language: .applescript, policy: policy) == nil)
let result = try await runEventHost(source, language: .applescript, policy: policy)
#expect(result.status != 0 && result.stdout.isEmpty)
#expect(result.stderr.contains("Refused Apple event"), "\(command): \(result.stderr)")
#expect(result.stderr.contains("Refused Apple event: \(refusal)."), "\(command): \(result.stderr)")
}
}

Expand Down
Loading
Loading