apple-notes-mcp 2.14.2 → 2.15.0

package/docs/FULL-DISK-ACCESS.md

@@ -1,8 +1,8 @@
 # Full Disk Access
 
 Apple Notes MCP works almost entirely without any special disk permission. The
-tools that need **Full Disk Access (FDA)** for the process that runs the MCP
-server are the ones that read Notes' own SQLite store:
+tools that need **Full Disk Access (FDA)** for the process responsible for the MCP
+server are the ones that read Notes' own SQLite store. Examples include:
 
 - **`get-checklist-state`** — reads a note's checklist done/undone state.
 - **Checklist annotations in `get-note-markdown`** — the `[x]` / `[ ]` prefixes on
@@ -17,9 +17,9 @@ server are the ones that read Notes' own SQLite store:
 - **`get-sync-status`** — degrades rather than fails: without database access it
   cannot see pending uploads or recent write activity.
 
-Everything else (creating, reading, searching, updating, moving, deleting notes;
-folders, accounts, attachments, stats, export, etc.) works **without** Full Disk
-Access.
+The AppleScript tools (creating, reading, searching, updating, moving, and
+deleting notes, for example) work **without** Full Disk Access. See the
+[full tool list](../README.md#full-disk-access) for all database-backed features.
 
 ## Why it's needed
 
@@ -46,7 +46,10 @@ ever **reads** this database; it never writes to it.)
 2. Go to **Privacy & Security → Full Disk Access**.
 3. Click the **+** button (you may need to unlock with Touch ID / your password
    first) and add the right entry for how you run the server:
-   - **Claude Desktop** → the **Node binary** that runs the server, e.g.
+   - **Permission broker** → `~/Applications/Apple Notes MCP Broker.app`, if you
+     opted in with `apple-notes-mcp setup --broker`. Read the
+     [trust trade-off below](#optional-permission-broker) before enabling it.
+   - **Claude Desktop without the broker** → the **Node binary** that runs the server, e.g.
      `/usr/local/bin/node` or `~/.nvm/versions/node/v24.11.1/bin/node`. The
      `doctor` tool prints the exact path. In the file picker, press **⌘⇧G** and
      paste it (use **⌘⇧.** to show hidden folders such as `~/.nvm`). Adding
@@ -61,7 +64,7 @@ ever **reads** this database; it never writes to it.)
    enough; quit the host application itself (⌘Q) and relaunch it. If `doctor`
    still reports Full Disk Access as not granted after that, restart the Mac.
 
-> **Why Claude Desktop needs the Node binary itself.** macOS checks Full Disk
+> **Why Claude Desktop needs the Node binary without the broker.** macOS checks Full Disk
 > Access against the *responsible process*, the app it holds accountable for a
 > request. A terminal passes that role on to everything it launches, so a grant
 > on Terminal or iTerm covers the server. Claude Desktop does not: it starts each
