@12-apps/mcp 1.0.0 → 1.3.0

package/src/server/registry.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { createToolRegistry } from "./registry";
+import { createToolRegistry, HTTP_STATUS_META_KEY } from "./registry";
 import type { GeneratedTool, RequestAuth } from "../types";
 
 const readTool: GeneratedTool = {
@@ -9,6 +9,17 @@ const readTool: GeneratedTool = {
   method: "GET",
   path: "/things/{id}",
   inputSchema: { type: "object", properties: { id: {} }, required: ["id"] },
+  outputSchema: {
+    type: "object",
+    properties: { id: { type: "string" } },
+    required: ["id"],
+  },
+  annotations: {
+    title: "Fixture tool",
+    readOnlyHint: true,
+    openWorldHint: false,
+    destructiveHint: false,
+  },
   parameters: [{ name: "id", in: "path", required: true, schema: {} }],
   bodyProps: [],
   bodyIsWhole: false,
@@ -16,7 +27,18 @@ const readTool: GeneratedTool = {
   security: [],
 };
 
-const writeTool: GeneratedTool = { ...readTool, name: "makeThing", method: "POST", mutating: true };
+const writeTool: GeneratedTool = {
+  ...readTool,
+  name: "makeThing",
+  method: "POST",
+  mutating: true,
+  annotations: {
+    title: "Fixture tool",
+    readOnlyHint: false,
+    openWorldHint: false,
+    destructiveHint: false,
+  },
+};
 
 const auth: RequestAuth = { bearer: "tok" };
 
@@ -36,6 +58,22 @@ function forbiddenFetch(): typeof fetch {
     })) as unknown as typeof fetch;
 }
 
+/** Answers with an arbitrary non-2xx, for asserting the status reaches `_meta`. */
+function statusFetch(status: number): typeof fetch {
+  return (async () =>
+    new Response(JSON.stringify({ error: "nope" }), {
+      status,
+      headers: { "content-type": "application/json" },
+    })) as unknown as typeof fetch;
+}
+
+/** Never reaches the route at all — the dispatch itself throws. */
+function throwingFetch(): typeof fetch {
+  return (async () => {
+    throw new Error("connect ECONNREFUSED");
+  }) as unknown as typeof fetch;
+}
+
 describe("createToolRegistry", () => {
   it("lists tools as MCP descriptors and honours the visibility filter", () => {
     const registry = createToolRegistry({
@@ -46,16 +84,49 @@ describe("createToolRegistry", () => {
     const names = registry.listTools().map((t) => t.name);
     expect(names).toEqual(["getThing"]);
     expect(registry.listTools()[0].inputSchema).toEqual(readTool.inputSchema);
+    expect(registry.listTools()[0].outputSchema).toEqual(readTool.outputSchema);
+    expect(registry.listTools()[0].annotations).toEqual(readTool.annotations);
+  });
+
+  it("strips redacted response fields from both text and structuredContent", async () => {
+    const redactingTool: GeneratedTool = {
+      ...readTool,
+      name: "getSupplier",
+      redactResponse: ["data.taxId"],
+    };
+    const registry = createToolRegistry({
+      tools: [redactingTool],
+      baseUrl: "https://app.example.com",
+      fetchImpl: (async () =>
+        new Response(
+          JSON.stringify({ data: { id: "s1", name: "ACME", taxId: "123" } }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        )) as unknown as typeof fetch,
+    });
+
+    const result = await registry.callTool("getSupplier", { id: "s1" }, auth);
+
+    expect(result.isError).toBe(false);
+    // The agent reads the text block even when it ignores structuredContent, so
+    // the value must be gone from both surfaces.
+    expect(result.content[0]?.text).not.toContain("123");
+    expect(result.content[0]?.text).toContain("ACME");
+    expect(result.structuredContent).toEqual({
+      data: { id: "s1", name: "ACME" },
+    });
   });
 
   it("returns an error result for an unknown tool", async () => {
-    const registry = createToolRegistry({ tools: [readTool], baseUrl: "https://app.example.com" });
+    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 () => {
+  it("proxies a successful call with text and schema-matching structured content", async () => {
     const registry = createToolRegistry({
       tools: [readTool],
       baseUrl: "https://app.example.com",
@@ -64,6 +135,7 @@ describe("createToolRegistry", () => {
     const result = await registry.callTool("getThing", { id: "1" }, auth);
     expect(result.isError).toBe(false);
     expect(JSON.parse(result.content[0].text)).toEqual({ id: "1" });
+    expect(result.structuredContent).toEqual({ id: "1" });
   });
 
   it("marks an upstream 403 as an error result (authz decided upstream)", async () => {
@@ -76,4 +148,41 @@ describe("createToolRegistry", () => {
     expect(result.isError).toBe(true);
     expect(result.content[0].text).toContain("forbidden");
   });
+
+  // `isError` alone cannot separate "correctly refused" from "actually broken":
+  // a 404 for a missing record and a 500 from a thrown route are the same bit.
+  // Callers that must tell them apart read the status from `_meta`.
+  it.each([403, 404, 422, 500])(
+    "carries the upstream %i in _meta so callers can classify the failure",
+    async (status) => {
+      const result = await createToolRegistry({
+        tools: [readTool],
+        baseUrl: "https://app.example.com",
+        fetchImpl: statusFetch(status),
+      }).callTool("getThing", { id: "1" }, auth);
+      expect(result.isError).toBe(true);
+      expect(result._meta?.[HTTP_STATUS_META_KEY]).toBe(status);
+    },
+  );
+
+  it("omits the status _meta when dispatch never reached the route", async () => {
+    const result = await createToolRegistry({
+      tools: [readTool],
+      baseUrl: "https://app.example.com",
+      fetchImpl: throwingFetch(),
+    }).callTool("getThing", { id: "1" }, auth);
+    expect(result.isError).toBe(true);
+    // No status at all is itself the signal — there was no HTTP answer to bucket.
+    expect(result._meta).toBeUndefined();
+    expect(result.content[0].text).toContain("Tool dispatch failed");
+  });
+
+  it("adds no _meta to a successful call", async () => {
+    const result = await createToolRegistry({
+      tools: [readTool],
+      baseUrl: "https://app.example.com",
+      fetchImpl: okFetch(),
+    }).callTool("getThing", { id: "1" }, auth);
+    expect(result._meta).toBeUndefined();
+  });
 });

package/src/server/registry.ts

@@ -1,5 +1,11 @@
 import { dispatchTool } from "../dispatch/proxy";
-import type { GeneratedTool, JsonSchema, RequestAuth } from "../types";
+import type {
+  GeneratedTool,
+  JsonSchema,
+  RequestAuth,
+  ToolAnnotations,
+} from "../types";
+import { redactResponseBody } from "./redact";
 
 /**
  * The registry is the transport-agnostic seam between the generated tools and the
@@ -14,12 +20,32 @@ export interface McpToolDescriptor {
   name: string;
   description: string;
   inputSchema: JsonSchema;
+  outputSchema?: JsonSchema;
+  annotations: ToolAnnotations;
 }
 
+/**
+ * `_meta` key carrying the upstream HTTP status of a dispatched call.
+ *
+ * `isError` is one bit, and it collapses answers that mean opposite things: a
+ * 404 for a record that does not exist, a 403 a guard correctly refused, a
+ * domain refusal ("this store does not use comandas"), and a 500 where the route
+ * threw all arrive identical. Callers that need to tell "correctly refused" from
+ * "actually broken" — `mcp:smoke` above all — cannot, because the status is
+ * known at dispatch and then dropped. Publishing it under a namespaced `_meta`
+ * key (permitted by the MCP result schema) keeps `isError` as the agent-facing
+ * signal while making the distinction recoverable.
+ */
+export const HTTP_STATUS_META_KEY = "dispatch/httpStatus";
+
 /** An MCP tool-call result (subset of the MCP schema). */
 export interface McpToolResult {
   content: Array<{ type: "text"; text: string }>;
   isError: boolean;
+  /** Machine-readable output matching the advertised outputSchema. */
+  structuredContent?: Record<string, unknown>;
+  /** Out-of-band metadata; carries {@link HTTP_STATUS_META_KEY} when dispatched. */
+  _meta?: Record<string, unknown>;
 }
 
 export interface ToolRegistry {
@@ -44,10 +70,35 @@ export interface RegistryOptions {
   isVisible?: (tool: GeneratedTool, auth?: RequestAuth) => boolean;
 }
 
-function textResult(value: unknown, isError: boolean): McpToolResult {
+function textResult(
+  value: unknown,
+  isError: boolean,
+  httpStatus?: number,
+): McpToolResult {
   const text =
     typeof value === "string" ? value : JSON.stringify(value, null, 2);
-  return { content: [{ type: "text", text }], isError };
+  const result: McpToolResult = { content: [{ type: "text", text }], isError };
+  if (httpStatus !== undefined) {
+    result._meta = { [HTTP_STATUS_META_KEY]: httpStatus };
+  }
+  return result;
+}
+
+function successfulResult(tool: GeneratedTool, value: unknown): McpToolResult {
+  // Redact BEFORE rendering the text block: the agent reads `content` even when
+  // it ignores `structuredContent`, so stripping only the latter would still
+  // hand over the field.
+  const safe = redactResponseBody(value, tool.redactResponse);
+  const result = textResult(safe, false);
+  if (
+    tool.outputSchema &&
+    safe !== null &&
+    typeof safe === "object" &&
+    !Array.isArray(safe)
+  ) {
+    result.structuredContent = safe as Record<string, unknown>;
+  }
+  return result;
 }
 
 export function createToolRegistry(options: RegistryOptions): ToolRegistry {
@@ -56,11 +107,15 @@ export function createToolRegistry(options: RegistryOptions): ToolRegistry {
   return {
     listTools(auth) {
       return options.tools
-        .filter((tool) => (options.isVisible ? options.isVisible(tool, auth) : true))
+        .filter((tool) =>
+          options.isVisible ? options.isVisible(tool, auth) : true,
+        )
         .map((tool) => ({
           name: tool.name,
           description: tool.description,
           inputSchema: tool.inputSchema,
+          ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+          annotations: tool.annotations,
         }));
     },
 
@@ -76,8 +131,11 @@ export function createToolRegistry(options: RegistryOptions): ToolRegistry {
         });
         // A non-2xx from the endpoint (e.g. 403 tenant-forbidden) is surfaced to
         // the agent as an error result, NOT thrown — the permission decision was
-        // made upstream and its message is the useful signal.
-        return textResult(result.body, !result.ok);
+        // made upstream and its message is the useful signal. The status rides
+        // along in `_meta` so a caller can tell a correct refusal from a break.
+        return result.ok
+          ? successfulResult(tool, result.body)
+          : textResult(result.body, true, result.status);
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         return textResult(`Tool dispatch failed: ${message}`, true);

package/src/types.ts

@@ -15,6 +15,23 @@
 /** A JSON Schema object (draft 2020-12). We treat schemas opaquely and forward them. */
 export type JsonSchema = Record<string, unknown>;
 
+/**
+ * MCP tool-behavior annotations used by clients for review and confirmation.
+ *
+ * Every value is required intentionally. ChatGPT App review treats a missing
+ * hint as a blocker, and an implicit protocol default is not enough evidence
+ * that a tool's behavior was audited. The Anthropic connector directory
+ * additionally requires a human-readable `title` on every tool, and derives
+ * auto-permissions from `readOnlyHint`/`destructiveHint`.
+ */
+export interface ToolAnnotations {
+  /** Human-readable tool label (required by the Anthropic connector review). */
+  title: string;
+  readOnlyHint: boolean;
+  openWorldHint: boolean;
+  destructiveHint: boolean;
+}
+
 /** Where an operation parameter is carried in the HTTP request. */
 export type ParameterLocation = "path" | "query" | "header";
 
@@ -43,6 +60,18 @@ export interface GeneratedTool {
   inputSchema: JsonSchema;
   /** Documented success-response schema, when the spec provides one. */
   outputSchema?: JsonSchema;
+  /** Explicit, behavior-audited MCP review hints. */
+  annotations: ToolAnnotations;
+  /**
+   * Dotted response paths stripped before the result reaches the agent.
+   *
+   * `outputSchema` is advertisement only — the dispatcher forwards the upstream
+   * body verbatim — so narrowing a schema alone would misdescribe what is
+   * actually sent. Redaction is what removes the value; the narrowed schema
+   * just keeps the advertisement honest. A segment that lands on an array is
+   * applied to every element.
+   */
+  redactResponse?: readonly string[];
   /** Path/query/header parameters, in declaration order. */
   parameters: ToolParameter[];
   /** Top-level property names sourced from the request body (routed to the body). */