@12-apps/mcp 1.0.0 → 1.3.0

package/package.json

@@ -1,17 +1,37 @@
 {
   "name": "@12-apps/mcp",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "type": "module",
-  "description": "App-agnostic MCP server core: generate one MCP tool per OpenAPI operation and proxy each call to the endpoint carrying the caller's bearer token (permission passthrough).",
+  "description": "App-agnostic MCP server core: generate one MCP tool per OpenAPI operation and proxy each call to the endpoint carrying the caller's bearer token (permission passthrough). Also ships the reusable AI-connect onboarding UI at @12-apps/mcp/react.",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./react": "./src/react/index.ts"
+  },
+  "scripts": {
+    "clean": "rm -rf node_modules coverage",
+    "test": "node ../../scripts/vitest-with-teardown.mjs run --passWithNoTests",
+    "test:watch": "vitest watch",
+    "lint": "eslint src --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@mui/icons-material": "^6.5.0",
+    "@12-apps/onboarding": "^1.3.0",
+    "@12-apps/ui": "^1.3.0",
+    "react": "^19.2.0"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0"
   },
   "devDependencies": {
+    "@mui/material": "^6.5.0",
+    "@12-apps/typescript-config": "^1.3.0",
     "@types/node": "^22.15.3",
+    "@types/react": "19.2.2",
     "eslint": "^9.39.1",
     "typescript": "^5.8.2",
-    "vitest": "^3.2.4",
-    "@12-apps/typescript-config": "0.0.0"
+    "vitest": "^3.2.4"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -19,7 +39,7 @@
   "license": "MIT",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
-    "access": "restricted"
+    "access": "public"
   },
   "repository": {
     "type": "git",
@@ -33,13 +53,5 @@
     "*.js",
     "*.mjs",
     "*.md"
-  ],
-  "scripts": {
-    "clean": "rm -rf node_modules coverage",
-    "test": "vitest run --passWithNoTests",
-    "test:watch": "vitest watch",
-    "lint": "eslint src --max-warnings 0",
-    "check-types": "tsc --noEmit",
-    "typecheck": "tsc --noEmit"
-  }
-}
+  ]
+}

package/src/dispatch/proxy.test.ts

