@12-apps/mcp 1.0.0

package/src/openapi/generate.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+
+import { generateTools, type OpenApiDocument } from "./generate";
+
+const doc: OpenApiDocument = {
+  paths: {
+    "/products/{id}": {
+      get: {
+        operationId: "getProduct",
+        summary: "Fetch a product",
+        parameters: [
+          { name: "id", in: "path", required: true, schema: { type: "string" } },
+          { name: "include", in: "query", required: false, schema: { type: "string" } },
+        ],
+        responses: {
+          "200": { content: { "application/json": { schema: { type: "object" } } } },
+        },
+        security: [{ bearerAuth: [] }],
+      },
+    },
+    "/products": {
+      post: {
+        summary: "Create a product",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                required: ["name"],
+                properties: {
+                  name: { type: "string" },
+                  priceCents: { type: "integer" },
+                },
+              },
+            },
+          },
+        },
+      },
+      get: {
+        operationId: "listProducts",
+        tags: ["internal"],
+      },
+    },
+  },
+};
+
+describe("generateTools", () => {
+  it("maps a GET operation with path + query params", () => {
+    const tools = generateTools(doc);
+    const get = tools.find((t) => t.name === "getProduct");
+    expect(get).toBeDefined();
+    expect(get?.method).toBe("GET");
+    expect(get?.path).toBe("/products/{id}");
+    expect(get?.mutating).toBe(false);
+    expect(get?.description).toBe("Fetch a product");
+    expect(get?.security).toEqual(["bearerAuth"]);
+    // path param is required even though only query is marked optional
+    expect(get?.inputSchema.required).toEqual(["id"]);
+    expect(Object.keys(get?.inputSchema.properties as object)).toEqual(["id", "include"]);
+    expect(get?.parameters.map((p) => `${p.in}:${p.name}`)).toEqual(["path:id", "query:include"]);
+    expect(get?.bodyProps).toEqual([]);
+    expect(get?.outputSchema).toEqual({ type: "object" });
+  });
+
+  it("flattens an object request body and records bodyProps + required", () => {
+    const post = generateTools(doc).find((t) => t.path === "/products" && t.method === "POST");
+    expect(post?.mutating).toBe(true);
+    expect(post?.name).toBe("post_products"); // no operationId -> slug
+    expect(post?.bodyProps).toEqual(["name", "priceCents"]);
+    expect(post?.bodyIsWhole).toBe(false);
+    expect(post?.inputSchema.required).toEqual(["name"]);
+    expect(Object.keys(post?.inputSchema.properties as object)).toEqual(["name", "priceCents"]);
+  });
+
+  it("excludes operations by tag", () => {
+    const names = generateTools(doc, { excludeTags: ["internal"] }).map((t) => t.name);
+    expect(names).not.toContain("listProducts");
+  });
+
+  it("filters by method", () => {
+    const methods = generateTools(doc, { includeMethods: ["get"] }).map((t) => t.method);
+    expect(new Set(methods)).toEqual(new Set(["GET"]));
+  });
+
+  it("is deterministic across calls", () => {
+    expect(generateTools(doc)).toEqual(generateTools(doc));
+  });
+
+  it("exposes a non-object body as a single verbatim property", () => {
+    const wholeBodyDoc: OpenApiDocument = {
+      paths: {
+        "/raw": {
+          post: {
+            operationId: "postRaw",
+            requestBody: { required: true, content: { "application/json": { schema: { type: "array" } } } },
+          },
+        },
+      },
+    };
+    const tool = generateTools(wholeBodyDoc)[0];
+    expect(tool.bodyIsWhole).toBe(true);
+    expect(tool.bodyProps).toEqual([]);
+    expect(tool.inputSchema.required).toEqual(["body"]);
+    expect((tool.inputSchema.properties as Record<string, unknown>).body).toEqual({ type: "array" });
+  });
+});

package/src/openapi/generate.ts

