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

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Navid Moazzez
+Copyright (c) 2026 NM Media
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -3,17 +3,16 @@
 # Apple Photos MCP + CLI
 
 [![npm](https://img.shields.io/npm/v/@thenavidm/apple-photos-mcp-cli?color=orange&label=npm)](https://www.npmjs.com/package/@thenavidm/apple-photos-mcp-cli)
-[![Stars](https://img.shields.io/github/stars/navidmoazzez/apple-photos-mcp-cli?style=flat&logo=github&label=Stars)](https://github.com/navidmoazzez/apple-photos-mcp-cli)
-[![License](https://img.shields.io/badge/License-MIT-blue)](./LICENSE)
+[![License](https://img.shields.io/badge/licence-MIT-green)](./LICENSE)
 [![YouTube](https://img.shields.io/badge/YouTube-@thenavidm-red?logo=youtube&logoColor=white)](https://youtube.com/@thenavidm?sub_confirmation=1)
 [![X](https://img.shields.io/badge/X-@thenavidm-black?logo=x)](https://x.com/thenavidm)
 [![LinkedIn](https://img.shields.io/badge/LinkedIn-thenavidm-0A66C2?logo=linkedin&logoColor=white)](https://linkedin.com/in/thenavidm)
 
-Apple Photos MCP server and CLI for Claude Code and AI agents. 13 tools to search, look at, organise and export your own library, entirely on your Mac.
+Apple Photos MCP server and CLI for Claude Code, Codex and AI agents. 13 tools to search, look at, organise and export your own library, entirely on your Mac.
 
 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=readme&utm_campaign=apple-photos-mcp).
+Built and maintained by [Navid Moazzez](https://navid.me?utm_source=github&utm_medium=referral&utm_campaign=apple-photos-mcp-cli&utm_content=readme).
 
 <img src="https://cdn.navid.media/repos/apple-photos-mcp.gif?v=1" alt="Claude Code using the Apple Photos MCP server" width="520">
 
@@ -52,19 +51,70 @@ Then just ask: _"which receipts do I have from Vietnam?"_
 
 ### Which one
 
-| What you are doing | Use |
+| Where you are | What you can reach |
 |---|---|
-| Inside a conversation with an agent | MCP |
-| Piping, scripting, cron, CI | CLI |
-| A one-off question in a terminal | CLI |
+| An agent that can run shell commands, like Claude Code or Cursor | Both. The CLI is the cheaper one: it costs nothing until you type it |
+| A terminal, a script, cron or CI | The CLI only. There is no MCP client in a shell |
 
 They are the same program reading the same tool definitions, so anything one
 can do, the other can. A test asserts they cannot drift.
 
+## Features
+
+Every tool is both a command and an MCP tool, with the same name. The command is
+the tool name with dashes.
+
+| Capability | CLI command | MCP tool |
+|---|---|---|
+| Search the whole library | `apple-photos-cli search-photos` | `search_photos` |
+| Actually look at photos | `apple-photos-cli look-at-photos` | `look_at_photos` |
+| Full metadata, camera and lens | `apple-photos-cli photo-info` | `photo_info` |
+| Real totals in one call | `apple-photos-cli library-stats` | `library_stats` |
+| What Apple can search for | `apple-photos-cli list-vocabulary` | `list_vocabulary` |
+| Export originals to disk | `apple-photos-cli export-originals` | `export_originals` |
+| Favourite or unfavourite | `apple-photos-cli favorite-photos` | `favorite_photos` |
+| 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` |
+| Find the right command | `apple-photos-cli which "..."` | not a tool |
+
+All 13 with their arguments are in [section 6](#6-tools-).
+
+## Output and exit codes
+
+Results on stdout, errors on stderr as JSON, so one parse handles both.
+
+| Flag | Result |
+|---|---|
+| none | pretty JSON |
+| `--json` | JSON, always |
+| `--compact` | the same JSON on one line |
+| `--select a,b.c` | keep only these fields |
+
+| Code | Means |
+|---|---|
+| `0` | it worked |
+| `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 |
+| `5` | the engine or Photos failed |
+| `10` | the engine could not start: install uv, or set `APPLE_PHOTOS_PYTHON` |
+
+## Which surface, and what each costs
+
+An MCP server is charged on every turn; a CLI costs nothing until it is called.
+
+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.
+
 ## Contents
 
 | | Section | |
 |---|---|---|
+| | [Features](#features) | Every tool, both surfaces |
+| | [Output and exit codes](#output-and-exit-codes) | What scripts branch on |
 | 1 | [What you can ask it](#1-what-you-can-ask-it-) | Real prompts, not features |
 | 2 | [Quick install](#2-quick-install-) | One command, no credential |
 | 3 | [Setup](#3-setup-) | One permission, once |
@@ -197,8 +247,8 @@ Apple Photos only exists on macOS, so there is no Windows or Linux path here.
 
 **If it already has other servers**, add only the `"apple-photos"` block inside the existing `"mcpServers"` object, and put a comma after the previous server's closing brace. One misplaced comma invalidates the file, and then every server disappears, not just this one.
 
-> **Tip**
-> Claude Desktop does not inherit your shell PATH. If `uvx` is not found, run `which uvx` in a terminal and use that absolute path as `"command"`.
+> [!TIP]
+> Claude Desktop does not inherit your shell PATH. If `npx` is not found, run `which npx` in a terminal and use that absolute path as `"command"`.
 
 Quit Claude Desktop completely with Cmd+Q and reopen it.
 
@@ -208,6 +258,8 @@ Quit Claude Desktop completely with Cmd+Q and reopen it.
 tail -f ~/Library/Logs/Claude/mcp-server-apple-photos.log
 ```
 
+There is also a one-click `.mcpb` bundle on the [releases page](https://github.com/thenavidm/apple-photos-mcp-cli/releases), installed through **Settings**, then **Extensions**, then **Install Extension**. It carries the server and the Python engine; uv still fetches the engine's dependencies on first run, because they build pyobjc and only work on macOS.
+
 ### Cursor
 
 **Cursor Settings**, then **MCP**, then **Add new global MCP server**. That opens `~/.cursor/mcp.json`. Same JSON shape as Claude Desktop, same `mcpServers` key. Save, then click reload next to the server.
@@ -227,8 +279,8 @@ For one project instead of globally, use `.cursor/mcp.json` in that project.
   "servers": {
     "apple-photos": {
       "type": "stdio",
-      "command": "uvx",
-      "args": ["--from", "git+https://github.com/navidmoazzez/apple-photos-mcp-cli", "apple-photos-mcp"]
+      "command": "npx",
+      "args": ["-y", "@thenavidm/apple-photos-mcp-cli@latest"]
     }
   }
 }
@@ -242,8 +294,8 @@ Reload the window: Cmd+Shift+P, then **Developer: Reload Window**.
 
 ```toml
 [mcp_servers.apple-photos]
-command = "uvx"
-args = ["--from", "git+https://github.com/navidmoazzez/apple-photos-mcp-cli", "apple-photos-mcp"]
+command = "npx"
+args = ["-y", "@thenavidm/apple-photos-mcp-cli@latest"]
 ```
 
 ### Gemini CLI
@@ -252,7 +304,7 @@ args = ["--from", "git+https://github.com/navidmoazzez/apple-photos-mcp-cli", "a
 
 ### Everything else
 
-Any stdio MCP client takes the same two things: the command `uvx`, and the args above.
+Any stdio MCP client takes the same two things: the command `npx`, and the args above.
 
 ### claude.ai on the web, with a relay
 
@@ -393,7 +445,7 @@ Run `doctor` before guessing. It names which of these it is.
 |---|---|---|
 | Permission denied reading the library | No Full Disk Access | [Section 3](#3-setup-). Quit the app with Cmd+Q, not just the window. |
 | Server does not appear in the client | Bad JSON, usually a comma | Paste the config into a JSON validator. One bad comma hides every server. |
-| `uvx: command not found` | The app cannot see your shell PATH | Use the absolute path from `which uvx` |
+| `npx: command not found` | The app cannot see your shell PATH | Use the absolute path from `which npx` |
 | Write tools are missing | `APPLE_PHOTOS_READ_ONLY` is set | Unset it and restart the client |
 | Reads work, writes fail | Photos automation not approved | Approve the popup, or Privacy & Security, then Automation |
 | First search takes half a minute | Building the index | One time, about 25 seconds for 37,000 items. Cached afterwards. |
@@ -409,6 +461,20 @@ A standard way to give an AI assistant real access to a tool, so it can act rath
 
 </details>
 
+<details>
+<summary><b>What is the CLI?</b></summary>
+
+`apple-photos-cli` is the same program as the MCP server, run as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal, a script or a cron job. Every tool is a command with dashes, so `search_photos` runs as `apple-photos-cli search-photos`.
+
+</details>
+
+<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.
+
+</details>
+
 <details>
 <summary><b>What is Apple Photos?</b></summary>
 
@@ -498,17 +564,17 @@ Delete the server from your client's config, or run `claude mcp remove apple-pho
 
 ## Questions
 
-Run into a problem or have a question? [Open an issue](https://github.com/navidmoazzez/apple-photos-mcp-cli/issues) and I will help.
+Run into a problem or have a question? [Open an issue](https://github.com/thenavidm/apple-photos-mcp-cli/issues) and I will help.
 
 ## 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. This Apple Photos MCP server is one piece of that system.
 
 **Links**
 
-- Personal website: [navid.me](https://navid.me?utm_source=github&utm_medium=readme&utm_campaign=apple-photos-mcp)
-- Link in bio: [navid.bio](https://navid.bio?utm_source=github&utm_medium=readme&utm_campaign=apple-photos-mcp)
-- Navid Media: [navid.media](https://navid.media?utm_source=github&utm_medium=readme&utm_campaign=apple-photos-mcp)
+- Personal website: [navid.me](https://navid.me?utm_source=github&utm_medium=referral&utm_campaign=apple-photos-mcp-cli&utm_content=readme)
+- Link in bio: [navid.bio](https://navid.bio)
+- Navid Media: [navid.media](https://navid.media)
 - YouTube: [@thenavidm](https://youtube.com/@thenavidm?sub_confirmation=1) and [@thenavidai](https://youtube.com/@thenavidai?sub_confirmation=1)
 - X: [@thenavidm](https://x.com/thenavidm)
 - Instagram: [@thenavidm](https://instagram.com/thenavidm)
@@ -532,4 +598,4 @@ Not affiliated with, endorsed by, or connected to Apple Inc. Apple, macOS, Photo
 
 ---
 
-© 2026 [NM Media](https://navid.media?utm_source=github&utm_medium=readme&utm_campaign=apple-photos-mcp). Made with ❤️ by [Navid Moazzez](https://navid.me?utm_source=github&utm_medium=readme&utm_campaign=apple-photos-mcp).
+© 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).

package/SKILL.md

@@ -152,6 +152,19 @@ photo_info(refs=[...])   # everything about specific items, including OCR text
 doctor()                 # run this first whenever anything misbehaves
 ```
 
+## Exit codes
+
+A script branches on the number, not the message:
+
+| Code | Means |
+|---|---|
+| 0 | it worked |
+| 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 |
+| 5 | the engine or Photos failed |
+| 10 | the engine could not start: install uv, or set `APPLE_PHOTOS_PYTHON` |
+
 ## When something breaks
 
 | Symptom | Cause | Fix |

package/lib/bridge.d.ts

@@ -14,30 +14,41 @@
  * 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, rather than a bespoke JSON protocol. That means the Python needs no
- * changes at all, and there is exactly one implementation of every tool.
+ * client, 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. */
+export type ContentPart = {
+    type: string;
+    text?: string;
+    data?: string;
+    mimeType?: string;
+};
 export type BridgeResult = {
+    /** Every part, untouched. Images must survive: look_at_photos returns them. */
+    content: ContentPart[];
+    /** The text parts joined, for the common case of a JSON payload. */
     text: string;
     isError: boolean;
 };
-/**
- * One long-lived connection to the Python server.
- *
- * Spawning per call would pay `uv`'s dependency resolution and a Photos library
- * scan every time, which is seconds each. The process is started on first use
- * and reused.
- */
 export declare class PythonBridge {
     private readonly config;
     private client?;
     private starting?;
+    /** The tail of the engine's stderr, so a failure can say what actually went wrong. */
+    private stderrTail;
     constructor(config: Config);
     private connect;
-    /** Call one Python tool and return its text payload. */
-    call(tool: string, args: Record<string, unknown>): Promise<BridgeResult>;
-    /** What the Python server says it offers. Used by `doctor` to prove the two agree. */
+    /**
+     * 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.
+     */
+    call(tool: string, args: Record<string, unknown>, timeoutMs?: number): Promise<BridgeResult>;
+    /** What the Python server says it offers, for checking the two lists agree. */
     listTools(): Promise<string[]>;
     close(): Promise<void>;
 }

package/lib/bridge.js

@@ -14,23 +14,18 @@
  * 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, rather than a bespoke JSON protocol. That means the Python needs no
- * changes at all, and there is exactly one implementation of every tool.
+ * client, 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 { BridgeError } from "./errors.js";
-/**
- * One long-lived connection to the Python server.
- *
- * Spawning per call would pay `uv`'s dependency resolution and a Photos library
- * scan every time, which is seconds each. The process is started on first use
- * and reused.
- */
 export class PythonBridge {
     config;
     client;
     starting;
+    /** The tail of the engine's stderr, so a failure can say what actually went wrong. */
+    stderrTail = "";
     constructor(config) {
         this.config = config;
     }
@@ -41,21 +36,38 @@ export class PythonBridge {
             return this.starting;
         this.starting = (async () => {
             const client = new Client({ name: "apple-photos-cli", version: "1.0.0" }, { capabilities: {} });
-            // `uv run` resolves osxphotos and photoscript on first use and caches
-            // them, so the reader needs neither a virtualenv nor a pip install.
             const transport = new StdioClientTransport({
                 command: this.config.pythonCommand,
                 args: this.config.pythonArgs,
                 env: { ...process.env, ...this.config.pythonEnv },
                 stderr: "pipe",
             });
+            // 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 {
-                await client.connect(transport);
+                // 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 });
             }
             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. ` +
-                    `Underlying error: ${error.message}`);
+                    `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;
@@ -67,25 +79,40 @@ export class PythonBridge {
             this.starting = undefined;
         }
     }
-    /** Call one Python tool and return its text payload. */
-    async call(tool, args) {
+    /**
+     * 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.
+     */
+    async call(tool, args, timeoutMs) {
         const client = await this.connect();
-        const result = (await client.callTool({ name: tool, arguments: args }));
-        const text = (result.content ?? [])
+        let result;
+        try {
+            result = (await client.callTool({ name: tool, arguments: args }, undefined, { timeout: 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 text = content
             .filter((part) => part.type === "text" && typeof part.text === "string")
             .map((part) => part.text)
             .join("\n");
-        return { text, isError: result.isError === true };
+        return { content, text, isError: result.isError === true };
     }
-    /** What the Python server says it offers. Used by `doctor` to prove the two agree. */
+    /** 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();
         return tools.map((tool) => tool.name);
     }
     async close() {
-        await this.client?.close().catch(() => undefined);
+        this.starting = undefined;
+        const client = this.client;
         this.client = undefined;
+        await client?.close().catch(() => undefined);
     }
 }
 //# sourceMappingURL=bridge.js.map

package/lib/bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src-ts/bridge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src-ts/bridge.ts"],"names":[],"mappings":"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"}

package/lib/cli.d.ts

@@ -28,16 +28,7 @@ type Flag = {
     help: string;
 };
 export declare function flagsFor(shape: ZodRawShape): Flag[];
-/**
- * Midjourney's own parameter spellings, accepted as flags.
- *
- * The schema names things in full because a tool description is read by a model
- * that has never seen a Midjourney prompt. A person at a terminal has, and they
- * will type `--ar 16:9`, because that is what the parameter is called
- * everywhere Midjourney documents it. Refusing the name the whole ecosystem
- * uses, to protect a naming convention nobody outside this repo can see, would
- * be the wrong trade.
- */
+/** Shorthands for this repo's arguments. Kept small on purpose. */
 export declare const FLAG_ALIASES: Record<string, string>;
 /**
  * Parse argv against a tool's flags.
@@ -67,11 +58,12 @@ export declare function emitError(error: unknown): void;
  */
 export declare function binName(): string;
 /**
- * Words people use mapped onto words the tools use.
+ * Words people use mapped onto words these tools use.
  *
- * Without this, "make a picture" matches nothing, because every tool says
- * "generate" and "image". A lookup that only works when you already know the
- * vocabulary is not a lookup.
+ * Without this, "save my photos to disk" matches four browsing tools and never
+ * export-originals, because nothing in that phrase appears in its name or
+ * description. Every target below has to be vocabulary a tool actually
+ * contains; a test asserts it.
  */
 export declare const SYNONYMS: Record<string, string[]>;
 /**
@@ -87,6 +79,27 @@ export declare function whichCommand(query: string): {
     tool: AnyToolSpec;
     score: number;
 }[];
+/**
+ * The house contract, so a script branches on the number the same way for
+ * every one of these CLIs: 0 ok, 2 usage or a refused write, 3 not found,
+ * 4 access refused, 5 the engine failed, 10 nothing set up yet.
+ */
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly usage: 2;
+    readonly notFound: 3;
+    readonly auth: 4;
+    readonly api: 5;
+    readonly rateLimited: 7;
+    readonly config: 10;
+};
+/**
+ * There is no account here, so "auth" is macOS refusing access: Full Disk
+ * Access for the library, or Automation for Photos itself. The engine reports
+ * its failures as text, so its words decide once the class has said what it
+ * can.
+ */
+export declare function exitCodeFor(error: unknown): number;
 export declare function isCliCommand(argv: string[]): boolean;
 export declare function runCli(argv: string[]): Promise<number>;
 export {};