@suluk/mcp 0.1.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@suluk/mcp",
+  "version": "0.1.0",
+  "description": "Project ONE OpenAPI v4 document into a Model Context Protocol (MCP) server: each operation becomes an MCP tool (read-only by default), served over the Streamable-HTTP JSON-RPC transport as a Hono-mountable app. Same contract that drives the API/SDK/docs/admin/panel now drives an agent-callable surface — zero hand-written tool schemas. CANDIDATE tooling — NOT official OAS.",
+  "publishConfig": {
+  "access": "public"
+},
+"license": "Apache-2.0",
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+  "directory": "tooling/ts/packages/mcp"
+},
+"homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+"bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+"type": "module",
+"main": "src/index.ts",
+"exports": {
+".": "./src/index.ts"
+},
+"dependencies": {
+"@suluk/core": "^0.1.7"
+},
+"peerDependencies": {
+"hono": "*"
+},
+"devDependencies": {
+"@types/bun": "latest",
+"hono": "*"
+},
+"scripts": {
+"test": "bun test",
+"typecheck": "tsc --noEmit -p ."
+}
+}

package/src/app.ts

@@ -0,0 +1,72 @@
+/**
+ * app.ts — mount a contract-projected MCP server at `basePath` (default `/mcp`) over the Streamable-HTTP transport.
+ * POST carries JSON-RPC (single message or a batch); we always answer with `application/json` (this server initiates
+ * no server→client stream, so GET returns 405, which is conformant). Tools are projected from the document on each
+ * request, so a per-request (per-role) `document` function yields a per-role tool set for free. Read-only by default.
+ */
+import { Hono, type Context } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import type { OpenAPIv4Document } from "@suluk/core";
+import { toolsFrom, type ToolsOptions, type McpOp } from "./tools";
+import { handleRpc, type RpcRequest } from "./protocol";
+import { originExec } from "./exec";
+
+/** Max JSON-RPC request body. MCP messages are tiny; this bounds a hostile oversized POST before it is parsed. */
+const MAX_BODY = 256 * 1024;
+
+export interface McpOptions extends ToolsOptions {
+  /** The v4 document — a value, or a per-request function (e.g. return projectDocument(doc, roleOf(c))). */
+  document: OpenAPIv4Document | ((c: Context) => OpenAPIv4Document | Promise<OpenAPIv4Document>);
+  basePath?: string;
+  /** Advertised server identity. */
+  name?: string;
+  version?: string;
+  /** Free-text guidance surfaced to the model on `initialize`. */
+  instructions?: string;
+  /** Gate the whole endpoint — return true to allow. Default: open (read-only catalog browsing). */
+  authorize?: (c: Context) => boolean | Promise<boolean>;
+  /** Override how a tool call is executed (default: same-origin fetch via {@link originExec}). */
+  exec?: (c: Context, op: McpOp, args: Record<string, unknown>) => Promise<unknown>;
+  /** Send permissive CORS so browser-based MCP clients can reach a public read-only server (default: true). */
+  cors?: boolean;
+}
+
+const CORS = { "access-control-allow-origin": "*", "access-control-allow-methods": "POST, OPTIONS", "access-control-allow-headers": "content-type, mcp-protocol-version, mcp-session-id, authorization" };
+
+export function mcpApp(opts: McpOptions): Hono {
+  const base = (opts.basePath ?? "/mcp").replace(/\/$/, "");
+  const info = { name: opts.name ?? "suluk-mcp", version: opts.version ?? "0.1.0" };
+  const authorize = opts.authorize ?? (() => true);
+  const cors = opts.cors !== false ? CORS : {};
+  const app = new Hono();
+
+  async function docFor(c: Context): Promise<OpenAPIv4Document> {
+    return typeof opts.document === "function" ? await opts.document(c) : opts.document;
+  }
+
+  app.options(base, (c) => c.body(null, 204, cors));
+
+  app.get(base, (c) => c.json({ jsonrpc: "2.0", id: null, error: { code: -32000, message: "This MCP endpoint does not offer a server→client stream; POST JSON-RPC instead." } }, 405, { ...cors, allow: "POST, OPTIONS" }));
+
+  const tooBig = (c: Context) => c.json({ jsonrpc: "2.0", id: null, error: { code: -32600, message: "Request body too large" } }, 413, cors);
+  app.post(base, bodyLimit({ maxSize: MAX_BODY, onError: tooBig }), async (c) => {
+    if (!(await authorize(c))) return c.json({ jsonrpc: "2.0", id: null, error: { code: -32001, message: "Unauthorized" } }, 401, cors);
+
+    let payload: unknown;
+    try { payload = await c.req.json(); } catch { return c.json({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } }, 400, cors); }
+
+    // MCP 2025-06-18 REMOVED JSON-RPC batching (one message per POST). Reject arrays up front — this also closes the
+    // batch→N-subrequest self-amplification vector (each tools/call would otherwise fan out into an origin fetch).
+    if (Array.isArray(payload)) return c.json({ jsonrpc: "2.0", id: null, error: { code: -32600, message: "Invalid Request: JSON-RPC batching was removed in MCP 2025-06-18 — send one message per request" } }, 400, cors);
+
+    const doc = await docFor(c);
+    const tools = toolsFrom(doc, opts);
+    const exec = opts.exec ? (op: McpOp, args: Record<string, unknown>) => opts.exec!(c, op, args) : (op: McpOp, args: Record<string, unknown>) => originExec(c, op, args);
+
+    const response = await handleRpc(payload as RpcRequest, { tools, info, exec, protocolVersion: undefined, instructions: opts.instructions });
+    if (response === null) return c.body(null, 202, cors); // a notification → accepted, no body
+    return c.json(response, 200, cors);
+  });
+
+  return app;
+}

