Phase 05 Plan 03: MCP Stdio Server Summary

Newline-delimited JSON-RPC 2.0 stdio server over the shared dispatcher: probe-plus-initialize handling, six-tool unchanged-map routing, and a client-shaped end-to-end drive, with no tool logic in the surface.

Performance

• Duration: not tracked by executor (plan constraints forbid running gates)
• Started: 2026-10-22
• Completed: 2026-10-22
• Tasks: 3
• Files modified: 2 created, 0 modified

Accomplishments

• src/mcp/server.ts speaks newline-delimited JSON-RPC 2.0 over stdio with node:readline plus JSON only: one newline-terminated object per reply on stdout, all diagnostics on stderr, stop on stdin close, no new dependency (P5-D2)
• Answers server/discover and initialize with revision 2026-07-28, stateless per request, exactly as mcp.md Q5 records (P5-D9)
• Exposes all six tools via tools/list plus tools/call, converts each request into the ToolCall map unchanged, returns ToolDispatcher.call's ToolOutcome verbatim, and touches no dispatcher member except call (P5-D11)
• test/mcp/server.test.ts proves framing purity, both handshakes, six-tool unchanged routing in order, catalogue-faithful refusals, and a probe-first status-plus-write drive whose replies deep-equal the harness dispatcher's own outcomes with the shared realm active label

Task Commits

No per-task commits were made by the executor: the assignment forbids all git commands and commits, and the orchestrator commits between waves.

1. Task 1: stdio framing with stdout purity (P5-D2, P5-D9) — uncommitted (orchestrator commits)
2. Task 2: Revision handshake and six-tool routing over the dispatcher (P5-D9, P5-D11) — uncommitted (orchestrator commits)
3. Task 3: Stdio-client-shaped end-to-end drive (P5-D1, TOOL-05) — uncommitted (orchestrator commits)

Files Created/Modified

• src/mcp/server.ts - MCP stdio server (createMcpServer, MCP_PROTOCOL_VERSION, MCP_TOOL_DESCRIPTORS, McpDispatcher pick type); type-only dispatcher import, call is the sole member used
• test/mcp/server.test.ts - 10 TOOL-05 tests: framing purity (3), probe plus initialize (2), six-tool routing plus refusal plus P5-D11 source pin (3), client-shaped drive plus shared-label pin (2); in-memory PassThrough stdio, no real process

Decisions Made

• Refusals ride as result envelopes carrying the verbatim ToolOutcome: the catalogue code surfaces by construction with no server-added mapping decision, and the deep-equal refusal test pins the exact shape.
• Malformed lines take no stdout reply at all (stderr diagnostic only): a Parse error envelope would still be stdout traffic for unparseable bytes, so total purity is the stronger and simpler rule.
• The tools/call argument cross is { [name]: args } as ToolCall with validation deferred to the pipeline: the server checks only name membership and record shape, so schema authority stays in one place.
• notifications/initialized and other id-less messages are silently absorbed: JSON-RPC notifications take no reply, and answering one would break the one-reply-per-request shape the tests pin.

Deviations from Plan

None - plan executed exactly as written.

Issues Encountered

• Two built-in style reminders fired on write (local isRecord guard, new Promise executor, real-timer hang guards). All three were left as written: the guard is the module's single canonical boundary check, Promise.withResolvers is not in the ES2023 lib so it would fail typecheck, and the hang-guard race matches the established sibling pattern in test/acp/agent.test.ts while still awaiting the real server.closed signal.

User Setup Required

None - no external service configuration required.

Next Phase Readiness

• Plan 05-06 can run this server against the ACP agent over one makeHarness dispatcher for the outcome-equal equivalence proof; the drive helper pattern in test/mcp/server.test.ts shows the shape.
• The P5-D12 no-logic guard can extend its allowlist scan to src/mcp/server.ts: the module references none of the D-99 symbols and the P5-D11 source-pin test already proves the dispatcher-member half.
• Verification not run by executor (forbidden): orchestrator must run npx tsc -p tsconfig.json && node --test dist/test/mcp/server.test.js and grep the test titles for TOOL-05 per the plan's verification step.

---

Phase: 05-omp-plugin-mcp-and-acp-surfacesCompleted: 2026-10-22