Phase 1: MCP design, contracts, and ADR

[neuromechanist]

Summary

Phase 1 of epic #1065 (issue #1293): design doc, zod contracts for the zarr index v3 reader and the MCP server's wire vocabulary, and a transport/decode spike. No route exists yet -- phases 2-4 (#1294-#1296) build the host fork and the tools.

Closes #1293
Part of epic #1065

Deliverables

• .context/mcp-server-design.md -- purpose/constraints, protocol revision and dual-era behavior (verified against a real wrangler dev run), host/routing, the six-tool surface, envelope/recipe field tables, compute-minimization rules and cache key scheme, analytics event shape, dependency table with spike verdicts, client compatibility table, phase 2-5 open items.
• shared/contract/zarr-index.ts -- .passthrough() zod reader mirroring shared/zarr-index.schema.json, plus test/contract-zarr-index.unit.test.ts (every real fixture passes both Ajv and the zod reader; three mutations fail both; the lower-bound-vs-closed-contract divergence is itself tested).
• shared/contract/mcp.ts -- the provenance envelope, buildReadRecipe(), and one input/output schema pair per tool, plus test/contract-mcp.unit.test.ts.
• Fixtures captured live with curl -sL -A "nemar-cli/mcp-phase1": zarr-index-nm000329-slice.json, zarr-index-on003392-meg-sss-slice.json (the one live MEG store carrying an ADR 0028 sss object), zarr-catalog-slice.json, zarr-array-level0.zarr.json, zarr-array-view1.zarr.json.
• backend/spike/mcp-transport/ -- a self-contained Worker (own package.json/wrangler.toml) proving the transport and settling decision 7's decode path under a real wrangler dev run. Replaced by phase 2 (Phase 2: MCP host fork and discovery tools #1294) and deleted in that PR.

Spike measurements

Measurement	Result
Transport, both protocol eras	server/discover, tools/list, tools/call (2026-07-28 envelope), legacy initialize, legacy tools/call with no envelope, -32020 (disagreeing Mcp-Name, missing Mcp-Method), GET/DELETE 405 -- all correct
Bundle size, with numcodecs	1447.36 KiB / gzip 465.24 KiB
Bundle size, without numcodecs	843.69 KiB / gzip 263.17 KiB (~604 KiB dead weight, see below)
tools/list wall time (local)	2.1-2.5 ms
tools/call decode_chunk wall time (local)	4.5-5.7 ms
Decode path (a): numcodecs WASM Blosc	Fails. RuntimeError: Aborted(CompileError: WebAssembly.instantiate(): Wasm code generation disallowed by embedder). Dynamic WASM compilation from a runtime-fetched buffer is exactly what workerd's embedder blocks; the npm package also ships no .wasm file to statically import instead.
Decode path (b): pure JS (blosc2 header + fzstd + unshuffle)	Works, matches a Python-derived ground truth exactly (first/last 16 values, full-array sum, an order-sensitive weighted checksum).
Chosen decode path	(b) -- confirmed on evidence, not preference; fzstd also serves events.parquet via hyparquet-compressors.

