ryan/simbarag
1
0
Fork 0
Code Issues Pull Requests 5 Actions 2 Packages Projects Releases Wiki Activity

Add Immich MCP technical design #90

Merged
ryan merged 1 commits from docs/immich-mcp-design into main 2026-10-13 09:08:15 -04:00
Conversation 0 Commits 1 Files Changed 2
+433
ryan commented 2026-10-13 08:41:07 -04:00
Owner
Copy Link
Copy Source

Adds docs/immich-mcp/design.md: an in-repo stdio MCP server (immich_mcp/) that Simba loads like Homebox and BookStack (admin-only), and that Claude Code can register with claude mcp add.

  • Phase 1 (read-only): find albums by fuzzy name, search photos by date, place or person with a trip date-cluster summary, CLIP search, and list photos missing from an existing album.
  • Phase 2 (writes): create an album and add photos to an album. These only register when IMMICH_ENABLE_WRITES=true, and each call needs an expected_count matching what the user confirmed. Nothing can delete.

Reviewed three times before opening:

  • Checked the endpoints, permissions and fields against the Immich 3.3.0-rc OpenAPI spec. This turned up the v3.2 deprecation of the flat search fields, so request bodies now go through one version-aware builder.
  • Fixed the local-day semantics (localDateTime is wall-clock time).
  • Flattened criteria into tool parameters, because nested $defs don't work well with the llama-server grammar.
  • Added the cwd and args support that load_stdio_tools needs.
  • Made the gap count and the add count use one shared helper.

Docs only, so no code changes.

🤖 Generated with Claude Code

Adds `docs/immich-mcp/design.md`: an in-repo stdio MCP server (`immich_mcp/`) that Simba loads like Homebox and BookStack (admin-only), and that Claude Code can register with `claude mcp add`. - **Phase 1 (read-only):** find albums by fuzzy name, search photos by date, place or person with a trip date-cluster summary, CLIP search, and list photos missing from an existing album. - **Phase 2 (writes):** create an album and add photos to an album. These only register when `IMMICH_ENABLE_WRITES=true`, and each call needs an `expected_count` matching what the user confirmed. Nothing can delete. Reviewed three times before opening: - Checked the endpoints, permissions and fields against the Immich 3.3.0-rc OpenAPI spec. This turned up the v3.2 deprecation of the flat search fields, so request bodies now go through one version-aware builder. - Fixed the local-day semantics (`localDateTime` is wall-clock time). - Flattened criteria into tool parameters, because nested `$defs` don't work well with the llama-server grammar. - Added the `cwd` and `args` support that `load_stdio_tools` needs. - Made the gap count and the add count use one shared helper. Docs only, so no code changes. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
ryan added 1 commit 2026-10-13 08:41:07 -04:00
Add Immich MCP technical design
CI / backend (push) Successful in 42s
Details
CI / frontend (push) Successful in 9m34s
Details
CI / backend (pull_request) Successful in 42s
Details
CI / frontend (pull_request) Successful in 9m34s
Details
200cd73924 
Design for an in-repo stdio MCP server that lets Simba (and Claude Code)
find existing albums, summarize trips by date clusters, and create or
fill albums behind a write flag and a confirmed-count check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ryan merged commit b24238ab24 into main 2026-10-13 09:08:15 -04:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
ryan
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: ryan/simbarag#90
Delete Branch "docs/immich-mcp-design"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?