@@ -0,0 +1,227 @@
+import type {
+  GeneratedTool,
+  GenerateOptions,
+  JsonSchema,
+  ParameterLocation,
+  ToolParameter,
+} from "../types";
+
+/**
+ * Minimal structural view of the OpenAPI 3.x document we consume. We intentionally
+ * model only the subset the generator reads; unknown fields are ignored and any
+ * `$ref` in a leaf schema is forwarded opaquely (the document is expected to be
+ * dereferenced by the loader for anything we need to introspect — request-body
+ * object properties in particular).
+ */
+export interface OpenApiOperation {
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  tags?: string[];
+  parameters?: OpenApiParameter[];
+  requestBody?: OpenApiRequestBody;
+  responses?: Record<string, OpenApiResponse>;
+  security?: Array<Record<string, string[]>>;
+}
+
+export interface OpenApiParameter {
+  name: string;
+  in: string;
+  required?: boolean;
+  schema?: JsonSchema;
+}
+
+export interface OpenApiRequestBody {
+  required?: boolean;
+  content?: Record<string, { schema?: JsonSchema }>;
+}
+
+export interface OpenApiResponse {
+  content?: Record<string, { schema?: JsonSchema }>;
+}
+
+export interface OpenApiDocument {
+  paths?: Record<string, Record<string, OpenApiOperation>>;
+  security?: Array<Record<string, string[]>>;
+}
+
+const HTTP_METHODS = ["get", "put", "post", "delete", "patch", "options", "head"] as const;
+const MUTATING = new Set(["post", "put", "patch", "delete"]);
+const PARAM_LOCATIONS = new Set<ParameterLocation>(["path", "query", "header"]);
+
+/** JSON body is the only content type the generic dispatcher understands. */
+const JSON_CONTENT = "application/json";
+
+function slugify(method: string, path: string): string {
+  const cleaned = path
+    .replace(/[{}]/g, "")
+    .replace(/[^a-zA-Z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .toLowerCase();
+  return `${method.toLowerCase()}_${cleaned || "root"}`;
+}
+
+function securityNames(op: OpenApiOperation, doc: OpenApiDocument): string[] {
+  const requirements = op.security ?? doc.security ?? [];
+  return [...new Set(requirements.flatMap((requirement) => Object.keys(requirement)))];
+}
+
+function bodySchema(op: OpenApiOperation): JsonSchema | undefined {
+  return op.requestBody?.content?.[JSON_CONTENT]?.schema;
+}
+
+function responseSchema(op: OpenApiOperation): JsonSchema | undefined {
+  const responses = op.responses ?? {};
+  const code = ["200", "201", "2XX", "default"].find((c) => responses[c]?.content?.[JSON_CONTENT]?.schema);
+  return code ? responses[code]?.content?.[JSON_CONTENT]?.schema : undefined;
+}
+
+/** Path params are always required regardless of how the spec marks them. */
+function paramRequired(location: ParameterLocation, raw: OpenApiParameter): boolean {
+  return location === "path" ? true : Boolean(raw.required);
+}
+
+/** OpenAPI path/query/header params (body is handled separately), in declaration order. */
+function toolParameters(op: OpenApiOperation): ToolParameter[] {
+  return (op.parameters ?? [])
+    .filter((raw) => PARAM_LOCATIONS.has(raw.in as ParameterLocation))
+    .map((raw) => {
+      const location = raw.in as ParameterLocation;
+      return {
+        name: raw.name,
+        in: location,
+        required: paramRequired(location, raw),
+        schema: raw.schema ?? { type: "string" },
+      };
+    });
+}
+
+interface BodyContribution {
+  properties: Record<string, JsonSchema>;
+  bodyProps: string[];
+  requiredProps: string[];
+  bodyIsWhole: boolean;
+}
+
+/**
+ * How the request body contributes to the flat input schema: an object body is
+ * flattened (its property names recorded so the dispatcher routes them back to
+ * the body); a non-object/opaque body is exposed as a single verbatim `body`
+ * property.
+ */
+function bodyContribution(op: OpenApiOperation): BodyContribution {
+  const body = bodySchema(op);
+  if (!body) return { properties: {}, bodyProps: [], requiredProps: [], bodyIsWhole: false };
+
+  const propSchemas = body.properties as Record<string, JsonSchema> | undefined;
+  if (body.type === "object" && propSchemas) {
+    const bodyRequired = new Set(Array.isArray(body.required) ? (body.required as string[]) : []);
+    const bodyProps = Object.keys(propSchemas);
+    return {
+      properties: propSchemas,
+      bodyProps,
+      requiredProps: bodyProps.filter((key) => bodyRequired.has(key)),
+      bodyIsWhole: false,
+    };
+  }
+
+  return {
+    properties: { body },
+    bodyProps: [],
+    requiredProps: op.requestBody?.required ? ["body"] : [],
+    bodyIsWhole: true,
+  };
+}
+
+interface BuiltInput {
+  inputSchema: JsonSchema;
+  parameters: ToolParameter[];
+  bodyProps: string[];
+  bodyIsWhole: boolean;
+}
+
+/**
+ * Build the agent-facing input schema and the routing metadata for one operation.
+ * Parameters and (flattened) body properties share one flat top level.
+ */
+function buildInput(op: OpenApiOperation): BuiltInput {
+  const parameters = toolParameters(op);
+  const paramProps: Record<string, JsonSchema> = {};
+  const required: string[] = [];
+  parameters.forEach((param) => {
+    paramProps[param.name] = param.schema;
+    if (param.required) required.push(param.name);
+  });
+
+  const body = bodyContribution(op);
+  const properties = { ...paramProps, ...body.properties };
+  const allRequired = [...required, ...body.requiredProps];
+  const inputSchema: JsonSchema = {
+    type: "object",
+    additionalProperties: false,
+    properties,
+    ...(allRequired.length ? { required: allRequired } : {}),
+  };
+  return { inputSchema, parameters, bodyProps: body.bodyProps, bodyIsWhole: body.bodyIsWhole };
+}
+
+/** The declared operations of a path item, as (method, operation) pairs. */
+function operationEntries(
+  pathItem: Record<string, OpenApiOperation>,
+): Array<[string, OpenApiOperation]> {
+  return HTTP_METHODS.filter((method) => pathItem[method]).map((method) => [
+    method,
+    pathItem[method] as OpenApiOperation,
+  ]);
+}
+
+function buildTool(
+  method: string,
+  path: string,
+  op: OpenApiOperation,
+  doc: OpenApiDocument,
+  seenNames: Set<string>,
+): GeneratedTool {
+  const candidate = op.operationId ?? slugify(method, path);
+  const name = seenNames.has(candidate) ? slugify(method, path) : candidate;
+  seenNames.add(name);
+
+  const { inputSchema, parameters, bodyProps, bodyIsWhole } = buildInput(op);
+  return {
+    name,
+    description: op.summary ?? op.description ?? `${method.toUpperCase()} ${path}`,
+    method: method.toUpperCase(),
+    path,
+    inputSchema,
+    outputSchema: responseSchema(op),
+    parameters,
+    bodyProps,
+    bodyIsWhole,
+    mutating: MUTATING.has(method),
+    security: securityNames(op, doc),
+  };
+}
+
+/**
+ * Generate one {@link GeneratedTool} per OpenAPI operation. Deterministic: the
+ * same document always yields the same tools in path/method declaration order,
+ * which is what makes the drift gate (`mcp:check`) a stable diff.
+ */
+export function generateTools(
+  doc: OpenApiDocument,
+  options: GenerateOptions = {},
+): GeneratedTool[] {
+  const includeMethods = options.includeMethods
+    ? new Set(options.includeMethods.map((m) => m.toLowerCase()))
+    : null;
+  const excludeTags = new Set(options.excludeTags ?? []);
+  const seenNames = new Set<string>();
+
+  return Object.entries(doc.paths ?? {}).flatMap(([path, pathItem]) =>
+    operationEntries(pathItem)
+      .filter(([method]) => !includeMethods || includeMethods.has(method))
+      .filter(([, op]) => !op.tags?.some((tag) => excludeTags.has(tag)))
+      .filter(([method]) => !options.filter || options.filter(method, path))
+      .map(([method, op]) => buildTool(method, path, op, doc, seenNames)),
+  );
+}

package/src/openapi/refs.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+
+import { inlineSchemaRefs, UnsupportedSchemaError } from "./refs";
+
+describe("inlineSchemaRefs", () => {
+  it("returns a flat schema structurally unchanged (no-op)", () => {
+    const flat = {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      properties: { data: { type: "array", items: { type: "string" } } },
+      required: ["data"],
+      additionalProperties: false,
+    };
+    expect(inlineSchemaRefs(flat)).toEqual(flat);
+  });
+
+  it("inlines a $defs reference and drops the $defs container", () => {
+    const schema = {
+      type: "object",
+      properties: { card: { $ref: "#/$defs/Card" } },
+      $defs: {
+        Card: { type: "object", properties: { last4: { type: "string" } } },
+      },
+    };
+    expect(inlineSchemaRefs(schema)).toEqual({
+      type: "object",
+      properties: { card: { type: "object", properties: { last4: { type: "string" } } } },
+    });
+  });
+
+  it("resolves diamond reuse (same def on sibling branches) without a cycle error", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        a: { $ref: "#/$defs/Widget" },
+        b: { $ref: "#/$defs/Widget" },
+      },
+      $defs: { Widget: { type: "object", properties: { x: { type: "string" } } } },
+    };
+    const inlined = inlineSchemaRefs(schema) as {
+      properties: { a: unknown; b: unknown };
+    };
+    expect(inlined.properties.a).toEqual({ type: "object", properties: { x: { type: "string" } } });
+    expect(inlined.properties.a).toEqual(inlined.properties.b);
+  });
+
+  it("supports #/definitions and #/components/schemas pointers", () => {
+    const legacy = {
+      type: "object",
+      properties: { v: { $ref: "#/definitions/V" } },
+      definitions: { V: { type: "number" } },
+    };
+    expect(inlineSchemaRefs(legacy)).toEqual({
+      type: "object",
+      properties: { v: { type: "number" } },
+    });
+  });
+
+  it("throws on a recursive schema", () => {
+    const recursive = {
+      type: "object",
+      properties: { child: { $ref: "#/$defs/Node" } },
+      $defs: {
+        Node: { type: "object", properties: { next: { $ref: "#/$defs/Node" } } },
+      },
+    };
+    expect(() => inlineSchemaRefs(recursive)).toThrow(UnsupportedSchemaError);
+    expect(() => inlineSchemaRefs(recursive)).toThrow(/Recursive schema not supported: Node/);
+  });
+
+  it("throws on an unresolved reference", () => {
+    expect(() => inlineSchemaRefs({ $ref: "#/$defs/Missing" })).toThrow(/Unresolved \$ref/);
+  });
+
+  it("throws on an unsupported (external) pointer", () => {
+    expect(() => inlineSchemaRefs({ $ref: "https://example.com/schema.json" })).toThrow(
+      /Unsupported \$ref pointer/,
+    );
+  });
+});