package/src/exec.ts

@@ -0,0 +1,43 @@
+/**
+ * exec.ts — the default tool executor: turn an `McpOp` + arguments back into an HTTP request against the SAME
+ * origin and return the parsed result. SSRF-safe by construction — the origin is fixed to the worker's own host,
+ * argument values are only ever `encodeURIComponent`'d into the path template or set via `searchParams` (which
+ * percent-encodes), so a caller can influence the path/query VALUES but never the scheme, host, or route.
+ */
+import type { Context } from "hono";
+import type { McpOp } from "./tools";
+
+/** Build the same-origin Request for an operation call. `origin` is trusted; `args` values are caller-supplied. */
+export function buildRequest(op: McpOp, args: Record<string, unknown>, origin: string, headers: Record<string, string> = {}): Request {
+  let path = op.path;
+  for (const p of op.pathParams) {
+    const v = args[p];
+    path = path.replace(new RegExp(`\\{${p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\}`, "g"), encodeURIComponent(String(v ?? "")));
+  }
+  const url = new URL(path, origin);
+  for (const q of op.queryParams) {
+    const v = args[q];
+    if (v !== undefined && v !== null && v !== "") url.searchParams.set(q, String(v));
+  }
+  const init: RequestInit = { method: op.method, headers: { accept: "application/json", ...headers } };
+  if (!op.readOnly && op.hasBody) {
+    (init.headers as Record<string, string>)["content-type"] = "application/json";
+    init.body = JSON.stringify(args.body ?? {});
+  }
+  return new Request(url, init);
+}
+
+/** Default executor — fetch the worker's own origin, forwarding the caller's auth so an authenticated agent acts as
+ *  itself. Read-only catalog ops need no auth; mutations (only exposed under `include:"all"`) ride the forwarded
+ *  session. Throws on a non-2xx so the protocol layer reports it as a tool error (`isError`). */
+export async function originExec(c: Context, op: McpOp, args: Record<string, unknown>): Promise<unknown> {
+  const origin = new URL(c.req.url).origin;
+  const fwd: Record<string, string> = {};
+  const cookie = c.req.header("cookie"); if (cookie) fwd.cookie = cookie;
+  const auth = c.req.header("authorization"); if (auth) fwd.authorization = auth;
+  const res = await fetch(buildRequest(op, args, origin, fwd));
+  const body = await res.text();
+  if (!res.ok) throw new Error(`${op.name} → HTTP ${res.status}${body ? `: ${body.slice(0, 300)}` : ""}`);
+  if (!body) return null;
+  try { return JSON.parse(body); } catch { return body; }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @suluk/mcp — project ONE OpenAPI v4 document into a Model Context Protocol server. The same contract that drives
+ * the API, SDK, docs, admin, and panel now drives an agent-callable surface: every operation becomes an MCP tool
+ * (read-only by default; mutations opt-in via `include:"all"`), served over the Streamable-HTTP JSON-RPC transport
+ * as a Hono-mountable app. No hand-written tool schemas, no config drift — the contract is the single source.
+ * Pure projection (`toolsFrom`) + pure protocol (`handleRpc`) are independently testable; `mcpApp` wires transport.
+ * CANDIDATE tooling — NOT official OAS.
+ */
+export { toolsFrom, type McpTool, type McpOp, type ToolsOptions } from "./tools";
+export { handleRpc, LATEST_PROTOCOL, SUPPORTED_PROTOCOLS, type RpcRequest, type RpcResponse, type RpcContext, type ToolExec } from "./protocol";
+export { buildRequest, originExec } from "./exec";
+export { mcpApp, type McpOptions } from "./app";

package/src/protocol.ts

@@ -0,0 +1,76 @@
+/**
+ * protocol.ts — the MCP JSON-RPC 2.0 method surface, PURE (transport injected via `exec`). Implements the minimal
+ * conformant request/response subset of the 2025-06-18 "Streamable HTTP" spec: `initialize`, `tools/list`,
+ * `tools/call`, `ping`, and notification swallowing. Tool failures are reported IN-BAND (`isError: true`) — only
+ * malformed requests / unknown methods become JSON-RPC protocol errors, exactly as the spec prescribes.
+ */
+import type { McpOp, McpTool } from "./tools";
+
+export const LATEST_PROTOCOL = "2025-06-18";
+export const SUPPORTED_PROTOCOLS = new Set(["2024-11-05", "2025-03-26", "2025-06-18"]);
+
+export interface RpcRequest { jsonrpc?: string; id?: string | number | null; method?: string; params?: Record<string, unknown> }
+export interface RpcResponse { jsonrpc: "2.0"; id: string | number | null; result?: unknown; error?: { code: number; message: string; data?: unknown } }
+
+export type ToolExec = (op: McpOp, args: Record<string, unknown>) => Promise<unknown>;
+
+export interface RpcContext {
+  tools: McpTool[];
+  info: { name: string; version: string };
+  exec: ToolExec;
+  /** Server's preferred protocol version (echoed back only if the client didn't pin a supported one). */
+  protocolVersion?: string;
+  /** Optional free-text usage guidance surfaced to the model on `initialize`. */
+  instructions?: string;
+}
+
+const err = (id: RpcRequest["id"], code: number, message: string, data?: unknown): RpcResponse =>
+  ({ jsonrpc: "2.0", id: id ?? null, error: { code, message, ...(data !== undefined ? { data } : {}) } });
+const ok = (id: RpcRequest["id"], result: unknown): RpcResponse => ({ jsonrpc: "2.0", id: id ?? null, result });
+
+/** Dispatch one JSON-RPC message. Returns `null` ONLY for a notification — a message with no `id` MEMBER; the caller
+ *  then emits no body. Anything carrying an `id` (even the discouraged `id: null`) always gets a correlated response. */
+export async function handleRpc(msg: RpcRequest, ctx: RpcContext): Promise<RpcResponse | null> {
+  if (msg === null || typeof msg !== "object" || Array.isArray(msg)) return err(null, -32600, "Invalid Request");
+  const method = msg.method;
+  const isNotification = !("id" in msg); // notification = NO id member; `id:null` is a (discouraged) request id, not this
+  if (typeof method !== "string") return isNotification ? null : err(msg.id, -32600, "Invalid Request: missing method");
+
+  // Notifications (e.g. notifications/initialized, notifications/cancelled) get no response.
+  if (method.startsWith("notifications/")) return null;
+
+  switch (method) {
+    case "initialize": {
+      const wanted = (msg.params?.protocolVersion as string | undefined);
+      const protocolVersion = wanted && SUPPORTED_PROTOCOLS.has(wanted) ? wanted : (ctx.protocolVersion ?? LATEST_PROTOCOL);
+      return ok(msg.id, {
+        protocolVersion,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: ctx.info,
+        ...(ctx.instructions ? { instructions: ctx.instructions } : {}),
+      });
+    }
+    case "ping":
+      return ok(msg.id, {});
+    case "tools/list":
+      return ok(msg.id, { tools: ctx.tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })) });
+    case "tools/call": {
+      const name = msg.params?.name;
+      const args = (msg.params?.arguments as Record<string, unknown> | undefined) ?? {};
+      if (typeof name !== "string") return err(msg.id, -32602, "Invalid params: 'name' is required");
+      const tool = ctx.tools.find((t) => t.name === name);
+      if (!tool) return err(msg.id, -32602, `Unknown tool: ${name}`);
+      try {
+        const data = await ctx.exec(tool.op, args);
+        const text = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+        const structured = data !== null && typeof data === "object" ? { structuredContent: data as Record<string, unknown> } : {};
+        return ok(msg.id, { content: [{ type: "text", text }], ...structured });
+      } catch (e) {
+        // Execution failures are TOOL results, not protocol errors (spec §Tools/Error handling).
+        return ok(msg.id, { content: [{ type: "text", text: `Error: ${(e as Error).message}` }], isError: true });
+      }
+    }
+    default:
+      return isNotification ? null : err(msg.id, -32601, `Method not found: ${method}`);
+  }
+}

