Repository navigation
feat(mcp): collection tools over MCP on the shared service layer - #106
Merged
Merged
Conversation
Seven tools - list_collections, get_collection, query_collection_rows, create_collection_row, update_collection_row, delete_collection_row and collection_history - call the CollectionStore singleton directly, exactly like the REST routes under /api/v1/databases. Error parity is structural: CollectionError extends MdwikiError and the existing run() wrapper renders the 409 conflict with current. The zod schemas encode wire shape only and derive from store constants; validation stays in the store.
…ansport Covers list, get, filtered + sorted query, create/update round trip with base_updated_at, the 409 conflict carrying current, validation parity with REST on a bad select option, delete and the history with the explicit agent and the 'mcp' default. Runs against a temp sqlite file and a temp fixture space only; the pinned tool inventory in api.test.ts grows to 28.
Adds them to the tool tables in docs/tools.md and README and records in docs/collections.md that agents use the same guarantees over MCP as over REST.
…m FILTER_OPS Review finding: the description restated the 14 ops by hand. Interpolating the store constant keeps the prose from drifting when an op is added.
…t a copied instance The walk copies space and database into a temp dir, starts the built server on a free port and drives all seven tools over Streamable HTTP MCP: filtered query, create, update, the 409 conflict with a stale base_updated_at, a validation refusal, delete and the scratch row's revision history. Every write stays below the temp dir, so the source instance is never touched.
…f the live instance Terminal capture of scripts/mcp-collections-walk.sh on 2026-11-15 against a copy of the live instance: all seven tools offered, a filtered query on real Dienste rows, the 409 carrying current, the bad_values refusal, the delete and the history with actors mcp and evidence-walk.
The walk shipped as .mjs with untyped callbacks and svelte-check includes it, so CI failed with implicit-any errors while the local run predated the file. It is now TypeScript with explicit response shapes, run through tsx like scripts/export.ts, and the runner and docs follow.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements #83: agents can read, query, write and audit collections over MCP with the same guarantees as REST.
Tools. Seven new tools on the existing service layer:
list_collections,get_collection,query_collection_rows,create_collection_row,update_collection_row,delete_collection_row,collection_history. The bodies call theCollectionStoresingleton exactly like the REST routes under/api/v1/databases, so validation and thebase_updated_atconflict behaviour are the same implementation, not a copy.CollectionError extends MdwikiError, so the existing MCP error wrapper renders 400/404/409 asisErrorJSON withcurrenton conflicts. Zod encodes wire shape only and derives the filter ops from the store'sFILTER_OPSconstant.collection-write.tsstays out of the machine paths; it is the browser-UI gate.Tests.
test/collections-mcp.test.tswalks the acceptance over a real MCP transport (InMemoryTransport client/server pair) on a temp sqlite and a temp fixture space, including the 409 withcurrent, validation parity proven against the REST route handler, and actor recording.test/api.test.tsgrows its pinned tool inventory from 21 to 28. 467 tests pass (baseline 459 plus 8 new),svelte-check0 errors, build green.Verification lever.
scripts/mcp-collections-walk.shreruns the acceptance against a copy of any instance: copy space and database into a temp dir, start the built server on a free port, drive all seven tools over Streamable HTTP MCP, delete the scratch row again. Every write stays below the temp dir.Evidence, measured 2026-11-15 against a copy of the live instance (7 collections, 153 rows):
The capture shows all seven tools offered over MCP, a filtered and sorted query on real Dienste rows, a create/update round trip, the stale-write 409 carrying
current, thebad_valuesrefusal for an unknown property, the delete and the scratch row's history with actorsmcp(default) andevidence-walk.Docs. The seven tools join the MCP inventories in the README and
docs/tools.mdwith their REST counterparts;docs/collections.mdstates the dual machine surface and documents the walk.Three deviations recorded by the implementer:
test/api.test.tshad to grow its pinned inventory (required consequence of new tools), thedocs/collections.mdintro claimed REST was the only machine path and is corrected, andquery_collection_rowsnormalizessortsdirection to'asc'at the call becauseRowQuery.sortstypes it as required while the zod schema keeps it optional. One review fix on top: the query tool description interpolatesFILTER_OPSinstead of restating the ops by hand.