package/src/openapi/refs.ts

@@ -0,0 +1,84 @@
+import type { JsonSchema } from "../types";
+
+/**
+ * Raised when a JSON Schema cannot be turned into a flat, self-contained tool
+ * input — an unresolvable `$ref`, an unsupported pointer, or a recursive schema.
+ * The MCP tool surface is deliberately finite and flat (it is handed to an LLM
+ * and committed to the drift manifest), so recursion is rejected rather than
+ * silently truncated.
+ */
+export class UnsupportedSchemaError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UnsupportedSchemaError";
+  }
+}
+
+/** Local-definition containers a `$ref` may point into, in resolution order. */
+const REF_PREFIXES = ["#/$defs/", "#/definitions/", "#/components/schemas/"] as const;
+const DEF_CONTAINERS = ["$defs", "definitions"] as const;
+
+/** The definition name a supported local pointer targets, or `null` if unsupported. */
+function refName(ref: string): string | null {
+  const prefix = REF_PREFIXES.find((candidate) => ref.startsWith(candidate));
+  return prefix ? decodeURIComponent(ref.slice(prefix.length)) : null;
+}
+
+/** Collect the `$defs`/`definitions` maps hoisted onto a schema root into one lookup. */
+function collectDefs(root: JsonSchema): Record<string, JsonSchema> {
+  const defs: Record<string, JsonSchema> = {};
+  DEF_CONTAINERS.forEach((key) => {
+    const container = root[key];
+    if (container && typeof container === "object") {
+      Object.assign(defs, container as Record<string, JsonSchema>);
+    }
+  });
+  return defs;
+}
+
+function inlineRef(
+  ref: string,
+  defs: Record<string, JsonSchema>,
+  active: Set<string>,
+): unknown {
+  const name = refName(ref);
+  if (name === null) throw new UnsupportedSchemaError(`Unsupported $ref pointer: ${ref}`);
+  const target = defs[name];
+  if (!target) throw new UnsupportedSchemaError(`Unresolved $ref: ${ref}`);
+  if (active.has(name)) throw new UnsupportedSchemaError(`Recursive schema not supported: ${name}`);
+  active.add(name);
+  const resolved = walk(target, defs, active);
+  active.delete(name);
+  return resolved;
+}
+
+/** Deep-copy `node`, inlining every `$ref` and stripping definition containers. */
+function walk(node: unknown, defs: Record<string, JsonSchema>, active: Set<string>): unknown {
+  if (Array.isArray(node)) return node.map((item) => walk(item, defs, active));
+  if (!node || typeof node !== "object") return node;
+
+  const obj = node as Record<string, unknown>;
+  if (typeof obj.$ref === "string") return inlineRef(obj.$ref, defs, active);
+
+  const out: Record<string, unknown> = {};
+  Object.entries(obj).forEach(([key, value]) => {
+    if (!DEF_CONTAINERS.includes(key as (typeof DEF_CONTAINERS)[number])) {
+      out[key] = walk(value, defs, active);
+    }
+  });
+  return out;
+}
+
+/**
+ * Inline every local `$ref` in a JSON Schema and drop the now-empty `$defs`/
+ * `definitions` containers, yielding a flat, self-contained schema. Diamond reuse
+ * (the same definition referenced by sibling branches) is fine; only a true cycle
+ * — a definition that references itself up the resolution stack — is rejected.
+ *
+ * A schema with no `$ref`/definitions is returned structurally unchanged, so
+ * inlining an already-flat spec is a no-op (the drift gate stays a stable diff).
+ */
+export function inlineSchemaRefs(schema: JsonSchema): JsonSchema {
+  const defs = collectDefs(schema);
+  return walk(schema, defs, new Set<string>()) as JsonSchema;
+}

