Skip to content

feat(mcp): collection tools over MCP on the shared service layer - #106

Merged
ssalentin merged 7 commits into
mainfrom
feat/is-83-mcp-collections
Nov 15, 2026
Merged

ssalentin merged 7 commits into
mainfrom
feat/is-83-mcp-collections

Conversation

@ssalentin

Copy link
Copy Markdown
Owner

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 the CollectionStore singleton exactly like the REST routes under /api/v1/databases, so validation and the base_updated_at conflict behaviour are the same implementation, not a copy. CollectionError extends MdwikiError, so the existing MCP error wrapper renders 400/404/409 as isError JSON with current on conflicts. Zod encodes wire shape only and derives the filter ops from the store's FILTER_OPS constant. collection-write.ts stays out of the machine paths; it is the browser-UI gate.

Tests. test/collections-mcp.test.ts walks the acceptance over a real MCP transport (InMemoryTransport client/server pair) on a temp sqlite and a temp fixture space, including the 409 with current, validation parity proven against the REST route handler, and actor recording. test/api.test.ts grows its pinned tool inventory from 21 to 28. 467 tests pass (baseline 459 plus 8 new), svelte-check 0 errors, build green.

Verification lever. scripts/mcp-collections-walk.sh reruns 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):

MCP collection tools acceptance walk

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, the bad_values refusal for an unknown property, the delete and the scratch row's history with actors mcp (default) and evidence-walk.

Docs. The seven tools join the MCP inventories in the README and docs/tools.md with their REST counterparts; docs/collections.md states the dual machine surface and documents the walk.

Three deviations recorded by the implementer: test/api.test.ts had to grow its pinned inventory (required consequence of new tools), the docs/collections.md intro claimed REST was the only machine path and is corrected, and query_collection_rows normalizes sorts direction to 'asc' at the call because RowQuery.sorts types it as required while the zod schema keeps it optional. One review fix on top: the query tool description interpolates FILTER_OPS instead of restating the ops by hand.

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.
@ssalentin
ssalentin merged commit e6826d4 into main Nov 15, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant