apple-photos-mcp 2.1.0 → 2.1.2

package/build/index.js

@@ -22152,6 +22152,14 @@ async function checkDependencies() {
   }
 }
 
+// src/utils/permissionErrors.ts
+function looksLikePermissionError(message) {
+  if (/not permitted|permission|full disk|denied|unable to open/i.test(message)) {
+    return true;
+  }
+  return /error copying\b.*photos\.sqlite/is.test(message);
+}
+
 // src/utils/exportPath.ts
 import { existsSync as existsSync2, realpathSync } from "node:fs";
 import { homedir } from "node:os";
@@ -22226,7 +22234,7 @@ function assertWritesEnabled(env = process.env) {
 
 // src/services/photosManager.ts
 function augmentPermissionError(message) {
-  if (/not permitted|permission|full disk|denied|unable to open/i.test(message)) {
+  if (looksLikePermissionError(message)) {
     return `${message}
 
 This looks like a macOS permission issue: ${FDA_REMEDIATION}`;
@@ -22702,9 +22710,6 @@ function withErrorHandling(handler, prefix) {
 // src/tools/doctor.ts
 import { existsSync as existsSync4 } from "node:fs";
 var PHOTOS_APP_PATH = "/System/Applications/Photos.app";
-function looksLikePermissionError(message) {
-  return /not permitted|permission|full disk|denied|unable to open/i.test(message);
-}
 async function runDoctor(manager2) {
   const checks = [];
   try {

package/docs/FULL-DISK-ACCESS.md

@@ -69,11 +69,81 @@ level and tools fail with a permissions-flavored error. Typical messages:
 
 - `operation not permitted`
 - `unable to open database file`
+- `Error copying …/Photos Library.photoslibrary/database/Photos.sqlite to /tmp/osxphotos_…/Photos.sqlite`
 - a generic "Library not found" / permission error from `health-check`
 
+The `Error copying …/Photos.sqlite to /tmp/…` form is the most misleading: osxphotos
+copies the live library database to a temp directory before opening it, and when
+the host process lacks FDA, macOS denies the **read of the source** — surfaced as a
+generic copy failure with no "permission" wording. It is still an FDA denial. (As of
+v2.1.1 `doctor` classifies this message as a Full Disk Access failure and points here
+rather than reporting "did not look permission-related".)
+
 These are macOS denying access, not a bug in the server. The fix is always the
 same: grant FDA to the host app and **fully restart it** (see above).
 
+### Gotcha: the "host app" for a Claude-spawned server may be a *nested* bundle
+
+If you granted Full Disk Access to `/Applications/Claude.app` (or to your
+terminal), fully restarted, even rebooted — and osxphotos-backed tools **still**
+fail with `Error copying …/Photos.sqlite …` while the exact same
+`osxphotos.PhotosDB()` call succeeds when you run the venv Python directly — the
+grant almost certainly landed on the wrong identity.
+
+macOS attributes a locally-spawned MCP subprocess's file access to the
+**responsible process**, which is not always the app icon you clicked:
+
+- **Claude Code (CLI/desktop Code tab)** spawns MCP servers under a **per-version
+  nested helper bundle**, not `/Applications/Claude.app`. Look for it at
+  `~/Library/Application Support/Claude/claude-code/<version>/claude.app`. This
+  bundle needs its **own** FDA grant, and it **silently resets on every Claude
+  auto-update** — the tell is a new, un-checked lowercase **"claude"** row
+  appearing in the Full Disk Access list.
+- **A terminal-launched server** is attributed to the terminal app
+  (Terminal/iTerm/VS Code), not to `node`.
+
+Fix it: open **System Settings → Privacy & Security → Full Disk Access**, look for
+a **"claude"** entry (distinct from "Claude") or add the nested
+`…/claude-code/<version>/claude.app` bundle via **+**, toggle it **on**, then
+restart the MCP server (a fresh session, or quit/relaunch the host). If it worked
+before and broke after an update, re-check this list first — the grant was reset,
+not lost for good.
+
+### Still failing after granting every host app? Check whether TCC attributed it to `node` itself
+
+Every fix above assumes responsibility climbs from the subprocess up to *some*
+app — Claude Desktop, the nested Code bundle, or your terminal. On at least one
+confirmed setup it didn't: TCC attributed the check directly to the `node`
+binary, and none of the wrapper-app grants ever touched it, because
+responsibility never climbed past `node` to see them.
+
+Don't guess between the theories above — the macOS unified log is
+authoritative. Reproduce the failure while streaming:
+
+```
+log stream --style compact --predicate 'subsystem == "com.apple.TCC"' --info
+```
+
+Look for a line like:
+
+```
+Handling access request to kTCCServiceSystemPolicyAllFiles,
+from Sub:{/usr/local/bin/node}
+Resp:{TCCDProcess: identifier=node, pid=…, responsible_path=/usr/local/bin/node, binary_path=/usr/local/bin/node},
+ReqResult(Auth Right: Denied …)
+```
+
+If `Resp:` names `node` (not `claude.app`, not your terminal), grant FDA to the
+**node binary itself**: **+** → ⌘⇧G → type the exact path from `responsible_path`
+above (commonly `/usr/local/bin/node`, `/opt/homebrew/bin/node`, or a
+pinned-runtime path) → toggle on → fully quit and relaunch the host app.
+
+A stable, Developer-ID-signed Node build (check `codesign -dv $(which node)` —
+look for a real `TeamIdentifier`, not `flags=0x2(adhoc)`) keeps this grant
+across Node upgrades. An ad-hoc-signed build (common with some Homebrew
+formulae) gets a new code identity on every rebuild, so the grant can need
+re-doing after `brew upgrade`.
+
 ## Note: exporting iCloud-only originals also needs Photos automation
 
 Full Disk Access covers reading and querying the library, and exporting any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-photos-mcp",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "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)",
   "type": "module",
   "main": "build/index.js",
@@ -73,7 +73,7 @@
   },
   "scripts": {
     "setup": "bash scripts/setup.sh",
-    "build": "tsc --noEmit && esbuild src/index.ts --bundle --platform=node --format=esm --outfile=build/index.js --banner:js=\"import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);\"",
+    "build": "tsc --noEmit && esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --outfile=build/index.js --banner:js=\"import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);\"",
     "start": "node build/index.js",
     "dev": "tsc --watch",
     "lint": "eslint src",
@@ -81,11 +81,13 @@
     "format": "prettier --write src",
     "format:check": "prettier --check src",
     "typecheck": "tsc --noEmit",
+    "sync:skills": "node scripts/sync-skills.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:integration": "vitest run --config vitest.integration.config.ts",
     "test:all": "vitest run && vitest run --config vitest.integration.config.ts",
-    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin .agents/plugins codex .hermes-plugin .antigravity-plugin"
+    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin .agents/plugins codex .hermes-plugin .antigravity-plugin",
+    "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)}\""
   }
 }

package/requirements.txt

@@ -1,5 +1,7 @@
-osxphotos>=0.69.0,<0.76
+# Exact-pinned (2026-07-20) so the sidecar environment is reproducible and
+# Dependabot's pip ecosystem can propose auditable bumps.
+osxphotos==0.75.9
 # Direct dependency of the opt-in write tools (also an osxphotos transitive
 # dep). Pinned because photos_reader.py uses its script_loader.run_script for
-# bulk album-id calls — keep the floor/ceiling in step when bumping.
-photoscript>=0.5.3,<0.6
+# bulk album-id calls — keep the two pins in step when bumping.
+photoscript==0.5.3