package/src/server/manifest.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+
+import { buildManifest, serializeManifest } from "./manifest";
+import type { GeneratedTool } from "../types";
+
+function tool(name: string): GeneratedTool {
+  return {
+    name,
+    description: `desc ${name}`,
+    method: "GET",
+    path: `/${name}`,
+    inputSchema: { type: "object", properties: {} },
+    parameters: [],
+    bodyProps: [],
+    bodyIsWhole: false,
+    mutating: false,
+    security: [],
+  };
+}
+
+describe("buildManifest", () => {
+  it("sorts tools by name regardless of input order", () => {
+    const manifest = buildManifest([tool("charlie"), tool("alpha"), tool("bravo")], {
+      version: 1,
+      source: "test",
+    });
+    expect(manifest.tools.map((t) => t.name)).toEqual(["alpha", "bravo", "charlie"]);
+    expect(manifest.version).toBe(1);
+    expect(manifest.source).toBe("test");
+  });
+});
+
+describe("serializeManifest", () => {
+  it("is deterministic and ends with a trailing newline", () => {
+    const a = serializeManifest(buildManifest([tool("b"), tool("a")], { version: 1, source: "s" }));
+    const b = serializeManifest(buildManifest([tool("a"), tool("b")], { version: 1, source: "s" }));
+    expect(a).toBe(b);
+    expect(a.endsWith("\n")).toBe(true);
+  });
+
+  it("deep-sorts object keys so key order never churns the diff", () => {
+    const t1 = tool("x");
+    const t2: GeneratedTool = { ...tool("x") };
+    // Same data, different key insertion order in inputSchema.
+    t1.inputSchema = { type: "object", properties: { b: {}, a: {} } };
+    t2.inputSchema = { properties: { a: {}, b: {} }, type: "object" };
+    const s1 = serializeManifest(buildManifest([t1], { version: 1, source: "s" }));
+    const s2 = serializeManifest(buildManifest([t2], { version: 1, source: "s" }));
+    expect(s1).toBe(s2);
+  });
+});

