@12-apps/mcp 3.0.0 → 3.2.0

package/ADOPTING.md

@@ -109,11 +109,14 @@ library updates, every host updates with **no app changes**. Same contract
     FENCED: a failing directory can never turn a valid grant into a 500, and nothing
     about the attempt is logged, because the only values in hand are an email and a
     client id.
-11. **Disconnecting means BOTH halves.** `connections.revokeByHost(...)` returns the
-    OAuth client ids it revoked, and the caller must then
-    `refreshTokens.revokeLiveForClient(email, clientId)` for each — a host holding a
-    live refresh token simply rotates its way back in and the card lights green on
-    the next grant. Neither half invalidates an outstanding ACCESS token: those are
+11. **Disconnecting means BOTH halves — call `disconnectAiHost`, not the stores.**
+    `connections.revokeByHost(...)` ends the rows and returns the OAuth client ids
+    behind them, and every live refresh token of those clients must be ended in the
+    same act — a host holding a live refresh token simply rotates its way back in
+    and the card lights green on the next grant. Since 12-48 the rule IS a
+    function: `disconnectAiHost(stores, { userId, email }, host)` does both and
+    reports what it ended, so a host cannot import one half without the other.
+    Neither half invalidates an outstanding ACCESS token: those are
     self-contained JWTs, so a disconnected host keeps working for at most their
     15-minute TTL and can then obtain nothing further.
 12. **These bodies are NOT the `{ data }` envelope.** A 302 with a `Location`, RFC
@@ -153,6 +156,38 @@ library updates, every host updates with **no app changes**. Same contract
 | POST | `/api/oauth/token` | `authorization_code` (single-use, PKCE-verified, bound `redirect_uri`) and `refresh_token` (rotated, client-bound, narrow-only scope) |
 | POST | `/api/oauth/register` | 201 RFC 7591 client information; the secret exactly once, hashed at rest |
 
+## The MCP transport (`/api/mcp`)
+
+`handleMcpJsonRpc` is the JSON-RPC 2.0 request half of the Streamable HTTP
+transport: the envelope, the method table (`initialize`, `ping`, `tools/list`,
+`tools/call`), the error codes and the notification convention. The host keeps
+what is its own — the server's name, its advertised surface version, and the
+`instructions` an agent reads on connect:
+
+```ts
+import { handleMcpJsonRpc, UNAUTHORIZED_CODE } from '@12-apps/mcp';
+
+const response = await handleMcpJsonRpc(body, registry, auth, {
+  serverInfo: { name: 'example-host', version: `${MCP_SURFACE_VERSION}.0.0` },
+  instructions: 'Resolve the tenant with `listUserTenants` before acting.',
+});
+```
+
+Three rules the signature enforces rather than documents:
+
+- **Discovery stays open.** `auth` is `null` when the request carried no valid
+  bearer; only `tools/call` refuses, with `UNAUTHORIZED_CODE` (-32001), which the
+  host maps to HTTP 401. A client can read the surface before it has a token.
+- **`null` means "no reply".** Notifications (`notifications/*`) return `null`,
+  and the host must send no body for them.
+- **A malformed payload is answered, not thrown.** A `null` batch element or an
+  object with no `method` returns -32600, so one bad element cannot 500 the route.
+
+`serverInfo.version` is the ONLY signal a connected client gets that the tool
+surface moved — this transport has no server→client stream, so
+`capabilities.tools` deliberately does not claim `listChanged`. Pair it with the
+surface lock (`mcp:generate`) so forgetting the bump is a build error.
+
 ## Minimal host (Hono)
 
 ```ts
@@ -234,10 +269,18 @@ Deliberate deltas to reconcile:
 
 ## What deliberately did NOT move into the package
 
-- **The account/connection SCREENS' endpoints** (`GET/DELETE
-  /api/account/mcp-connections`) — they mix session resolution, published plugin
-  URLs and a logger. The stores they need (`listActive`, `revokeByHost`,
-  `revokeLiveForClient`) are all here; the route is a follow-up.
+- **The account/connection SCREENS' route files** (`GET/DELETE
+  /api/account/mcp-connections`) — they answer in the HOST's app-wide response
+  envelope and mix its session resolution, published plugin URLs and logger, so
+  the handler stays host code (unlike the OAuth endpoints, whose shapes are
+  fixed by RFC — rule 12 — these are ordinary host API routes). What DID move
+  (12-48) is the operations under them: `listAiConnections` (the stored open
+  `host` string narrowed to the package's own `AiProvider` union) and
+  `disconnectAiHost`, which owns the disconnect's both-halves rule — revoke the
+  connection rows AND end every live refresh token of each returned client id in
+  one call. A host that imports the disconnect cannot get only half of it; half
+  is the failure mode where the assistant rotates its live token and the card
+  the user just disconnected lights green again on the next grant (rule 11).
 - **The MCP registry itself** — which endpoints become tools, their annotations
   and redactions, is the host's catalogue. The package generates, dispatches and
   gates it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/mcp",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "type": "module",
   "description": "App-agnostic MCP server core: generate one MCP tool per OpenAPI operation and proxy each call carrying the caller's bearer token (permission passthrough). Also ships the OAuth 2.1 authorization server (./oauth, ./hono: register/authorize/token, JWKS and both .well-known documents), the package-owned Prisma partial + migration for its three tables, the mcp:generate/mcp:check (./generate) and mcp:coverage (./coverage) gates, and the reusable AI-connect onboarding UI (./react).",
   "exports": {
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@12-apps/onboarding": "^2.0.0",
-    "@12-apps/rbac": "^4.0.0",
+    "@12-apps/rbac": "^4.0.1",
     "@12-apps/ui": "^5.0.0",
     "@mui/icons-material": "^6.5.0",
     "jose": "^6.1.3",

package/src/index.ts

@@ -44,6 +44,19 @@ export {
   type McpToolDescriptor,
   type McpToolResult,
 } from "./server/registry";
+// The JSON-RPC 2.0 request half of the Streamable HTTP transport. The envelope,
+// the method table and the error codes are the specification's and live here; the
+// server NAME, its version and the `instructions` an agent reads on connect are
+// one product's vocabulary and arrive as options.
+export {
+  handleMcpJsonRpc,
+  MCP_PROTOCOL_VERSION,
+  UNAUTHORIZED_CODE,
+  type JsonRpcRequest,
+  type JsonRpcResponse,
+  type McpJsonRpcOptions,
+  type McpServerInfo,
+} from "./server/jsonrpc";
 export {
   buildManifest,
   serializeManifest,

package/src/oauth/connections.ts

@@ -0,0 +1,104 @@
+import { providerForHostId, type AiProvider } from "../guide";
+import type {
+  McpConnectionStore,
+  RefreshTokenStore,
+  StoredMcpConnection,
+} from "./stores";
+
+/**
+ * The account surface's connection OPERATIONS (12-48) — the half of the
+ * `GET/DELETE /api/account/mcp-connections` endpoints that is contract rather
+ * than host vocabulary.
+ *
+ * The ROUTE stays in the host on purpose: it mixes the host's session
+ * resolution, its response envelope, its published plugin URLs and its logger,
+ * and injecting all four here would make the config surface bigger than the
+ * handler it replaces. What must NOT stay in each host is the disconnect's
+ * both-halves rule, because getting it half right LOOKS right:
+ *
+ * `connections.revokeByHost` ends the connection rows and returns the OAuth
+ * client ids behind them — and a host that stops there has revoked nothing that
+ * matters. The assistant still holds a live refresh token for each of those
+ * clients, rotates it on schedule, and the very next grant records fresh
+ * activity: the card the user just disconnected lights green again on its own.
+ * So the rule is one function: revoke the rows AND end every live refresh token
+ * of each returned client, in the same call, with no way to import one half
+ * without the other.
+ *
+ * Deliberately NOT invalidated here: the assistant's current ACCESS token.
+ * Those are self-contained JWTs the server does not track; a just-disconnected
+ * host keeps working for at most their TTL (15 minutes by default) and can then
+ * obtain nothing further.
+ */
+
+/** An active AI connection, narrowed for display. */
+export interface AiConnectionSnapshot {
+  oauthClientId: string;
+  clientName: string | null;
+  /** The provider this connection is attributed to (`null` = pre-attribution). */
+  host: AiProvider | null;
+  connectedAt: Date;
+  lastActiveAt: Date;
+}
+
+/** The caller the operations act for — always the session's own user. */
+export interface AiConnectionCaller {
+  /** The host's user id — what `mcp_connections` rows are keyed by. */
+  userId: string;
+  /** The identity refresh tokens are bound to (the AS binds by email). */
+  email: string;
+}
+
+/** What one disconnect actually ended, for the host's log and response. */
+export interface AiDisconnectResult {
+  /** OAuth client ids whose connection rows were revoked. */
+  disconnectedClientIds: string[];
+  /** Live refresh tokens ended across those clients — the half that cuts access. */
+  revokedRefreshTokens: number;
+}
+
+/** Narrow a stored `host` string to a known provider, or `null`. */
+function asProvider(host: string | null): AiProvider | null {
+  return host === null ? null : providerForHostId(host);
+}
+
+/**
+ * A user's active connections, most-recently-active first, with the stored open
+ * `host` string narrowed to the package's closed {@link AiProvider} union — the
+ * store cannot know which assistants have screens, but the union is this
+ * package's own vocabulary (`guide.ts`), so the narrowing lives beside it
+ * rather than being re-derived in every host.
+ */
+export async function listAiConnections(
+  connections: McpConnectionStore,
+  userId: string,
+): Promise<AiConnectionSnapshot[]> {
+  const rows: StoredMcpConnection[] = await connections.listActive(userId);
+  return rows.map((row) => ({ ...row, host: asProvider(row.host) }));
+}
+
+/**
+ * Disconnect one provider for this user — BOTH halves, atomically from the
+ * caller's point of view (see the module doc for why one half alone is a
+ * disconnect that undoes itself).
+ *
+ * Idempotent: disconnecting a provider that was never connected returns zero
+ * counts rather than failing, so a double-click is harmless. Repeat calls also
+ * report zero — `revokeLiveForClient` skips already-revoked tokens by contract.
+ */
+export async function disconnectAiHost(
+  stores: { connections: McpConnectionStore; refreshTokens: RefreshTokenStore },
+  caller: AiConnectionCaller,
+  host: AiProvider,
+): Promise<AiDisconnectResult> {
+  const disconnectedClientIds = await stores.connections.revokeByHost(caller.userId, host);
+  const revoked = await Promise.all(
+    disconnectedClientIds.map((clientId) =>
+      stores.refreshTokens.revokeLiveForClient(caller.email, clientId),
+    ),
+  );
+  return {
+    disconnectedClientIds,
+    revokedRefreshTokens: revoked.reduce((total, count) => total + count, 0),
+  };
+}

package/src/oauth/index.ts

@@ -115,3 +115,10 @@ export type {
   StoredRefreshToken,
   TokenEndpointAuthMethod,
 } from "./stores";
+export {
+  disconnectAiHost,
+  listAiConnections,
+  type AiConnectionCaller,
+  type AiConnectionSnapshot,
+  type AiDisconnectResult,
+} from "./connections";

package/src/server/jsonrpc.ts

@@ -0,0 +1,167 @@
+import type { RequestAuth } from "../types";
+
+import type { ToolRegistry } from "./registry";
+
+/**
+ * The MCP JSON-RPC 2.0 request half of the Streamable HTTP transport.
+ *
+ * Implemented directly rather than via the MCP SDK because the SDK's transport is
+ * Node-`http` oriented, and a host serving Web `Request`/`Response` (a Next route
+ * handler, a Hono route) has no `http.IncomingMessage` to hand it. It covers the
+ * methods a client needs to discover and call tools: `initialize`, `tools/list`,
+ * `tools/call`, plus `ping`.
+ *
+ * WHAT IS MECHANISM AND LIVES HERE: the envelope, the method table, the error
+ * codes, the well-formedness rule, and the notification convention. None of it
+ * varies per host — it is JSON-RPC 2.0 and the MCP specification.
+ *
+ * WHAT IS VOCABULARY AND STAYS WITH THE HOST: the server's NAME, its version, and
+ * the `instructions` string an agent reads on connect. Those describe one
+ * particular product's tool surface, so they arrive as {@link McpJsonRpcOptions}
+ * rather than being written here.
+ */
+
+/** The MCP protocol revision this transport implements. */
+export const MCP_PROTOCOL_VERSION = "2025-06-18";
+
+/**
+ * JSON-RPC error code for "authentication required", returned by `tools/call`
+ * when the request carried no valid bearer. Outside the reserved -32768..-32000
+ * band's *defined* codes on purpose: it is an implementation-defined server
+ * error, and a host maps it to HTTP 401.
+ */
+export const UNAUTHORIZED_CODE = -32001;
+
+/** JSON-RPC "Invalid Request" — a payload that isn't a well-formed request object. */
+const INVALID_REQUEST_CODE = -32600;
+
+/** JSON-RPC "Method not found". */
+const METHOD_NOT_FOUND_CODE = -32601;
+
+/** JSON-RPC "Invalid params". */
+const INVALID_PARAMS_CODE = -32602;
+
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id?: string | number | null;
+  method: string;
+  params?: unknown;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: string | number | null;
+  result?: unknown;
+  error?: { code: number; message: string };
+}
+
+/** What a client is told it connected to, in `initialize`'s `serverInfo`. */
+export interface McpServerInfo {
+  /** The server's name, as a connected host displays it. */
+  name: string;
+  /**
+   * The advertised surface version.
+   *
+   * This is the ONLY signal a client gets that the tool surface changed: the
+   * transport is request/response only, so `notifications/tools/list_changed`
+   * can never be sent, and a host that cached `tools/list` at the handshake has
+   * no other reason to ask again. See `server/surface-lock.ts` for the guard
+   * that makes forgetting to move it a build error instead of a comment.
+   */
+  version: string;
+}
+
+export interface McpJsonRpcOptions {
+  /** The host's identity, returned verbatim in `initialize`. */
+  serverInfo: McpServerInfo;
+  /**
+   * Server-level guidance surfaced to the model on `initialize` (the MCP spec's
+   * optional `instructions` field). Omitted from the result when absent, rather
+   * than sent empty — a blank string is a claim that there is guidance.
+   */
+  instructions?: string;
+  /**
+   * Override the advertised protocol revision. Defaults to
+   * {@link MCP_PROTOCOL_VERSION}; a host should not normally set it.
+   */
+  protocolVersion?: string;
+}
+
+function ok(id: JsonRpcRequest["id"], result: unknown): JsonRpcResponse {
+  return { jsonrpc: "2.0", id: id ?? null, result };
+}
+
+function fail(id: JsonRpcRequest["id"], code: number, message: string): JsonRpcResponse {
+  return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+}
+
+/** A parsed body is a usable request only if it's an object carrying a string `method`. */
+function isWellFormed(request: JsonRpcRequest): boolean {
+  return request != null && typeof request === "object" && typeof request.method === "string";
+}
+
+async function handleToolsCall(
+  request: JsonRpcRequest,
+  registry: ToolRegistry,
+  auth: RequestAuth | null,
+): Promise<JsonRpcResponse> {
+  if (!auth) return fail(request.id, UNAUTHORIZED_CODE, "Authentication required");
+  const params = (request.params ?? {}) as { name?: string; arguments?: Record<string, unknown> };
+  if (!params.name) return fail(request.id, INVALID_PARAMS_CODE, "Missing tool name");
+  const result = await registry.callTool(params.name, params.arguments ?? {}, auth);
+  return ok(request.id, result);
+}
+
+function handleInitialize(
+  request: JsonRpcRequest,
+  options: McpJsonRpcOptions,
+): JsonRpcResponse {
+  return ok(request.id, {
+    protocolVersion: options.protocolVersion ?? MCP_PROTOCOL_VERSION,
+    // Deliberately does NOT claim `listChanged`: this transport has no
+    // server→client stream, so the notification could never be sent, and
+    // advertising it would stop a host from ever re-reading `tools/list`.
+    capabilities: { tools: {} },
+    serverInfo: options.serverInfo,
+    ...(options.instructions ? { instructions: options.instructions } : {}),
+  });
+}
+
+/**
+ * Handle one MCP JSON-RPC request.
+ *
+ * Returns `null` for notifications (no id, no reply expected). `auth` is the
+ * verified caller identity, or `null` when the request carried no valid bearer —
+ * `tools/call` then returns {@link UNAUTHORIZED_CODE}, which the host surfaces as
+ * HTTP 401. Discovery (`initialize`, `ping`, `tools/list`) stays open, so a client
+ * can read the surface before it has a token.
+ */
+export async function handleMcpJsonRpc(
+  request: JsonRpcRequest,
+  registry: ToolRegistry,
+  auth: RequestAuth | null,
+  options: McpJsonRpcOptions,
+): Promise<JsonRpcResponse | null> {
+  // A host casts the parsed body to JsonRpcRequest without validating it, so a
+  // malformed payload can arrive here: a `null` body/batch element, a non-object,
+  // or an object with no `method`. Reject any of these as Invalid Request rather
+  // than dereferencing `request`/`request.method` and throwing a 500 below.
+  if (!isWellFormed(request)) {
+    return fail(request?.id ?? null, INVALID_REQUEST_CODE, "Invalid Request");
+  }
+  switch (request.method) {
+    case "initialize":
+      return handleInitialize(request, options);
+    case "ping":
+      return ok(request.id, {});
+    case "tools/list":
+      return ok(request.id, { tools: registry.listTools(auth ?? undefined) });
+    case "tools/call":
+      return handleToolsCall(request, registry, auth);
+    default:
+      // JSON-RPC notifications (`notifications/*`) expect no reply — silently
+      // ignore any we don't explicitly handle, rather than returning an error.
+      if (request.method.startsWith("notifications/")) return null;
+      return fail(request.id, METHOD_NOT_FOUND_CODE, `Method not found: ${request.method}`);
+  }
+}