Initial Commit

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

@@ -0,0 +1,98 @@
+# 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)
+
+- [x] 0.1 Confirm clean working tree (`git status`) and no in-flight worktrees with uncommitted work.
+- [x] 0.2 Account for every entry in `git worktree list`.
+- [x] 0.3 §0a Sync — fast-forward worktree to expected base SHA.
+- [x] 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
+
+- [x] 1.1 `proposal.md` with `## Impact` → `### Affected dependents` per §14a.
+- [x] 1.2 `design.md` covering architecture, transports, file layout, telemetry, trade-offs.
+- [x] 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.