@@ -83,15 +86,61 @@ ever **reads** this database; it never writes to it.)
 > }
 > ```
 >
-> A Developer-ID-signed Node keeps its grant across updates at the same path;
-> an ad-hoc-signed one (typically Homebrew's) does not. See
+> A Developer-ID-signed Node at a stable path avoids the identity changes of
+> ad-hoc rebuilds. Permission continuity still depends on its designated code
+> requirement and macOS permission state. See
 > [Node runtime and TCC permissions](NODE-RUNTIME-AND-TCC-PERMISSIONS.md).
 
+## Optional permission broker
+
+`apple-notes-mcp setup --broker` installs a signed app at
+`~/Applications/Apple Notes MCP Broker.app`. Grant Full Disk Access to that app
+and allow it to control Notes when macOS asks. Brokered sessions use its grants
+instead of those of the Node binary or MCP host that launched the client.
+Setup requires a standalone Node runtime linked only to system libraries; see
+the [runtime setup guide](NODE-RUNTIME-AND-TCC-PERMISSIONS.md).
+
+**This trusts every process running as your macOS user.** While the broker is
+running, any such process can connect and use the server's Notes capabilities
+under the broker's Full Disk Access and Notes Automation grants. The socket's
+permissions and same-UID check exclude other users; they do not authenticate
+apps running as you. That is comparable trust exposure to granting Full Disk
+Access to Node. Use the broker only if you accept this trade-off.
+
+The broker runs a server sealed inside its signed app, verifies the bundle and
+the pinned Node executable before spawning, and accepts only a short allowlist
+of numeric limits and timeouts from clients. Code paths, helper paths, and
+safety overrides cannot be selected through a socket request, and brokered
+servers skip local JSON configuration files. External native
+helpers are unavailable in broker sessions; tools that require them need an
+in-process server. See [Permission broker](../README.md#permission-broker-opt-in)
+for the security design and signing caveats.
+
+The signature and hash checks reject changes detected at startup or before
+spawn. They do not provide OS isolation against a hostile, unsandboxed
+same-user process modifying the user-writable bundle or runtime after
+validation. Installed Shortcuts are user-managed trusted integrations; the
+broker does not authenticate their contents.
+
+After updating the package or replacing the broker's Node runtime, run
+`apple-notes-mcp setup --broker` again, restart your MCP clients, and check
+`doctor`. Rebuilding with an ad-hoc signature or changing the signing identity
+may require new macOS grants.
+
+To bypass the broker for one client, set `APPLE_NOTES_MCP_BROKER=off` in that
+client's environment. This does **not** stop the broker or prevent other
+same-user processes from using it. To remove that access, run
+`apple-notes-mcp setup --broker --uninstall`, then restart your clients. You can
+also revoke the broker's Full Disk Access and Notes Automation grants in System
+Settings.
+
 ## Verifying it worked
 
 Run the **`doctor`** tool. It reports a dedicated **Full Disk Access** check as
 `ok` / `warn` / `fail` with the reason, so you can confirm the grant took effect
-without guessing. You can also just call `get-checklist-state` on a note that has
+without guessing. Its `broker` field identifies whether the session uses the
+broker or has fallen back to an in-process server with its own permissions.
+You can also just call `get-checklist-state` on a note that has
 a checklist — if it returns items with `[x]`/`[ ]` state, FDA is working.
 
 ## Without Full Disk Access
@@ -108,8 +157,9 @@ The server degrades gracefully — nothing crashes:
   appear as plain list items without the `[x]`/`[ ]` annotations.
 - `get-sync-status` still answers, but with no database visibility it reports no
   pending uploads and no active sync — treat that as "unknown", not "idle".
-- **Every other tool works normally**, since the rest of the server is pure
-  AppleScript.
+- **AppleScript-only tools work normally.** See the
+  [full tool list](../README.md#full-disk-access) for other database-backed tools
+  that require FDA.
 
 See also: [Known Limitations](../README.md#known-limitations) and
 [Creating Checklists](../README.md#creating-checklists) in the README.

package/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md

@@ -1,10 +1,10 @@
 # Node runtime & TCC permission stability
 
 macOS gates this MCP server's access to your data behind **TCC** permissions —
-**Full Disk Access** (to read app data such as Mail, Notes, or Photos) and
-**Automation / Apple Events** (to drive an app like Mail.app or Notes.app via
-AppleScript). See this repo's Full Disk Access / Automation notes for *which*
-operations need which permission.
+**Full Disk Access** (to read the Notes database) and **Automation / Apple
+Events** (to drive Notes.app via AppleScript). See the
+[Full Disk Access guide](FULL-DISK-ACCESS.md) for which operations need which
+permission.
 
 This page is about a **separate, recurring annoyance**: being asked to approve
 those permissions **over and over**, often right after a routine `brew upgrade`.
@@ -13,19 +13,24 @@ those permissions **over and over**, often right after a routine `brew upgrade`.
 
 - You granted Full Disk Access (and/or Automation) to "node", but days later
   macOS prompts again — `"node" wants access to ...` or `"node" wants to control
-  "Mail"`.
+  "Notes"`.
 - System Settings → Privacy & Security → Full Disk Access shows **several
   identical "node" rows**, usually only one enabled.
 - It tends to happen immediately after you update Node.
 
 ## Cause
 
