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

package/README.md

@@ -1,14 +1,17 @@
 <img src="https://cdn.navid.media/connectors/apple-photos-icon.png" alt="Apple Photos" width="88">
 
-# Apple Photos MCP
+# Apple Photos MCP + CLI
 
-[![Stars](https://img.shields.io/github/stars/navidmoazzez/apple-photos-mcp?style=flat&logo=github&label=Stars)](https://github.com/navidmoazzez/apple-photos-mcp)
+[![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)
 [![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)
 
-Give any AI agent real access to your own Apple Photos library, so it can find, see, organize and export your photos instead of guessing.
+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.
+
+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).
 
@@ -16,12 +19,54 @@ Built and maintained by [Navid Moazzez](https://navid.me?utm_source=github&utm_m
 
 Everything runs on your Mac. There is no backend.
 
+## Two ways to use it
+
+### Command line
+
+`apple-photos-cli` in your terminal, for scripting, cron, pipes, or a quick
+question without opening anything:
+
+```bash
+apple-photos-cli                                    # every command, one line each
+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 <command> --help                   # what any command takes
+```
+
+`--json` gives JSON, `--compact` puts it on one line, `--select total,videos`
+keeps only the fields you name, and errors are JSON on stderr whichever you
+pick. `--confirm` is the shell spelling of the confirmation archiving requires.
+
+### MCP server, for AI agents
+
+`apple-photos-mcp` is what Claude Code, Claude Desktop, Cursor and the rest
+launch. You never run it by hand:
+
+```bash
+claude mcp add apple-photos -- npx -y @thenavidm/apple-photos-mcp-cli@latest
+```
+
+Then just ask: _"which receipts do I have from Vietnam?"_
+
+### Which one
+
+| What you are doing | Use |
+|---|---|
+| Inside a conversation with an agent | MCP |
+| Piping, scripting, cron, CI | CLI |
+| A one-off question in a terminal | CLI |
+
+They are the same program reading the same tool definitions, so anything one
+can do, the other can. A test asserts they cannot drift.
+
 ## Contents
 
 | | Section | |
 |---|---|---|
 | 1 | [What you can ask it](#1-what-you-can-ask-it-) | Real prompts, not features |
-| 2 | [Quick install](#2-quick-install-) | The package only |
+| 2 | [Quick install](#2-quick-install-) | One command, no credential |
 | 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` |
@@ -49,21 +94,26 @@ The first one is the point. Your library already knows what is in every photo, b
 
 ## 2. Quick install ⚡
 
-macOS, and Python 3.11 or newer.
-
-> **Not on PyPI yet.** Install it from GitHub until it is published. The command below works today.
+macOS, and Node 20 or newer.
 
 ```bash
-uvx --from git+https://github.com/navidmoazzez/apple-photos-mcp apple-photos-mcp --version
+npx -y @thenavidm/apple-photos-mcp-cli@latest --version
 ```
 
-If you do not have [uv](https://docs.astral.sh/uv/), which is the Python equivalent of `npx`:
+That is the whole install. `npx` fetches it on demand, so there is nothing to
+update later.
+
+The engine underneath is Python, because `osxphotos` and `photoscript` are the
+only libraries that can read a Photos library and both are Python-only. You do
+not install them: [uv](https://docs.astral.sh/uv/) fetches them on first run and
+caches them. If you do not have uv:
 
 ```bash
 curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
-That completes the install. No account, no API key, no credential.
+No account, no API key, no credential. macOS will ask for permission the first
+time something reads the library.
 
 ## 3. Setup 🔑
 
@@ -107,7 +157,7 @@ Set up apple-photos-mcp for me.
 
 ```bash
 claude mcp add apple-photos -s user \
-  -- uvx --from git+https://github.com/navidmoazzez/apple-photos-mcp apple-photos-mcp
+  -- npx -y @thenavidm/apple-photos-mcp-cli@latest
 ```
 
 `-s user` makes it available in every project rather than just the current one.
@@ -138,8 +188,8 @@ Apple Photos only exists on macOS, so there is no Windows or Linux path here.
 {
   "mcpServers": {
     "apple-photos": {
-      "command": "uvx",
-      "args": ["--from", "git+https://github.com/navidmoazzez/apple-photos-mcp", "apple-photos-mcp"]
+      "command": "npx",
+      "args": ["-y", "@thenavidm/apple-photos-mcp-cli@latest"]
     }
   }
 }
@@ -178,7 +228,7 @@ For one project instead of globally, use `.cursor/mcp.json` in that project.
     "apple-photos": {
       "type": "stdio",
       "command": "uvx",
-      "args": ["--from", "git+https://github.com/navidmoazzez/apple-photos-mcp", "apple-photos-mcp"]
+      "args": ["--from", "git+https://github.com/navidmoazzez/apple-photos-mcp-cli", "apple-photos-mcp"]
     }
   }
 }
@@ -193,7 +243,7 @@ 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", "apple-photos-mcp"]
+args = ["--from", "git+https://github.com/navidmoazzez/apple-photos-mcp-cli", "apple-photos-mcp"]
 ```
 
 ### Gemini CLI
@@ -215,7 +265,7 @@ That relay is not included here. It is a separate deployment with its own hostin
 ## 5. Check it worked 🩺
 
 ```bash
-uvx --from git+https://github.com/navidmoazzez/apple-photos-mcp apple-photos-mcp doctor
+npx -y @thenavidm/apple-photos-mcp-cli@latest doctor
 ```
 
 Or just ask your agent: **"run doctor on apple photos"**.
@@ -448,7 +498,7 @@ 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/issues) and I will help.
+Run into a problem or have a question? [Open an issue](https://github.com/navidmoazzez/apple-photos-mcp-cli/issues) and I will help.
 
 ## About the author
 

package/SKILL.md

@@ -16,6 +16,22 @@ description: >
 The library is read directly from disk on this Mac. Nothing is uploaded, and
 nothing here can permanently delete a photo.
 
+
+## Two surfaces, same tools
+
+The MCP server is for work inside a conversation. The CLI is for scripting,
+piping and one-off questions, and costs no context until it is called.
+
+```bash
+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 <command> --help
+```
+
+The command is the tool name with dashes. `--select total,videos` trims the
+output, which matters on a library this size.
+
 ## The one thing that matters
 
 Search returns candidates. It does not return answers.

package/lib/bridge.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The bridge to the Python engine.
+ *
+ * Apple Photos is the one case the house standard carves out for Python: the
+ * only libraries that can read a Photos library are `osxphotos` and
+ * `photoscript`, both Python-only, both macOS-only, both pulling in pyobjc.
+ * Reimplementing them in TypeScript would mean reimplementing Apple's private
+ * SQLite schema, which is not a thing to own.
+ *
+ * So the engine stays Python and this layer wraps it, the way
+ * google-workspace-mcp wraps the `gws` binary. What TypeScript buys is the part
+ * Python cost us: `npx` with no toolchain to install first, a CLI generated
+ * 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, rather than a bespoke JSON protocol. That means the Python needs no
+ * changes at all, and there is exactly one implementation of every tool.
+ */
+import type { Config } from "./config.js";
+export type BridgeResult = {
+    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?;
+    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. */
+    listTools(): Promise<string[]>;
+    close(): Promise<void>;
+}

package/lib/bridge.js

@@ -0,0 +1,91 @@
+/**
+ * The bridge to the Python engine.
+ *
+ * Apple Photos is the one case the house standard carves out for Python: the
+ * only libraries that can read a Photos library are `osxphotos` and
+ * `photoscript`, both Python-only, both macOS-only, both pulling in pyobjc.
+ * Reimplementing them in TypeScript would mean reimplementing Apple's private
+ * SQLite schema, which is not a thing to own.
+ *
+ * So the engine stays Python and this layer wraps it, the way
+ * google-workspace-mcp wraps the `gws` binary. What TypeScript buys is the part
+ * Python cost us: `npx` with no toolchain to install first, a CLI generated
+ * 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, rather than a bespoke JSON protocol. That means the Python needs no
+ * changes at all, and there is exactly 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;
+    constructor(config) {
+        this.config = config;
+    }
+    async connect() {
+        if (this.client)
+            return this.client;
+        if (this.starting)
+            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",
+            });
+            try {
+                await client.connect(transport);
+            }
+            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}`);
+            }
+            this.client = client;
+            return client;
+        })();
+        try {
+            return await this.starting;
+        }
+        finally {
+            this.starting = undefined;
+        }
+    }
+    /** Call one Python tool and return its text payload. */
+    async call(tool, args) {
+        const client = await this.connect();
+        const result = (await client.callTool({ name: tool, arguments: args }));
+        const text = (result.content ?? [])
+            .filter((part) => part.type === "text" && typeof part.text === "string")
+            .map((part) => part.text)
+            .join("\n");
+        return { text, isError: result.isError === true };
+    }
+    /** What the Python server says it offers. Used by `doctor` to prove the two 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.client = undefined;
+    }
+}
+//# sourceMappingURL=bridge.js.map

package/lib/bridge.js.map

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

package/lib/cli.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The CLI adapter.
+ *
+ * `register()` in tools/kit.ts turns a `ToolSpec` into an MCP tool. This turns
+ * the same spec into a shell command, from the same `ALL_TOOLS` array, through
+ * the same handler and the same `WriteGuard`. Nothing is described twice, so a
+ * tool added tomorrow is a command tomorrow and the two surfaces cannot drift.
+ *
+ * The command IS the tool name. `submit_imagine` runs as `submit-imagine`, and
+ * the underscore form works too. Inventing a prettier command tree would mean a
+ * hand-written mapping, which is exactly the drift this avoids, and it would
+ * force anyone reading the SKILL.md to learn two vocabularies for one action.
+ *
+ * Zod is the only schema: every flag, its placeholder, its help text and its
+ * validation come from the shape the MCP tool already declares.
+ */
+import { type ZodRawShape } from "zod";
+import { type AnyToolSpec } from "./tools/kit.js";
+/** How a value reaches the parser, once the Zod wrappers are peeled off. */
+type FlagKind = "string" | "number" | "boolean" | "enum" | "json";
+type Flag = {
+    key: string;
+    flag: string;
+    kind: FlagKind;
+    required: boolean;
+    repeatable: boolean;
+    choices?: string[];
+    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.
+ */
+export declare const FLAG_ALIASES: Record<string, string>;
+/**
+ * Parse argv against a tool's flags.
+ *
+ * Zod does the real validation afterwards, so this only has to get values into
+ * the right JavaScript types and catch the mistakes Zod would otherwise report
+ * in terms of a schema the person at the terminal never sees.
+ */
+export declare function parseArgs(argv: string[], flags: Flag[]): Record<string, unknown>;
+/**
+ * Keep only the named fields.
+ *
+ * These endpoints are verbose: one explore page is tens of kilobytes of JSON,
+ * most of it layout hints. An agent piping that into its own context pays for
+ * every byte. `--select id,status,images` cuts it to what was asked for.
+ * Dotted paths descend, and arrays are traversed element-wise.
+ */
+export declare function selectFields(data: unknown, paths: string[]): unknown;
+/** Errors are JSON on stderr, always, so a caller parses one shape. */
+export declare function emitError(error: unknown): void;
+/**
+ * The name this was invoked as, so examples are copy-pasteable.
+ *
+ * The package puts two binaries on the same file. Printing `apple-photos-mcp` at
+ * someone who typed `apple-photos-cli` hands them a command that works but is not
+ * the one in their fingers.
+ */
+export declare function binName(): string;
+/**
+ * Words people use mapped onto words the 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.
+ */
+export declare const SYNONYMS: Record<string, string[]>;
+/**
+ * Resolve a capability described in words to the command that does it.
+ *
+ * An agent that knows what it wants but not what this tool calls it would
+ * otherwise read the full tool list to find out, which is the cost the CLI
+ * exists to avoid. Scoring is deliberately dumb: name and title carry the most
+ * weight, because a tool called `download_job` should win "download my images"
+ * without any cleverness.
+ */
+export declare function whichCommand(query: string): {
+    tool: AnyToolSpec;
+    score: number;
+}[];
+export declare function isCliCommand(argv: string[]): boolean;
+export declare function runCli(argv: string[]): Promise<number>;
+export {};