apple-tools-mcp 2.1.4 → 3.0.0

package/README.md

@@ -374,6 +374,81 @@ launchctl load ~/Library/LaunchAgents/com.apple-tools-mcp.indexer.plist
 
 KeepAlive belongs on this indexer job only — not on the MCP stdio process.
 
+## Remote HTTP transport (v3.0.0)
+
+Every tool the stdio server exposes — including the write tools — is also
+available over **Streamable HTTP**, so it's reachable from other machines,
+not just whatever process spawned it locally. This is additive: stdio still
+works exactly as before for local same-machine MCP clients that spawn it
+directly. The intended MacBook clients are Claude Desktop, Claude Code,
+Codex Desktop, and ChatGPT Desktop. Claude Desktop uses the included local
+HTTP-to-stdio proxy; Claude Code and Codex connect to the Mini's HTTP
+endpoint directly. ChatGPT Desktop does not currently support this private
+MCP connection; see the client guide for its provider-supported options.
+
+Because HTTP reaches beyond "whoever spawned this process," which stdio's
+trust model relies on, **every HTTP request needs a bearer token.** stdio
+has no equivalent check — a locally spawned child process is already
+trusted by whoever spawned it.
+
+**Entrypoint:** `node index.js --transport=http`  
+**Convenience bin:** `apple-tools-http` (`bin/apple-tools-http.js`; npm global install provides it)  
+**npm script (clone only):** `npm run http`
+
+### Auth token
+
+The token is a random secret generated on first run and stored in the
+macOS Keychain (service `apple-tools-mcp-http`) — never in a config file,
+the server's config file, or logs after the one-time generation banner.
+There's no external account and no cost; it's a self-issued password,
+like an SSH key.
+
+```bash
+apple-tools-mcp http-token   # prints the token, generating one first if needed
+```
+
+Clients send it as `Authorization: Bearer <token>`. Rotate it by deleting
+the Keychain item and restarting the server (it generates a fresh one on
+the next run), then update every client using the old value.
+
+### Config
+
+`~/.apple-tools-mcp/config.json` (same file the index interval uses):
+
+```json
+{
+  "httpHost": "127.0.0.1",
+  "httpPort": 8421
+}
+```
+
+Env overrides: `APPLE_TOOLS_HTTP_HOST`, `APPLE_TOOLS_HTTP_PORT`. The default
+host is `127.0.0.1`, so HTTP is local-only until you explicitly set a network
+address such as `0.0.0.0`. Default port is 8421 (the indexer's stdio process
+needs no port; this is only for `--transport=http`). For remote access, use a
+Tailscale address for clients that connect directly from your tailnet, or
+put the server behind a TLS-terminating reverse proxy. Do not send the
+bearer token over an untrusted LAN. Cloud-hosted connectors need a separate
+way to reach the server; a private Tailscale address alone is insufficient.
+
+### LaunchAgent
+
+See `examples/com.apple-tools-http.plist` (copy to
+`~/Library/LaunchAgents/`, replace the `REPLACE_ME*` placeholders the same
+way as the indexer plist above, then `launchctl load` it). Runs alongside
+the indexer LaunchAgent, not instead of it — the HTTP server is a second,
+independent process.
+
+### Wiring up clients
+
+See `examples/mcp-client.md` for the MacBook setup. Short version:
+
+- **On the Mini:** set `httpHost` to its LAN or Tailscale IP and restart the HTTP server. Retrieve the bearer token with `apple-tools-mcp http-token`.
+- **Claude Desktop on the MacBook:** configure the included `apple-tools-http-proxy` as a local MCP server. It forwards tool calls to the Mini over HTTP.
+- **Claude Code and Codex Desktop on the MacBook:** add `http://<mini-address>:8421/mcp` and the token. The client guide has commands for both.
+- **ChatGPT Desktop on the MacBook:** current custom MCP support does not provide a direct private HTTP connection in the desktop app. The client guide describes the documented ChatGPT web route.
+- **Claude / ChatGPT cloud connectors:** a connector does not connect from your device's tailnet interface. [Claude requires a publicly reachable server](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp); [ChatGPT directs private-network servers to Secure MCP Tunnel and currently supports MCP apps on web only](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt). Use the provider's supported network setup before adding this server as a cloud connector.
+
 ## Available Tools
 
 Once configured, your MCP client can use these tools:
@@ -464,7 +539,7 @@ Two arguments are available on **every** write tool:
 
 `body_format: "html"` uses the same compose path with a tag-stripped body pasted into Mail's native editor. It does **not** set Mail's `content` or `html content` — those setters cite-wrap the whole message (`>` prefixes and `<blockquote type="cite">`, same iOS purple bar). Mail may still generate its own HTML alternative from the native compose. The default is plain text.
 
-**Compose is not quoted.** `mail_send` / `mail_draft` (plain and html) call `make new outgoing message` **without** AppleScript `content:` so `newMessage` is a real Mail object, then fill the body into the compose window (subject title-marker + coordinate AX hit-test, then AXValue). Mail's `mailto` command was shipped in 2.0.4 and **fails on Mini/MacBook Mail**: it does not return an outgoing message (`newMessage` undefined, AppleScript **-2753**). On current Mail (Ventura+, FB11734014) `content` / `html content` store the body as a citation: every plain-text line prefixed with `>`, plus a `multipart/alternative` HTML part wrapped in `<blockquote type="cite">`. Desktop Mail often hides the bar with inline styles; iOS Mail paints the whole body purple with a left quote bar — even when the subject is not `Re:`/`Fwd:` and there is no `In-Reply-To`. Reply and forward still quote the original, which is expected (those paths still prepend via `content`; fixing reply/forward cite-wrap is out of scope for 2.1.0).
+**Compose is not quoted.** `mail_send` / `mail_draft` (plain and html) call `make new outgoing message` **without** AppleScript `content:` so `newMessage` is a real Mail object, then paste the body into the compose window (exact subject title, role `AXWebArea`, proven focus, Cmd-A + clipboard). Mail's `mailto` command was shipped in 2.0.4 and **fails on Mini/MacBook Mail**: it does not return an outgoing message (`newMessage` undefined, AppleScript **-2753**). On current Mail (Ventura+, FB11734014) `content` / `html content` store the body as a citation: every plain-text line prefixed with `>`, plus a `multipart/alternative` HTML part wrapped in `<blockquote type="cite">`. Desktop Mail often hides the bar with inline styles; iOS Mail paints the whole body purple with a left quote bar — even when the subject is not `Re:`/`Fwd:` and there is no `In-Reply-To`. Reply and forward still quote the original, which is expected (those paths still prepend via `content`; fixing reply/forward cite-wrap is out of scope for 2.1.0).
 
 Keystrokes use System Events, so **node needs Accessibility** (Privacy & Security → Accessibility) **and** Automation → Mail **and** Automation → System Events. Run `apple-tools-mcp permissions` after first install or upgrade so **node → System Events** pops **Allow** in the same sitting as Mail / Messages / Contacts / Calendar. An Accessibility / System Events deny is not a Mail Automation deny (`-1743` / `-10004`).
 
