suaveplan/openspec/archive/2026-05-25-enterprise-mcp/tasks.md

Tasks: enterprise-mcp

Change ID: enterprise-mcp Package: @suaveplan/mcp Target path: packages/devtools/tooling/mcp Prerequisites on Verdaccio: @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/logger, @suaveplan/opentelemetry.

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status) and no in-flight worktrees with uncommitted work.
• 0.2 Account for every entry in git worktree list.
• 0.3 §0a Sync — fast-forward worktree to expected base SHA.
• 0.4 Read CLAUDE.md, AGENTS.md, openspec/AGENTS.md, openspec/project.md, /mnt/s/web/suaveplan/enterprise/mcp.md, and the main-branch source.

1. OpenSpec authoring

• 1.1 proposal.md with ## Impact → ### Affected dependents per §14a.
• 1.2 design.md covering architecture, transports, file layout, telemetry, trade-offs.
• 1.3 specs/mcp/spec.md — every requirement carries a **Verified by:** line at draft time.

2. Scaffold the package

• 2.1 Create packages/devtools/tooling/mcp/ with package.json (0.1.0, sideEffects: false, exports map), tsconfig.lib.json, vite.config.ts, vitest.config.ts, README.md.
• 2.2 Add mcp to the tooling plugin in scripts/folder-reorg/assignment.yml.

3. Error codes

• 3.1 src/error-codes/error-codes.ts — MCP_CODES = defineCodes("MCP", […]) + MCPError / MCPTransportError / MCPProtocolError extending SuaveplanError<MCPCode>.
• 3.2 error-codes.test.ts — namespacing, leaves, reachability harness.
• 3.3 error-codes.md.

4. Wire-type schemas

• 4.1 src/schemas/schemas.ts — Zod schemas for every wire type (JSON-RPC envelopes + every MCP method's params & result).
• 4.2 schemas.test.ts.
• 4.3 schemas.md.

5. Telemetry + events

• 5.1 src/telemetry/telemetry.ts — meter @suaveplan/mcp, three instruments, getter/reset helpers for tests.
• 5.2 src/events/events.ts — MCPEventMap declaration.
• 5.3 Tests + docs.

6. JSON-RPC dispatcher

• 6.1 src/jsonrpc/dispatcher/dispatcher.ts — id allocator, pending-request map, request/notify/handler registry, cancellation, timeout.
• 6.2 Tests covering correlation, abort, cancel-on-notify, timeout, transport-close rejection, method-not-found, invalid-params.
• 6.3 dispatcher.md.

7. Transports

• 7.1 src/transport/transport/ — interface + base.
• 7.2 src/transport/in-memory/in-memory.ts — InMemoryTransport.pair().
• 7.3 src/transport/stdio/stdio.ts — newline-delimited JSON over injectable AsyncIterable<Uint8Array> + writable handle.
• 7.4 src/transport/http-sse/http-sse.ts — injectable fetchImpl + eventSourceImpl.
• 7.5 Tests + docs for each.

8. MCPServer

• 8.1 src/server/mcp-server/mcp-server.ts — registration, lifecycle, authorize, sampling/completion providers, abort, progress, resource subscriptions, fan-out.
• 8.2 mcp-server.test.ts (≤500 lines) covering every scenario in the spec delta.
• 8.3 mcp-server.md.

9. MCPClient

• 9.1 src/client/mcp-client/mcp-client.ts — connect (initialize handshake), refreshes, callTool / readResource / getPrompt / complete / subscribeResource, sampling + roots providers, progress forwarding, abort.
• 9.2 mcp-client.test.ts (≤500 lines).
• 9.3 mcp-client.md.

10. End-to-end test

• 10.1 src/e2e/handshake.test.ts — full round-trip across every MCP method via InMemoryTransport.pair().

11. Package barrel + docs

• 11.1 src/index.ts — explicit named re-exports only (§6a).
• 11.2 Root README.md covering quick-start, transport comparison, API table, error codes.

12. Verification

• 12.1 bunx turbo lint --filter=@suaveplan/mcp — green.
• 12.2 bunx turbo typecheck --filter=@suaveplan/mcp — green.
• 12.3 bunx turbo test --filter=@suaveplan/mcp — green.
• 12.4 bunx turbo build --filter=@suaveplan/mcp — green.
• 12.5 bunx turbo test:coverage --filter=@suaveplan/mcp — 100 % statements/branches/functions/lines.
• 12.6 grep -rnE "from ['\"](vitest|bun:test)['\"]" packages/devtools/tooling/mcp/src/ — zero output.
• 12.7 grep -rnE "from \"node:" packages/devtools/tooling/mcp/src/ — zero output.
• 12.8 bun scripts/folder-reorg/generate-manifest.ts — MANIFEST.md regenerated.

13. Archival

• 13.1 Flip @suaveplan/mcp row in STATUS.md from – to ✅ with the README one-liner.
• 13.2 Fold openspec/changes/enterprise-mcp/specs/mcp/spec.md into openspec/specs/mcp/spec.md.
• 13.3 Move openspec/changes/enterprise-mcp/ to openspec/archive/2026-05-25-enterprise-mcp/.

14. Commit

• 14.1 Branch feat/migrate-mcp already created; commit per feat(mcp): migrate … + Claude co-author footer. Do NOT push.