apple-photos-mcp 2.1.4 → 2.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -81,9 +81,24 @@ The Codex plugin runs the published `apple-photos-mcp` server through `npx` and
81
81
 
82
82
  ### Other Hosts (Hermes, Antigravity)
83
83
 
84
- Configuration for two more hosts is included — each registers the same `apple-photos` MCP server (`npx -y apple-photos-mcp`). As a Python-sidecar (osxphotos) server it also needs Full Disk Access; see [Requirements](#requirements).
84
+ Two more hosts can run the same `apple-photos` MCP server (`npx -y apple-photos-mcp`). As a Python-sidecar (osxphotos) server it also needs Full Disk Access; see [Requirements](#requirements).
85
85
 
86
- - **[Hermes Agent](https://hermes-agent.nousresearch.com/)** (NousResearch) — Hermes has no plugin/marketplace drop-in. Add the server with `hermes mcp add apple-photos --command npx --args -y apple-photos-mcp`, or merge [`.hermes-plugin/config.yaml`](https://github.com/sweetrb/apple-photos-mcp/blob/main/.hermes-plugin/config.yaml) into `~/.hermes/config.yaml`. Details: [`.hermes-plugin/README.md`](https://github.com/sweetrb/apple-photos-mcp/blob/main/.hermes-plugin/README.md).
86
+ - **[Hermes Agent](https://hermes-agent.nousresearch.com/)** (NousResearch) — Hermes has no plugin/marketplace drop-in, so there is nothing in this repo to install from. Register the server with the CLI:
87
+
88
+ ```bash
89
+ hermes mcp add apple-photos --command npx --args -y apple-photos-mcp
90
+ ```
91
+
92
+ Or add it to `~/.hermes/config.yaml` by hand:
93
+
94
+ ```yaml
95
+ mcp_servers:
96
+ apple-photos:
97
+ command: npx
98
+ args: ["-y", "apple-photos-mcp"]
99
+ ```
100
+
101
+ Restart your Hermes session afterward so the tools load.
87
102
  - **[Antigravity](https://antigravity.google/)** (Google) — add the server entry from [`.antigravity-plugin/mcp_config.json`](https://github.com/sweetrb/apple-photos-mcp/blob/main/.antigravity-plugin/mcp_config.json) to `~/.gemini/config/mcp_config.json` (or via Antigravity's MCP settings).
88
103
 
89
104
  ### Manual Installation
@@ -217,7 +232,7 @@ The write tools stay **registered** even while disabled (MCP clients cache the t
217
232
  - **Explicit targets only.** Every write takes explicit UUIDs, names, or file paths — there are no wildcard/all-photos operations, and every target is validated to exist before anything is modified (unknown UUIDs come back as clear errors or per-UUID `notFound` lists; import source paths must exist under the same allowlist roots as export).
218
233
  - **Bounded batches.** Album operations accept at most 100 UUIDs per call; imports at most 50 files.
219
234
  - **Reversible by design.** Metadata writes echo before/after values so an agent can revert; `set-keywords` uses union semantics (read-merge-write) so keywords you don't mention are never clobbered; album adds are idempotent; `set-photo-date` is a **dry run by default** — it writes nothing until you pass `dryRun: false`, and always echoes before/after so an applied change can be reverted.
220
- - **The mechanism:** writes drive **Photos.app via AppleScript** (the [photoscript](https://github.com/RhetTbull/photoscript) library). Photos is launched if it isn't running, and macOS asks for **Automation permission** for the host app with a one-time system prompt on the first write. Writes always target the library **currently open in Photos.app** (normally the system library) — the `library` parameter of the read tools does not apply. (Reads, by contrast, go through osxphotos straight to the Photos database — fast and prompt-free. Why writes *can't* use that same path — and why osxphotos/PhotoKit aren't an escape from AppleScript — is spelled out in [docs/WRITE-BACKEND.md](docs/WRITE-BACKEND.md).)
235
+ - **The mechanism:** writes drive **Photos.app via AppleScript** (the [photoscript](https://github.com/RhetTbull/photoscript) library). Photos is launched if it isn't running, and macOS asks for **Automation permission** for the host app with a one-time system prompt on the first write. Writes always target the library **currently open in Photos.app** (normally the system library) — the `library` parameter of the read tools does not apply. (Reads, by contrast, go through osxphotos straight to the Photos database — fast and prompt-free. Why writes *can't* use that same path — and why osxphotos/PhotoKit aren't an escape from AppleScript — is spelled out in [docs/WRITE-BACKEND.md](https://github.com/sweetrb/apple-photos-mcp/blob/main/docs/WRITE-BACKEND.md).)
221
236
  - **One quirk to know:** Photos' AppleScript dictionary has no "remove from album" verb, so `remove-from-album` **rebuilds the album** (same name, remaining photos): the album's UUID changes (the response reports old and new) and any custom manual sort order is lost.
222
237
 
223
238
  ---
@@ -240,7 +255,7 @@ Verify osxphotos is installed and the Photos library can be opened.
240
255
 
241
256
  #### `doctor`
242
257
 
243
- Run a full setup diagnostic: the resolved Python interpreter (path + version — warns when it's older than the required 3.11, with `brew install python@3.12` advice), osxphotos installation, Photos library readability, and Full Disk Access — each reported as ok / warn / fail with an actionable message. This is the richer counterpart to `health-check`; reach for it first when a tool returns a permission or "unable to open" error.
258
+ Run a full setup diagnostic — six checks: the resolved Python interpreter (path + version — warns when it's older than the required 3.11, with `brew install python@3.12` advice), osxphotos installation, sidecar mode (persistent vs one-shot fallback, plus the last respawn), the write-tools gate (enabled/disabled, with the opt-in recipe and — when enabled — whether the photoscript backend and Photos.app look usable), Photos library readability, and Full Disk Access — each reported as ok / warn / fail with an actionable message. This is the richer counterpart to `health-check`; reach for it first when a tool returns a permission or "unable to open" error.
244
259
 
245
260
  **Parameters:** None
246
261
 
@@ -427,7 +442,7 @@ Return one photo as an **inline viewable image** — an MCP image content block
427
442
  | `minSize` | number | No | Smallest acceptable long-edge size in pixels (default `360`, max `8192`). The smallest qualifying derivative is served — raise it (e.g. `1024`) when you need detail like small text |
428
443
  | `library` | string | No | Path to a non-default `.photoslibrary` |
429
444
 
430
- **Returns:** An image content block plus structured metadata: `uuid`, source `path`, `width`/`height`, `mimeType`, `byteSize`, and `isDerivative` (`false` means no suitable derivative existed and the image was rendered from the original via `sips` — never upscaled). Movies get a thumbnail only when Photos generated a poster-frame derivative; an iCloud-only photo with no local derivative or original returns an error suggesting `export` (which downloads on demand).
445
+ **Returns:** An image content block plus structured metadata: `uuid`, source `path`, `width`/`height`, `mimeType`, `byteSize`, and `isDerivative` (`false` means no suitable derivative existed and the image was rendered from the original via `sips` — never upscaled). Movies get a thumbnail only when Photos generated a poster-frame derivative; an iCloud-only photo with no local derivative or original returns an error suggesting `export` (which downloads on demand). Responses are capped at **8 MB**: derivative selection pre-filters on that cap, but a `sips`-rendered fallback from a very high-resolution original can still exceed it and returns `thumbnail is <n> bytes (cap 8388608); request a smaller minSize` — lower `minSize`, or use `export` for the full file.
431
446
 
432
447
  ---
433
448
 
@@ -437,12 +452,12 @@ Group **exact duplicates** using Photos' own fingerprint-based detection — the
437
452
 
438
453
  | Parameter | Type | Required | Description |
439
454
  |-----------|------|----------|-------------|
440
- | `limit` | number | No | Max duplicate groups to return (default `100`; `groupCount` reports the total) |
455
+ | `limit` | number | No | Max duplicate groups to return (default `100`, max `10000`; `groupCount` reports the total) |
441
456
  | `library` | string | No | Path to a non-default `.photoslibrary` |
442
457
 
443
458
  **Returns:** `groupCount` (total groups), `returned`, and `groups` ordered newest-first — each with the member `uuids` and per-member `filename`, `date`, `size`, `width`/`height`, and `isMovie`. Hidden and Recently-Deleted photos are never group members.
444
459
 
445
- **Exact means exact:** the fingerprint matches identical image data only — edited copies, resized versions, and burst siblings will NOT group. Use `get-thumbnail` on a group's members to eyeball them before acting. This server cannot delete photos (Photos exposes no scriptable delete) — to act on duplicates, collect them into a quarantine album in Photos.app and review/delete there.
460
+ **Exact means exact:** the fingerprint matches identical image data only — edited copies, resized versions, and burst siblings will NOT group. Use `get-thumbnail` on a group's members to eyeball them before acting. This server cannot delete photos (Photos exposes no scriptable delete) — to act on duplicates, quarantine the extra copies into an album (`create-album` + `add-to-album` when [writes are enabled](#write-tools-opt-in), otherwise by hand in Photos.app) and review/delete inside Photos.app. See the [dedupe pattern](#duplicate-cleanup).
446
461
 
447
462
  ---
448
463
 
@@ -478,7 +493,7 @@ List keywords sorted by usage count.
478
493
 
479
494
  | Parameter | Type | Required | Description |
480
495
  |-----------|------|----------|-------------|
481
- | `limit` | number | No | Cap to top-N keywords |
496
+ | `limit` | number | No | Cap to top-N keywords (max `100000`) |
482
497
  | `library` | string | No | Path to a non-default `.photoslibrary` |
483
498
 
484
499
  **Returns:** Keywords with their photo counts, sorted descending.
@@ -491,7 +506,7 @@ List people detected by Photos face recognition, sorted by photo count.
491
506
 
492
507
  | Parameter | Type | Required | Description |
493
508
  |-----------|------|----------|-------------|
494
- | `limit` | number | No | Cap to top-N persons |
509
+ | `limit` | number | No | Cap to top-N persons (max `100000`) |
495
510
  | `library` | string | No | Path to a non-default `.photoslibrary` |
496
511
 
497
512
  **Returns:** Persons with their photo counts, sorted descending. Unidentified faces appear as `_UNKNOWN_`.
@@ -546,7 +561,7 @@ Export one or more photos by UUID to a destination directory.
546
561
 
547
562
  ### Write (opt-in — see [Write tools](#write-tools-opt-in))
548
563
 
549
- All five tools below require `APPLE_PHOTOS_MCP_ENABLE_WRITES=1` and return a clear opt-in error otherwise. They drive Photos.app via AppleScript (macOS Automation permission; Photos is launched if needed), always target the library currently open in Photos.app (no `library` parameter), and can never delete photos.
564
+ All seven tools below require `APPLE_PHOTOS_MCP_ENABLE_WRITES=1` and return a clear opt-in error otherwise. They drive Photos.app via AppleScript (macOS Automation permission; Photos is launched if needed), always target the library currently open in Photos.app (no `library` parameter), and can never delete photos.
550
565
 
551
566
  #### `create-album`
552
567
 
@@ -583,6 +598,8 @@ Remove photos from an album — **never from the library** (they remain in All P
583
598
 
584
599
  **Album rebuild caveat:** Photos' AppleScript has no remove verb, so removal rebuilds the album (create replacement → copy the kept photos → delete the original → rename). The album's **UUID changes** (use `album.uuid` from the response) and custom manual sort order is lost. When none of the UUIDs are members, nothing is rebuilt (`albumRecreated: false`).
585
600
 
601
+ **If a rebuild is interrupted:** the replacement is built under a scratch name `apple-photos-mcp-tmp-<hex>` and renamed last. If the call is killed mid-rebuild — e.g. the 10-minute rebuild budget expires while copying a very large album — the original album and every photo are safe, but an `apple-photos-mcp-tmp-…` album may be left behind; delete it in Photos.app. In the rare case the kill lands in the brief window *after* the original was deleted, the kept photos are still safe under that scratch name — rename it back. The scratch name is picked fresh (and collision-checked) per call, so repeatedly retrying a timing-out removal strands a *distinct* album each time.
602
+
586
603
  #### `set-photo-metadata`
587
604
 
588
605
  Set a photo's title, description, and/or favorite flag. Only the fields you pass are touched.
@@ -590,8 +607,8 @@ Set a photo's title, description, and/or favorite flag. Only the fields you pass
590
607
  | Parameter | Type | Required | Description |
591
608
  |-----------|------|----------|-------------|
592
609
  | `uuid` | string | Yes | Photo UUID |
593
- | `title` | string | No | New title (empty string clears it) |
594
- | `description` | string | No | New description (empty string clears it) |
610
+ | `title` | string | No | New title (≤ 255 chars; empty string clears it) |
611
+ | `description` | string | No | New description (≤ 2048 chars; empty string clears it) |
595
612
  | `favorite` | boolean | No | Set or clear the favorite flag |
596
613
 
597
614
  **Returns:** `uuid`, `updated` (which fields were written), and full `before` / `after` values of all three fields — revert a change by writing the `before` values back.
@@ -603,8 +620,8 @@ Add and/or remove keywords on a photo with **union semantics**: the photo's curr
603
620
  | Parameter | Type | Required | Description |
604
621
  |-----------|------|----------|-------------|
605
622
  | `uuid` | string | Yes | Photo UUID |
606
- | `add` | string[] | No | Keywords to add (≤ 100; created in Photos if new) |
607
- | `remove` | string[] | No | Keywords to remove from this photo (≤ 100; exact match) |
623
+ | `add` | string[] | No | Keywords to add (≤ 100 entries, each ≤ 255 chars; created in Photos if new) |
624
+ | `remove` | string[] | No | Keywords to remove from this photo (≤ 100 entries, each ≤ 255 chars; exact match) |
608
625
 
609
626
  At least one of `add` / `remove` is required; a keyword in both is rejected.
610
627
 
@@ -874,7 +891,7 @@ All configuration is optional — the server works out of the box.
874
891
  |----------|---------|-------------|
875
892
  | `APPLE_PHOTOS_MCP_ENABLE_WRITES` | unset (**read-only**) | Set to `1` to enable the [write tools](#write-tools-opt-in) (`create-album`, `add-to-album`, `remove-from-album`, `set-photo-metadata`, `set-keywords`, `set-photo-date`, `import-photos`). Until then every write tool returns a clear opt-in error and the server cannot modify the library. Restart the server after changing it. |
876
893
  | `APPLE_PHOTOS_MCP_MAX_BUFFER` | `104857600` (100 MB) | Max bytes captured from the Python sidecar's stdout. Raise it if a very large library/query is truncated; lower it to cap memory. |
877
- | `APPLE_PHOTOS_MCP_TIMEOUT` | `60000` (60 s) | Default per-command timeout, in milliseconds, for the Python sidecar. The first (cold) call parses the whole Photos database, and on very large libraries (100k+ photos) that load alone can exceed 60 s — raise this if tools report "Operation timed out". `export` keeps its own 30-minute window. |
894
+ | `APPLE_PHOTOS_MCP_TIMEOUT` | `60000` (60 s) | Default per-command timeout, in milliseconds, for the Python sidecar. The first (cold) call parses the whole Photos database, and on very large libraries (100k+ photos) that load alone can exceed 60 s — raise this if tools report "Operation timed out". **It sets only the DEFAULT budget** — it applies to `query`, `get-photo`, `get-photos`, `get-thumbnail`, `library-info`, `list-albums`, `list-folders`, `list-keywords`, `list-persons` and `health-check`, and is ignored by every tool that carries a fixed budget: `get-selected-photos` 2 min; `find-duplicates`, `create-album`, `add-to-album`, `set-photo-metadata`, `set-keywords` and `set-photo-date` 5 min; `remove-from-album` and `import-photos` 10 min; `export` 30 min. Those budgets are not configurable — a timeout on one of them says so instead of pointing here. |
878
895
  | `APPLE_PHOTOS_MCP_PERSISTENT_SIDECAR` | unset (persistent mode on) | Set to `0` (or `false`) to disable the long-lived serve-mode sidecar and spawn a fresh Python process per call (pre-1.4.0 behavior). Every call then re-pays the full library parse — only useful for debugging. |
879
896
  | `APPLE_PHOTOS_MCP_SIDECAR_IDLE_MS` | `300000` (5 min) | How long the persistent sidecar may sit idle before it's killed to free memory (a resident parsed library holds hundreds of MB for large libraries). The next call transparently respawns it, re-paying the one-time parse. `0` = never kill on idle. |
880
897
  | `APPLE_PHOTOS_MCP_NO_AUTO_SETUP` | unset (auto-setup on) | Set to `1` (or any truthy value) to disable the automatic first-use venv bootstrap. With it on, you must run `pnpm run setup` (or `pip3 install osxphotos`) yourself. |
package/build/index.js CHANGED
@@ -21826,7 +21826,7 @@ function findSystemPython() {
21826
21826
  }
21827
21827
  }
21828
21828
  throw new Error(
21829
- `Python 3 not found on PATH. Install Python 3.11+ (stock macOS ships 3.9 \u2014 brew install python@3.12), then retry. See ${REQUIREMENTS_URL}.`
21829
+ `Python 3 not found on PATH. Install Python 3.11+ (stock macOS ships 3.9 \u2014 brew install python@3.12), then retry. Run the doctor tool to diagnose, or see ${REQUIREMENTS_URL}.`
21830
21830
  );
21831
21831
  }
21832
21832
  function resolvePython() {
@@ -21965,10 +21965,11 @@ function mapStructuredError(structured) {
21965
21965
  }
21966
21966
  return structured;
21967
21967
  }
21968
- function timeoutError(timeoutMs) {
21969
- return `Operation timed out after ${timeoutMs}ms. Library may be very large. Raise ${ENV_PREFIX}_TIMEOUT (ms) if the library needs longer to load.`;
21968
+ function timeoutError(timeoutMs, envConfigurable) {
21969
+ const remedy = envConfigurable ? `Raise ${ENV_PREFIX}_TIMEOUT (ms) if the library needs longer to load.` : `This tool's timeout is fixed at ${timeoutMs}ms; ${ENV_PREFIX}_TIMEOUT does not apply to it.`;
21970
+ return `Operation timed out after ${timeoutMs}ms. Library may be very large. ${remedy}`;
21970
21971
  }
21971
- async function execReader(command, args, timeoutMs) {
21972
+ async function execReader(command, args, timeoutMs, envConfigurable = true) {
21972
21973
  const python = resolvePython();
21973
21974
  const scriptPath = getScriptPath();
21974
21975
  const fullArgs = [scriptPath, command, ...args];
@@ -22004,7 +22005,7 @@ async function execReader(command, args, timeoutMs) {
22004
22005
  }
22005
22006
  const bufferExceeded = /maxBuffer.*exceeded/i.test(error2.message ?? "");
22006
22007
  if (error2.killed === true && !bufferExceeded || error2.message?.includes("ETIMEDOUT") || error2.message?.includes("timed out")) {
22007
- return { error: timeoutError(timeoutMs) };
22008
+ return { error: timeoutError(timeoutMs, envConfigurable) };
22008
22009
  }
22009
22010
  if (stderr) {
22010
22011
  return { error: stderr };
@@ -22070,7 +22071,7 @@ function getSidecarInfo() {
22070
22071
  }
22071
22072
  return { mode: "persistent", ...base };
22072
22073
  }
22073
- async function executeSidecar(command, args, timeoutMs, onProgress) {
22074
+ async function executeSidecar(command, args, timeoutMs, envConfigurable, onProgress) {
22074
22075
  if (persistentModeEnabled() && serveDisabledReason === null) {
22075
22076
  const outcome = await persistentClient.request(command, args, timeoutMs, onProgress);
22076
22077
  switch (outcome.kind) {
@@ -22089,7 +22090,7 @@ async function executeSidecar(command, args, timeoutMs, onProgress) {
22089
22090
  case "error":
22090
22091
  return { error: mapStructuredError(outcome.error) };
22091
22092
  case "timeout":
22092
- return { error: timeoutError(timeoutMs) };
22093
+ return { error: timeoutError(timeoutMs, envConfigurable) };
22093
22094
  case "fallback": {
22094
22095
  if (!looksLikeMissingDep(outcome.reason)) {
22095
22096
  serveDisabledReason = outcome.reason;
@@ -22104,17 +22105,18 @@ async function executeSidecar(command, args, timeoutMs, onProgress) {
22104
22105
  }
22105
22106
  }
22106
22107
  }
22107
- return execReader(command, args, timeoutMs);
22108
+ return execReader(command, args, timeoutMs, envConfigurable);
22108
22109
  }
22109
22110
  async function runPhotosReader(command, args, timeoutMs, onProgress) {
22110
22111
  return sidecarGate(async () => {
22111
22112
  await ensureReady();
22113
+ const envConfigurable = timeoutMs === void 0;
22112
22114
  const timeout = timeoutMs ?? getDefaultTimeout();
22113
- const result = await executeSidecar(command, args, timeout, onProgress);
22115
+ const result = await executeSidecar(command, args, timeout, envConfigurable, onProgress);
22114
22116
  if (result.error && looksLikeMissingDep(result.error) && !bootstrapAttempted && !autoSetupDisabled()) {
22115
22117
  if (await attemptBootstrap()) {
22116
22118
  persistentClient.kill("venv bootstrapped");
22117
- return executeSidecar(command, args, timeout, onProgress);
22119
+ return executeSidecar(command, args, timeout, envConfigurable, onProgress);
22118
22120
  }
22119
22121
  }
22120
22122
  return result;
@@ -23494,7 +23496,7 @@ ${lines.join("\n")}`, { count, persons });
23494
23496
  server.registerTool(
23495
23497
  "export",
23496
23498
  {
23497
- description: "Use when: you want to copy one or more photos (by UUID, typically from query) out to a destination directory on disk. By default exports the original; set edited=true for the edited version, live=true to also include the live-photo video, raw=true to also include the raw image. Large batches report per-photo MCP progress notifications when the request carries a progressToken.\nReturns: the destination path, counts of files exported and skipped, the exported file paths, and a per-UUID reason for anything skipped (e.g. file already exists at the destination, UUID not found / in trash, iCloud download failed).\nDo not use when: you only need metadata or file paths rather than copies on disk \u2014 use get-photo; or you're still figuring out which photos to export \u2014 use query first.\nSafety: this is the only side-effecting tool \u2014 it writes files into the destination directory (created if missing). dest must resolve (after expanding ~ and following symlinks) to a path under your home directory, /tmp, /private/tmp, or /Volumes; anything else is rejected. With overwrite=true it OVERWRITES existing files of the same name in place; without it, existing files are skipped and reported per-UUID. If an original isn't on disk (iCloud 'Optimize Mac Storage'), the export falls back to driving Photos.app via AppleScript to download it on demand \u2014 this is slow for large batches and requires Photos.app installed, signed in to iCloud, and Automation permission granted.",
23499
+ description: "Use when: you want to copy one or more photos (by UUID, typically from query) out to a destination directory on disk. By default exports the original; set edited=true for the edited version, live=true to also include the live-photo video, raw=true to also include the raw image. Large batches report per-photo MCP progress notifications when the request carries a progressToken.\nReturns: the destination path, counts of files exported and skipped, the exported file paths, and a per-UUID reason for anything skipped (e.g. file already exists at the destination, UUID not found / in trash, iCloud download failed).\nDo not use when: you only need metadata or file paths rather than copies on disk \u2014 use get-photo; or you're still figuring out which photos to export \u2014 use query first.\nSafety: the only side-effecting tool on the read path \u2014 it writes files into the destination directory (created if missing); the opt-in write tools (APPLE_PHOTOS_MCP_ENABLE_WRITES=1) can also modify the library, but nothing else here writes anywhere. dest must resolve (after expanding ~ and following symlinks) to a path under your home directory, /tmp, /private/tmp, or /Volumes; anything else is rejected. With overwrite=true it OVERWRITES existing files of the same name in place; without it, existing files are skipped and reported per-UUID. If an original isn't on disk (iCloud 'Optimize Mac Storage'), the export falls back to driving Photos.app via AppleScript to download it on demand \u2014 this is slow for large batches and requires Photos.app installed, signed in to iCloud, and Automation permission granted.",
23498
23500
  inputSchema: {
23499
23501
  ...libraryArg,
23500
23502
  uuid: external_exports.array(external_exports.string().max(256)).min(1).max(1e3).describe("Photo UUID(s) to export"),
@@ -23516,17 +23518,20 @@ server.registerTool(
23516
23518
  },
23517
23519
  withErrorHandling(async ({ library, uuid: uuid2, dest, edited, live, raw, overwrite }, extra) => {
23518
23520
  const progressToken = extra?._meta?.progressToken;
23521
+ const inFlight = [];
23519
23522
  const onProgress = progressToken === void 0 ? void 0 : (p) => {
23520
- void extra.sendNotification({
23521
- method: "notifications/progress",
23522
- params: {
23523
- progressToken,
23524
- progress: p.done,
23525
- total: p.total,
23526
- message: p.current ? `Exporting ${p.current} (${p.done + 1}/${p.total})` : `Exported ${p.done}/${p.total}`
23527
- }
23528
- }).catch(() => {
23529
- });
23523
+ inFlight.push(
23524
+ extra.sendNotification({
23525
+ method: "notifications/progress",
23526
+ params: {
23527
+ progressToken,
23528
+ progress: p.done,
23529
+ total: p.total,
23530
+ message: p.current ? `Exporting ${p.current} (${p.done + 1}/${p.total})` : `Exported ${p.done}/${p.total}`
23531
+ }
23532
+ }).catch(() => {
23533
+ })
23534
+ );
23530
23535
  };
23531
23536
  const result = await manager.exportPhotos(uuid2, dest, {
23532
23537
  edited,
@@ -23536,6 +23541,9 @@ server.registerTool(
23536
23541
  library,
23537
23542
  onProgress
23538
23543
  });
23544
+ if (inFlight.length) {
23545
+ await Promise.all(inFlight);
23546
+ }
23539
23547
  const lines = [
23540
23548
  `Destination: ${result.destination}`,
23541
23549
  `Exported: ${result.exportedCount} file(s)`,
@@ -23614,7 +23622,7 @@ server.registerTool(
23614
23622
  server.registerTool(
23615
23623
  "remove-from-album",
23616
23624
  {
23617
- description: "Use when: you want to take photos OUT of an album \u2014 undoing a mis-filing, or clearing reviewed items from a quarantine album. This removes ALBUM MEMBERSHIP only.\nReturns: the album AFTER the operation ({uuid, name, path} \u2014 note the uuid CHANGES when anything was removed), removedCount, removed, notInAlbum (requested UUIDs that weren't members \u2014 no-ops), albumRecreated, and previousAlbumUuid.\nDo not use when: you want to delete photos from the library \u2014 this server cannot delete photos at all (quarantine them in an album and review in Photos.app instead); or the photos aren't in the album (harmless, but pointless).\nSafety: WRITE tool \u2014 disabled unless APPLE_PHOTOS_MCP_ENABLE_WRITES=1 (run doctor to check). NEVER deletes photos from the library \u2014 removed photos stay in All Photos and every other album. Photos' AppleScript has no remove-from-album verb, so the album is REBUILT (same name and remaining photos): its UUID changes and any custom manual sort order is lost; re-fetch the album UUID from the response. When none of the UUIDs are members, nothing is rebuilt. Max 100 UUIDs per call. Drives Photos.app via AppleScript (requires macOS Automation permission). Writes target the library currently open in Photos.app.",
23625
+ description: "Use when: you want to take photos OUT of an album \u2014 undoing a mis-filing, or clearing reviewed items from a quarantine album. This removes ALBUM MEMBERSHIP only.\nReturns: the album AFTER the operation ({uuid, name, path} \u2014 note the uuid CHANGES when anything was removed), removedCount, removed, notInAlbum (requested UUIDs that weren't members \u2014 no-ops), albumRecreated, and previousAlbumUuid.\nDo not use when: you want to delete photos from the library \u2014 this server cannot delete photos at all (quarantine them in an album and review in Photos.app instead); or the photos aren't in the album (harmless, but pointless).\nSafety: WRITE tool \u2014 disabled unless APPLE_PHOTOS_MCP_ENABLE_WRITES=1 (run doctor to check). NEVER deletes photos from the library \u2014 removed photos stay in All Photos and every other album. Photos' AppleScript has no remove-from-album verb, so the album is REBUILT (same name and remaining photos): its UUID changes and any custom manual sort order is lost; re-fetch the album UUID from the response. When none of the UUIDs are members, nothing is rebuilt. The replacement is built under a scratch name `apple-photos-mcp-tmp-<hex>` and renamed last, so a call killed mid-rebuild (e.g. the 10-minute budget expiring while copying a very large album) leaves the original album and every photo intact but can strand an `apple-photos-mcp-tmp-\u2026` album to delete in Photos.app; each interrupted run strands a distinct one. Max 100 UUIDs per call. Drives Photos.app via AppleScript (requires macOS Automation permission). Writes target the library currently open in Photos.app.",
23618
23626
  inputSchema: {
23619
23627
  album: external_exports.string().min(1).max(1024).describe("Album name or UUID (UUID-looking values try the id lookup first)"),
23620
23628
  uuid: external_exports.array(uuidSchema).min(1).max(100).describe("Photo UUID(s) to remove from the album (1\u2013100)")
@@ -2,8 +2,17 @@
2
2
 
3
3
  Apple Photos MCP needs **Full Disk Access (FDA)** for the process that runs the
4
4
  MCP server. Unlike some Apple MCP servers, this is **not optional** — without it,
5
- **no tool works**, because every tool ultimately reads the Photos library's
6
- SQLite database, and that database lives in a macOS-protected directory.
5
+ **no read tool works**: every read (`query`, browse, thumbnails, `export`,
6
+ diagnostics) goes through osxphotos to the Photos library's SQLite database, and
7
+ that database lives in a macOS-protected directory.
8
+
9
+ The opt-in **write** tools are the one exception to the *mechanism*: they drive
10
+ Photos.app over AppleScript rather than reading the database, so what they need
11
+ is macOS **Automation** permission, not FDA (a write failing with AppleScript
12
+ error `-1743` is an Automation problem — granting FDA will not fix it; see
13
+ [WRITE-BACKEND.md](./WRITE-BACKEND.md)). FDA is still effectively mandatory in
14
+ practice, because the photo UUIDs the write tools operate on come from
15
+ FDA-backed reads.
7
16
 
8
17
  ## Why it's needed
9
18
 
@@ -19,7 +28,7 @@ Everything under `~/Pictures/Photos Library.photoslibrary/` is gated by macOS
19
28
  privacy protection. Reading it requires **Full Disk Access** for the *host*
20
29
  process — the application that actually launches `node` and spawns the Python
21
30
  sidecar. Without that grant, macOS denies the read before osxphotos can open the
22
- database, and the server can do nothing.
31
+ database, and the read path can do nothing.
23
32
 
24
33
  (The MCP only ever **reads** the library database; it never writes to it. See
25
34
  [LIMITATIONS.md](./LIMITATIONS.md).)
@@ -48,10 +57,10 @@ database, and the server can do nothing.
48
57
  ## Verifying it worked
49
58
 
50
59
  The best verification is the **`doctor`** tool. It runs the full setup
51
- diagnostic — osxphotos install, Photos library readability, and **Full Disk
52
- Access** — and reports each as ok / warn / fail. The Full Disk Access check is
53
- explicit: if the grant took effect it reports `ok`; if it's missing it reports
54
- `fail` with a pointer back to this guide.
60
+ diagnostic — six checks, including **Full Disk Access** — and reports each as
61
+ ok / warn / fail. The Full Disk Access check is explicit: if the grant took
62
+ effect it reports `ok`; if it's missing it reports `fail` with a pointer back to
63
+ this guide.
55
64
 
56
65
  For a quicker smoke test, run **`health-check`**. It confirms two things in one
57
66
  shot: that osxphotos is installed, and that the Photos library can actually be
@@ -52,7 +52,11 @@ so writes always target that library (normally the system one) — the read
52
52
  tools' `library` parameter does not apply; (3) Photos' AppleScript dictionary
53
53
  has **no remove-from-album verb**, so `remove-from-album` rebuilds the album
54
54
  (same name, remaining photos): the album's **UUID changes** and custom manual
55
- sort order is lost; (4) Photos is launched if it isn't running, so the first
55
+ sort order is lost — the replacement is built under a scratch name
56
+ `apple-photos-mcp-tmp-<hex>` and renamed last, so a rebuild killed part-way
57
+ (e.g. its fixed 10-minute budget expiring on a very large album) leaves the
58
+ original album and every photo safe but can strand an `apple-photos-mcp-tmp-…`
59
+ album, one per interrupted attempt; (4) Photos is launched if it isn't running, so the first
56
60
  write can be slow; (5) `set-photo-date` rewrites the **Photos library date
57
61
  only** — the same thing Photos.app's *Adjust Date & Time* does — the file's
58
62
  EXIF is never modified, so an exported original still carries its old EXIF
@@ -62,8 +66,10 @@ duplicate makes Photos.app show a **blocking dialog** a human must answer.
62
66
  **What to do:** Run `doctor` first — its `writes` check reports the gate state
63
67
  and backend readiness. Grant the Automation prompt once from a GUI session.
64
68
  After a `remove-from-album`, use the returned `album.uuid` (or the album name)
65
- for follow-up calls. Preview date fixes with `set-photo-date`'s default dry
66
- run before applying.
69
+ for follow-up calls; if one was interrupted, delete any leftover
70
+ `apple-photos-mcp-tmp-…` album in Photos.app (or, if the original vanished,
71
+ rename the scratch album back). Preview date fixes with `set-photo-date`'s
72
+ default dry run before applying.
67
73
 
68
74
  ## `get-selected-photos` needs a live GUI selection
69
75
 
@@ -106,7 +112,7 @@ its dedicated Full Disk Access check reports ok / warn / fail with remediation
106
112
  **Why:** Opening a Photos library means starting Python, importing osxphotos,
107
113
  and parsing the entire library database — about 4 seconds on a ~30k-photo
108
114
  library, and it scales with library size (a 100k+ photo library can take much
109
- longer, potentially past the default 60 s timeout — raise
115
+ longer, potentially past the default 60 s budget — raise
110
116
  `APPLE_PHOTOS_MCP_TIMEOUT` if so). Since 1.4.0 the sidecar is a **persistent
111
117
  process**, so this cost is paid **once**: the parsed library stays resident
112
118
  and follow-up calls complete in milliseconds. The cold cost recurs only when
@@ -118,7 +124,11 @@ are never stale).
118
124
 
119
125
  **What to do:** Nothing, usually — chain as many calls as you like; only the
120
126
  first pays the parse. If even the cold call times out on a very large library,
121
- raise `APPLE_PHOTOS_MCP_TIMEOUT` (ms). To keep the sidecar resident longer (or
127
+ raise `APPLE_PHOTOS_MCP_TIMEOUT` (ms) — but note it sets only the **default**
128
+ budget: `export` (30 min), `import-photos` and `remove-from-album` (10 min),
129
+ the other write tools and `find-duplicates` (5 min) and `get-selected-photos`
130
+ (2 min) carry their own fixed budgets that the variable cannot change, and a
131
+ timeout on one of those says so rather than pointing at the variable. To keep the sidecar resident longer (or
122
132
  forever), raise `APPLE_PHOTOS_MCP_SIDECAR_IDLE_MS` or set it to `0` — at the
123
133
  price of a few hundred MB of resident memory for large libraries. `doctor`'s
124
134
  `sidecar_mode` check shows whether the persistent sidecar is active and when
@@ -10,7 +10,8 @@ ends, explained below.
10
10
  | Path | Backend | Why |
11
11
  |------|---------|-----|
12
12
  | **Reads** — `query`, browse, `export`, diagnostics | **osxphotos**, reading the Photos SQLite DB directly | Fast, no app scripting, no Automation prompt, no Photos.app launch. |
13
- | **Writes** — `create-album`, `add-to-album`, `remove-from-album`, `set-photo-metadata`, `set-keywords` (opt-in, gated behind `APPLE_PHOTOS_MCP_ENABLE_WRITES=1`) | **photoscript → AppleScript → Photos.app** | The only *safe, supported* way to mutate the live library. |
13
+ | **Writes** — `create-album`, `add-to-album`, `remove-from-album`, `set-photo-metadata`, `set-keywords`, `set-photo-date`, `import-photos` (opt-in, gated behind `APPLE_PHOTOS_MCP_ENABLE_WRITES=1`) | **photoscript → AppleScript → Photos.app** | The only *safe, supported* way to mutate the live library. |
14
+ | **`get-selected-photos`** — the one photoscript-backed READ (not gated) | **photoscript → AppleScript → Photos.app**, then osxphotos for the metadata | A live GUI selection exists only inside Photos.app; nothing in the database describes it. |
14
15
 
15
16
  ## Why not write to the SQLite DB the way we read it?
16
17
 
@@ -39,7 +40,7 @@ not grant PhotoKit write access to a bare `python3`/`node` interpreter. osxphoto
39
40
  bundles a PhotoKit module, and its own source notes it *"[hasn't] figured out how
40
41
  to get the call to requestAuthorization to actually work"* for this case.
41
42
  Shipping PhotoKit writes would mean building, signing, notarizing, and
42
- distributing a native (Swift) helper — a large lift, disproportionate to five
43
+ distributing a native (Swift) helper — a large lift, disproportionate to seven
43
44
  opt-in tools, and an unsolved problem even in osxphotos.
44
45
 
45
46
  ## The accepted trade-off
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "apple-photos-mcp",
3
- "version": "2.1.4",
3
+ "version": "2.1.6",
4
4
  "description": "MCP server for Apple Photos - query, search, export, and inspect the macOS Photos library via Claude and other AI assistants, plus opt-in album/metadata write tools (read-only by default)",
5
5
  "type": "module",
6
6
  "main": "build/index.js",
@@ -87,7 +87,7 @@
87
87
  "test:coverage": "vitest run --coverage",
88
88
  "test:integration": "vitest run --config vitest.integration.config.ts",
89
89
  "test:all": "vitest run && vitest run --config vitest.integration.config.ts",
90
- "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin .agents/plugins codex .hermes-plugin .antigravity-plugin",
90
+ "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin .agents/plugins codex .antigravity-plugin",
91
91
  "preinstall": "node -e \"const fs=require('fs');const ua=process.env.npm_config_user_agent||'';if(fs.existsSync('.git')&&!ua.startsWith('pnpm')){console.error('\\nThis repo uses pnpm. npm/yarn resolve dependencies off-lockfile and the committed bundle will mismatch CI.\\n\\n corepack enable && pnpm install --frozen-lockfile\\n');process.exit(1)}\""
92
92
  }
93
93
  }