package/src/server/manifest.ts

@@ -0,0 +1,47 @@
+import type { GeneratedTool, ToolManifest } from "../types";
+
+/**
+ * The manifest is the committed source-of-truth artifact the CI drift gate
+ * (`mcp:check` → `12-apps/ci` `mcp-contract.yml`) diffs against a fresh
+ * regeneration. If an endpoint's schema changes without the manifest being
+ * regenerated, the diff fails the build — that is how the served MCP surface is
+ * kept in lockstep with the endpoint surface.
+ */
+
+export interface BuildManifestOptions {
+  /** Bumped intentionally on any tool-shape change (mirrors the golden catalog). */
+  version: number;
+  /** Human label for the spec, e.g. "future-pay web @ openapi.json". */
+  source: string;
+}
+
+/** Sort object keys recursively so serialization is stable regardless of insertion order. */
+function sortDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortDeep);
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) =>
+      a < b ? -1 : a > b ? 1 : 0,
+    );
+    return Object.fromEntries(entries.map(([key, val]) => [key, sortDeep(val)]));
+  }
+  return value;
+}
+
+export function buildManifest(
+  tools: GeneratedTool[],
+  options: BuildManifestOptions,
+): ToolManifest {
+  // Tools are sorted by name so the manifest ordering is deterministic across
+  // spec edits that reorder paths.
+  const sorted = [...tools].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return { version: options.version, source: options.source, tools: sorted };
+}
+
+/**
+ * Canonical JSON for a manifest — deep-key-sorted and trailing-newline'd, so the
+ * committed artifact and a regeneration diff cleanly (no key-order or whitespace
+ * churn). `mcp:check` regenerates, serializes with this, and `git diff --exit-code`s.
+ */
+export function serializeManifest(manifest: ToolManifest): string {
+  return `${JSON.stringify(sortDeep(manifest), null, 2)}\n`;
+}

