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

package/lib/config.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Everything read from the environment, in one place.
+ *
+ * There are no credentials here and there is nothing to configure to get
+ * started: the library is on this Mac and macOS decides who may read it. The
+ * only real setting is how to start Python.
+ */
+export type Config = {
+    pythonCommand: string;
+    pythonArgs: string[];
+    pythonEnv: Record<string, string>;
+    readOnly: boolean;
+    allowDestructive: boolean;
+    auditPath?: string;
+    exportDir?: string;
+};
+export declare function loadConfig(): Config;
+/** Every variable the code reads, so --help, the README and the tests agree. */
+export declare const ENV_VARS: readonly ["APPLE_PHOTOS_PYTHON", "APPLE_PHOTOS_PYTHONPATH", "APPLE_PHOTOS_READ_ONLY", "APPLE_PHOTOS_ALLOW_DESTRUCTIVE", "APPLE_PHOTOS_AUDIT_LOG", "APPLE_PHOTOS_EXPORT_DIR"];

package/lib/config.js

@@ -0,0 +1,58 @@
+/**
+ * Everything read from the environment, in one place.
+ *
+ * There are no credentials here and there is nothing to configure to get
+ * started: the library is on this Mac and macOS decides who may read it. The
+ * only real setting is how to start Python.
+ */
+import { fileURLToPath } from "node:url";
+function bool(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === "")
+        return fallback;
+    return !["0", "false", "no", "off"].includes(raw.trim().toLowerCase());
+}
+function str(name) {
+    const raw = process.env[name];
+    return raw && raw.trim() ? raw.trim() : undefined;
+}
+/**
+ * Where the Python engine lives, resolved from this file rather than the
+ * working directory.
+ *
+ * `src` relative to CWD works when you run from a clone and breaks everywhere
+ * else, which is every `npx` install: the engine ships inside the package and
+ * the caller is in their own project. dist/ sits one level under the package
+ * root, so the engine is always ../src from here.
+ */
+function packagedEnginePath() {
+    return fileURLToPath(new URL("../src", import.meta.url));
+}
+export function loadConfig() {
+    // `uv run --with ...` needs no virtualenv and caches after the first run, so
+    // a reader with only Node installed still gets a working server.
+    const explicit = str("APPLE_PHOTOS_PYTHON");
+    const pythonCommand = explicit ?? "uv";
+    const pythonArgs = explicit
+        ? ["-m", "apple_photos_mcp"]
+        : ["run", "--with", "osxphotos", "--with", "photoscript", "--with", "mcp", "python3", "-m", "apple_photos_mcp"];
+    return {
+        pythonCommand,
+        pythonArgs,
+        pythonEnv: { PYTHONPATH: str("APPLE_PHOTOS_PYTHONPATH") ?? packagedEnginePath() },
+        readOnly: bool("APPLE_PHOTOS_READ_ONLY", false),
+        allowDestructive: bool("APPLE_PHOTOS_ALLOW_DESTRUCTIVE", true),
+        auditPath: str("APPLE_PHOTOS_AUDIT_LOG"),
+        exportDir: str("APPLE_PHOTOS_EXPORT_DIR"),
+    };
+}
+/** Every variable the code reads, so --help, the README and the tests agree. */
+export const ENV_VARS = [
+    "APPLE_PHOTOS_PYTHON",
+    "APPLE_PHOTOS_PYTHONPATH",
+    "APPLE_PHOTOS_READ_ONLY",
+    "APPLE_PHOTOS_ALLOW_DESTRUCTIVE",
+    "APPLE_PHOTOS_AUDIT_LOG",
+    "APPLE_PHOTOS_EXPORT_DIR",
+];
+//# sourceMappingURL=config.js.map

package/lib/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src-ts/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAYzC,SAAS,IAAI,CAAC,IAAY,EAAE,QAAiB;IAC3C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC5D,OAAO,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,SAAS,GAAG,CAAC,IAAY;IACvB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,kBAAkB;IACzB,OAAO,aAAa,CAAC,IAAI,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,6EAA6E;IAC7E,iEAAiE;IACjE,MAAM,QAAQ,GAAG,GAAG,CAAC,qBAAqB,CAAC,CAAC;IAC5C,MAAM,aAAa,GAAG,QAAQ,IAAI,IAAI,CAAC;IACvC,MAAM,UAAU,GAAG,QAAQ;QACzB,CAAC,CAAC,CAAC,IAAI,EAAE,kBAAkB,CAAC;QAC5B,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,kBAAkB,CAAC,CAAC;IAElH,OAAO;QACL,aAAa;QACb,UAAU;QACV,SAAS,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,yBAAyB,CAAC,IAAI,kBAAkB,EAAE,EAAE;QACjF,QAAQ,EAAE,IAAI,CAAC,wBAAwB,EAAE,KAAK,CAAC;QAC/C,gBAAgB,EAAE,IAAI,CAAC,gCAAgC,EAAE,IAAI,CAAC;QAC9D,SAAS,EAAE,GAAG,CAAC,wBAAwB,CAAC;QACxC,SAAS,EAAE,GAAG,CAAC,yBAAyB,CAAC;KAC1C,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,qBAAqB;IACrB,yBAAyB;IACzB,wBAAwB;IACxB,gCAAgC;IAChC,wBAAwB;IACxB,yBAAyB;CACjB,CAAC"}

package/lib/errors.d.ts

@@ -0,0 +1,15 @@
+/** Typed failures, each carrying the fix rather than just the symptom. */
+export declare class PhotosError extends Error {
+    readonly detail: string;
+    constructor(message: string, detail?: string);
+    toJSON(): Record<string, unknown>;
+}
+/** The Python engine could not be started. Nothing reached the library. */
+export declare class BridgeError extends PhotosError {
+}
+/** The engine ran but refused the request. */
+export declare class ToolError extends PhotosError {
+}
+/** Writes are off, or a destructive tool was called without confirmation. */
+export declare class WriteBlockedError extends PhotosError {
+}

package/lib/errors.js

@@ -0,0 +1,22 @@
+/** Typed failures, each carrying the fix rather than just the symptom. */
+export class PhotosError extends Error {
+    detail;
+    constructor(message, detail = "") {
+        super(message);
+        this.name = new.target.name;
+        this.detail = detail;
+    }
+    toJSON() {
+        return { error: this.message, type: this.name, ...(this.detail ? { detail: this.detail.slice(0, 500) } : {}) };
+    }
+}
+/** The Python engine could not be started. Nothing reached the library. */
+export class BridgeError extends PhotosError {
+}
+/** The engine ran but refused the request. */
+export class ToolError extends PhotosError {
+}
+/** Writes are off, or a destructive tool was called without confirmation. */
+export class WriteBlockedError extends PhotosError {
+}
+//# sourceMappingURL=errors.js.map

package/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src-ts/errors.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAE1E,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,MAAM,CAAS;IAExB,YAAY,OAAe,EAAE,MAAM,GAAG,EAAE;QACtC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,MAAM;QACJ,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACjH,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,OAAO,WAAY,SAAQ,WAAW;CAAG;AAE/C,8CAA8C;AAC9C,MAAM,OAAO,SAAU,SAAQ,WAAW;CAAG;AAE7C,6EAA6E;AAC7E,MAAM,OAAO,iBAAkB,SAAQ,WAAW;CAAG"}

package/lib/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Entry point.
+ *
+ * `apple-photos-mcp`          stdio, which is what MCP clients launch
+ * `apple-photos-cli <tool>`   run one tool from the shell
+ * `apple-photos-cli doctor`   check the setup and say what is wrong
+ *
+ * The shell surface is generated from the same `ALL_TOOLS` array the server
+ * registers, so every tool is a command and neither surface can drift.
+ */
+export {};

package/lib/index.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * Entry point.
+ *
+ * `apple-photos-mcp`          stdio, which is what MCP clients launch
+ * `apple-photos-cli <tool>`   run one tool from the shell
+ * `apple-photos-cli doctor`   check the setup and say what is wrong
+ *
+ * The shell surface is generated from the same `ALL_TOOLS` array the server
+ * registers, so every tool is a command and neither surface can drift.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { buildServer, VERSION } from "./server.js";
+import { isCliCommand, runCli } from "./cli.js";
+const HELP = `apple-photos-mcp ${VERSION}
+
+  apple-photos-mcp                 Run over stdio. This is what an MCP client launches.
+  apple-photos-cli tools           List every tool as a shell command.
+  apple-photos-cli <tool> [flags]  Run one tool. Same names as the MCP surface.
+  apple-photos-cli <tool> --help   What that tool takes.
+  apple-photos-cli doctor          Check the setup and report what is wrong.
+  apple-photos-mcp --version       Print the version.
+
+  Every command prints JSON on --json, trims it with --select, and reports
+  errors as JSON on stderr.
+
+There are no credentials. The library is on this Mac and macOS decides who may
+read it; the first run will ask for permission. Nothing is uploaded anywhere.
+
+Engine:
+  APPLE_PHOTOS_PYTHON              a Python with osxphotos and photoscript.
+                                   Defaults to uv, which fetches them on demand.
+  APPLE_PHOTOS_PYTHONPATH          where the engine package lives, default src
+
+Behaviour:
+  APPLE_PHOTOS_EXPORT_DIR          where export_originals writes by default
+
+Safety:
+  APPLE_PHOTOS_READ_ONLY=1         hide everything that is not a read
+  APPLE_PHOTOS_ALLOW_DESTRUCTIVE=0 keep reads and edits, block archiving
+  APPLE_PHOTOS_AUDIT_LOG           append-only log of every attempted change
+
+https://github.com/navidmoazzez/apple-photos-mcp
+`;
+function invokedAsCli() {
+    const name = (process.argv[1] ?? "").split("/").pop() ?? "";
+    return name.startsWith("apple-photos-cli");
+}
+/**
+ * This only runs on a Mac, but the package must still install anywhere.
+ *
+ * An `"os": ["darwin"]` field in package.json looks right and breaks the thing
+ * that matters: the HQ connector imports ALL_TOOLS for its schemas on a Linux
+ * builder, never executing a tool, and npm refuses to install at all. The
+ * pyproject next door already made this call for the same reason — its comment
+ * notes that platform markers make `pip install` fail on Linux "instead of
+ * installing and then telling the user this server needs a Mac".
+ *
+ * So: install anywhere, refuse to run anywhere but macOS, and say why.
+ */
+function requireMac() {
+    if (process.platform === "darwin")
+        return;
+    process.stderr.write(`${JSON.stringify({
+        error: "Apple Photos only exists on macOS, so this server cannot run on " +
+            `${process.platform}. It installs anywhere because the tool definitions are ` +
+            "read by other tooling, but reaching a library needs a Mac.",
+    }, null, 2)}\n`);
+    process.exit(1);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const command = argv[0];
+    if (argv.includes("--version") || argv.includes("-v")) {
+        process.stdout.write(`${VERSION}\n`);
+        return;
+    }
+    requireMac();
+    if (invokedAsCli() && argv.length === 0) {
+        process.exitCode = await runCli(["tools"]);
+        return;
+    }
+    if (isCliCommand(argv)) {
+        process.exitCode = await runCli(argv);
+        return;
+    }
+    // Neither binary takes a positional argument that is not a command, so a
+    // stray word is a typo rather than a reason to sit waiting on stdin.
+    if (command !== undefined && !command.startsWith("-") && command !== "help") {
+        process.stderr.write(`${JSON.stringify({ error: `Unknown command '${command}'. Run \`apple-photos-cli\` to list them.` }, null, 2)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (argv.includes("--help") || argv.includes("-h") || command === "help") {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (argv.includes("--version") || argv.includes("-v")) {
+        process.stdout.write(`${VERSION}\n`);
+        return;
+    }
+    const built = buildServer(loadConfig());
+    const transport = new StdioServerTransport();
+    await built.server.connect(transport);
+    const shutdown = async () => {
+        await built.bridge.close();
+        process.exit(0);
+    };
+    process.on("SIGTERM", () => void shutdown());
+    process.on("SIGINT", () => void shutdown());
+}
+main().catch((error) => {
+    process.stderr.write(`[apple-photos-mcp] ${error.message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

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

package/lib/safety.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Decides whether a change is allowed to reach the library.
+ *
+ * The hazard here is not publishing, it is losing something. Nothing in a
+ * Photos library is public, but a wrong `archive_photos` moves someone's own
+ * pictures out of view, and macOS gives this process no way to put them back.
+ *
+ * So archiving asks. Favouriting, titling, keywording and adding to an album do
+ * not: each is one click to undo in Photos, and confirming everything trains
+ * the reflex that makes the confirmation on a real removal worthless.
+ */
+import type { Config } from "./config.js";
+export type Risk = "read" | "write" | "destructive";
+export type Surface = "mcp" | "cli";
+export declare function needsConfirm(risk: Risk): boolean;
+export declare class WriteGuard {
+    private readonly config;
+    private readonly surface;
+    constructor(config: Config, surface?: Surface);
+    private get confirmFlag();
+    get readOnly(): boolean;
+    check(tool: string, risk: Risk, confirm: boolean | undefined, summary: string): void;
+    private audit;
+}
+export declare function annotationsFor(risk: Risk, options?: {
+    idempotent?: boolean;
+}): Record<string, boolean>;

package/lib/safety.js

@@ -0,0 +1,70 @@
+/**
+ * Decides whether a change is allowed to reach the library.
+ *
+ * The hazard here is not publishing, it is losing something. Nothing in a
+ * Photos library is public, but a wrong `archive_photos` moves someone's own
+ * pictures out of view, and macOS gives this process no way to put them back.
+ *
+ * So archiving asks. Favouriting, titling, keywording and adding to an album do
+ * not: each is one click to undo in Photos, and confirming everything trains
+ * the reflex that makes the confirmation on a real removal worthless.
+ */
+import { appendFileSync } from "node:fs";
+import { WriteBlockedError } from "./errors.js";
+export function needsConfirm(risk) {
+    return risk === "destructive";
+}
+export class WriteGuard {
+    config;
+    surface;
+    constructor(config, surface = "mcp") {
+        this.config = config;
+        this.surface = surface;
+    }
+    get confirmFlag() {
+        return this.surface === "cli" ? "--confirm" : "confirm: true";
+    }
+    get readOnly() {
+        return this.config.readOnly;
+    }
+    check(tool, risk, confirm, summary) {
+        if (risk === "read")
+            return;
+        if (this.config.readOnly) {
+            this.audit(tool, risk, summary, "blocked: read-only");
+            throw new WriteBlockedError(`${tool} is unavailable: this server is running with APPLE_PHOTOS_READ_ONLY=1.`);
+        }
+        if (needsConfirm(risk)) {
+            if (!this.config.allowDestructive) {
+                this.audit(tool, risk, summary, "blocked: destructive disabled");
+                throw new WriteBlockedError(`${tool} is unavailable: this server is running with APPLE_PHOTOS_ALLOW_DESTRUCTIVE=0.`);
+            }
+            if (confirm !== true) {
+                this.audit(tool, risk, summary, "blocked: no confirm");
+                throw new WriteBlockedError(`${tool} cannot be undone from here, so it will not run without ${this.confirmFlag}. About to: ${summary}.`);
+            }
+        }
+        this.audit(tool, risk, summary, "allowed");
+    }
+    audit(tool, risk, summary, outcome) {
+        if (!this.config.auditPath)
+            return;
+        const line = JSON.stringify({ at: new Date().toISOString(), surface: this.surface, tool, risk, summary, outcome });
+        try {
+            appendFileSync(this.config.auditPath, `${line}\n`, { mode: 0o600 });
+        }
+        catch {
+            // A failing audit log must never take the tool call down with it.
+        }
+    }
+}
+export function annotationsFor(risk, options = {}) {
+    return {
+        readOnlyHint: risk === "read",
+        destructiveHint: risk === "destructive",
+        idempotentHint: options.idempotent ?? risk === "read",
+        // Everything stays on this Mac: no network, no upload, nothing leaves.
+        openWorldHint: false,
+    };
+}
+//# sourceMappingURL=safety.js.map

package/lib/safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.js","sourceRoot":"","sources":["../src-ts/safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAKhD,MAAM,UAAU,YAAY,CAAC,IAAU;IACrC,OAAO,IAAI,KAAK,aAAa,CAAC;AAChC,CAAC;AAED,MAAM,OAAO,UAAU;IACJ,MAAM,CAAS;IACf,OAAO,CAAU;IAElC,YAAY,MAAc,EAAE,UAAmB,KAAK;QAClD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,IAAY,WAAW;QACrB,OAAO,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,eAAe,CAAC;IAChE,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,IAAY,EAAE,IAAU,EAAE,OAA4B,EAAE,OAAe;QAC3E,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO;QAE5B,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC;YACtD,MAAM,IAAI,iBAAiB,CAAC,GAAG,IAAI,wEAAwE,CAAC,CAAC;QAC/G,CAAC;QAED,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;gBAClC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,+BAA+B,CAAC,CAAC;gBACjE,MAAM,IAAI,iBAAiB,CAAC,GAAG,IAAI,gFAAgF,CAAC,CAAC;YACvH,CAAC;YACD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,qBAAqB,CAAC,CAAC;gBACvD,MAAM,IAAI,iBAAiB,CACzB,GAAG,IAAI,2DAA2D,IAAI,CAAC,WAAW,eAAe,OAAO,GAAG,CAC5G,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IAC7C,CAAC;IAEO,KAAK,CAAC,IAAY,EAAE,IAAU,EAAE,OAAe,EAAE,OAAe;QACtE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS;YAAE,OAAO;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QACnH,IAAI,CAAC;YACH,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,IAAI,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACP,kEAAkE;QACpE,CAAC;IACH,CAAC;CACF;AAED,MAAM,UAAU,cAAc,CAAC,IAAU,EAAE,UAAoC,EAAE;IAC/E,OAAO;QACL,YAAY,EAAE,IAAI,KAAK,MAAM;QAC7B,eAAe,EAAE,IAAI,KAAK,aAAa;QACvC,cAAc,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI,KAAK,MAAM;QACrD,uEAAuE;QACvE,aAAa,EAAE,KAAK;KACrB,CAAC;AACJ,CAAC"}

package/lib/server.d.ts

@@ -0,0 +1,10 @@
+/** Assembles the MCP server: instructions, tools, and the read-only filter. */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { PythonBridge } from "./bridge.js";
+import type { Config } from "./config.js";
+export declare const VERSION: string;
+export type BuiltServer = {
+    server: McpServer;
+    bridge: PythonBridge;
+};
+export declare function buildServer(config: Config): BuiltServer;

package/lib/server.js

@@ -0,0 +1,38 @@
+/** Assembles the MCP server: instructions, tools, and the read-only filter. */
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { PythonBridge } from "./bridge.js";
+import { WriteGuard } from "./safety.js";
+import { ALL_TOOLS } from "./tools/index.js";
+import { register } from "./tools/kit.js";
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+export const VERSION = pkg.version;
+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.`;
+export function buildServer(config) {
+    const server = new McpServer({ name: "apple-photos-mcp", version: VERSION }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    const bridge = new PythonBridge(config);
+    const guard = new WriteGuard(config, "mcp");
+    const context = { bridge, config, guard };
+    // READ_ONLY removes writes from the list rather than failing them when
+    // called. A model cannot call a tool it cannot see.
+    const tools = ALL_TOOLS.filter((tool) => !config.readOnly || tool.risk === "read");
+    for (const tool of tools)
+        register(server, () => context, tool);
+    return { server, bridge };
+}
+//# sourceMappingURL=server.js.map

package/lib/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src-ts/server.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAoB,MAAM,gBAAgB,CAAC;AAE5D,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAC9D,MAAM,CAAC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;AAEnC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;sLAciK,CAAC;AAIvL,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,OAAO,EAAE,EAC9C,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,YAAY,EAAE,YAAY,EAAE,CAC5D,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAEvD,uEAAuE;IACvE,oDAAoD;IACpD,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;IACnF,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAEhE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC"}

package/lib/tools/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Every tool, mirroring the Python engine exactly.
+ *
+ * The names and arguments match `src/apple_photos_mcp/server.py` one for one,
+ * because this layer proxies rather than reimplements. A test asserts the two
+ * lists agree, so a tool added to Python and forgotten here fails the suite
+ * rather than quietly going missing from the CLI and from HQ.
+ */
+import { z } from "zod";
+import { type AnyToolSpec } from "./kit.js";
+export declare const readTools: (import("./kit.js").ToolSpec<{
+    query: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    kind: z.ZodOptional<z.ZodEnum<["photo", "video"]>>;
+    person: z.ZodOptional<z.ZodString>;
+    album: z.ZodOptional<z.ZodString>;
+    place: z.ZodOptional<z.ZodString>;
+    year: z.ZodOptional<z.ZodNumber>;
+    date_from: z.ZodOptional<z.ZodString>;
+    date_to: z.ZodOptional<z.ZodString>;
+    favorites_only: z.ZodOptional<z.ZodBoolean>;
+    screenshots: z.ZodOptional<z.ZodEnum<["include", "exclude", "only"]>>;
+    include_hidden: z.ZodOptional<z.ZodBoolean>;
+}> | import("./kit.js").ToolSpec<{
+    refs: z.ZodArray<z.ZodString, "many">;
+    size: z.ZodOptional<z.ZodNumber>;
+}> | import("./kit.js").ToolSpec<{
+    refs: z.ZodArray<z.ZodString, "many">;
+}> | import("./kit.js").ToolSpec<{}> | import("./kit.js").ToolSpec<{
+    starts_with: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}>)[];
+export declare const writeTools: (import("./kit.js").ToolSpec<{
+    refs: z.ZodArray<z.ZodString, "many">;
+    directory: z.ZodOptional<z.ZodString>;
+}> | import("./kit.js").ToolSpec<{
+    refs: z.ZodArray<z.ZodString, "many">;
+    favorite: z.ZodOptional<z.ZodBoolean>;
+}> | import("./kit.js").ToolSpec<{
+    ref: z.ZodString;
+    title: z.ZodString;
+}> | import("./kit.js").ToolSpec<{
+    ref: z.ZodString;
+    description: z.ZodString;
+}> | import("./kit.js").ToolSpec<{
+    refs: z.ZodArray<z.ZodString, "many">;
+    keywords: z.ZodArray<z.ZodString, "many">;
+}> | import("./kit.js").ToolSpec<{
+    album: z.ZodString;
+    refs: z.ZodArray<z.ZodString, "many">;
+}> | import("./kit.js").ToolSpec<{
+    confirm: z.ZodOptional<z.ZodBoolean>;
+    refs: z.ZodArray<z.ZodString, "many">;
+}>)[];
+export declare const ALL_TOOLS: AnyToolSpec[];

package/lib/tools/index.js

@@ -0,0 +1,154 @@
+/**
+ * Every tool, mirroring the Python engine exactly.
+ *
+ * The names and arguments match `src/apple_photos_mcp/server.py` one for one,
+ * because this layer proxies rather than reimplements. A test asserts the two
+ * lists agree, so a tool added to Python and forgotten here fails the suite
+ * rather than quietly going missing from the CLI and from HQ.
+ */
+import { z } from "zod";
+import { confirmArg, defineTool } from "./kit.js";
+const REFS = z
+    .array(z.string())
+    .describe("Item refs: Photos uuids from search_photos, or exact filenames like IMG_8402.mov.");
+export const readTools = [
+    defineTool({
+        name: "search_photos",
+        title: "Search the library",
+        description: "Search the entire Photos library through Apple's own on-device index: what a picture looks like, text read inside it, the place, the activity, and any named faces.\n\nThis covers every item, not a sample. `limit` caps what comes back, not what is searched, so the match count is library-wide.\n\nApple's visual vocabulary is a closed list of roughly 1,500 words. A term it has never heard of matches nothing, and no rephrasing of the same idea helps: check `unmatched_terms` in the result, or call list_vocabulary.\n\nSearch returns candidates, not answers. The filenames tell you nothing, so call look_at_photos on the top few before describing them.",
+        schema: {
+            query: z.string().optional().describe("What to look for, in Apple's vocabulary. Empty returns the newest items."),
+            limit: z.number().int().min(1).max(200).optional().describe("How many to return. Defaults to 12."),
+            kind: z.enum(["photo", "video"]).optional().describe("Restrict to photos or videos."),
+            person: z.string().optional().describe("A face the user has named in Photos."),
+            album: z.string().optional().describe("Restrict to one album."),
+            place: z.string().optional().describe("A place name, as Photos records it."),
+            year: z.number().int().optional().describe("Restrict to one year."),
+            date_from: z.string().optional().describe("ISO date, inclusive."),
+            date_to: z.string().optional().describe("ISO date, inclusive."),
+            favorites_only: z.boolean().optional().describe("Only items the user favourited."),
+            screenshots: z
+                .enum(["include", "exclude", "only"])
+                .optional()
+                .describe("Screenshots are a fifth of a typical library and skew any count. Defaults to include."),
+            include_hidden: z.boolean().optional().describe("Include hidden items."),
+        },
+        risk: "read",
+    }),
+    defineTool({
+        name: "look_at_photos",
+        title: "Actually look at photos",
+        description: "Return the images themselves so they can be looked at, rather than reasoned about from filenames and labels.\n\nCall this on the top few results before describing, recommending or choosing between them. Search gives candidates; this is the only way to know what is in them.",
+        schema: {
+            refs: REFS,
+            size: z.number().int().min(64).max(2048).optional().describe("Longest edge in pixels. Defaults to 640."),
+        },
+        risk: "read",
+    }),
+    defineTool({
+        name: "photo_info",
+        title: "Full metadata for specific items",
+        description: "Everything Photos knows about specific items: date, place, camera and lens, dimensions, albums, keywords, faces, and whether the original is on this Mac or still in iCloud.",
+        schema: { refs: REFS },
+        risk: "read",
+    }),
+    defineTool({
+        name: "library_stats",
+        title: "Whole-library totals",
+        description: "Real totals for the whole library in one call: items, photos against videos, favourites, screenshots, how many carry ML labels, text or a place, named people, and every album.\n\nUse this for any question about scale or proportion. Counting by running searches and eyeballing results both costs far more and gets the wrong answer, because it double-counts overlapping terms and cannot see items with no place or label at all.",
+        schema: {},
+        risk: "read",
+    }),
+    defineTool({
+        name: "list_vocabulary",
+        title: "What Apple can actually search for",
+        description: "List the scene labels Apple's index understands. The vocabulary is closed, about 1,500 words, so this is how to find the term that will match rather than guessing synonyms that cannot.",
+        schema: {
+            starts_with: z.string().optional().describe("Filter to labels starting with this."),
+            limit: z.number().int().min(1).max(2000).optional().describe("How many to return. Defaults to 200."),
+        },
+        risk: "read",
+    }),
+    defineTool({
+        name: "doctor",
+        title: "Check the setup",
+        description: "Check that the Photos library is reachable, the engine starts, and this Mac has granted the permissions needed. Run it first when something fails, because a permissions problem and an empty library look identical from a tool call.",
+        schema: {},
+        risk: "read",
+    }),
+];
+export const writeTools = [
+    defineTool({
+        name: "export_originals",
+        title: "Export originals to disk",
+        description: "Export the original files to a folder on this Mac. Most items live in iCloud rather than on the disk, so an export downloads them first and can be slow.\n\nNothing is uploaded anywhere: the files land in a local folder and stay there.",
+        schema: {
+            refs: REFS,
+            directory: z.string().optional().describe("Where to write. Defaults to a dated folder under ~/Downloads."),
+        },
+        risk: "write",
+        idempotent: true,
+        summary: (args) => `export ${args.refs.length} original(s)`,
+    }),
+    defineTool({
+        name: "favorite_photos",
+        title: "Favourite or unfavourite",
+        description: "Mark items as favourites, or clear the mark. One click to undo in Photos, so this does not ask for confirmation.",
+        schema: {
+            refs: REFS,
+            favorite: z.boolean().optional().describe("False to unfavourite. Defaults to true."),
+        },
+        risk: "write",
+        idempotent: true,
+        summary: (args) => `${args.favorite === false ? "unfavourite" : "favourite"} ${args.refs.length} item(s)`,
+    }),
+    defineTool({
+        name: "set_photo_title",
+        title: "Set a title",
+        description: "Set the title on one item, as shown in Photos.",
+        schema: { ref: z.string().describe("One uuid or filename."), title: z.string().describe("The title to set.") },
+        risk: "write",
+        idempotent: true,
+        summary: (args) => `title ${String(args.ref)}`,
+    }),
+    defineTool({
+        name: "set_photo_description",
+        title: "Set a description",
+        description: "Set the description, the caption field Photos shows under an item.",
+        schema: {
+            ref: z.string().describe("One uuid or filename."),
+            description: z.string().describe("The description to set."),
+        },
+        risk: "write",
+        idempotent: true,
+        summary: (args) => `describe ${String(args.ref)}`,
+    }),
+    defineTool({
+        name: "add_keywords",
+        title: "Add keywords",
+        description: "Add keywords to items. Keywords are how a library stays searchable beyond what Apple's own index recognises.",
+        schema: { refs: REFS, keywords: z.array(z.string()).describe("Keywords to add.") },
+        risk: "write",
+        idempotent: true,
+        summary: (args) => `keyword ${args.refs.length} item(s)`,
+    }),
+    defineTool({
+        name: "add_to_album",
+        title: "Add to an album",
+        description: "Add items to an album, creating it if it does not exist.",
+        schema: { album: z.string().describe("Album name."), refs: REFS },
+        risk: "write",
+        idempotent: true,
+        summary: (args) => `add ${args.refs.length} item(s) to '${String(args.album)}'`,
+    }),
+    defineTool({
+        name: "archive_photos",
+        title: "Move items into an archive album",
+        description: "Move items into an album for the user to review and empty by hand.\n\nThis is as close to deleting as anything here gets: macOS does not permit a process to delete from a Photos library, so nothing is destroyed, but the items leave the flow the user was looking at and only they can put them back. It needs confirmation for that reason.",
+        schema: { refs: REFS, ...confirmArg },
+        risk: "destructive",
+        summary: (args) => `archive ${args.refs.length} item(s)`,
+    }),
+];
+export const ALL_TOOLS = [...readTools, ...writeTools];
+//# sourceMappingURL=index.js.map