Full derivation (including how fixtures/chunk.bin was captured via two range requests against the shard's trailing index) is in backend/spike/mcp-transport/README.md.

zod / hono gate (decision 10)

Attempted per plan step 5: bump zod to ^4.2.0 (root + backend) and hono to ^4.11.4 (backend), then bun install && bun test && bun run typecheck.

• hono bump: kept. Unconditional per decision 10; bun run typecheck and the backend suite are green.
• zod bump: reverted. bun run typecheck went green after two mechanical fixes (z.record(valueSchema) -> z.record(z.string(), valueSchema) in src/lib/upload-progress.ts and two call sites in backend/src/routes/admin/doi.ts -- kept regardless of the revert, since the two-arg form is valid under zod 3 too). But bun test surfaced a real incompatibility: backend/test/openapi-document.test.ts's drift guard failed with strictVersionTagSchema.openapi is not a function. Traced to a genuine zod-4/@asteasolutions/zod-to-openapi order dependency -- extendZodWithOpenApi(z)'s prototype patch is no longer retroactive under zod 4, so a contract schema imported before the patch runs never gets .openapi(). Bumping zod-to-openapi itself to 9.1.0 (which declares zod: "^4.0.0" as a peer) did not change this. A per-file import reorder fixes the standalone script, but bun test runs test/ and backend/test/ in ONE process, and dozens of other files import shared/contract/* before this test's own module graph runs -- closing that gap for real needs a bunfig.toml test-preload hook the repo does not have today. That's new test infrastructure, not a mechanical fix, so per decision 10's fallback the bump was reverted: this phase's contracts stay on zod 3, and the MCP SDK's own nested zod 4 copy is what the SDK uses (the "two-copy risk" decision 10 named). Full derivation in .context/mcp-server-design.md section 10.1.

bun test at HEAD: 5551 pass / 111 skip / 49 fail, identical failure set to a baseline run before any of this PR's dependency changes (diffed line-for-line -- the one difference between the two runs was the openapi drift-guard failure, which the revert fixed). Every remaining failure is a pre-existing environment gap in this worktree (missing test/.env.test / TEST_ADMIN_API_KEY / TEST_USER_API_KEY, missing AWS credentials, one D1 SQLite table gap in an ephemeral test context) -- none touch zod, hono, or anything this PR changes. bun run typecheck is clean.

ADR 0050

Omitted from this PR per decision 11. origin/dev does not yet carry ADR 0049 (PR #1292 is still open) -- re-checked immediately before opening this PR. The decision text (protocol/stack, access, compute-minimization, decode path, and the zod/hono gate outcome) lives in .context/mcp-server-design.md instead; phase 5 files the ADR once #1292 lands.

Deviations from the plan

1. The epic base branch feature/issue-1065-epic-mcp-server did not exist on origin. It existed only as a local branch in a sibling worktree (/Users/yahya/Documents/git/nemar/epic-mcp-server), unpushed. Pushed it as-is (no new commits, just the existing ref) so this PR could target it as specified, rather than redesigning around a different base.
2. The zod repo-wide bump was reverted (see above) -- decision 10 explicitly anticipated and provided for this outcome ("otherwise author the MCP tool schemas against the SDK's own zod 4 and keep contracts on zod 3, documenting the two-copy risk").
3. ADR 0050 omitted -- decision 11's own numbering rule, confirmed against origin/dev at PR time.

Test plan

• bun test test/contract-zarr-index.unit.test.ts test/contract-mcp.unit.test.ts -- green
• bun run typecheck -- green
• bash backend/spike/mcp-transport/smoke.sh -- all required checks PASS
• bun test test/adr-index.unit.test.ts -- green (no ADR added this PR, still consistent)
• Full bun test at repo root -- green modulo pre-existing environment-gap failures (see above), diffed against a pre-change baseline to confirm no regressions

[github-actions]

📦 Package Preview

Your package is ready to test!

bun install -g nemar-cli@PR1314

Version: 0.9.17-PR1314.d0cbba6
Commit: d0cbba6

---

_{🤖 Updated on each push.}

[neuromechanist]

Review pass (code, tests, comments, types, silent failures) folded into three commits on top of the implementer's work:

• Lead corrections to the design doc: the rendered PNG is cached keyed by width (plan decision 4), an over-cap taste is rejected rather than downgraded, and the zarrita snippet uses the FetchStore form.
• Contract fixes: a catalog row's null DOI or license is authoritative over the index's stale hoisted copy; layout templates are filled in one pass and a template lacking a needed placeholder throws; buildReadRecipe takes Zarr's own data_type through a new zarrArrayMetadataSchema; a taste requires channels (a live MEG store has 320, so an omitted list cannot be bounded); sss iff derived is enforced on the store reader and the envelope; ranges enforce end >= start; flagToBoolean is the one 0/1/null conversion; min_participants is dropped because no server-side filter exists.
• Spike hardening: the decoder refuses a non-int16 typesize, a zero blocksize, a cbytes mismatch, out-of-range offsets, and an odd decoded byte length; smoke.sh asserts HTTP status on every call. Smoke run after the change: 10/10 PASS.
• Tests: 26 to 51 in the two contract files. Every tool input default and cap, both read_window output branches, the catalog document, the real zarr.json fixtures, and each envelope fallback branch are now pinned.
• Filed zod 4 bump is blocked by zod-to-openapi's prototype patch order #1316 for the zod 4 bump blocker (zod-to-openapi prototype patch order). Section 12 of the design doc records how phase 2 registers tools across the zod 3 / zod 4 split.