package/src/server/registry.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+
+import { createToolRegistry } from "./registry";
+import type { GeneratedTool, RequestAuth } from "../types";
+
+const readTool: GeneratedTool = {
+  name: "getThing",
+  description: "Get a thing",
+  method: "GET",
+  path: "/things/{id}",
+  inputSchema: { type: "object", properties: { id: {} }, required: ["id"] },
+  parameters: [{ name: "id", in: "path", required: true, schema: {} }],
+  bodyProps: [],
+  bodyIsWhole: false,
+  mutating: false,
+  security: [],
+};
+
+const writeTool: GeneratedTool = { ...readTool, name: "makeThing", method: "POST", mutating: true };
+
+const auth: RequestAuth = { bearer: "tok" };
+
+function okFetch(): typeof fetch {
+  return (async () =>
+    new Response(JSON.stringify({ id: "1" }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    })) as unknown as typeof fetch;
+}
+
+function forbiddenFetch(): typeof fetch {
+  return (async () =>
+    new Response(JSON.stringify({ error: "forbidden" }), {
+      status: 403,
+      headers: { "content-type": "application/json" },
+    })) as unknown as typeof fetch;
+}
+
+describe("createToolRegistry", () => {
+  it("lists tools as MCP descriptors and honours the visibility filter", () => {
+    const registry = createToolRegistry({
+      tools: [readTool, writeTool],
+      baseUrl: "https://app.example.com",
+      isVisible: (tool) => !tool.mutating,
+    });
+    const names = registry.listTools().map((t) => t.name);
+    expect(names).toEqual(["getThing"]);
+    expect(registry.listTools()[0].inputSchema).toEqual(readTool.inputSchema);
+  });
+
+  it("returns an error result for an unknown tool", async () => {
+    const registry = createToolRegistry({ tools: [readTool], baseUrl: "https://app.example.com" });
+    const result = await registry.callTool("nope", {}, auth);
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("Unknown tool");
+  });
+
+  it("proxies a successful call and returns a text result", async () => {
+    const registry = createToolRegistry({
+      tools: [readTool],
+      baseUrl: "https://app.example.com",
+      fetchImpl: okFetch(),
+    });
+    const result = await registry.callTool("getThing", { id: "1" }, auth);
+    expect(result.isError).toBe(false);
+    expect(JSON.parse(result.content[0].text)).toEqual({ id: "1" });
+  });
+
+  it("marks an upstream 403 as an error result (authz decided upstream)", async () => {
+    const registry = createToolRegistry({
+      tools: [readTool],
+      baseUrl: "https://app.example.com",
+      fetchImpl: forbiddenFetch(),
+    });
+    const result = await registry.callTool("getThing", { id: "1" }, auth);
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("forbidden");
+  });
+});