feat(api): streamable-HTTP MCP server endpoint (/api/mcp, PAT-authed) #332

Merged

james merged 1 commit from 331-mcp-endpoint into main 2026-06-28 22:06:07 +00:00

Conversation 1 Commits 1 Files changed 5 +774 -2

james commented 2026-06-28 22:00:36 +00:00

Owner

Copy link

Exposes Carol's shared #51 agent tool registry to external agent runtimes over a streamable-HTTP MCP endpoint at POST /api/mcp (#331), so a user can paste a Carol PAT into Claude Code / opencode / a custom MCP client and read + write their own data. Implements ADR-0029/ADR-0030.

What's in it

• POST /api/mcp — JSON-RPC 2.0, single application/json responses (no SSE). Handles initialize / notifications/initialized / ping / tools/list / tools/call. PAT-authed via the existing getAuthIdentity (same pattern as /api/agent/proposals/*); no token → 401. Stateless (no Mcp-Session-Id) — every request re-authenticates.
• tools/list = the #51 registry (listTools()) + commit_proposal/reject_proposal meta-tools. Each tool's zod schema → JSON Schema via zod v4's z.toJSONSchema (io: "input" so .transform() DTOs represent what a client sends; allOf-of-objects from idSchema.and(bodySchema) flattened to satisfy MCP's inputSchema.type === "object").
• tools/call — read tools return data; write tools return a ProposedChange and never mutate; commit_proposal is the only mutator (the #51 commit path) and writes the audit event. AgentError/validation failures become MCP isError results, not 500s; unknown tool/method → JSON-RPC -32602/-32601.

Safety

• Per-user scoping is structural: userId comes only from the PAT, tools take no user_id (asserted by test), so cross-user access is unrepresentable; a cross-user commit_proposal inherits #51's 404 (surfaced as an isError with status: 404).

Decisions

• Minimal handler over the official SDK — @modelcontextprotocol/sdk's StreamableHTTPServerTransport is built on Node http req/res + session bookkeeping that doesn't fit a single Next App Router handler returning a Web Response; the method set is small and fully testable in-process. No new dependencies.
• /api/mcp is JSON-RPC, not a typed REST route → added to the OpenAPI coverage EXCLUDED_PATHS (like /api/openapi.json), not the spec. Short "Connect an external agent (MCP)" note added to the README; no new env var.

Verification

• @carol/api typecheck + lint clean; openapi:check up to date · coverage 108 pairs; @carol/api-client unaffected.
• Full suite on BOTH engines: 1055 passed / 0 skipped — ran an ephemeral Postgres so the MCP tools/call data-layer paths (via #51's repositories) are proven on Postgres too. New tests/api/mcp.test.ts (14 tests) drives the real PAT Bearer path: 401 without a token, initialize capabilities/protocolVersion, tools/list includes registry + meta-tools with no user_id, read round-trip, write returns a proposal + leaves the DB unchanged, commit_proposal applies + audits, cross-user commit → 404, invalid args → isError.

Caveat for review

The protocol surface is unit-tested in-process but not yet verified against a live Claude Code connection (no client in CI) — worth a manual smoke test (paste a PAT into Claude Code's MCP config) before relying on it. Stateless single-JSON-response mode is spec-compliant; if a specific client requires Mcp-Session-Id or SSE, that's a small follow-up.

Closes #331

🤖 Generated with Claude Code

Exposes Carol's shared #51 agent tool registry to external agent runtimes over a streamable-HTTP MCP endpoint at `POST /api/mcp` (#331), so a user can paste a Carol PAT into Claude Code / opencode / a custom MCP client and read + write their own data. Implements ADR-0029/ADR-0030. ## What's in it - **`POST /api/mcp`** — JSON-RPC 2.0, single `application/json` responses (no SSE). Handles `initialize` / `notifications/initialized` / `ping` / `tools/list` / `tools/call`. **PAT-authed** via the existing `getAuthIdentity` (same pattern as `/api/agent/proposals/*`); no token → `401`. Stateless (no `Mcp-Session-Id`) — every request re-authenticates. - **`tools/list`** = the #51 registry (`listTools()`) + `commit_proposal`/`reject_proposal` meta-tools. Each tool's zod schema → JSON Schema via **zod v4's `z.toJSONSchema`** (`io: "input"` so `.transform()` DTOs represent what a client sends; `allOf`-of-objects from `idSchema.and(bodySchema)` flattened to satisfy MCP's `inputSchema.type === "object"`). - **`tools/call`** — read tools return data; **write tools return a `ProposedChange` and never mutate**; `commit_proposal` is the only mutator (the #51 commit path) and writes the audit event. `AgentError`/validation failures become MCP `isError` results, not 500s; unknown tool/method → JSON-RPC `-32602`/`-32601`. ## Safety - Per-user scoping is structural: `userId` comes **only** from the PAT, tools take no `user_id` (asserted by test), so cross-user access is unrepresentable; a cross-user `commit_proposal` inherits #51's **404** (surfaced as an `isError` with `status: 404`). ## Decisions - **Minimal handler over the official SDK** — `@modelcontextprotocol/sdk`'s `StreamableHTTPServerTransport` is built on Node `http` req/res + session bookkeeping that doesn't fit a single Next App Router handler returning a Web `Response`; the method set is small and fully testable in-process. **No new dependencies.** - `/api/mcp` is JSON-RPC, not a typed REST route → added to the OpenAPI coverage `EXCLUDED_PATHS` (like `/api/openapi.json`), not the spec. Short "Connect an external agent (MCP)" note added to the README; no new env var. ## Verification - `@carol/api` typecheck + lint clean; `openapi:check` up to date · coverage 108 pairs; `@carol/api-client` unaffected. - **Full suite on BOTH engines: 1055 passed / 0 skipped** — ran an ephemeral Postgres so the MCP `tools/call` data-layer paths (via #51's repositories) are proven on Postgres too. New `tests/api/mcp.test.ts` (14 tests) drives the real PAT Bearer path: 401 without a token, `initialize` capabilities/protocolVersion, `tools/list` includes registry + meta-tools with no `user_id`, read round-trip, write returns a proposal + leaves the DB unchanged, `commit_proposal` applies + audits, cross-user commit → 404, invalid args → `isError`. ## Caveat for review The protocol surface is unit-tested in-process but **not yet verified against a live Claude Code connection** (no client in CI) — worth a manual smoke test (paste a PAT into Claude Code's MCP config) before relying on it. Stateless single-JSON-response mode is spec-compliant; if a specific client requires `Mcp-Session-Id` or SSE, that's a small follow-up. Closes #331 🤖 Generated with [Claude Code](https://claude.com/claude-code)

james added 1 commit 2026-06-28 22:00:37 +00:00

feat(api): streamable-HTTP MCP server endpoint (/api/mcp, PAT-authed) ... 2872ec6b06

Exposes Carol's shared #51 agent tool registry to external agent runtimes
over a streamable-HTTP MCP endpoint at POST /api/mcp, PAT-authed via
getAuthIdentity (#331). JSON-RPC 2.0 with single application/json
responses (no SSE); implements initialize / notifications/initialized /
ping / tools/list / tools/call.

tools/list returns the #51 registry plus commit_proposal/reject_proposal
meta-tools. Read tools return data; write tools return a ProposedChange
and never mutate — commit_proposal is the only mutator and writes the
audit event. Per-user scoping is structural: the userId comes only from
the PAT, tools take no user_id, so cross-user access is unrepresentable
and a cross-user commit returns 404.

Minimal spec-compliant handler chosen over the official SDK (its
Node-http transport doesn't fit a Next Web-Response handler); no new
deps (zod v4's z.toJSONSchema converts tool schemas). Excluded from the
OpenAPI coverage gate (JSON-RPC, not a typed REST route). Tests run on
both DB engines through the #51 data layer.

Closes #331

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

forgejo-actions commented 2026-06-28 22:05:28 +00:00

Copy link

📊 Test coverage

Patch coverage: no testable lines changed.

Overall (app/, lib/, db/, excluding UI per ADR-0019):

Metric	Value	Soft target
Lines	78.1% ✅	≥ 50%
Branches	69.5% ⚠️	≥ 75%
Functions	78.5%	informational

Soft thresholds per ADR-0019. Coverage is informational and does not block merge.

<!-- coverage-comment --> ## 📊 Test coverage **Patch coverage:** no testable lines changed. **Overall** (`app/`, `lib/`, `db/`, excluding UI per ADR-0019): | Metric | Value | Soft target | |---|---|---| | Lines | 78.1% ✅ | ≥ 50% | | Branches | 69.5% ⚠️ | ≥ 75% | | Functions | 78.5% | informational | Soft thresholds per [ADR-0019](docs/adr/0019-coverage-soft-targets.md). Coverage is informational and does not block merge.

james merged commit 2a17d977cf into main 2026-06-28 22:06:07 +00:00

james deleted branch 331-mcp-endpoint 2026-06-28 22:06:08 +00:00

james referenced this pull request from a commit 2026-06-28 22:06:08 +00:00

Merge pull request 'feat(api): streamable-HTTP MCP server endpoint (/api/mcp, PAT-authed)' (#332) from 331-mcp-endpoint into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area:auth

Authentication and authorization

  

area:ci

Forgejo Actions, build, test, security, release

  

area:db

Database abstraction, migrations, persistence

  

area:infra

Containerization, deployment, foundational tooling

  

area:native

React Native app (Android + Linux Flatpak)

  

area:pwa

PWA / web frontend

  

area:service

Backend service, API routes, persistence

  

epic

High-level tracker; links several feature tickets

  

feature

A user-facing feature

  

foundation

Foundational work that other tickets build on

No labels

area:auth

area:ci

area:db

area:infra

area:native

area:pwa

area:service

epic

feature

foundation

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

james/carol!332

No description provided.