@12-apps/mcp 3.1.0 → 3.2.0

package/ADOPTING.md

@@ -156,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/mcp",
-  "version": "3.1.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": {

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/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}`);
+  }
+}