-TCC binds a permission grant to the **code identity of the binary that performs
-the access** — here, the `node` executable that launches the MCP server. For a
-binary that is only **ad-hoc signed** (no Developer ID / Team ID), TCC keys the
-grant to the binary's **cdhash**, a hash of its contents.
+TCC checks the **responsible process** for an access. Under Claude Desktop
+without the broker, that is the `node` executable running the server; under a
+terminal host it can be the terminal app. With the broker, it is
+`~/Applications/Apple Notes MCP Broker.app`.
 
-Homebrew's `node` formula is ad-hoc signed:
+An **ad-hoc-signed** binary has no certificate-backed signing identity. Its
+**cdhash** changes when its code changes, so a grant to one build may not apply
+after an update. Moving the executable, including changing the resolved path
+behind a version-manager symlink, can also require a new grant.
+
+Check the Node binary you actually use. An ad-hoc signature looks like this:
 
 ```bash
 $ codesign -dvvv "$(which node)" 2>&1 | grep -E 'Signature|TeamIdentifier'
@@ -33,21 +38,86 @@ Signature=adhoc
 TeamIdentifier=not set
 ```
 
-Every Node update **replaces the binary**, which **changes the cdhash**, so TCC
-no longer recognizes it as the thing you approved — and re-prompts. The extra
-"node" rows are stale cdhashes from previous versions.
+The `doctor` tool reports the runtime path and warns about ad-hoc signing.
+Duplicate "node" rows in System Settings can be entries for previous binaries.
+
+Certificate-signed code has a **designated requirement** that can identify it
+across builds. Apple's documented Apple Development requirement includes the
+leaf certificate's Common Name, while its Developer ID example uses certificate
+type and Team ID constraints. A matching bundle identifier and Team ID alone
+are therefore not a promise of permission continuity. See Apple's
+[TN3127: Inside Code Signing: Requirements](https://developer.apple.com/documentation/technotes/tn3127-inside-code-signing-requirements).
 
-By contrast, properly signed apps (Chrome, Slack, …) keep their permissions
-across auto-updates because TCC matches them on a stable **Designated
-Requirement** derived from their Developer ID, not on the cdhash.
+## Option 1: opt in to the permission broker
 
-## Fix: run the MCP under the official, Developer-ID-signed Node
+The broker puts the grants on a signed app at a fixed path and runs a bundled
+copy of the MCP server for connected clients. Run setup using a standalone Node
+runtime whose dynamic library dependencies are all under `/usr/lib/` or
+`/System/Library/`. Other dependencies, including the non-system libraries used
+by common Homebrew Node builds, are rejected: pinning the Node executable alone
+would not protect those libraries. The download steps under Option 2 below show
+how to install an official Node runtime at a fixed path.
+
+```bash
+apple-notes-mcp setup --broker
+apple-notes-mcp setup --broker --check
+# Or explicitly select your standalone runtime for setup:
+/path/to/node /path/to/apple-notes-mcp/build/index.js setup --broker
+```
+
+Add `~/Applications/Apple Notes MCP Broker.app` in **System Settings → Privacy
+& Security → Full Disk Access**, and allow it to control Notes when prompted.
+Restart your MCP client and run `doctor` to confirm that it is using the broker.
+
+**Review the trust trade-off before installing:** every process running as your
+macOS user can use the broker's Notes capabilities under its Full Disk Access
+and Notes Automation grants. The socket's same-UID check excludes other users,
+but does not authenticate same-user apps. This is comparable trust exposure to
+granting Full Disk Access to a general-purpose Node binary. Socket requests
+cannot select executable paths or safety overrides; this does not identify a
+trusted MCP client. Brokered servers skip local JSON configuration files, and
+external native helpers are unavailable in broker sessions.
+See the [broker security design](../README.md#permission-broker-opt-in).
+
+The signature and hash checks reject modifications detected at startup or
+before spawn. They do not make later filesystem reads atomic or provide OS
+isolation against a hostile, unsandboxed same-user process modifying the
+user-writable bundle or runtime after validation. Installed Shortcuts remain
+user-managed trusted integrations; the broker does not authenticate their
+contents.
+
+Setup automatically selects an identity only when exactly one Developer ID
+Application or Apple Development identity qualifies. If more than one qualifies
+across those types, specify `--sign-identity`. If none qualify, it signs ad hoc
+and warns about re-granting permissions.
+Keeping a compatible designated requirement can help preserve grants across
+rebuilds, but **Apple Development signing is not a guarantee of continuity across
+certificate renewal or signing identity changes**. Ad-hoc rebuilds may require
+new grants. Always check `doctor` after reinstalling.
+
+The signed configuration pins the Node executable's canonical path and digest.
+After a package update, or after replacing or moving that runtime, run
+`apple-notes-mcp setup --broker` again to refresh the bundled server and pin,
+then restart your clients. A stale or unavailable broker causes clients to run
+in-process with their own permissions; `doctor` reports that fallback.
+
+Set `APPLE_NOTES_MCP_BROKER=off` to bypass it for one client. The broker continues
+running and remains reachable by other same-user processes. To remove that
+access, run `apple-notes-mcp setup --broker --uninstall` and restart your clients;
+you can also revoke the broker's grants in System Settings.
+
+## Option 2: run in-process under Developer-ID-signed Node
 
 Node binaries distributed from **nodejs.org** are signed with a real Developer
 ID (`Node.js Foundation`, Team `HX7739G8FX`), notarized, and self-contained.
-Pointing the MCP server at one gives TCC a **stable** identity to match, so a
-permission you grant **persists across future Node updates**. It also decouples
-the MCP runtime from your Homebrew/dev Node, which can keep updating freely.
+Keeping the executable at a stable path avoids the path changes of version
+managers and the code-identity changes of ad-hoc rebuilds. Permission continuity
+still depends on the designated requirement and macOS permission state. This
+also decouples the MCP runtime from your Homebrew/dev Node.
+
+If you installed the broker, set `APPLE_NOTES_MCP_BROKER=off` in this client's
+environment or uninstall it before using this option. Otherwise the client
+will hand off to the broker when it is available.
 
 ### Steps (Apple Silicon shown; use `darwin-x64` on Intel)
 
@@ -92,19 +162,18 @@ the MCP runtime from your Homebrew/dev Node, which can keep updating freely.
 
 4. **Restart your MCP client** so the server relaunches under the new Node.
 
-5. **Grant the permissions once** to the new binary:
+5. **Grant the permissions** to the new binary:
    - *Full Disk Access*: System Settings → Privacy & Security → Full Disk Access
      → **+** → ⌘⇧G → paste `~/mcp-runtime/node-current/bin/node`.
-   - *Automation*: the first time the server drives an app you'll get a one-time
+   - *Automation*: the first time the server drives an app you'll get a
      `"node" wants to control "<App>"` prompt — click **Allow**.
 
    ⚠️ **A TCC grant is keyed to the binary's resolved *path*, not only to its
    signature.** Because the steps above unpack Node into a fixed directory
    (`~/mcp-runtime/node-current`) rather than a versioned one, that path never
-   moves and the grants survive Node updates — see "Updating" below. If you
+   moves — see "Updating" below. If you
    instead point `node-current` at a `node-vX.Y.Z-…` directory, every update
-   changes the resolved path, presents a brand-new ungranted identity, and you
-   will be re-prompted for all of it.
+   changes the resolved path and may require you to grant permissions again.
 
    You can delete any stale "node" rows from the Full Disk Access list.
 
@@ -123,11 +192,12 @@ rm -rf node-current && mkdir -p node-current
 tar -xzf node-$VER-$ARCH.tar.gz --strip-components=1 -C node-current
 ```
 
-The path is unchanged and the official builds are Developer-ID signed with a
-requirement that pins identifier + Team ID (no cdhash), so **both** halves of
-the grant still match: existing grants carry over with no re-approval.
+The path stays unchanged. Check the replacement binary's signature as above,
+then run `doctor` in your MCP client to verify that macOS retained its grants.
+Do not assume a new signing identity or a changed designated requirement will
+match an earlier grant.
 
 ⚠️ **Restart your MCP client afterwards.** Replacing the binary unlinks the one
-any already-running server is executing; macOS then cannot validate that path,
-so those processes fail with *"Permission denied"* until they are restarted.
-Nothing is wrong with your grants — a freshly launched server works fine.
+any already-running server is executing; those processes can fail with
+*"Permission denied"* until restarted. Recheck permissions from a fresh session
+before changing grants.