MCP gap-fill roadmap (tracking)

[joestump]

Tracking issue for the Karakeep MCP gap-fill work — expanding the MCP server from 20 → 32 tools across four waves. Each wave/PR is its own ticket below; this issue holds the overview and tracks progress. (Originally drafted as apps/mcp/ROADMAP.md, but a planning doc doesn't belong in the source tree — it lives here in the backlog instead.)

Tickets

• MCP W1-PR1: list-bookmarks, get-list-bookmarks, check-bookmark-url #3 — W1-PR1: list-bookmarks, get-list-bookmarks, check-bookmark-url (PR feat(mcp): add list-bookmarks, get-list-bookmarks, check-bookmark-url (W1-PR1) #9)
• MCP W1-PR2: get-bookmark-lists, get-bookmark-highlights #4 — W1-PR2: get-bookmark-lists, get-bookmark-highlights
• MCP W2: Feeds suite (list/create/get/update/delete/fetch) #5 — W2: Feeds suite (list/create/get/update/delete/fetch)
• MCP W3-PR1: upload-asset, get-asset #6 — W3-PR1: upload-asset, get-asset
• MCP W3-PR2: attach/replace/detach-bookmark-asset #7 — W3-PR2: attach/replace/detach-bookmark-asset (depends on MCP W3-PR1: upload-asset, get-asset #6)
• MCP W4: create-tag #8 — W4: create-tag

Overview

This backlog turns six researched PR specs into an ordered, PR-by-PR implementation plan for expanding the Karakeep MCP server (apps/mcp). Work each PR in the order listed; waves and PR ordering are load-bearing (dependencies flow forward within Wave 3).

Current coverage: The MCP server ships 20 tools today, spanning bookmarks (create/get/update, content, search), lists (get, create, add/remove membership), and tags (get, attach/detach, update/delete). Notable gaps: no way to browse bookmarks without a search query, no way to enumerate a list's contents, no reverse lookups (which lists/highlights a bookmark has), no Feeds surface at all, no Assets surface at all, and no explicit tag creation.

What these waves add (20 → 32 tools):

Wave	Adds	Tools
W1 — Bookmarks	Read/browse + sub-resource lookups	5
W2 — Feeds	Full RSS feed CRUD + fetch	6
W3 — Assets	Upload/fetch + attach/replace/detach	5
W4 — Tags	Explicit tag creation	1

All tools follow the established apps/mcp conventions: typed karakeepClient calls (openapi-fetch), pickDefined for optional query/body assembly, toMcpToolError on failure, shared formatting helpers (compactBookmark, compactTag, formatList), the nextCursor → "Next page cursor:" pagination convention, and exported input-schema + handler pairs so every tool is unit-testable by direct import.

---

Summary Table

PR	Wave	Tools	Complexity	Depends on
W1-PR1	W1 — Bookmarks	list-bookmarks, get-list-bookmarks, check-bookmark-url	S	—
W1-PR2	W1 — Bookmarks	get-bookmark-lists, get-bookmark-highlights	S	—
W2	W2 — Feeds	list-feeds, create-feed, get-feed, update-feed, delete-feed, fetch-feed	M	—
W3-PR1	W3 — Assets	upload-asset, get-asset	M	—
W3-PR2	W3 — Assets	attach-bookmark-asset, replace-bookmark-asset, detach-bookmark-asset	S	W3-PR1 (flow, not code)
W4	W4 — Tags	create-tag	S	—

Dependency note: Only W3-PR2 has a soft dependency — it consumes the assetId produced by W3-PR1's upload-asset and references the same UploadedAsset shape in its curl instructions. The code is self-contained (both edit apps/mcp/src/assets.ts), so W3-PR1 should land first to avoid a merge conflict and keep the upload→attach story coherent. Everything else is independent.

---

Out of scope / future

These waves deliberately skip the following (verified absent, deferred, or intentionally excluded):

• Full Highlights CRUD suite — W1-PR2 adds only read (get-bookmark-highlights). Create/update/delete highlight tools are deferred.
• summarize-bookmark — excluded on purpose; the model can summarize fetched content itself, so a server-side summarize tool adds little.
• users/me + user stats — no account/profile or usage-stats tools in these waves.
• Backups — no backup/export tooling.
• Admin jobs — no admin/maintenance/job-management tools.
• Signed-URL asset uploads — the pre-signed upload endpoints (POST /bookmarks/{bookmarkId}/assets/request-upload, PUT /assets/upload) do not exist in the current OpenAPI spec or SDK. W3-PR2 works around this with an out-of-band bearer-auth curl flow; a true signed-upload flow is a backend dependency, not an MCP-only PR.

🤖 Posted on behalf of @joestump by Claude.