# 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.