Replace the 27 MCP tools with the eight-tool surface v2 #310

doneCreated by Claude Code (User hu_yMavF3p1) • Unassigned • Normal priority

Description

Implement the concept in #309: recall, project_get, project_store, item_get, item_list, item_store, item_action, item_delete, with per-kind JSON fields, one patch rule, one version per item and read, write and irreversible kept in separate tools.

Why now

Most MCP clients load the whole tool list into every session, so the 19,000 characters are paid by every agent every time. The kinds are not fixed: commits (#299) and further kinds will follow, and each one costs three to four tools today against one description line per tool in v2. There are no external users yet, so a switch without aliases is cheapest now.

Scope

v2 changes the tool surface only. Two decisions on #309 change the data model and run after the switch as their own tasks, so that v2 does not wait for migrations:

  • #320 drops revisions and introduces the full-state history. Until then v2 maps version onto the item's existing Version column and checks it against the published revision internally. No revision id appears in any v2 response.
  • #321 changes memory visibility to private/shared and drops organization memories. Until then item_store accepts today's visibility values and recall keeps today's upstream rule.

Order

  1. #311 Prototype and measure. Gate: the list lands well below 19,000 characters and a real session on the stubs needs no more retries than today. Per-tool sizes for on-demand loading and keyword findability are recorded, not gating. Stop and revise #309 only if one of the two gating criteria fails.
  2. #312 Decide the open questions. Done; decisions are on #309.
  3. #313 item_get and item_list, #314 item_action and item_delete, #316 recall, project_get, project_store.
  4. #315 item_store with batches, on the existing data model.
  5. #317 Switch in one step, without aliases.
  6. #320 and #321 afterwards, each with its own migration and release note.

Until the switch, the v2 tools are built and tested without being advertised, so connected agents keep seeing only the current surface and the budget test keeps measuring what they receive.

Folds in: #304 (paging contract, used by item_list), #305 (partial reads, used by item_get). Related: #302, #291, #299.

Acceptance

  • Every subtask done; McpDiscoveryTests budget lowered to the measured size with the reason recorded.
  • #309 updated from "planned" to the implemented surface; #279 and #287 describe the new tools.
  • Every tool description names its kinds in the first sentence, so keyword tool search in clients that load tools on demand finds the right tool.
  • Adding a kind is documented as a checklist: the fields line in item_store, the filters line in item_list, the actions row in item_action, the server-side validator, tests. No new tool.
Connection interrupted or session ended. Reload

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please retry or reload the page.