ADR-002: MCP as an inbound adapter over the shared core
Date: 2026-07-04 Status: Decided
Context
Section titled “Context”Agents need the engine’s capabilities: scaffold a project, read and write its data files, run the audit, generate the artifacts. The engine already exposes these through inbound ports consumed by the REST adapter, the SPA, and the CLI.
Decision
Section titled “Decision”The MCP server is a third inbound adapter, mounted at /mcp on the same FastAPI application using stateless streamable HTTP. Tools mirror the inbound ports and serialize through the same DTO mappers as the REST adapter, so the OpenAPI contract stays the single serialization surface. Binary transfer (artifact downloads, ZIP export and import) stays on the HTTP API; tools report where the artifacts live. One prompt, estimate-project, carries the multi-step estimation runbook parametrized with the project’s live state.
Rationale
Section titled “Rationale”- Every door goes through the same use cases, so slug validation, path containment, and the audit gate behave identically whether a write arrives from the SPA, REST, the CLI, or an agent.
- Mirroring the HTTP mappers avoids a parallel MCP-only response shape that would drift.
- The same fail-closed auth gate (ADR-001) covers
/mcp; no second credential story.
Alternatives considered and rejected
Section titled “Alternatives considered and rejected”- A sidecar MCP service calling the REST API: a second deployable with its own auth story, re-serializing what the app already serves.
- Streaming workbooks through MCP tools: base64 spreadsheets through an agent context serve no one; the HTTP download path already exists.