@@ -486,6 +561,8 @@ Keystrokes use System Events, so **node needs Accessibility** (Privacy & Securit
 
 **Compile prove (2.1.4 on the Mini host):** Unpatched `buildComposeScript` / `buildMailBodyPasteHandler` `osacompile` **-2741** on those bare AXTitle reads; patched AXTitle-inside-System-Events tell `osacompile` exit 0. Report: `results-214/SOLUTION-PROBE-REPORT.md`. Global install untouched. Live Sent is the 2.1.3 ship prove after npm.
 
+**Probe 3 body delivery (2.1.5).** Mini Probe 3 (`atm-p3-deliver.applescript`, classic AppleScript / System Events, not JXA) proved a click-free path: exact subject window title, first `AXWebArea` from `entire contents` of that window, `set focused of` that element to true, then an independent `AXFocusedUIElement` re-read that must match role `AXWebArea` and position/size before any keystroke. Delivery is Cmd-A + clipboard paste. No Mail `content` / `html content`. No `AXValue` write (`AXUIElementSetAttributeValue` on content is a silent no-op; 2.1.4 `atmAxHitFill` returned `OK` when that value was empty, so the keystroke recovery never ran). No coordinate `click at` (Probe 3: a click can land on another Space or app). Focus mismatch is `BODY_FOCUS_UNPROVEN`: the draft is deleted and nothing is sent. The post-paste body needle runs only when the focused element is still that proven body, so a To: recipient chip (`U+FFFC`) is not `BODY_PASTE_MISDIRECTED`. Sent/Outbox verify, `dry_run`, and confirm are unchanged.
+
 **Manual prove (2.1.3 on the Mini host):** After `apple-tools-mcp permissions` reports System Events granted, `mail_send` a short **multiline** plain message and a short `body_format: "html"` message whose body looks like ordinary paragraphs (for example `<p>Quick note</p>`), neither with a `Re:`/`Fwd:` subject. The body must land via title-marker + hit-test (not Tab / focused-role): no `BODY_FOCUS_FAILED` / `BODY_PASTE_MISDIRECTED`. Inspect each Sent `.emlx`: the text/plain part must contain the intended text (newlines preserved) and must not prefix every body line with `>`, and any HTML alternative must not wrap the whole body in `<blockquote type="cite">`. Compose must succeed (no `-2753` / undefined `newMessage`). Prove the production path (write-bridge with node → System Events allowed, **or** the documented in-process fallback). That quote-prefix Mini Sent prove is a separate bar from the 2.0.7 verify contract.
 
 Emails are addressed by their RFC822 **Message-ID**. Pass `message_id`, or pass the `file_path` from `mail_search` / `mail_recent` and the server reads the Message-ID out of the `.emlx` headers for you. `mail_archive` moves the message to its account's Archive (or All Mail) mailbox; `mail_trash` moves it to that account's Trash.
@@ -591,7 +668,7 @@ Ask your MCP client things like:
 
 ## Privacy & Security
 
-- **Local Processing**: All embeddings are generated locally using Xenova/Transformers
+- **Local Processing**: All embeddings are generated locally using Hugging Face Transformers.js
 - **No Cloud Services**: No data is sent to external servers; the write bridge is a local unix socket, never a network port
 - **Reads are read-only**: Search and lookup tools never modify your data. The [write tools](#write-tools-200) are the only ones that change anything, and they are opt-in per call, with `confirm` required for deletes and multi-recipient sends
 - **No credentials**: The server holds no tokens or passwords. It uses the Mail, Messages, Calendar, and Contacts apps you are already signed into
@@ -720,4 +797,4 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 - Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
 - Vector search powered by [LanceDB](https://lancedb.com/)
-- Local embeddings via [Xenova/Transformers](https://github.com/xenova/transformers.js)
+- Local embeddings via [Hugging Face Transformers.js](https://github.com/huggingface/transformers.js)

package/bin/apple-tools-http-proxy.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { runHttpStdioProxy } from "../lib/httpStdioProxy.js";
+
+const url = process.argv[2];
+if (!url || process.argv.length !== 3) {
+  console.error("Usage: apple-tools-http-proxy <http://mini-address:8421/mcp>");
+  process.exitCode = 2;
+} else {
+  try {
+    await runHttpStdioProxy({ url, token: process.env.APPLE_TOOLS_MCP_TOKEN });
+  } catch (error) {
+    console.error(`Apple Tools HTTP proxy: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/bin/apple-tools-http.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * npm bin for the HTTP transport.
+ * Dedicated wrapper so npm 12 pack/publish keeps the CLI — `index.js` as a
+ * bin target is rewritten with "script name index.js was invalid and removed".
+ * Injects `--transport=http` so a realpath to this file still starts the
+ * HTTP server. `permissions` / `http-token` still win (same contract as the
+ * apple-tools-indexer bin name for `--mode=indexer`).
+ */
+if (!process.argv.includes('--transport=http')) {
+  const transportIdx = process.argv.indexOf('--transport');
+  if (transportIdx === -1 || process.argv[transportIdx + 1] !== 'http') {
+    process.argv.splice(2, 0, '--transport=http');
+  }
+}
+await import('../index.js');

package/examples/com.apple-tools-http.plist

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.REPLACE_ME.apple-tools-http</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/bin/env</string>
+    <string>node</string>
+    <string>REPLACE_ME_WITH_REPO_PATH/bin/apple-tools-http.js</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>WorkingDirectory</key>
+  <string>/Users/REPLACE_ME</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>REPLACE_ME_WITH_NODE_BIN_DIR:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    <key>NODE_OPTIONS</key>
+    <string>--max-old-space-size=4096</string>
+    <key>HOME</key>
+    <string>/Users/REPLACE_ME</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>/Users/REPLACE_ME/Library/Logs/apple-tools-http.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>/Users/REPLACE_ME/Library/Logs/apple-tools-http.err.log</string>
+</dict>
+</plist>

package/examples/config.json.example

@@ -0,0 +1,5 @@
+{
+  "indexInterval": "5m",
+  "httpHost": "127.0.0.1",
+  "httpPort": 8421
+}

package/examples/mcp-client.md

@@ -0,0 +1,98 @@
+# MacBook MCP client setup (Streamable HTTP, v3.0.0+)
+
+`--transport=http` exposes the same tools as stdio mode (including writes:
+sending iMessage, editing contacts/calendar) over the network, so every
+request must carry the bearer token from `apple-tools-mcp http-token`.
+This HTTP transport is for connecting the MacBook's Claude Desktop,
+Claude Code, and Codex Desktop to the MCP server on the Mac Mini. ChatGPT
+Desktop is also a target, but its current custom MCP support does not
+accept a private server directly in the desktop app.
+
+## Server on the Mac Mini
+
+Set `httpHost` in `~/.apple-tools-mcp/config.json` to the Mini's LAN or
+Tailscale IP (or set `APPLE_TOOLS_HTTP_HOST` to that address), then restart
+the HTTP server. The default `127.0.0.1` bind only accepts clients on the
+Mini. Retrieve the token on the Mini with `apple-tools-mcp http-token`.
+
+## Claude Desktop on the MacBook
+
+Install this package on the MacBook and find the absolute path of
+`apple-tools-http-proxy` with `command -v apple-tools-http-proxy`. In
+`~/Library/Application Support/Claude/claude_desktop_config.json`, add a
+local MCP server entry using that path:
+
+```json
+{
+  "mcpServers": {
+    "apple-tools": {
+      "command": "/absolute/path/to/apple-tools-http-proxy",
+      "args": ["http://<mini-address>:8421/mcp"],
+      "env": { "APPLE_TOOLS_MCP_TOKEN": "<token-from-mini>" }
+    }
+  }
+}
+```
+
+Merge this entry into any existing `mcpServers` object, then fully quit and
+reopen Claude Desktop. This local proxy makes the private-network request
+from the MacBook. Claude Desktop's **custom connector** instead connects
+from Anthropic's cloud and cannot use the Mini's private LAN or Tailscale IP.
+[Anthropic documents the distinction](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
+The example puts the token in Claude Desktop's local configuration; restrict
+that file to your account.
+
+## Claude Code on the MacBook
+
+```bash
+claude mcp add --transport http apple-tools http://<mini-address>:8421/mcp \
+  -H "Authorization: Bearer <token-from-mini>" \
+  -s user
+```
+
+`<mini-address>` is the Mini's LAN or Tailscale IP, matching the address
+on which the server listens.
+
+## Codex Desktop on the MacBook
+
+Make the token from the Mini available as `APPLE_TOOLS_MCP_TOKEN` in the
+MacBook environment that runs Codex, then add the server:
+
+```bash
+codex mcp add apple-tools --url http://<mini-address>:8421/mcp \
+  --bearer-token-env-var APPLE_TOOLS_MCP_TOKEN
+```
+
+The Codex CLI and desktop app share MCP configuration, but the token
+environment variable must be available to whichever Codex process connects.
+[OpenAI's Codex MCP setup guide](https://developers.openai.com/learn/docs-mcp)
+describes their shared configuration.
+
+## Network access
+
+For access away from the LAN, run Tailscale on both the Mini and MacBook and
+use the Mini's Tailscale IP. Use TLS or a trusted private network before
+sending the bearer token across the network. Keep the Mini's HTTP server
+running while either client uses its tools.
+
+## ChatGPT Desktop on the MacBook
+
+[OpenAI currently documents custom MCP apps for ChatGPT web](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt),
+not ChatGPT Desktop. ChatGPT also cannot connect directly to the Mini's
+private address. If you use ChatGPT web, OpenAI's
+[Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)
+is the documented way to reach a private MCP server, subject to the
+account and workspace access described there. This repository's HTTP
+server does not by itself enable the requested ChatGPT Desktop connection.
+
+## Getting/rotating the token
+
+```bash
+apple-tools-mcp http-token              # print the current token (generates one if missing)
+```
+
+On the Mini, the token lives in the macOS Keychain (service
+`apple-tools-mcp-http`), never in the server's config file or the repo. To
+rotate it, delete the Keychain item and restart the HTTP server — it'll
+generate a new one on the next run —
+then update every client that was using the old value.