@@ -9,6 +9,12 @@ const getTool: GeneratedTool = {
   method: "GET",
   path: "/products/{id}",
   inputSchema: {},
+  annotations: {
+    title: "Fixture tool",
+    readOnlyHint: true,
+    openWorldHint: false,
+    destructiveHint: false,
+  },
   parameters: [
     { name: "id", in: "path", required: true, schema: {} },
     { name: "include", in: "query", required: false, schema: {} },
@@ -26,6 +32,12 @@ const postTool: GeneratedTool = {
   method: "POST",
   path: "/products",
   inputSchema: {},
+  annotations: {
+    title: "Fixture tool",
+    readOnlyHint: false,
+    openWorldHint: true,
+    destructiveHint: false,
+  },
   parameters: [],
   bodyProps: ["name", "priceCents"],
   bodyIsWhole: false,
@@ -38,7 +50,11 @@ interface Captured {
   init: RequestInit;
 }
 
-function fakeFetch(status: number, payload: unknown, captured: Captured[]): typeof fetch {
+function fakeFetch(
+  status: number,
+  payload: unknown,
+  captured: Captured[],
+): typeof fetch {
   return (async (url: string, init: RequestInit) => {
     captured.push({ url, init });
     return new Response(JSON.stringify(payload), {
@@ -54,12 +70,18 @@ describe("dispatchTool", () => {
     const result = await dispatchTool(
       getTool,
       { id: "abc 1", include: "variations", "x-trace": "t1" },
-      { baseUrl: "https://app.example.com", bearer: "tok123", fetchImpl: fakeFetch(200, { ok: 1 }, captured) },
+      {
+        baseUrl: "https://app.example.com",
+        bearer: "tok123",
+        fetchImpl: fakeFetch(200, { ok: 1 }, captured),
+      },
     );
 
     expect(captured).toHaveLength(1);
     const { url, init } = captured[0];
-    expect(url).toBe("https://app.example.com/products/abc%201?include=variations");
+    expect(url).toBe(
+      "https://app.example.com/products/abc%201?include=variations",
+    );
     const headers = init.headers as Record<string, string>;
     expect(headers.authorization).toBe("Bearer tok123");
     expect(headers["x-trace"]).toBe("t1");
@@ -74,17 +96,34 @@ describe("dispatchTool", () => {
     await dispatchTool(
       postTool,
       { name: "Cola", priceCents: 500, sneaky: "drop-me" },
-      { baseUrl: "https://app.example.com", bearer: "t", fetchImpl: fakeFetch(201, {}, captured) },
+      {
+        baseUrl: "https://app.example.com",
+        bearer: "t",
+        fetchImpl: fakeFetch(201, {}, captured),
+      },
     );
     const { init } = captured[0];
     expect(init.method).toBe("POST");
-    expect(JSON.parse(init.body as string)).toEqual({ name: "Cola", priceCents: 500 });
-    expect((init.headers as Record<string, string>)["content-type"]).toBe("application/json");
+    expect(JSON.parse(init.body as string)).toEqual({
+      name: "Cola",
+      priceCents: 500,
+    });
+    expect((init.headers as Record<string, string>)["content-type"]).toBe(
+      "application/json",
+    );
   });
 
   it("throws on a missing required path parameter", async () => {
     await expect(
-      dispatchTool(getTool, {}, { baseUrl: "https://app.example.com", bearer: "t", fetchImpl: fakeFetch(200, {}, []) }),
+      dispatchTool(
+        getTool,
+        {},
+        {
+          baseUrl: "https://app.example.com",
+          bearer: "t",
+          fetchImpl: fakeFetch(200, {}, []),
+        },
+      ),
     ).rejects.toBeInstanceOf(DispatchInputError);
   });
 
@@ -92,7 +131,11 @@ describe("dispatchTool", () => {
     const result = await dispatchTool(
       getTool,
       { id: "1" },
-      { baseUrl: "https://app.example.com", bearer: "t", fetchImpl: fakeFetch(403, { error: "forbidden" }, []) },
+      {
+        baseUrl: "https://app.example.com",
+        bearer: "t",
+        fetchImpl: fakeFetch(403, { error: "forbidden" }, []),
+      },
     );
     expect(result.ok).toBe(false);
     expect(result.status).toBe(403);
@@ -109,7 +152,11 @@ describe("dispatchTool", () => {
     await dispatchTool(
       getTool,
       { id: "1" },
-      { baseUrl: "http://localhost:4105", bearer: "t", fetchImpl: fakeFetch(200, {}, captured) },
+      {
+        baseUrl: "http://localhost:4105",
+        bearer: "t",
+        fetchImpl: fakeFetch(200, {}, captured),
+      },
     );
     const headers = captured[0].init.headers as Record<string, string>;
     expect(headers["x-forwarded-proto"]).toBe("http");
@@ -121,7 +168,11 @@ describe("dispatchTool", () => {
     await dispatchTool(
       getTool,
       { id: "1" },
-      { baseUrl: "https://menu.example.com", bearer: "t", fetchImpl: fakeFetch(200, {}, captured) },
+      {
+        baseUrl: "https://menu.example.com",
+        bearer: "t",
+        fetchImpl: fakeFetch(200, {}, captured),
+      },
     );
     const headers = captured[0].init.headers as Record<string, string>;
     expect(headers["x-forwarded-proto"]).toBe("https");

package/src/guide.ts

@@ -0,0 +1,253 @@
+/**
+ * AI-integration guide content — the reusable copy for a store's "Integração com
+ * IA" onboarding. Pure, public, non-sensitive text (no React) so the on-page
+ * walkthrough stays a portable, testable content module. Host brand marks/icons
+ * and colours live in the components. Apps may pass their own overrides to
+ * `<AiIntegrationOnboarding>`; these are the shared defaults.
+ *
+ * The MCP endpoint URL is NOT hardcoded here — the app derives it per request
+ * from the deployment origin and passes it in.
+ */
+
+/** Which brand a host belongs to — drives the icon/accent in the UI. */
+export type AiHostBrand = "claude" | "openai";
+
+export interface AiHostLink {
+  /** Deep-link straight to the host's connector settings, when one exists. */
+  url: string;
+  label: string;
+}
+
+/**
+ * One stage of the "configure the connector" part of the flow. A host can split
+ * configuration across several stages, each with its OWN deep link, step label
+ * and instructions — e.g. ChatGPT needs "enable developer mode" (Security
+ * settings) and then "configurar" (create the connector). When a host declares
+ * `configureStages`, the wizard renders one wizard step per stage (between
+ * "Copiar URL" and "Confirmar") instead of the default Configurar/Conectar
+ * split, and the sign-in happens inside a stage — no prompt to paste.
+ */
+export interface AiHostConfigureStage {
+  /** Stable id — also the wizard step id + test id suffix (`ai-stage-${id}`). */
+  id: string;
+  /** Step label shown in the stepper. */
+  label: string;
+  /** Optional deep link opened on this stage (unlocks "Próximo" once opened). */
+  link?: AiHostLink;
+  /** The instructions shown for this stage. */
+  steps: readonly string[];
+}
+
+/**
+ * The AI providers a connection can be attributed to — derived server-side from
+ * the OAuth client's redirect URIs (and confirmed by the `announceAiConnection`
+ * tool). Drives which host card lights up green on the status board.
+ */
+export type AiProvider = "claude" | "chatgpt" | "codex";
+
+/** The provider a host id belongs to (claude-desktop shares Claude's provider). */
+export function providerForHostId(hostId: string): AiProvider | null {
+  if (hostId === "claude" || hostId === "claude-desktop") return "claude";
+  if (hostId === "chatgpt") return "chatgpt";
+  if (hostId === "codex") return "codex";
+  return null;
+}
+
+export interface AiHostGuide {
+  /** Stable id — also the panel test id suffix (`ai-setup-${id}`). */
+  id: string;
+  /** Tab label shown to the owner. */
+  label: string;
+  brand: AiHostBrand;
+  /** One-line hint of what this host is (web app, desktop app, CLI…). */
+  kind: string;
+  /** Optional direct link button (desktop apps have no deep link). */
+  link?: AiHostLink;
+  /**
+   * Optional link to the host's OFFICIAL connector docs — a stable vendor URL
+   * shown as a "Para mais informações" reference (never a deep link with a
+   * volatile connector id / UI params).
+   */
+  docs?: AiHostLink;
+  steps: readonly string[];
+  /**
+   * Optional per-stage configuration (each with its own deep link + label). When
+   * present, the wizard renders one step per stage in place of the default
+   * Configurar → Conectar split, and `steps` mirrors the flattened stage
+   * instructions so the MCP guide stays a single source of truth.
+   */
+  configureStages?: readonly AiHostConfigureStage[];
+  /**
+   * Optional deep link to a PUBLISHED one-click plugin/connector for this host
+   * (set per app via env, e.g. `CHATGPT_PLUGIN_URL` / `CLAUDE_PLUGIN_URL`). When
+   * present, the wizard swaps the manual "copy URL + configure connector" path
+   * for a simplified "open → Install → authorize" flow: the owner never copies
+   * the MCP URL. Absent → the full manual flow.
+   */
+  pluginUrl?: string;
+}
+
+const CONNECTOR_TAIL: readonly string[] = [
+  "Deixe OAuth Client ID e Client Secret em branco — não é preciso gerar credenciais: a loja registra o conector automaticamente no primeiro acesso.",
+  "Confirme e clique em Connect: abre a tela de login da loja — entre com a SUA conta de lojista e autorize o acesso.",
+  "Pronto: ative o conector na conversa para o assistente consultar e operar a sua loja.",
+];
+
+/**
+ * ChatGPT's two-stage configuration (Developer mode is now required before a
+ * connector can be created). Stage 1 enables Developer mode in Security & login;
+ * stage 2 creates the connector and signs in — which registers the connection on
+ * the store side, so no prompt needs to be pasted afterwards.
+ */
+const CHATGPT_CONFIGURE_STAGES: readonly AiHostConfigureStage[] = [
+  {
+    id: "enable-dev-mode",
+    label: "enable developer mode",
+    link: {
+      url: "https://chatgpt.com/plugins#settings/Security",
+      label: "Abrir Segurança e login",
+    },
+    steps: [
+      "Ative o Modo desenvolvedor em Settings › Security and login (Segurança e login).",
+    ],
+  },
+  {
+    id: "configurar",
+    label: "configurar",
+    link: {
+      url: "https://chatgpt.com/plugins#settings/Connectors?create-connector=true&redirectAfter=%2Fplugins",
+      label: "Criar o conector",
+    },
+    steps: [
+      "Isso vai abrir um popup para você criar um plugin novo. Coloque como nome o nome da sua loja e, no campo MCP, o link copiado no passo anterior.",
+      'Marque a caixa "I understand and want to continue" — a OpenAI não revisou este servidor MCP; ela avisa que sites podem tentar roubar seus dados ou induzir o modelo a ações indevidas, incluindo destruir dados.',
+      'Clique em "Sign in with Future Drink" e entre com a sua conta de lojista para autorizar o acesso. Pronto: a conexão é registrada automaticamente.',
+    ],
+  },
+];
+
+/**
+ * The AI hosts a store owner can connect, in recommended order. Same OAuth flow
+ * everywhere (the host drives it) — only the menu path differs per app.
+ */
+export const AI_HOST_GUIDES: readonly AiHostGuide[] = [
+  {
+    id: "claude",
+    label: "Claude.ai",
+    brand: "claude",
+    kind: "No navegador",
+    link: {
+      url: "https://claude.ai/new?modal=add-custom-connector#settings/customize-connectors",
+      label: "Abrir os conectores do Claude",
+    },
+    docs: {
+      url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
+      label: "documentação oficial da Anthropic — conectores personalizados",
+    },
+    steps: [
+      "Clique no botão acima (ou vá em Settings › Customize › Connectors) e escolha Add custom connector.",
+      "Dê um nome ao conector (ex.: o nome da sua loja) e cole a URL do servidor MCP da sua loja (copie acima) no campo de URL.",
+      ...CONNECTOR_TAIL,
+    ],
+  },
+  {
+    id: "claude-desktop",
+    label: "Claude Desktop",
+    brand: "claude",
+    kind: "Aplicativo (Windows/Mac)",
+    docs: {
+      url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
+      label: "documentação oficial da Anthropic — conectores personalizados",
+    },
+    steps: [
+      "Abra o Claude Desktop e vá em Settings (⚙️) › Connectors.",
+      "Clique em Add custom connector e cole a URL do servidor MCP da sua loja (copie acima).",
+      ...CONNECTOR_TAIL,
+    ],
+  },
+  {
+    id: "chatgpt",
+    label: "ChatGPT",
+    brand: "openai",
+    kind: "No navegador",
+    link: { url: "https://chatgpt.com/plugins", label: "Abrir os plugins do ChatGPT" },
+    docs: {
+      url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
+      label: "documentação oficial da OpenAI — conectar um servidor MCP ao ChatGPT",
+    },
+    configureStages: CHATGPT_CONFIGURE_STAGES,
+    // Mirrors the flattened stage instructions so the MCP connect guide
+    // (`connectToChatGpt`) can never drift from what owners see in the wizard.
+    steps: CHATGPT_CONFIGURE_STAGES.flatMap((stage) => stage.steps),
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    brand: "openai",
+    kind: "App / CLI de desenvolvedor",
+    link: { url: "https://developers.openai.com/codex", label: "Documentação do Codex" },
+    docs: {
+      url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
+      label: "documentação oficial da OpenAI — conectar um servidor MCP",
+    },
+    steps: [
+      "No Codex, abra as configurações de MCP (Settings › MCP no app, ou o arquivo de configuração na CLI).",
+      "Adicione um servidor MCP e cole a URL do servidor MCP da sua loja (copie acima) como um conector remoto (HTTP).",
+      ...CONNECTOR_TAIL,
+    ],
+  },
+];
+
+export interface AiCapability {
+  /** Stable id — maps to an icon in the component. */
+  id: string;
+  /** Card headline. */
+  title: string;
+  /** Short supporting line, usually an example prompt in quotes. */
+  detail: string;
+}
+
+/** What a connected assistant does for the owner — one marketing card each. */
+export const AI_CAPABILITIES: readonly AiCapability[] = [
+  {
+    id: "orders",
+    title: "Acompanhe seus pedidos",
+    detail: '"Quais pedidos entraram hoje?"',
+  },
+  {
+    id: "inventory",
+    title: "Controle o estoque",
+    detail: '"Quanto ainda tenho do produto X? Registre a entrada de 20 unidades."',
+  },
+  {
+    id: "catalog",
+    title: "Gerencie o catálogo",
+    detail: "Crie e edite produtos e categorias conversando.",
+  },
+  {
+    id: "sales",
+    title: "Entenda suas vendas",
+    detail: '"Qual foi o faturamento da semana?"',
+  },
+];
+
+/**
+ * The permission model in one line, shown prominently: the assistant acts AS
+ * the signed-in owner (auth-passthrough) — it can do exactly what the owner
+ * can, nothing more, and no extra credential/API key is ever created.
+ */
+export const AI_PERMISSION_MODEL =
+  "O assistente age em seu nome, com exatamente as suas permissões: ele pode fazer o que você pode fazer na sua loja — nada além disso. Não é preciso criar nenhuma chave ou credencial extra; a autorização usa o seu próprio login.";
+
+/**
+ * The message the owner pastes into the assistant's chat right after connecting.
+ * It makes the assistant (1) call `announceAiConnection` reporting which host it
+ * is (chatgpt / claude / codex) — the tool that registers the connection on the
+ * server side so the store learns which assistant connected — and (2) call a
+ * real read tool to confirm access. The owner types nothing.
+ */
+export const AI_CONNECT_PROMPT =
+  "Você agora tem acesso ao conector MCP da minha loja. Faça, nesta ordem:\n" +
+  '1) Execute a ferramenta announceAiConnection informando qual assistente você é (host: "chatgpt", "claude" ou "codex") para registrar a conexão com a minha loja.\n' +
+  "2) Execute a ferramenta listInventory para confirmar o acesso ao estoque da minha loja.\n" +
+  "Se precisar do identificador da loja, me pergunte o tenantSlug.";

package/src/index.ts

@@ -9,6 +9,22 @@
  */
 
 export * from "./types";
+// Shared AI-connect guide content (pure data, no React) — the single source of
+// truth for BOTH the `@12-apps/mcp/react` onboarding UI and the server-side connect
+// tools, so what an agent reads via MCP cannot drift from what owners see.
+export {
+  AI_HOST_GUIDES,
+  AI_CAPABILITIES,
+  AI_PERMISSION_MODEL,
+  AI_CONNECT_PROMPT,
+  providerForHostId,
+  type AiHostBrand,
+  type AiHostLink,
+  type AiHostConfigureStage,
+  type AiHostGuide,
+  type AiProvider,
+  type AiCapability,
+} from "./guide";
 export { generateTools } from "./openapi/generate";
 export { inlineSchemaRefs, UnsupportedSchemaError } from "./openapi/refs";
 export type {
@@ -21,6 +37,7 @@ export type {
 export { dispatchTool, DispatchInputError } from "./dispatch/proxy";
 export {
   createToolRegistry,
+  HTTP_STATUS_META_KEY,
   type ToolRegistry,
   type RegistryOptions,
   type McpToolDescriptor,

package/src/openapi/generate.test.ts

@@ -8,12 +8,30 @@ const doc: OpenApiDocument = {
       get: {
         operationId: "getProduct",
         summary: "Fetch a product",
+        "x-mcp-tool-annotations": {
+          title: "Fixture tool",
+          readOnlyHint: true,
+          openWorldHint: false,
+          destructiveHint: false,
+        },
         parameters: [
-          { name: "id", in: "path", required: true, schema: { type: "string" } },
-          { name: "include", in: "query", required: false, schema: { type: "string" } },
+          {
+            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" } } } },
+          "200": {
+            content: { "application/json": { schema: { type: "object" } } },
+          },
         },
         security: [{ bearerAuth: [] }],
       },
@@ -21,6 +39,12 @@ const doc: OpenApiDocument = {
     "/products": {
       post: {
         summary: "Create a product",
+        "x-mcp-tool-annotations": {
+          title: "Fixture tool",
+          readOnlyHint: false,
+          openWorldHint: true,
+          destructiveHint: false,
+        },
         requestBody: {
           required: true,
           content: {
@@ -40,6 +64,12 @@ const doc: OpenApiDocument = {
       get: {
         operationId: "listProducts",
         tags: ["internal"],
+        "x-mcp-tool-annotations": {
+          title: "Fixture tool",
+          readOnlyHint: true,
+          openWorldHint: false,
+          destructiveHint: false,
+        },
       },
     },
   },
@@ -55,31 +85,52 @@ describe("generateTools", () => {
     expect(get?.mutating).toBe(false);
     expect(get?.description).toBe("Fetch a product");
     expect(get?.security).toEqual(["bearerAuth"]);
+    expect(get?.annotations).toEqual({
+      title: "Fixture tool",
+      readOnlyHint: true,
+      openWorldHint: false,
+      destructiveHint: false,
+    });
     // 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(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");
+    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"]);
+    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);
+    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);
+    const methods = generateTools(doc, { includeMethods: ["get"] }).map(
+      (t) => t.method,
+    );
     expect(new Set(methods)).toEqual(new Set(["GET"]));
   });
 
@@ -93,7 +144,16 @@ describe("generateTools", () => {
         "/raw": {
           post: {
             operationId: "postRaw",
-            requestBody: { required: true, content: { "application/json": { schema: { type: "array" } } } },
+            "x-mcp-tool-annotations": {
+              title: "Fixture tool",
+              readOnlyHint: false,
+              openWorldHint: false,
+              destructiveHint: false,
+            },
+            requestBody: {
+              required: true,
+              content: { "application/json": { schema: { type: "array" } } },
+            },
           },
         },
       },
@@ -102,6 +162,58 @@ describe("generateTools", () => {
     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" });
+    expect(
+      (tool.inputSchema.properties as Record<string, unknown>).body,
+    ).toEqual({ type: "array" });
+  });
+
+  it("rejects operations whose review hints were not explicitly audited", () => {
+    const unaudited: OpenApiDocument = {
+      paths: { "/unsafe-default": { get: { operationId: "unsafeDefault" } } },
+    };
+    expect(() => generateTools(unaudited)).toThrow(
+      /must explicitly set readOnlyHint, openWorldHint, and destructiveHint/,
+    );
+  });
+
+  it("rejects an operation with no human-readable annotations title", () => {
+    const untitled: OpenApiDocument = {
+      paths: {
+        "/untitled": {
+          get: {
+            operationId: "untitled",
+            "x-mcp-tool-annotations": {
+              readOnlyHint: true,
+              openWorldHint: false,
+              destructiveHint: false,
+            } as never,
+          },
+        },
+      },
+    };
+    expect(() => generateTools(untitled)).toThrow(
+      /must set a human-readable annotations.title/,
+    );
+  });
+
+  it("carries the response-redaction list onto the generated tool", () => {
+    const redacting: OpenApiDocument = {
+      paths: {
+        "/suppliers": {
+          get: {
+            operationId: "listSuppliers",
+            "x-mcp-tool-annotations": {
+              title: "List suppliers",
+              readOnlyHint: true,
+              openWorldHint: false,
+              destructiveHint: false,
+            },
+            "x-mcp-redact-response": ["data.taxId"],
+          },
+        },
+      },
+    };
+    const [tool] = generateTools(redacting);
+    expect(tool?.redactResponse).toEqual(["data.taxId"]);
   });
 });