feat(harness): add MCP client - #79

Summary

Adds the low-level MCP client the MCP service will build on: one scoped connection to one server, over stdio or Streamable HTTP, through the official SDK (@modelcontextprotocol/client 2.3.1).

• src/mcp/client.ts: McpClient.connect(...) returns a Connection with tools(), resources(cursor?), resourceTemplates(cursor?), readResource(uri), callTool(...) and onToolsChanged / onResourcesChanged / onSessionExpired / onClose callbacks.

  • Timeouts: 30 s to start, 60 s per request, restarted by progress.
  • Retries: HTTP connect and list/read retry transient failures; tool calls never retry.
  • Errors: HTTP session expiry becomes SessionExpiredError, auth failures become NeedsAuthError.
  • Closing the scope ends the HTTP session and never fires onClose.

• src/mcp/stdio.ts: stdio transport. Servers run on the host in their own process group.

  • A crash is reported with the exit code and the stderr tail.
  • Closing ends stdin, waits 2 s, then SIGTERM and SIGKILL to the group.
  • An exit hook stops leftover servers if the host exits without closing them.

• src/mcp/content.ts: tool results as model text and image content. src/mcp/error.ts: tagged errors.

• SDK validation: list pages and tool results (against a tool's outputSchema) are validated by the SDK.

• Process.terminate: the process-group stop sequence moves out of the host shell into sandbox/utils/process.ts, shared by the host shell and the stdio transport.

• Server logging: onLog receives the server's notifications/message entries, and src/mcp/log.ts (McpLog) appends them one line per entry, rotating the file past 5 MB.

• Readable validation errors: the SDK's multi-line issue list becomes one line, Invalid result for <method>: <path>: <message>; the raw list is logged at debug level.

• Tracing: entry points use Effect.fn (McpClient.connect, McpStdio.make, McpLog.make), and each request gets a span named McpClient.<method>.

No user-facing surface yet: config, the MCP service, scoping and tool wiring come in follow-up PRs stacked on this one.

Test plan

• test/mcp.client.test.ts: 29 scenarios against real stdio and Streamable HTTP fixture servers.
  • Process behaviour: crash mid-call, process-group cleanup, a server that ignores SIGTERM.
  • Protocol: message framing and the 16 MiB limit, progress keeping a call alive, cancellation.
  • HTTP: transient retry, connection refused, session expiry, 401 with and without an auth provider.
  • Data: roots, resources and paging, output-schema validation, malformed list pages, server logging and log rotation.
  • Error messages: a missing command or working directory.
  • Ends with __artifacts__/mcp.client.json, stable across runs.
• Sandbox tests still pass after the Process.terminate extraction
• vp check and vp run typecheck
• Node SEA bundle with the SDK (checked once the follow-up PRs land)

🤖 Generated with Claude Code