apple-tools-mcp 2.1.5 → 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:
@@ -593,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
@@ -722,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.