package/src/tools.ts

@@ -0,0 +1,135 @@
+/**
+ * tools.ts — project an OpenAPI v4 document's operations into MCP tool descriptors. PURE: no transport, no fetch.
+ * Each `Request` (an operation; the key in `pathItem.requests` is its name/identity, C009) becomes one tool whose
+ * `inputSchema` is the operation's path + query params (flattened) plus, for mutations, a nested `body`. The op
+ * metadata (`McpOp`) is what the executor needs to turn a tool call back into an HTTP request.
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+
+export interface McpOp {
+  /** Tool name (sanitized to MCP rules) — also how the executor finds the operation. */
+  name: string;
+  method: string;
+  /** Path template with a leading slash, e.g. `/product/{id}`. */
+  path: string;
+  /** Path-template variable names, in template order — all required. */
+  pathParams: string[];
+  /** Query parameter names. */
+  queryParams: string[];
+  /** Whether this op carries a request body (the tool exposes it under `body`). */
+  hasBody: boolean;
+  /** GET/HEAD — safe, side-effect-free. The default projection only exposes these. */
+  readOnly: boolean;
+}
+
+export interface McpTool {
+  name: string;
+  description: string;
+  inputSchema: { type: "object"; properties: Record<string, unknown>; required?: string[]; additionalProperties: boolean };
+  op: McpOp;
+}
+
+export interface ToolsOptions {
+  /** `"read"` (default) exposes only GET/HEAD operations; `"all"` also exposes mutations. */
+  include?: "read" | "all";
+  /** Operation names to omit. */
+  hide?: string[];
+  /** If set, expose ONLY these operation names (after hide). */
+  only?: string[];
+  /** Include `deprecated` operations (default: skip them). */
+  includeDeprecated?: boolean;
+}
+
+const RESERVED_BODY = "body";
+
+/** MCP tool names must be `[A-Za-z0-9_-]{1,64}`. Operation names usually already comply; sanitize defensively. */
+function toolName(raw: string): string {
+  const cleaned = raw.replace(/[^A-Za-z0-9_-]/g, "_").replace(/^_+|_+$/g, "") || "op";
+  return cleaned.slice(0, 64);
+}
+
+function deref(node: unknown, doc: OpenAPIv4Document, seen = new Set<string>()): Record<string, unknown> | undefined {
+  if (!node || typeof node !== "object") return undefined;
+  const ref = (node as { $ref?: string }).$ref;
+  if (typeof ref === "string") {
+    if (seen.has(ref)) return undefined; // cycle guard
+    seen.add(ref);
+    const m = /^#\/components\/schemas\/(.+)$/.exec(ref);
+    const name = m?.[1];
+    const target = name ? (doc.components?.schemas as Record<string, unknown> | undefined)?.[name] : undefined;
+    return target ? deref(target, doc, seen) : undefined;
+  }
+  return node as Record<string, unknown>;
+}
+
+/** Pull `{properties, required}` out of an (object) schema, dereferencing a top-level $ref first. */
+function objectShape(schema: unknown, doc: OpenAPIv4Document): { properties: Record<string, unknown>; required: string[] } {
+  const s = deref(schema, doc);
+  const properties = (s?.properties && typeof s.properties === "object" ? (s.properties as Record<string, unknown>) : {});
+  const required = Array.isArray(s?.required) ? (s!.required as string[]) : [];
+  return { properties, required };
+}
+
+/** Extract `{name}` template variables from a path, in order. */
+function templateVars(path: string): string[] {
+  return Array.from(path.matchAll(/\{([^}]+)\}/g), (m) => m[1]);
+}
+
+export function toolsFrom(doc: OpenAPIv4Document, opts: ToolsOptions = {}): McpTool[] {
+  const include = opts.include ?? "read";
+  const hide = new Set(opts.hide ?? []);
+  const only = opts.only ? new Set(opts.only) : null;
+  const out: McpTool[] = [];
+  const used = new Set<string>();
+
+  for (const [rawPath, pathItem] of Object.entries(doc.paths ?? {})) {
+    const requests = (pathItem as { requests?: Record<string, unknown> }).requests ?? {};
+    const path = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
+    const pathVars = templateVars(path);
+
+    for (const [opName, reqRaw] of Object.entries(requests)) {
+      const req = reqRaw as {
+        method?: string; summary?: string; description?: string; deprecated?: boolean;
+        parameterSchema?: { path?: unknown; query?: unknown; body?: unknown };
+        contentSchema?: unknown;
+      };
+      const method = String(req.method ?? "GET").toUpperCase();
+      const readOnly = method === "GET" || method === "HEAD";
+
+      if (req.deprecated && !opts.includeDeprecated) continue;
+      if (include === "read" && !readOnly) continue;
+      if (hide.has(opName)) continue;
+      if (only && !only.has(opName)) continue;
+
+      const ps = req.parameterSchema ?? {};
+      const pathShape = objectShape(ps.path, doc);
+      const queryShape = objectShape(ps.query, doc);
+      const bodySchema = ps.body ?? req.contentSchema;
+      const hasBody = !readOnly && bodySchema != null;
+
+      const properties: Record<string, unknown> = {};
+      const required: string[] = [];
+      // Every template var IS a path param (the uriTemplate is authoritative, C019); the path schema only adds types.
+      // Union them — using one OR the other drops a var the other side declares, yielding an unsubstitutable {var}.
+      const pathNames = Array.from(new Set([...pathVars, ...Object.keys(pathShape.properties)]));
+      for (const p of pathNames) { properties[p] = pathShape.properties[p] ?? { type: "string" }; required.push(p); }
+      for (const [q, schema] of Object.entries(queryShape.properties)) { if (q in properties) continue; properties[q] = schema; if (queryShape.required.includes(q)) required.push(q); }
+      if (hasBody) { properties[RESERVED_BODY] = deref(bodySchema, doc) ?? bodySchema; required.push(RESERVED_BODY); }
+
+      // Dedup colliding names while keeping inside MCP's 64-char limit: RESERVE room for the suffix rather than
+      // re-truncating it away (which would loop forever when two ops share an already-64-char sanitized prefix).
+      const base = toolName(opName);
+      let name = base;
+      for (let i = 1; used.has(name); i++) { const sfx = `_${i}`; name = base.slice(0, 64 - sfx.length) + sfx; }
+      used.add(name);
+
+      out.push({
+        name,
+        description: req.summary || req.description || `${method} ${path}`,
+        inputSchema: { type: "object", properties, ...(required.length ? { required } : {}), additionalProperties: false },
+        op: { name, method, path, pathParams: pathNames, queryParams: Object.keys(queryShape.properties), hasBody, readOnly },
+      });
+    }
+  }
+  return out;
+}

