@thenavidm/apple-photos-mcp-cli 1.0.0 → 1.0.2

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":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAGjF,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI1C;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IACN,MAAM,CAAS;IACxB,MAAM,CAAU;IAChB,QAAQ,CAAmB;IAEnC,YAAY,MAAc;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAEO,KAAK,CAAC,OAAO;QACnB,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC;QACpC,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC;QAExC,IAAI,CAAC,QAAQ,GAAG,CAAC,KAAK,IAAI,EAAE;YAC1B,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,OAAO,EAAE,EAC9C,EAAE,YAAY,EAAE,EAAE,EAAE,CACrB,CAAC;YAEF,sEAAsE;YACtE,oEAAoE;YACpE,MAAM,SAAS,GAAG,IAAI,oBAAoB,CAAC;gBACzC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,aAAa;gBAClC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU;gBAC5B,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,EAA4B;gBAC3E,MAAM,EAAE,MAAM;aACf,CAAC,CAAC;YAEH,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAClC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,WAAW,CACnB,4CAA4C,IAAI,CAAC,MAAM,CAAC,aAAa,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM;oBAC7G,qHAAqH;oBACrH,qBAAsB,KAAe,CAAC,OAAO,EAAE,CAClD,CAAC;YACJ,CAAC;YAED,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;YACrB,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC,EAAE,CAAC;QAEL,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC;QAC7B,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,wDAAwD;IACxD,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,IAA6B;QACpD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QAEpC,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAGrE,CAAC;QAEF,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;aAChC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;aACvE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAc,CAAC;aAClC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;IACpD,CAAC;IAED,sFAAsF;IACtF,KAAK,CAAC,SAAS;QACb,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACpC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC;QAC3C,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IAC1B,CAAC;CACF"}

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 {};