@thenavidm/apple-photos-mcp-cli 1.1.0 → 2.0.0

package/README.md

@@ -12,7 +12,7 @@ Apple Photos MCP server and CLI for Claude Code, Codex and AI agents. 13 tools t
 
 Give any AI agent real access to your own Apple Photos library, so it can find, see, organise and export your photos instead of guessing.
 
-Built and maintained by [Navid Moazzez](https://navid.me?utm_source=github&utm_medium=referral&utm_campaign=apple-photos-mcp-cli&utm_content=readme).
+Built and maintained by [Navid Moazzez](https://navid.me?utm_source=github&utm_medium=referral&utm_campaign=apple-photos-mcp-cli&utm_content=readme). Built on [Slipway](https://github.com/thenavidm/slipway), which turns one definition of each tool into the MCP server and the CLI.
 
 <img src="https://cdn.navid.media/repos/apple-photos-mcp.gif?v=1" alt="Claude Code using the Apple Photos MCP server" width="520">
 
@@ -31,6 +31,7 @@ apple-photos-cli library-stats --json               # real totals, one call
 apple-photos-cli search-photos "sunset" --limit 5 --screenshots exclude
 apple-photos-cli photo-info --refs IMG_2073.MOV
 apple-photos-cli export-originals --refs <uuid> --directory ./out
+apple-photos-cli which save my photos to disk       # find the command for a task
 apple-photos-cli <command> --help                   # what any command takes
 ```
 
@@ -76,10 +77,10 @@ the tool name with dashes.
 | Title and description | `apple-photos-cli set-photo-title` / `set-photo-description` | `set_photo_title` / `set_photo_description` |
 | Keywords and albums | `apple-photos-cli add-keywords` / `add-to-album` | `add_keywords` / `add_to_album` |
 | Move into an archive album | `apple-photos-cli archive-photos` | `archive_photos` |
-| Check the setup | `apple-photos-cli doctor` | `doctor` |
+| Check the setup | `apple-photos-cli doctor`, or `check-setup` for the engine's report alone | `doctor` |
 | Find the right command | `apple-photos-cli which "..."` | not a tool |
 
-All 13 with their arguments are in [section 6](#6-tools-).
+All 13 with their arguments are in [section 6](#6-tools-%EF%B8%8F).
 
 ## Output and exit codes
 
@@ -91,10 +92,12 @@ Results on stdout, errors on stderr as JSON, so one parse handles both.
 | `--json` | JSON, always |
 | `--compact` | the same JSON on one line |
 | `--select a,b.c` | keep only these fields |
+| `--agent` | one-line JSON, no prompts and no color, for a script or an agent |
 
 | Code | Means |
 |---|---|
 | `0` | it worked |
+| `1` | something unexpected went wrong |
 | `2` | it was typed wrong, or a write was refused: a missing flag, a bad value, no `--confirm`, or read only |
 | `3` | a photo or album wasn't found |
 | `4` | macOS refused access: Full Disk Access, or Automation for Photos |
@@ -103,11 +106,49 @@ Results on stdout, errors on stderr as JSON, so one parse handles both.
 
 ## Which surface, and what each costs
 
-An MCP server is charged on every turn; a CLI costs nothing until it is called.
+Both surfaces are the same program with the same 13 tools. The
+difference is when the model pays for them. Measured in Claude Code:
 
-The `tools/list` payload for these 13 tools is about **2,800 tokens**, plus the
-server instructions, on every turn of every conversation whether you use it or
-not. The CLI is free until you run something, which is why both exist.
+| | MCP server | CLI |
+|---|---|---|
+| Every message, with every tool loaded | 3,400 tokens | nothing |
+| Every message, Claude Code's default | 650 tokens | nothing |
+| When Apple Photos comes up | nothing more, or the tools it picks | 2,500 tokens for `SKILL.md`, once |
+| 20 messages with Apple Photos in 1, every tool loaded | 68,000 tokens | 2,500 tokens |
+
+Claude Code's [tool search](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search)
+is on by default: it sends only the tool names and the server instructions,
+and loads a tool's full definition when the model reaches for it. An app that
+loads every tool up front pays the first line on every message, whether
+Apple Photos comes up or not. With the skill added, Claude Code also lists its
+one-line description, about 180 tokens.
+
+To spend less, turn the server off when you are not using it, which in Claude
+Code is the `/mcp` panel. `APPLE_PHOTOS_READ_ONLY=1` takes the 6 write tools off the list, leaving 7.
+Or install the CLI and add the server on the days it earns its place.
+
+Measured on 2026-10-05 against 1.1.1, with Claude Code 2.1.286 on Claude Opus
+5.5 (one short prompt with and without the server connected, once with
+`ENABLE_TOOL_SEARCH=false` and once with the default, the difference read from
+the API's own usage figures; `SKILL.md` the same way) and Codex 0.159.3 on
+gpt-6.1-sol, with an empty home folder and an engine that could not start, so
+nothing read the library:
+
+| Cost | 1.1.1 | 2.0.0 |
+| --- | --- | --- |
+| Claude Code, every tool loaded, every message | 3,843 | 3,402 |
+| Claude Code's default, tool search, every message | 656 | 654 |
+| `SKILL.md`, read once | 2,510 | 2,490 |
+| Codex over the CLI, one task, median of five | 191,767 | 53,232 |
+| Codex over MCP, the same task, median of five | 39,915 | 39,959 |
+
+The task was "find the command that exports original photo files to a folder
+on this Mac, and the flags it requires". In 1.1.1, `<command> --help` printed
+the general help, so every run tried seven to ten commands before it found the
+flags; every 2.0.0 run read the general help and the command's own: two. Over
+MCP the server's printout was shorter in every 2.0.0 run, and the medians
+differ by the model's own replies. Other apps and models count tokens a little
+differently, and tool-list characters divided by four are not API usage.
 
 ## Contents
 
@@ -120,11 +161,11 @@ not. The CLI is free until you run something, which is why both exist.
 | 3 | [Setup](#3-setup-) | One permission, once |
 | 4 | [Connect your client](#4-connect-your-client-) | Every client, copy and paste |
 | 5 | [Check it worked](#5-check-it-worked-) | `doctor` |
-| 6 | [Tools](#6-tools-) | All 13 |
-| 7 | [Working safely](#7-working-safely-) | What asks, what does not |
+| 6 | [Tools](#6-tools-%EF%B8%8F) | All 13 |
+| 7 | [Working safely](#7-working-safely-%EF%B8%8F) | What asks, what does not |
 | 8 | [What Apple Photos actually does](#8-what-apple-photos-actually-does-) | The things that surprise people |
 | 9 | [Your data](#9-your-data-) | What is stored, and where |
-| 10 | [Configuration](#10-configuration-) | Every setting |
+| 10 | [Configuration](#10-configuration-%EF%B8%8F) | Every setting |
 | 11 | [Troubleshooting](#11-troubleshooting-) | When something breaks |
 | 12 | [FAQ](#12-faq-) | Start here if you are new |
 
@@ -324,13 +365,11 @@ Or just ask your agent: **"run doctor on apple photos"**.
 
 Healthy output includes a line like:
 
-```json
-{
-  "check": "index",
-  "ok": true,
-  "detail": "37129 assets indexed (35983 with ML labels, 10807 with readable text)"
-}
 ```
+  ✓ index          37129 assets indexed (35983 with ML labels, 10807 with readable text)
+```
+
+`--json` prints the same checks as JSON, and `apple-photos-cli check-setup` prints the engine's own report.
 
 The two things that actually fail:
 
@@ -355,7 +394,7 @@ The two things that actually fail:
 | Tool | What it does |
 |---|---|
 | `library_stats` | Totals, albums, named people, how much is iCloud only |
-| `doctor` | Diagnose setup |
+| `doctor` | Diagnose setup. On the CLI it is `check-setup`, because `doctor` there runs these checks with the CLI's own |
 
 **Organizing**
 
@@ -366,7 +405,7 @@ The two things that actually fail:
 | `add_keywords` | Add keywords, keeping existing ones |
 | `set_photo_title` | Set one item's title |
 | `set_photo_description` | Set one item's caption |
-| `archive_photos` | Move to an archive album. Needs `confirm: true` |
+| `archive_photos` | Move to an archive album. Needs confirming |
 
 **Getting files out**
 
@@ -380,11 +419,11 @@ Organizing works out of the box, because that is the point of the tool. Three th
 
 **Nothing can delete a photo.** macOS does not expose scripted deletion to any application, and this server does not try to route around that. `archive_photos` moves items into an album so they leave your main view, and you empty that album yourself.
 
-**`archive_photos` is the only tool that asks.** It needs `confirm: true`. Everything else it can do is one click to undo in Photos, and requiring confirmation on all of them would just teach a model to pass `confirm` reflexively, including on the one that matters.
+**`archive_photos` is the only tool that asks.** Over MCP a person approves it: Claude Code (2.1.246 and later) shows its own prompt, and an app that can show forms asks with an approval form whose one box starts unticked. Where an app can do neither, the model's `confirm: true` still counts, and `APPLE_PHOTOS_CONFIRM=model` makes it enough everywhere; in a terminal it is `--confirm`, which `--agent` never adds. `APPLE_PHOTOS_ALLOW_DESTRUCTIVE=0` refuses it, confirmed or not. Everything else it can do is one click to undo in Photos, and requiring confirmation on all of them would just teach a model to pass `confirm` reflexively, including on the one that matters.
 
 **`APPLE_PHOTOS_READ_ONLY=1` removes every write tool.** They vanish from the tool list rather than erroring when called, because a model cannot call a tool it cannot see. This is the right setting for an agent working unattended.
 
-`APPLE_PHOTOS_AUDIT_LOG=~/.apple-photos-mcp/writes.jsonl` records one JSON line per attempted write, allowed and blocked alike.
+`APPLE_PHOTOS_AUDIT_LOG=~/.apple-photos-mcp/writes.jsonl` records one JSON line per attempted write, allowed and blocked alike, with who approved it, then whether it was done or failed.
 
 Every tool carries MCP annotations, so a client can decide what to auto-approve: reads are marked read-only, organizing is marked non-destructive, and `archive_photos` is marked destructive. Nothing is marked open-world, because nothing here leaves your machine.
 
@@ -428,7 +467,13 @@ Every setting is an environment variable, set in your client's `env` block.
 | Variable | Default | What it does |
 |---|---|---|
 | `APPLE_PHOTOS_READ_ONLY` | off | Removes every write tool from the tool list |
+| `APPLE_PHOTOS_ALLOW_DESTRUCTIVE` | on | `0` refuses `archive_photos`, confirmed or not |
+| `APPLE_PHOTOS_CONFIRM` | `human` | `model` lets `confirm: true` alone approve an archive over MCP, for an agent with no person to ask |
 | `APPLE_PHOTOS_AUDIT_LOG` | off | Path for one JSON line per attempted write |
+| `APPLE_PHOTOS_PYTHON` | `uv` | A Python that has osxphotos and photoscript; uv fetches them on demand when unset |
+| `APPLE_PHOTOS_PYTHONPATH` | the copy in this package | Where the engine's package lives |
+| `APPLE_PHOTOS_STARTUP_TIMEOUT_MS` | `300000` | How long the engine may take to start, since a cold uv run builds pyobjc |
+| `APPLE_PHOTOS_REQUEST_TIMEOUT_MS` | `300000` | How long one call may take |
 | `APPLE_PHOTOS_LIBRARY` | last opened | Path to a specific `.photoslibrary` |
 | `APPLE_PHOTOS_EXPORT_DIR` | `~/Downloads/Photos Exports` | Default export folder |
 | `APPLE_PHOTOS_PREVIEW_DIR` | `~/.apple-photos-mcp/previews` | Where previews are cached |
@@ -436,6 +481,11 @@ Every setting is an environment variable, set in your client's `env` block.
 | `APPLE_PHOTOS_PREVIEW_MAX` | `8` | Most items rendered per `look_at_photos` call |
 | `APPLE_PHOTOS_WRITE_BATCH_MAX` | `100` | Most items a single write may touch |
 | `APPLE_PHOTOS_ARCHIVE_ALBUM` | `Archived by Claude` | Album `archive_photos` moves items into |
+| `APPLE_PHOTOS_SURFACE` | `full` | `search` lists three tools that find, describe and run the rest |
+| `APPLE_PHOTOS_TOOL_TIMEOUT_MS` | none | Give up on any tool after this long |
+| `APPLE_PHOTOS_HTTP_PORT`, `APPLE_PHOTOS_HTTP_HOST`, `APPLE_PHOTOS_HTTP_TOKEN` | 8787, 127.0.0.1, none | For `--http`. Any host but 127.0.0.1 needs the bearer token |
+| `APPLE_PHOTOS_HTTP_ALLOWED_ORIGINS` | none | Comma-separated browser origins allowed to call `--http`; a page from any other site is refused |
+| `APPLE_PHOTOS_DEBUG` | `0` | `1` prints debug lines on stderr |
 
 ## 11. Troubleshooting 🔧
 
@@ -471,7 +521,7 @@ A standard way to give an AI assistant real access to a tool, so it can act rath
 <details>
 <summary><b>Should I use the MCP server or the CLI?</b></summary>
 
-Use the MCP server in an app with no terminal, like Claude Desktop's chat. Use the CLI anywhere commands run: an agent like Claude Code, Codex or OpenCode, a script or a cron job. The MCP server sends its full tool list to the model on every turn, and the CLI costs nothing until it runs.
+Use the MCP server in an app with no terminal, like Claude Desktop's chat. Use the CLI anywhere commands run: an agent like Claude Code, Codex or OpenCode, a script or a cron job. The MCP server's tools take up context on every message, and the CLI costs nothing until it runs.
 
 </details>
 
@@ -568,7 +618,7 @@ Run into a problem or have a question? [Open an issue](https://github.com/thenav
 
 ## About the author
 
-Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. This Apple Photos MCP server is one piece of that system.
+Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. He creates useful free tools, MCP servers and CLIs that creators and founders can use in their own workflows.
 
 **Links**
 
@@ -586,7 +636,9 @@ If this is useful, star the repo and come say hi on [X](https://x.com/thenavidm)
 
 | Package | License | Why |
 |---|---|---|
-| [mcp](https://github.com/modelcontextprotocol/python-sdk) | MIT | The MCP protocol implementation |
+| [Slipway](https://github.com/thenavidm/slipway) | Apache-2.0 | The MCP server and the CLI from one definition of each tool |
+| [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) | Apache-2.0 | The MCP protocol and its transports, through Slipway |
+| [mcp](https://github.com/modelcontextprotocol/python-sdk) | MIT | The MCP protocol for the Python engine |
 | [osxphotos](https://github.com/RhetTbull/osxphotos) | MIT | Reads the Photos library database and Apple's on-device ML metadata |
 | [photoscript](https://github.com/RhetTbull/photoscript) | MIT | Drives Photos.app for writes |
 
@@ -598,4 +650,4 @@ Not affiliated with, endorsed by, or connected to Apple Inc. Apple, macOS, Photo
 
 ---
 
-© 2026 [NM Media](https://navid.media). Made with ❤️ by [Navid Moazzez](https://navid.me?utm_source=github&utm_medium=referral&utm_campaign=apple-photos-mcp-cli&utm_content=readme).
+© 2026 [Navid Media](https://navid.media?utm_source=github&utm_medium=referral&utm_campaign=apple-photos-mcp-cli&utm_content=readme). Made with ❤️ by [Navid Moazzez](https://navid.me?utm_source=github&utm_medium=referral&utm_campaign=apple-photos-mcp-cli&utm_content=readme).

package/SKILL.md

@@ -26,6 +26,7 @@ piping and one-off questions, and costs no context until it is called.
 apple-photos-cli library-stats --json
 apple-photos-cli search-photos "sunset" --limit 5 --screenshots exclude
 apple-photos-cli photo-info --refs IMG_2073.MOV
+apple-photos-cli which <words>
 apple-photos-cli <command> --help
 ```
 
@@ -61,8 +62,6 @@ into the library. That is the index:
 | Faces | Only people the user has actually named in Photos |
 | Albums, keywords, titles | Only what the user typed themselves |
 
-Two consequences worth internalizing.
-
 **The visual vocabulary is closed.** Apple knows "Sunset" but not "golden hour",
 "Crowd" but not "keynote", "Dog" but not "goofy". If a result comes back with
 `unmatched_terms`, that word does not exist in this library and rephrasing the
@@ -97,9 +96,8 @@ Useful habits:
 look_at_photos(refs=["<uuid>", "<uuid>", "<uuid>"])
 ```
 
-This works even when the photo lives only in iCloud, because it reads the
-thumbnail Apple already stored on this Mac rather than downloading the original.
-It is fast, so use it freely.
+This works even for iCloud-only photos: it reads the thumbnail already on this
+Mac, so it is fast. Use it freely.
 
 Up to eight items render per call. Ask for a bigger `size` only when fine detail
 matters, such as reading text off a receipt.
@@ -125,9 +123,9 @@ Each of those is one click to undo in Photos, so none of them ask first.
 archive_photos(refs=[...], confirm=True)
 ```
 
-`archive_photos` is the only tool that requires `confirm: true`. Call it without
-confirm to see what it would do, then again with confirm once the user has
-actually asked for those specific items to go.
+`archive_photos` is the only tool that needs confirming: the user approves it
+over MCP, or `confirm: true` where the app cannot ask, and `--confirm` on the
+CLI. Call it only once the user has asked for those specific items to go.
 
 **Nothing deletes.** macOS does not let any app delete photos by script. This
 moves items into an album for the user to empty by hand. Always say so rather
@@ -149,7 +147,7 @@ wants to see a photo, look at it instead.
 library_stats()          # totals, albums, named people, how much is in iCloud
 list_vocabulary()        # the visual words this library knows
 photo_info(refs=[...])   # everything about specific items, including OCR text
-doctor()                 # run this first whenever anything misbehaves
+doctor()                 # run this first whenever anything misbehaves; apple-photos-cli doctor
 ```
 
 ## Exit codes
@@ -159,6 +157,7 @@ A script branches on the number, not the message:
 | Code | Means |
 |---|---|
 | 0 | it worked |
+| 1 | something unexpected went wrong |
 | 2 | typed wrong, or a write was refused: a missing flag, a bad value, no `--confirm`, or read only |
 | 3 | a photo or album was not found |
 | 4 | macOS refused access: Full Disk Access, or Automation for Photos |
@@ -170,7 +169,6 @@ A script branches on the number, not the message:
 | Symptom | Cause | Fix |
 |---|---|---|
 | Permission denied on the library | No Full Disk Access | System Settings, Privacy & Security, Full Disk Access. Add the app running the server, then fully quit and reopen it. |
-| Write tools are missing entirely | `APPLE_PHOTOS_READ_ONLY=1` is set | Unset it and restart the client |
 | A write fails but reads work | Photos automation not allowed | Approve the one-time popup, or System Settings, Privacy & Security, Automation |
 | No preview for one photo | iCloud-only with no cached thumbnail | Open it once in Photos, or export it |
 | Library not found | Photos has never run, or a non-default library | Set `APPLE_PHOTOS_LIBRARY` to the .photoslibrary path |

package/lib/app.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The Apple Photos app: everything Slipway needs to ship the MCP server and the CLI.
+ *
+ * Mac only. The tools are declared here in TypeScript and run by the Python
+ * engine, which reads the library through osxphotos and photoscript; the
+ * bridge starts it on the first call. This file only describes; `index.ts` runs.
+ */
+import type { ToolContext } from "./tools/kit.js";
+export type AppOptions = {
+    /** Replace how calls reach the engine, for tests that stand a fake one in. */
+    context?: (env: NodeJS.ProcessEnv) => ToolContext;
+};
+export declare function createApp(options?: AppOptions): import("@thenavidm/slipway").App<ToolContext>;
+export declare const app: import("@thenavidm/slipway").App<ToolContext>;

package/lib/app.js

@@ -0,0 +1,138 @@
+/**
+ * The Apple Photos app: everything Slipway needs to ship the MCP server and the CLI.
+ *
+ * Mac only. The tools are declared here in TypeScript and run by the Python
+ * engine, which reads the library through osxphotos and photoscript; the
+ * bridge starts it on the first call. This file only describes; `index.ts` runs.
+ */
+import { slipway } from "@thenavidm/slipway";
+import { PythonBridge } from "./bridge.js";
+import { loadConfig } from "./config.js";
+import { PhotosError } from "./errors.js";
+import { TOOLS } from "./tools/index.js";
+import { VERSION } from "./version.js";
+const INSTRUCTIONS = `Tools for the user's own Apple Photos library, read directly on this Mac. Nothing is uploaded anywhere.
+
+How to actually find something:
+
+1. search_photos first. It queries Apple's own on-device index across the whole library, so the match count is library-wide; \`limit\` caps what comes back, not what is searched.
+2. Then look_at_photos on the top few. Search returns candidates, not answers, and filenames tell you nothing. Look before you describe, recommend or choose.
+3. Only then reply, naming the file and the date so the user can find it.
+
+Three things that prevent confident wrong answers:
+
+- For anything about scale or proportion, call library_stats. It gives real totals in one call. Counting by running searches and reading results double-counts overlapping terms and cannot see the items that carry no place or label, which in a typical library is thousands.
+- Apple's visual vocabulary is closed, about 1,500 words. If a result carries \`unmatched_terms\`, Apple has never heard of that word and rephrasing the same idea will not help. Read \`did_you_mean\`, or call list_vocabulary.
+- Screenshots are often a fifth of a library and skew every count. Use \`screenshots: "exclude"\` when the question is about photographs.
+
+Nothing here can delete a photo; macOS does not permit it. archive_photos moves items into an album for the user to empty by hand, and it is the one tool that asks for confirmation.`;
+/**
+ * The engine's own doctor: macOS, Python, Full Disk Access, the library, its
+ * index and the write switches, each as one check. When the engine cannot even
+ * start, that is the one check, with how to fix it.
+ */
+async function doctor({ bridge }) {
+    try {
+        const result = await bridge.call("doctor", {});
+        const report = JSON.parse(result.text);
+        return (report.checks ?? []).map((check) => ({ name: check.check, ok: check.ok, detail: check.detail, ...(check.fix ? { fix: check.fix } : {}) }));
+    }
+    catch (error) {
+        // The message carries the advice, which goes in fix; the cause is its first sentence and the engine's own words.
+        const cause = error.message.split(/(?<=`)\. /)[0] ?? error.message;
+        const detail = error instanceof PhotosError && error.detail ? `${cause}: ${error.detail.split("\n")[0]}` : cause;
+        return [
+            {
+                name: "Photos engine",
+                ok: false,
+                detail,
+                fix: "Install uv (https://docs.astral.sh/uv/) or set APPLE_PHOTOS_PYTHON to a Python that has osxphotos and photoscript.",
+            },
+        ];
+    }
+}
+/** 1.1's spellings for the refs and the folder, which `which` and help still accept. */
+const FLAG_ALIASES = {
+    uuid: "refs",
+    uuids: "refs",
+    ref: "refs",
+    file: "refs",
+    files: "refs",
+    out: "directory",
+    dir: "directory",
+    n: "limit",
+};
+/** The words people use for what the tools call something else, as 1.1's `which` read them. */
+const SYNONYMS = {
+    save: ["export", "originals"],
+    saving: ["export", "originals"],
+    download: ["export", "originals"],
+    copy: ["export", "originals"],
+    disk: ["export", "originals"],
+    file: ["export", "originals"],
+    files: ["export", "originals"],
+    find: ["search"],
+    show: ["search", "look"],
+    see: ["look"],
+    view: ["look"],
+    preview: ["look"],
+    image: ["photos"],
+    images: ["photos"],
+    picture: ["photos"],
+    pictures: ["photos"],
+    pic: ["photos"],
+    pics: ["photos"],
+    video: ["photos"],
+    videos: ["photos"],
+    tag: ["keywords"],
+    tags: ["keywords"],
+    label: ["keywords"],
+    labels: ["keywords"],
+    caption: ["description"],
+    name: ["title"],
+    heart: ["favourite", "favorite"],
+    star: ["favourite", "favorite"],
+    like: ["favourite", "favorite"],
+    delete: ["archive"],
+};
+export function createApp(options = {}) {
+    return slipway({
+        name: "apple-photos",
+        title: "Apple Photos",
+        version: VERSION,
+        package: "@thenavidm/apple-photos-mcp-cli",
+        envPrefix: "APPLE_PHOTOS",
+        description: "Search, look at and organize the Apple Photos library on this Mac, through Apple's own on-device index. Nothing is uploaded.",
+        instructions: INSTRUCTIONS,
+        context: options.context ??
+            ((env) => {
+                const config = loadConfig(env);
+                return { config, bridge: new PythonBridge(config) };
+            }),
+        // Nothing to sign in to: macOS decides who may read the library, and doctor says whether it lets this.
+        configured: () => true,
+        tools: TOOLS,
+        doctor,
+        // The checks are the engine's, on this Mac, so they run on every doctor rather than only with --network.
+        doctorNetwork: true,
+        flagAliases: FLAG_ALIASES,
+        synonyms: SYNONYMS,
+        login: "There is no sign-in: the library is on this Mac, and macOS decides who may read it. The first run asks for permission; if it is refused, give the app that launches this server Full Disk Access, then run apple-photos-cli doctor.",
+        settings: [
+            { env: "APPLE_PHOTOS_PYTHON", description: "A Python that has osxphotos and photoscript; uv fetches them on demand when unset." },
+            { env: "APPLE_PHOTOS_LIBRARY", description: "Another Photos library; the system library when unset." },
+            { env: "APPLE_PHOTOS_EXPORT_DIR", description: "Where export_originals writes; ~/Downloads/Photos Exports when unset." },
+            { env: "APPLE_PHOTOS_ARCHIVE_ALBUM", description: "The album archive_photos moves items into." },
+            { env: "APPLE_PHOTOS_PYTHONPATH", description: "Where the engine's package lives; the copy shipped with this package when unset.", tuning: true },
+            { env: "APPLE_PHOTOS_STARTUP_TIMEOUT_MS", description: "How long the engine may take to start; 300000, since a cold uv run builds pyobjc.", tuning: true },
+            { env: "APPLE_PHOTOS_REQUEST_TIMEOUT_MS", description: "How long one call may take; 300000.", tuning: true },
+            { env: "APPLE_PHOTOS_PREVIEW_DIR", description: "Where look_at_photos renders previews.", tuning: true },
+            { env: "APPLE_PHOTOS_PREVIEW_PX", description: "The default preview size in pixels.", tuning: true },
+            { env: "APPLE_PHOTOS_PREVIEW_MAX", description: "How many previews one call renders.", tuning: true },
+            { env: "APPLE_PHOTOS_WRITE_BATCH_MAX", description: "How many items one write may touch.", tuning: true },
+        ],
+        links: { repository: "https://github.com/thenavidm/apple-photos-mcp-cli" },
+    });
+}
+export const app = createApp();
+//# sourceMappingURL=app.js.map

package/lib/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src-ts/app.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAoB,MAAM,oBAAoB,CAAC;AAE/D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;sLAciK,CAAC;AAEvL;;;;GAIG;AACH,KAAK,UAAU,MAAM,CAAC,EAAE,MAAM,EAAe;IAC3C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAqF,CAAC;QAC3H,OAAO,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACrJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,iHAAiH;QACjH,MAAM,KAAK,GAAI,KAAe,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAK,KAAe,CAAC,OAAO,CAAC;QACzF,MAAM,MAAM,GAAG,KAAK,YAAY,WAAW,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;QACjH,OAAO;YACL;gBACE,IAAI,EAAE,eAAe;gBACrB,EAAE,EAAE,KAAK;gBACT,MAAM;gBACN,GAAG,EAAE,oHAAoH;aAC1H;SACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,wFAAwF;AACxF,MAAM,YAAY,GAA2B;IAC3C,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,MAAM;IACb,GAAG,EAAE,MAAM;IACX,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,MAAM;IACb,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,WAAW;IAChB,CAAC,EAAE,OAAO;CACX,CAAC;AAEF,+FAA+F;AAC/F,MAAM,QAAQ,GAA6B;IACzC,IAAI,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC7B,MAAM,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC;IACjC,IAAI,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC7B,IAAI,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC7B,IAAI,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC7B,KAAK,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC9B,IAAI,EAAE,CAAC,QAAQ,CAAC;IAChB,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,CAAC,MAAM,CAAC;IACb,IAAI,EAAE,CAAC,MAAM,CAAC;IACd,OAAO,EAAE,CAAC,MAAM,CAAC;IACjB,KAAK,EAAE,CAAC,QAAQ,CAAC;IACjB,MAAM,EAAE,CAAC,QAAQ,CAAC;IAClB,OAAO,EAAE,CAAC,QAAQ,CAAC;IACnB,QAAQ,EAAE,CAAC,QAAQ,CAAC;IACpB,GAAG,EAAE,CAAC,QAAQ,CAAC;IACf,IAAI,EAAE,CAAC,QAAQ,CAAC;IAChB,KAAK,EAAE,CAAC,QAAQ,CAAC;IACjB,MAAM,EAAE,CAAC,QAAQ,CAAC;IAClB,GAAG,EAAE,CAAC,UAAU,CAAC;IACjB,IAAI,EAAE,CAAC,UAAU,CAAC;IAClB,KAAK,EAAE,CAAC,UAAU,CAAC;IACnB,MAAM,EAAE,CAAC,UAAU,CAAC;IACpB,OAAO,EAAE,CAAC,aAAa,CAAC;IACxB,IAAI,EAAE,CAAC,OAAO,CAAC;IACf,KAAK,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC;IAChC,IAAI,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC;IAC/B,IAAI,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC;IAC/B,MAAM,EAAE,CAAC,SAAS,CAAC;CACpB,CAAC;AAOF,MAAM,UAAU,SAAS,CAAC,UAAsB,EAAE;IAChD,OAAO,OAAO,CAAc;QAC1B,IAAI,EAAE,cAAc;QACpB,KAAK,EAAE,cAAc;QACrB,OAAO,EAAE,OAAO;QAChB,OAAO,EAAE,iCAAiC;QAC1C,SAAS,EAAE,cAAc;QACzB,WAAW,EAAE,8HAA8H;QAC3I,YAAY,EAAE,YAAY;QAC1B,OAAO,EACL,OAAO,CAAC,OAAO;YACf,CAAC,CAAC,GAAG,EAAE,EAAE;gBACP,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;gBAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;YACtD,CAAC,CAAC;QACJ,uGAAuG;QACvG,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI;QACtB,KAAK,EAAE,KAAK;QACZ,MAAM;QACN,yGAAyG;QACzG,aAAa,EAAE,IAAI;QACnB,WAAW,EAAE,YAAY;QACzB,QAAQ,EAAE,QAAQ;QAClB,KAAK,EACH,qOAAqO;QACvO,QAAQ,EAAE;YACR,EAAE,GAAG,EAAE,qBAAqB,EAAE,WAAW,EAAE,oFAAoF,EAAE;YACjI,EAAE,GAAG,EAAE,sBAAsB,EAAE,WAAW,EAAE,wDAAwD,EAAE;YACtG,EAAE,GAAG,EAAE,yBAAyB,EAAE,WAAW,EAAE,uEAAuE,EAAE;YACxH,EAAE,GAAG,EAAE,4BAA4B,EAAE,WAAW,EAAE,4CAA4C,EAAE;YAChG,EAAE,GAAG,EAAE,yBAAyB,EAAE,WAAW,EAAE,kFAAkF,EAAE,MAAM,EAAE,IAAI,EAAE;YACjJ,EAAE,GAAG,EAAE,iCAAiC,EAAE,WAAW,EAAE,mFAAmF,EAAE,MAAM,EAAE,IAAI,EAAE;YAC1J,EAAE,GAAG,EAAE,iCAAiC,EAAE,WAAW,EAAE,qCAAqC,EAAE,MAAM,EAAE,IAAI,EAAE;YAC5G,EAAE,GAAG,EAAE,0BAA0B,EAAE,WAAW,EAAE,wCAAwC,EAAE,MAAM,EAAE,IAAI,EAAE;YACxG,EAAE,GAAG,EAAE,yBAAyB,EAAE,WAAW,EAAE,qCAAqC,EAAE,MAAM,EAAE,IAAI,EAAE;YACpG,EAAE,GAAG,EAAE,0BAA0B,EAAE,WAAW,EAAE,qCAAqC,EAAE,MAAM,EAAE,IAAI,EAAE;YACrG,EAAE,GAAG,EAAE,8BAA8B,EAAE,WAAW,EAAE,qCAAqC,EAAE,MAAM,EAAE,IAAI,EAAE;SAC1G;QACD,KAAK,EAAE,EAAE,UAAU,EAAE,mDAAmD,EAAE;KAC3E,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC"}

package/lib/bridge.d.ts

@@ -13,9 +13,9 @@
  * from the same tool array as the MCP server, and a static `ALL_TOOLS` that the
  * HQ connector can import so the hosted surface cannot drift from this one.
  *
- * Calls are proxied to the Python MCP server over stdio using the official
- * client, so the Python needs no changes and there is one implementation of
- * every tool.
+ * Calls are proxied to the Python MCP server over stdio, through the small
+ * client in engine.ts, so the Python needs no changes and there is one
+ * implementation of every tool.
  */
 import type { Config } from "./config.js";
 /** A content part as the MCP protocol carries it: text, image, or anything later. */
@@ -34,7 +34,7 @@ export type BridgeResult = {
 };
 export declare class PythonBridge {
     private readonly config;
-    private client?;
+    private engine?;
     private starting?;
     /** The tail of the engine's stderr, so a failure can say what actually went wrong. */
     private stderrTail;
@@ -44,8 +44,8 @@ export declare class PythonBridge {
      * Call one Python tool and return every content part.
      *
      * `timeoutMs` matters: exporting originals pulls them out of iCloud first and
-     * rendering previews is not quick either, so the protocol default of 60s
-     * cancels work the engine is still doing.
+     * rendering previews is not quick either, so a short default would cancel
+     * work the engine is still doing.
      */
     call(tool: string, args: Record<string, unknown>, timeoutMs?: number): Promise<BridgeResult>;
     /** What the Python server says it offers, for checking the two lists agree. */

package/lib/bridge.js

@@ -13,16 +13,16 @@
  * from the same tool array as the MCP server, and a static `ALL_TOOLS` that the
  * HQ connector can import so the hosted surface cannot drift from this one.
  *
- * Calls are proxied to the Python MCP server over stdio using the official
- * client, so the Python needs no changes and there is one implementation of
- * every tool.
+ * Calls are proxied to the Python MCP server over stdio, through the small
+ * client in engine.ts, so the Python needs no changes and there is one
+ * implementation of every tool.
  */
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StdioEngine } from "./engine.js";
 import { BridgeError } from "./errors.js";
+import { VERSION } from "./version.js";
 export class PythonBridge {
     config;
-    client;
+    engine;
     starting;
     /** The tail of the engine's stderr, so a failure can say what actually went wrong. */
     stderrTail = "";
@@ -30,47 +30,41 @@ export class PythonBridge {
         this.config = config;
     }
     async connect() {
-        if (this.client)
-            return this.client;
+        if (this.engine)
+            return this.engine;
         if (this.starting)
             return this.starting;
         this.starting = (async () => {
-            const client = new Client({ name: "apple-photos-cli", version: "1.0.0" }, { capabilities: {} });
-            const transport = new StdioClientTransport({
+            const engine = new StdioEngine({
                 command: this.config.pythonCommand,
                 args: this.config.pythonArgs,
-                env: { ...process.env, ...this.config.pythonEnv },
-                stderr: "pipe",
+                env: this.config.pythonEnv,
+                clientInfo: { name: "apple-photos-cli", version: VERSION },
+                // Drained as it arrives: osxphotos is chatty on a large library, and an
+                // unread pipe fills and blocks the engine. Keeping the tail also means a
+                // failure can name the actual cause, a missing module or a Full Disk
+                // Access denial, instead of a boilerplate "install uv".
+                onStderr: (chunk) => {
+                    this.stderrTail = (this.stderrTail + chunk).slice(-4000);
+                },
+                // A dead engine must not stay cached, or one crash breaks every later
+                // call for the life of the process.
+                onClose: () => {
+                    if (this.engine === engine)
+                        this.engine = undefined;
+                },
             });
-            // Drain stderr immediately. The SDK pipes it into a PassThrough with a
-            // 16KB buffer; with no reader that fills, the OS pipe fills behind it,
-            // and the child blocks writing to stderr. osxphotos is chatty on a large
-            // library, so this is a real hang, not a theoretical one. Keeping the
-            // tail also means a failure can name the actual cause — a missing module,
-            // a Full Disk Access denial — instead of a boilerplate "install uv".
-            transport.stderr?.on("data", (chunk) => {
-                this.stderrTail = (this.stderrTail + chunk.toString()).slice(-4000);
-            });
-            // A dead client must not stay cached, or one engine crash bricks every
-            // later call for the life of the process with "Connection closed".
-            const forget = () => {
-                if (this.client === client)
-                    this.client = undefined;
-            };
-            client.onclose = forget;
-            client.onerror = forget;
             try {
-                // The default is 60s, and a cold `uv` run builds pyobjc, which takes
-                // longer than that on a fresh cache. Failing there reported "install
-                // uv" at the one moment uv was working correctly.
-                await client.connect(transport, { timeout: this.config.startupTimeoutMs });
+                // A cold `uv` run builds pyobjc, which takes longer than a minute on a
+                // fresh cache, so the wait is the configured startup timeout.
+                await engine.start(this.config.startupTimeoutMs);
             }
             catch (error) {
                 throw new BridgeError(`Could not start the Photos engine with \`${this.config.pythonCommand} ${this.config.pythonArgs.join(" ")}\`. ` +
                     `Install uv (https://docs.astral.sh/uv/) or set APPLE_PHOTOS_PYTHON to a Python that has osxphotos and photoscript.`, [error.message, this.stderrTail.trim()].filter(Boolean).join("\n"));
             }
-            this.client = client;
-            return client;
+            this.engine = engine;
+            return engine;
         })();
         try {
             return await this.starting;
@@ -83,36 +77,36 @@ export class PythonBridge {
      * Call one Python tool and return every content part.
      *
      * `timeoutMs` matters: exporting originals pulls them out of iCloud first and
-     * rendering previews is not quick either, so the protocol default of 60s
-     * cancels work the engine is still doing.
+     * rendering previews is not quick either, so a short default would cancel
+     * work the engine is still doing.
      */
     async call(tool, args, timeoutMs) {
-        const client = await this.connect();
+        const engine = await this.connect();
         let result;
         try {
-            result = (await client.callTool({ name: tool, arguments: args }, undefined, { timeout: timeoutMs ?? this.config.requestTimeoutMs }));
+            result = (await engine.request("tools/call", { name: tool, arguments: args }, timeoutMs ?? this.config.requestTimeoutMs));
         }
         catch (error) {
             throw new BridgeError(`The Photos engine failed while running ${tool}.`, [error.message, this.stderrTail.trim()].filter(Boolean).join("\n"));
         }
-        const content = result.content ?? [];
+        const content = result?.content ?? [];
         const text = content
             .filter((part) => part.type === "text" && typeof part.text === "string")
             .map((part) => part.text)
             .join("\n");
-        return { content, text, isError: result.isError === true };
+        return { content, text, isError: result?.isError === true };
     }
     /** What the Python server says it offers, for checking the two lists agree. */
     async listTools() {
-        const client = await this.connect();
-        const { tools } = await client.listTools();
+        const engine = await this.connect();
+        const { tools } = (await engine.request("tools/list", {}, this.config.requestTimeoutMs));
         return tools.map((tool) => tool.name);
     }
     async close() {
         this.starting = undefined;
-        const client = this.client;
-        this.client = undefined;
-        await client?.close().catch(() => undefined);
+        const engine = this.engine;
+        this.engine = undefined;
+        await engine?.close().catch(() => undefined);
     }
 }
 //# sourceMappingURL=bridge.js.map