package/test/mcp.test.ts

@@ -0,0 +1,162 @@
+import { test, expect, describe } from "bun:test";
+import { toolsFrom, handleRpc, buildRequest, mcpApp, LATEST_PROTOCOL, type RpcContext } from "../src/index";
+
+// A tiny v4-shaped document: a read op with a path param + query, and a mutation with a body.
+const doc = {
+  components: { schemas: { ProductCreate: { type: "object", required: ["name"], properties: { name: { type: "string" }, priceCents: { type: "integer" } } } } },
+  paths: {
+    "product": { requests: {
+      listProduct: { method: "GET", summary: "List products", parameterSchema: { query: { type: "object", properties: { limit: { type: "integer" }, q: { type: "string" } }, required: ["limit"] } } },
+      createProduct: { method: "POST", summary: "Create a product", parameterSchema: { body: { $ref: "#/components/schemas/ProductCreate" } } },
+    } },
+    "product/{id}": { requests: {
+      getProduct: { method: "GET", summary: "Get one product", parameterSchema: { path: { type: "object", properties: { id: { type: "integer" } } } } },
+      deleteProduct: { method: "DELETE", summary: "Delete a product", deprecated: true, parameterSchema: { path: { type: "object", properties: { id: { type: "integer" } } } } },
+    } },
+  },
+} as never;
+
+describe("toolsFrom — contract → MCP tools", () => {
+  test("read-only by default: only GET ops, mutations + deprecated excluded", () => {
+    const names = toolsFrom(doc).map((t) => t.name).sort();
+    expect(names).toEqual(["getProduct", "listProduct"]); // createProduct (POST) + deleteProduct (deprecated) excluded
+  });
+  test("inputSchema flattens path + query params; path param required", () => {
+    const get = toolsFrom(doc).find((t) => t.name === "getProduct")!;
+    expect(get.inputSchema.properties).toHaveProperty("id");
+    expect(get.inputSchema.required).toEqual(["id"]);
+    expect(get.op).toMatchObject({ method: "GET", path: "/product/{id}", pathParams: ["id"], readOnly: true });
+    const list = toolsFrom(doc).find((t) => t.name === "listProduct")!;
+    expect(Object.keys(list.inputSchema.properties).sort()).toEqual(["limit", "q"]);
+    expect(list.inputSchema.required).toEqual(["limit"]);
+    expect(list.op.queryParams.sort()).toEqual(["limit", "q"]);
+  });
+  test("include:'all' exposes mutations with a deref'd body schema under `body`", () => {
+    const tools = toolsFrom(doc, { include: "all" });
+    const create = tools.find((t) => t.name === "createProduct")!;
+    expect(create.op.method).toBe("POST");
+    expect(create.op.hasBody).toBe(true);
+    expect(create.inputSchema.required).toContain("body");
+    expect((create.inputSchema.properties.body as { properties: object }).properties).toHaveProperty("name"); // $ref resolved
+  });
+  test("hide / only filters", () => {
+    expect(toolsFrom(doc, { hide: ["listProduct"] }).map((t) => t.name)).toEqual(["getProduct"]);
+    expect(toolsFrom(doc, { only: ["listProduct"] }).map((t) => t.name)).toEqual(["listProduct"]);
+  });
+});
+
+describe("buildRequest — SSRF-safe HTTP projection", () => {
+  test("path params encoded into the template; query set on the URL; origin never escapes", () => {
+    const op = toolsFrom(doc).find((t) => t.name === "getProduct")!.op;
+    const req = buildRequest(op, { id: "../../etc/passwd" }, "https://shop.example");
+    const u = new URL(req.url);
+    expect(u.origin).toBe("https://shop.example");           // host is fixed — no SSRF
+    expect(u.pathname).toBe("/product/..%2F..%2Fetc%2Fpasswd"); // traversal neutralized by encodeURIComponent
+  });
+  test("query op: empty/nullish values dropped, present ones encoded", () => {
+    const op = toolsFrom(doc).find((t) => t.name === "listProduct")!.op;
+    const u = new URL(buildRequest(op, { limit: 10, q: "a b&c" }, "https://shop.example").url);
+    expect(u.searchParams.get("limit")).toBe("10");
+    expect(u.searchParams.get("q")).toBe("a b&c");
+  });
+});
+
+describe("handleRpc — JSON-RPC surface", () => {
+  const ctx: RpcContext = { tools: toolsFrom(doc), info: { name: "test", version: "9" }, exec: async (op, args) => ({ ran: op.name, args }) };
+  test("initialize negotiates protocol + advertises tools capability", async () => {
+    const r = await handleRpc({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-03-26" } }, ctx);
+    expect(r!.result).toMatchObject({ protocolVersion: "2025-03-26", capabilities: { tools: { listChanged: false } }, serverInfo: { name: "test" } });
+    const r2 = await handleRpc({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "9999-99-99" } }, ctx);
+    expect((r2!.result as { protocolVersion: string }).protocolVersion).toBe(LATEST_PROTOCOL); // unsupported → server default
+  });
+  test("notifications get no response", async () => {
+    expect(await handleRpc({ jsonrpc: "2.0", method: "notifications/initialized" }, ctx)).toBeNull();
+  });
+  test("tools/list returns name+description+inputSchema only", async () => {
+    const r = await handleRpc({ jsonrpc: "2.0", id: 2, method: "tools/list" }, ctx);
+    const tools = (r!.result as { tools: { name: string }[] }).tools;
+    expect(tools.map((t) => t.name).sort()).toEqual(["getProduct", "listProduct"]);
+    expect(tools[0]).toHaveProperty("inputSchema");
+  });
+  test("tools/call runs exec and returns text + structuredContent", async () => {
+    const r = await handleRpc({ jsonrpc: "2.0", id: 3, method: "tools/call", params: { name: "getProduct", arguments: { id: 7 } } }, ctx);
+    const res = r!.result as { content: { type: string; text: string }[]; structuredContent: { ran: string } };
+    expect(res.content[0].type).toBe("text");
+    expect(res.structuredContent.ran).toBe("getProduct");
+  });
+  test("unknown tool → invalid params; tool throw → in-band isError (not a protocol error)", async () => {
+    const bad = await handleRpc({ jsonrpc: "2.0", id: 4, method: "tools/call", params: { name: "nope" } }, ctx);
+    expect(bad!.error!.code).toBe(-32602);
+    const throwing: RpcContext = { ...ctx, exec: async () => { throw new Error("boom"); } };
+    const r = await handleRpc({ jsonrpc: "2.0", id: 5, method: "tools/call", params: { name: "getProduct", arguments: {} } }, throwing);
+    expect(r!.error).toBeUndefined();
+    expect((r!.result as { isError: boolean }).isError).toBe(true);
+  });
+  test("unknown method → -32601", async () => {
+    const r = await handleRpc({ jsonrpc: "2.0", id: 6, method: "no/such" }, ctx);
+    expect(r!.error!.code).toBe(-32601);
+  });
+});
+
+describe("mcpApp — transport", () => {
+  const app = mcpApp({ document: doc, name: "shop", exec: async (_c, op) => ({ ok: op.name }) });
+  test("GET → 405 (no server stream); OPTIONS → 204 CORS; POST initialize works", async () => {
+    expect((await app.request("/mcp", { method: "GET" })).status).toBe(405);
+    const opt = await app.request("/mcp", { method: "OPTIONS" });
+    expect(opt.status).toBe(204);
+    expect(opt.headers.get("access-control-allow-origin")).toBe("*");
+    const res = await app.request("/mcp", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize" }) });
+    expect(res.status).toBe(200);
+    expect((await res.json()).result.serverInfo.name).toBe("shop");
+  });
+  test("a notification-only POST → 202 no body", async () => {
+    const res = await app.request("/mcp", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) });
+    expect(res.status).toBe(202);
+  });
+  test("authorize:false → 401", async () => {
+    const gated = mcpApp({ document: doc, authorize: () => false });
+    const res = await gated.request("/mcp", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" }) });
+    expect(res.status).toBe(401);
+  });
+  test("MCP 2025-06-18: a batch (array) POST is rejected, not fanned out", async () => {
+    const res = await app.request("/mcp", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify([{ jsonrpc: "2.0", id: 1, method: "ping" }]) });
+    expect(res.status).toBe(400);
+    expect((await res.json()).error.code).toBe(-32600);
+  });
+  test("oversized body → 413 before parse", async () => {
+    const huge = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "ping", params: { pad: "x".repeat(300 * 1024) } });
+    const res = await app.request("/mcp", { method: "POST", headers: { "content-type": "application/json", "content-length": String(huge.length) }, body: huge });
+    expect(res.status).toBe(413);
+  });
+});
+
+describe("review-hardening regressions", () => {
+  test("name dedup terminates + stays ≤64 chars for >64-char ops sharing a prefix", () => {
+    const long = "x".repeat(64);
+    const requests = { [long + "A"]: { method: "GET" }, [long + "B"]: { method: "GET" } };
+    const names = toolsFrom({ paths: { thing: { requests } } } as never).map((t) => t.name);
+    expect(names.length).toBe(2);
+    expect(names[0]).not.toBe(names[1]);
+    expect(names.every((n) => n.length <= 64 && /^[A-Za-z0-9_-]+$/.test(n))).toBe(true);
+  });
+  test("every path template var becomes a path param even when the path schema only types some of them", () => {
+    const getOrgProduct = { method: "GET", parameterSchema: { path: { type: "object", properties: { id: { type: "integer" } } } } };
+    const d = { paths: { "/org/{org}/product/{id}": { requests: { getOrgProduct } } } } as never;
+    const t = toolsFrom(d)[0];
+    expect(t.op.pathParams.sort()).toEqual(["id", "org"]);
+    expect(Object.keys(t.inputSchema.properties).sort()).toEqual(["id", "org"]);
+    const u = new URL(buildRequest(t.op, { org: "acme", id: 7 }, "https://shop.example").url);
+    expect(u.pathname).toBe("/org/acme/product/7"); // both vars substituted — no literal {org}
+  });
+  test("a request with id:null still gets a correlated error (not swallowed as a notification)", async () => {
+    const ctx: RpcContext = { tools: toolsFrom(doc), info: { name: "t", version: "1" }, exec: async () => ({}) };
+    const r = await handleRpc({ jsonrpc: "2.0", id: null, method: "no/such" }, ctx);
+    expect(r).not.toBeNull();
+    expect(r!.error!.code).toBe(-32601);
+  });
+  test("a non-object message → -32600 Invalid Request", async () => {
+    const ctx: RpcContext = { tools: [], info: { name: "t", version: "1" }, exec: async () => ({}) };
+    expect((await handleRpc(1 as never, ctx))!.error!.code).toBe(-32600);
+    expect((await handleRpc(null as never, ctx))!.error!.code).toBe(-32600);
+  });
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../tsconfig.base.json", "compilerOptions": { "types": ["bun"] }, "include": ["src", "test"] }