Phase 4 — Hosted MCP server (streamable HTTP on /mcp)

P4 SHIPPED + live-verified. Blocker fixed forward: embed dereferenced contract at build time (contract.generated.ts) + no-FS-read test + drift gate. Live MCP client: tools/list=21, callTool listProducts real data, callTool createItem created BUILD-13 end-to-end. agent-p4-fix metrics: ~233,000 tokens across fix+close. Phase 4 done.

Phase 4 CLOSED. Hosted MCP server live at POST /mcp, verified end-to-end with a real MCP client (tools/list=21, tools/call listProducts + createItem both succeed; created BUILD-13 via MCP). The deployed-500 incident (BUILD-12) is fixed: contract now embedded at build time (src/mcp/contract.generated.ts), no runtime FS read, guarded by check-mcp-contract-drift.sh.

BLOCKED: merge to main clean (no-ff, no conflicts), all gates green (jest 100/100/100/100, tsc, eslint, all check-*.sh, check-pr-invariants), cdk deploy LasitavaProjectsStack succeeded (UPDATE_COMPLETE, confirmed via describe-stacks). Live MCP verify against POST /mcp FAILED at the initialize handshake: MCP SDK client (StreamableHTTPClientTransport) got HTTP 500. CloudWatch logs for McpFn (LasitavaProjectsStack-McpFnFE65A12E-pHky5j2XiVLu) show the real cause: Error: Failed to load OpenAPI contract from "/contract/openapi.yaml": ResolverError: Error opening file /contract/openapi.yaml: ENOENT: no such file or directory. Root cause: src/mcp/contractLoader.ts resolves DEFAULT_SPEC_PATH via path.join(__dirname, "..", "..", "contract", "openapi.yaml") — works in local/jest (real filesystem) but the esbuild NodejsFunction bundle for McpFn (infra/stacks/projects-stack.ts) only packages compiled JS, not the contract/ yaml tree, so it 404s at runtime in the deployed Lambda. DocsFn avoids this by embedding the contract as a generated TS module (src/lambda/docs/contractSite.generated.ts) instead of a runtime file read - McpFn needs the same treatment (embed/bundle the dereferenced contract, or add an esbuild copy step for contract/**). No MCP mutation was attempted/landed (failure was pre-tools/list, at initialize). Stopping here per standing instruction - not patching/redeploying without an explicit go-ahead. BUILD-5 NOT moved to Done.

START: Phase 4 close (Task 4.5). Merging feat/p4-mcp to main, batched local cdk deploy, then live MCP verify against POST /mcp.

4.4 done: CDK mcpFn + POST /mcp route (HttpApi constructed early for self-hop base url, no circular dep), least-privilege (no table grant), /mcp allowlisted in parity, bridge FakeRes.destroy hardening. agent-p4-cdk metrics: 130,185 tokens, ~14 min, 349 tests at 100 percent. Next: 4.5 batched deploy + live MCP verify (tools/list + tools/call).

FINISH Task 4.4: mcpFn + POST /mcp wired into projects-stack.ts. HttpApi moved before the Lambda block so mcpFn env can self-ref httpApi.apiEndpoint (MCP_API_BASE_URL) -- confirmed no circular CFN dep (synth clean, Fn::GetAtt on ApiEndpoint into env, DependsOn only ServiceRole). mcpFn gets NO table grant (least privilege, self-hops via HTTP). /mcp added to NON_CONTRACT_ROUTES, parity green. Allowlist enumeration: ApiGatewayV2(Api/Integration/Route/Stage), DynamoDB::Table, IAM(Policy/Role), Lambda(Function/Permission) -- no new type. Lambda count 9->10, IAM Policy count unchanged at 8. Plus FakeRes.destroy no-op hardening in bridge.ts (guards internal SDK error path) + stale comment fix, TDD unit test added. Full suite 100/100/100/100 (38 suites/349 tests), tsc clean, eslint clean, all check-*.sh + check-pr-invariants green. 2 commits on feat/p4-mcp: e3ea000 infra wiring, d578e1a bridge hardening. No live deploy (4.5 not in scope).

Started Task 4.4: wire mcpFn Lambda + POST /mcp route into projects-stack.ts (HttpApi moved earlier for self-hop base url), plus FakeRes.destroy hardening.

4.2+4.3 done: Lambda event-bridge (fake req/res over the SDK Hono-based streamable-HTTP transport, rawHeaders + Accept/Content-Type/Host handling) + hosted MCP handler (fresh stateless JSON transport per invoke, self-hop client). tools/list returns 21 tools, tools/call dispatches, bad requests never 500. agent-p4-bridge metrics: 214,068 tokens, ~21.6 min, 345 tests at 100 percent. In review; next 4.4 CDK /mcp route.

FINISH tasks 4.2+4.3. Shipped: src/lambda/mcp/bridge.ts (event-bridge, 9 tests) + src/lambda/mcp/handler.ts (hosted entrypoint, 9 tests), both 100/100/100/100, full suite 345/345 green, ratchet held, tsc+eslint+all check-*.sh clean. Key finding: v1.30.0 StreamableHTTPServerTransport wraps hono getRequestListener not raw http-shaped as the plan assumed -- bridge normalizes Accept/Content-Type/Host headers accordingly (confirmed via source read + Context7). No CDK route/Lambda yet (4.4). No transition -- feature item stays as-is per protocol.

Green commit: Task 4.3 hosted MCP handler (src/lambda/mcp/handler.ts + 9 tests, 100/100/100/100). Three layers: handleMcp (fresh transport/server per call), handleMcpRequest (real contract+tools, injected client), handler (real self-hop client + actorFromEvent). tools/list returns all 21 real contract ops in test.

Green commit: Task 4.2 Lambda event-bridge (src/lambda/mcp/bridge.ts + 9 tests, 100/100/100/100). Confirmed via source read the Node transport wraps hono getRequestListener, not raw http-shaped; normalized Accept/Content-Type/Host headers accordingly.

Started P4 tasks 4.2+4.3: Lambda event-bridge + hosted MCP entrypoint (stateless streamable HTTP).

P4.1 done: MCP protocol core (listToolsResult strips handler; callTool is isError-safe, never throws over JSON-RPC; buildMcpServer wiring). agent-p4-server metrics: 80,716 tokens, ~8 min, 327 tests at 100 percent. Next: 4.2 Lambda bridge + real entrypoint (streamable HTTP transport).

Finished P4.1 MCP protocol core: src/mcp/server.ts (listToolsResult/callTool/buildMcpServer), 100/100/100/100, ratchet untouched, all gates green. Branch feat/p4-mcp, not merged (task-only, not transitioning BUILD-5).

Green: feat(mcp) protocol core (listTools/callTool/buildMcpServer), src/mcp/server.ts, 100/100/100/100, all gates pass.

Green: docs: phase 4 hosted MCP plan committed.

Started P4.1 MCP protocol core (feat/p4-mcp).

P4 hosted MCP server resumes right after the item-detail view ships (single writer on the repo tree).

MCP protocol core (server.ts listTools/callTool) under review; bridge + CDK wiring next.