@12-apps/mcp 3.2.0 → 3.2.1

package/dist/generate/index.d.ts

@@ -0,0 +1,91 @@
+import { T as ToolManifest, O as OpenApiDocument } from '../generate-Dx3cK8th.js';
+
+/**
+ * `@12-apps/mcp/generate` — the `mcp:generate` / `mcp:check` gate (12-23), moved
+ * out of the origin host's `apps/web/scripts/mcp/generate.ts` so a host's own script is
+ * a one-line call and `12-apps/ci`'s `mcp-contract.yml`, which shells out to the
+ * consumer's `mcp:check` package script, keeps working unchanged.
+ *
+ * It renders the committed surface artifacts from the host's OpenAPI document:
+ *
+ *   openapi.json      — the document itself, canonicalized
+ *   manifest.json     — the MCP tool manifest generated from it
+ *   surface-lock.json — which surface the current version stands for
+ *
+ * With `check: true` it regenerates IN MEMORY and fails on any drift — the same
+ * command CI runs, so a forgotten regeneration is a red build rather than a tool
+ * list that silently disagrees with the endpoints.
+ *
+ * It ALSO refuses, in both modes, to emit a tool surface that changed while the
+ * advertised VERSION did not. That version is the only signal a connected host has
+ * that `tools/list` is worth re-reading, so a shipped tool behind an unmoved
+ * version is invisible to every client that already cached it — and "remember to
+ * bump it" as a comment is not a rule (see `server/surface-lock.ts`).
+ */
+/** One extra artifact a host renders from the same manifest, e.g. a store submission. */
+interface McpExtraArtifact {
+    /** Absolute path of the committed file. */
+    path: string;
+    /** Rendered text, INCLUDING its trailing newline (compared byte for byte). */
+    render: (manifest: ToolManifest) => string;
+}
+interface McpGenerateOptions {
+    /**
+     * The host's OpenAPI document, or a thunk producing it. A thunk is the useful
+     * form: building it usually evaluates a Zod registry, and `--check` should pay
+     * that cost once, when it runs.
+     */
+    document: OpenApiDocument | (() => OpenApiDocument);
+    /**
+     * The advertised surface version — the number a client is handed on `initialize`
+     * and caches `tools/list` against.
+     */
+    version: number;
+    /** Human label for the spec the tools were generated from. */
+    source: string;
+    /**
+     * Where the host's version constant lives, repo-relative — quoted verbatim in
+     * the surface-lock failure, so the fix is a path and a value rather than a hunt.
+     */
+    versionLocation: string;
+    /** The constant's name, if the host does not call it `MCP_SURFACE_VERSION`. */
+    versionName?: string;
+    /** Where the three artifacts are committed. */
+    outputs: {
+        openapi: string;
+        manifest: string;
+        surfaceLock: string;
+    };
+    /** Anything else the host commits from the same manifest. */
+    extraArtifacts?: readonly McpExtraArtifact[];
+}
+/** The rendered text of every artifact, keyed by its committed path. */
+type RenderedArtifacts = Map<string, string>;
+interface McpGenerateResult {
+    artifacts: RenderedArtifacts;
+    /** Non-null when the surface moved without a version bump — the message to print. */
+    surfaceProblem: string | null;
+}
+/**
+ * Render every artifact from the document. Pure: nothing is written and nothing is
+ * compared, so a caller can diff, print or discard the result.
+ */
+declare function renderMcpArtifacts(options: McpGenerateOptions): McpGenerateResult;
+/** Every artifact whose committed text differs from a fresh render. */
+declare function mcpArtifactDrift(artifacts: RenderedArtifacts): string[];
+/** Write every artifact, creating directories as needed. */
+declare function writeMcpArtifacts(artifacts: RenderedArtifacts): void;
+interface McpGenerateCliOptions extends McpGenerateOptions {
+    /** `true` for `mcp:check` (verify only), `false` for `mcp:generate` (write). */
+    check: boolean;
+    /** The command to suggest on drift. Default: `pnpm mcp:generate`. */
+    regenerateCommand?: string;
+}
+/**
+ * The CLI face: render, then either verify or write, printing the verdict and
+ * exiting non-zero on any failure. A host's `scripts/mcp/generate.ts` becomes an
+ * import, its document builder, and one call.
+ */
+declare function mcpGenerateCli(options: McpGenerateCliOptions): void;
+
+export { type McpExtraArtifact, type McpGenerateCliOptions, type McpGenerateOptions, type McpGenerateResult, type RenderedArtifacts, mcpArtifactDrift, mcpGenerateCli, renderMcpArtifacts, writeMcpArtifacts };

package/dist/generate/index.js

@@ -0,0 +1,101 @@
+import {
+  buildManifest,
+  generateTools,
+  serializeManifest,
+  serializeSurfaceLock,
+  surfaceDigest,
+  surfaceLockProblem
+} from "../chunk-HAZOPC6U.js";
+import {
+  __name
+} from "../chunk-7QVYU63E.js";
+
+// src/generate/index.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname } from "path";
+function readOrEmpty(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+__name(readOrEmpty, "readOrEmpty");
+function readSurfaceLock(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+__name(readSurfaceLock, "readSurfaceLock");
+function renderMcpArtifacts(options) {
+  const document = typeof options.document === "function" ? options.document() : options.document;
+  const tools = generateTools(document);
+  const digest = surfaceDigest(tools, options.source);
+  const surfaceProblem = surfaceLockProblem({
+    previous: readSurfaceLock(options.outputs.surfaceLock),
+    version: options.version,
+    digest,
+    versionLocation: options.versionLocation,
+    ...options.versionName ? { versionName: options.versionName } : {}
+  });
+  const manifestValue = buildManifest(tools, {
+    version: options.version,
+    source: options.source
+  });
+  const artifacts = /* @__PURE__ */ new Map([
+    [options.outputs.openapi, `${JSON.stringify(document, null, 2)}
+`],
+    [options.outputs.manifest, serializeManifest(manifestValue)],
+    [
+      options.outputs.surfaceLock,
+      serializeSurfaceLock({ version: options.version, digest })
+    ]
+  ]);
+  for (const extra of options.extraArtifacts ?? []) {
+    artifacts.set(extra.path, extra.render(manifestValue));
+  }
+  return { artifacts, surfaceProblem };
+}
+__name(renderMcpArtifacts, "renderMcpArtifacts");
+function mcpArtifactDrift(artifacts) {
+  return [...artifacts.entries()].filter(([path, rendered]) => readOrEmpty(path) !== rendered).map(([path]) => path);
+}
+__name(mcpArtifactDrift, "mcpArtifactDrift");
+function writeMcpArtifacts(artifacts) {
+  for (const [path, contents] of artifacts) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, contents);
+  }
+}
+__name(writeMcpArtifacts, "writeMcpArtifacts");
+function mcpGenerateCli(options) {
+  const { artifacts, surfaceProblem } = renderMcpArtifacts(options);
+  if (surfaceProblem) {
+    console.error(`[mcp:surface] ${surfaceProblem}`);
+    process.exit(1);
+  }
+  if (options.check) {
+    const drift = mcpArtifactDrift(artifacts);
+    if (drift.length > 0) {
+      console.error(
+        `[mcp:check] drift in: ${drift.join(", ")}.
+Run \`${options.regenerateCommand ?? "pnpm mcp:generate"}\` and commit the result.`
+      );
+      process.exit(1);
+    }
+    console.log("[mcp:check] MCP surface is in sync with the OpenAPI registry.");
+    return;
+  }
+  writeMcpArtifacts(artifacts);
+  console.log(`[mcp:generate] wrote ${[...artifacts.keys()].join(", ")}`);
+}
+__name(mcpGenerateCli, "mcpGenerateCli");
+export {
+  mcpArtifactDrift,
+  mcpGenerateCli,
+  renderMcpArtifacts,
+  writeMcpArtifacts
+};
+//# sourceMappingURL=index.js.map

package/dist/generate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/generate/index.ts"],"sourcesContent":["import { mkdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\n\nimport { generateTools, type OpenApiDocument } from \"../openapi/generate\";\nimport { buildManifest, serializeManifest } from \"../server/manifest\";\nimport {\n  serializeSurfaceLock,\n  surfaceDigest,\n  surfaceLockProblem,\n  type SurfaceLock,\n} from \"../server/surface-lock\";\nimport type { ToolManifest } from \"../types\";\n\n/**\n * `@12-apps/mcp/generate` — the `mcp:generate` / `mcp:check` gate (12-23), moved\n * out of the origin host's `apps/web/scripts/mcp/generate.ts` so a host's own script is\n * a one-line call and `12-apps/ci`'s `mcp-contract.yml`, which shells out to the\n * consumer's `mcp:check` package script, keeps working unchanged.\n *\n * It renders the committed surface artifacts from the host's OpenAPI document:\n *\n *   openapi.json      — the document itself, canonicalized\n *   manifest.json     — the MCP tool manifest generated from it\n *   surface-lock.json — which surface the current version stands for\n *\n * With `check: true` it regenerates IN MEMORY and fails on any drift — the same\n * command CI runs, so a forgotten regeneration is a red build rather than a tool\n * list that silently disagrees with the endpoints.\n *\n * It ALSO refuses, in both modes, to emit a tool surface that changed while the\n * advertised VERSION did not. That version is the only signal a connected host has\n * that `tools/list` is worth re-reading, so a shipped tool behind an unmoved\n * version is invisible to every client that already cached it — and \"remember to\n * bump it\" as a comment is not a rule (see `server/surface-lock.ts`).\n */\n\n/** One extra artifact a host renders from the same manifest, e.g. a store submission. */\nexport interface McpExtraArtifact {\n  /** Absolute path of the committed file. */\n  path: string;\n  /** Rendered text, INCLUDING its trailing newline (compared byte for byte). */\n  render: (manifest: ToolManifest) => string;\n}\n\nexport interface McpGenerateOptions {\n  /**\n   * The host's OpenAPI document, or a thunk producing it. A thunk is the useful\n   * form: building it usually evaluates a Zod registry, and `--check` should pay\n   * that cost once, when it runs.\n   */\n  document: OpenApiDocument | (() => OpenApiDocument);\n  /**\n   * The advertised surface version — the number a client is handed on `initialize`\n   * and caches `tools/list` against.\n   */\n  version: number;\n  /** Human label for the spec the tools were generated from. */\n  source: string;\n  /**\n   * Where the host's version constant lives, repo-relative — quoted verbatim in\n   * the surface-lock failure, so the fix is a path and a value rather than a hunt.\n   */\n  versionLocation: string;\n  /** The constant's name, if the host does not call it `MCP_SURFACE_VERSION`. */\n  versionName?: string;\n  /** Where the three artifacts are committed. */\n  outputs: {\n    openapi: string;\n    manifest: string;\n    surfaceLock: string;\n  };\n  /** Anything else the host commits from the same manifest. */\n  extraArtifacts?: readonly McpExtraArtifact[];\n}\n\n/** The rendered text of every artifact, keyed by its committed path. */\nexport type RenderedArtifacts = Map<string, string>;\n\nexport interface McpGenerateResult {\n  artifacts: RenderedArtifacts;\n  /** Non-null when the surface moved without a version bump — the message to print. */\n  surfaceProblem: string | null;\n}\n\nfunction readOrEmpty(path: string): string {\n  try {\n    return readFileSync(path, \"utf8\");\n  } catch {\n    return \"\";\n  }\n}\n\nfunction readSurfaceLock(path: string): SurfaceLock | null {\n  try {\n    return JSON.parse(readFileSync(path, \"utf8\")) as SurfaceLock;\n  } catch {\n    // No lock committed yet — there is nothing to contradict.\n    return null;\n  }\n}\n\n/**\n * Render every artifact from the document. Pure: nothing is written and nothing is\n * compared, so a caller can diff, print or discard the result.\n */\nexport function renderMcpArtifacts(options: McpGenerateOptions): McpGenerateResult {\n  const document =\n    typeof options.document === \"function\" ? options.document() : options.document;\n  const tools = generateTools(document);\n\n  // Before anything is written or compared: does this version still stand for this\n  // surface? The digest is of what `tools/list` would actually return, which is\n  // neither over- nor under-sensitive the way a paths filter on the registry's\n  // source tree is in both directions.\n  const digest = surfaceDigest(tools, options.source);\n  const surfaceProblem = surfaceLockProblem({\n    previous: readSurfaceLock(options.outputs.surfaceLock),\n    version: options.version,\n    digest,\n    versionLocation: options.versionLocation,\n    ...(options.versionName ? { versionName: options.versionName } : {}),\n  });\n\n  const manifestValue = buildManifest(tools, {\n    version: options.version,\n    source: options.source,\n  });\n\n  const artifacts: RenderedArtifacts = new Map([\n    [options.outputs.openapi, `${JSON.stringify(document, null, 2)}\\n`],\n    [options.outputs.manifest, serializeManifest(manifestValue)],\n    [\n      options.outputs.surfaceLock,\n      serializeSurfaceLock({ version: options.version, digest }),\n    ],\n  ]);\n  for (const extra of options.extraArtifacts ?? []) {\n    artifacts.set(extra.path, extra.render(manifestValue));\n  }\n\n  return { artifacts, surfaceProblem };\n}\n\n/** Every artifact whose committed text differs from a fresh render. */\nexport function mcpArtifactDrift(artifacts: RenderedArtifacts): string[] {\n  return [...artifacts.entries()]\n    .filter(([path, rendered]) => readOrEmpty(path) !== rendered)\n    .map(([path]) => path);\n}\n\n/** Write every artifact, creating directories as needed. */\nexport function writeMcpArtifacts(artifacts: RenderedArtifacts): void {\n  for (const [path, contents] of artifacts) {\n    mkdirSync(dirname(path), { recursive: true });\n    writeFileSync(path, contents);\n  }\n}\n\nexport interface McpGenerateCliOptions extends McpGenerateOptions {\n  /** `true` for `mcp:check` (verify only), `false` for `mcp:generate` (write). */\n  check: boolean;\n  /** The command to suggest on drift. Default: `pnpm mcp:generate`. */\n  regenerateCommand?: string;\n}\n\n/**\n * The CLI face: render, then either verify or write, printing the verdict and\n * exiting non-zero on any failure. A host's `scripts/mcp/generate.ts` becomes an\n * import, its document builder, and one call.\n */\nexport function mcpGenerateCli(options: McpGenerateCliOptions): void {\n  const { artifacts, surfaceProblem } = renderMcpArtifacts(options);\n\n  if (surfaceProblem) {\n    // Exits rather than throws so the message IS the whole output — it names the\n    // number to change and where, which is the entire point of failing here\n    // instead of leaving it to review.\n    console.error(`[mcp:surface] ${surfaceProblem}`);\n    process.exit(1);\n  }\n\n  if (options.check) {\n    const drift = mcpArtifactDrift(artifacts);\n    if (drift.length > 0) {\n      console.error(\n        `[mcp:check] drift in: ${drift.join(\", \")}.\\n` +\n          `Run \\`${options.regenerateCommand ?? \"pnpm mcp:generate\"}\\` and commit the result.`,\n      );\n      process.exit(1);\n    }\n    console.log(\"[mcp:check] MCP surface is in sync with the OpenAPI registry.\");\n    return;\n  }\n\n  writeMcpArtifacts(artifacts);\n  console.log(`[mcp:generate] wrote ${[...artifacts.keys()].join(\", \")}`);\n}\n"],"mappings":";;;;;;;;;;;;;AAAA,SAAS,WAAW,cAAc,qBAAqB;AACvD,SAAS,eAAe;AAmFxB,SAAS,YAAY,MAAsB;AACzC,MAAI;AACF,WAAO,aAAa,MAAM,MAAM;AAAA,EAClC,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AANS;AAQT,SAAS,gBAAgB,MAAkC;AACzD,MAAI;AACF,WAAO,KAAK,MAAM,aAAa,MAAM,MAAM,CAAC;AAAA,EAC9C,QAAQ;AAEN,WAAO;AAAA,EACT;AACF;AAPS;AAaF,SAAS,mBAAmB,SAAgD;AACjF,QAAM,WACJ,OAAO,QAAQ,aAAa,aAAa,QAAQ,SAAS,IAAI,QAAQ;AACxE,QAAM,QAAQ,cAAc,QAAQ;AAMpC,QAAM,SAAS,cAAc,OAAO,QAAQ,MAAM;AAClD,QAAM,iBAAiB,mBAAmB;AAAA,IACxC,UAAU,gBAAgB,QAAQ,QAAQ,WAAW;AAAA,IACrD,SAAS,QAAQ;AAAA,IACjB;AAAA,IACA,iBAAiB,QAAQ;AAAA,IACzB,GAAI,QAAQ,cAAc,EAAE,aAAa,QAAQ,YAAY,IAAI,CAAC;AAAA,EACpE,CAAC;AAED,QAAM,gBAAgB,cAAc,OAAO;AAAA,IACzC,SAAS,QAAQ;AAAA,IACjB,QAAQ,QAAQ;AAAA,EAClB,CAAC;AAED,QAAM,YAA+B,oBAAI,IAAI;AAAA,IAC3C,CAAC,QAAQ,QAAQ,SAAS,GAAG,KAAK,UAAU,UAAU,MAAM,CAAC,CAAC;AAAA,CAAI;AAAA,IAClE,CAAC,QAAQ,QAAQ,UAAU,kBAAkB,aAAa,CAAC;AAAA,IAC3D;AAAA,MACE,QAAQ,QAAQ;AAAA,MAChB,qBAAqB,EAAE,SAAS,QAAQ,SAAS,OAAO,CAAC;AAAA,IAC3D;AAAA,EACF,CAAC;AACD,aAAW,SAAS,QAAQ,kBAAkB,CAAC,GAAG;AAChD,cAAU,IAAI,MAAM,MAAM,MAAM,OAAO,aAAa,CAAC;AAAA,EACvD;AAEA,SAAO,EAAE,WAAW,eAAe;AACrC;AApCgB;AAuCT,SAAS,iBAAiB,WAAwC;AACvE,SAAO,CAAC,GAAG,UAAU,QAAQ,CAAC,EAC3B,OAAO,CAAC,CAAC,MAAM,QAAQ,MAAM,YAAY,IAAI,MAAM,QAAQ,EAC3D,IAAI,CAAC,CAAC,IAAI,MAAM,IAAI;AACzB;AAJgB;AAOT,SAAS,kBAAkB,WAAoC;AACpE,aAAW,CAAC,MAAM,QAAQ,KAAK,WAAW;AACxC,cAAU,QAAQ,IAAI,GAAG,EAAE,WAAW,KAAK,CAAC;AAC5C,kBAAc,MAAM,QAAQ;AAAA,EAC9B;AACF;AALgB;AAmBT,SAAS,eAAe,SAAsC;AACnE,QAAM,EAAE,WAAW,eAAe,IAAI,mBAAmB,OAAO;AAEhE,MAAI,gBAAgB;AAIlB,YAAQ,MAAM,iBAAiB,cAAc,EAAE;AAC/C,YAAQ,KAAK,CAAC;AAAA,EAChB;AAEA,MAAI,QAAQ,OAAO;AACjB,UAAM,QAAQ,iBAAiB,SAAS;AACxC,QAAI,MAAM,SAAS,GAAG;AACpB,cAAQ;AAAA,QACN,yBAAyB,MAAM,KAAK,IAAI,CAAC;AAAA,QAC9B,QAAQ,qBAAqB,mBAAmB;AAAA,MAC7D;AACA,cAAQ,KAAK,CAAC;AAAA,IAChB;AACA,YAAQ,IAAI,+DAA+D;AAC3E;AAAA,EACF;AAEA,oBAAkB,SAAS;AAC3B,UAAQ,IAAI,wBAAwB,CAAC,GAAG,UAAU,KAAK,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE;AACxE;AA1BgB;","names":[]}

package/dist/generate-Dx3cK8th.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Core types for the app-agnostic MCP layer.
+ *
+ * The design in one sentence: generate one MCP tool per OpenAPI operation, and
+ * dispatch each tool call by proxying to the real HTTP endpoint carrying the
+ * caller's bearer token — so an agent gets exactly the user's permissions and
+ * authorization stays entirely in the endpoints (never re-implemented here).
+ *
+ * This package is deliberately free of any app/domain specifics and of the MCP
+ * transport SDK: it turns a spec into tools and a tool call into an HTTP request.
+ * The consuming app supplies the OpenAPI document, the base URL, and an
+ * {@link AuthResolver}; it binds {@link ToolRegistry} to the MCP transport.
+ */
+/** A JSON Schema object (draft 2020-12). We treat schemas opaquely and forward them. */
+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`.
+ */
+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. */
+type ParameterLocation = "path" | "query" | "header";
+/** One OpenAPI operation parameter, retained so the dispatcher can route args. */
+interface ToolParameter {
+    name: string;
+    in: ParameterLocation;
+    required: boolean;
+    schema: JsonSchema;
+}
+/**
+ * A single generated MCP tool: an agent-facing input schema plus everything the
+ * dispatcher needs to reconstruct the HTTP call. This is the unit that is both
+ * served to agents and committed to the drift manifest.
+ */
+interface GeneratedTool {
+    /** Stable tool id: the operationId, or a `method_path` slug when absent. */
+    name: string;
+    description: string;
+    /** Uppercase HTTP method, e.g. "GET", "POST". */
+    method: string;
+    /** OpenAPI path template, e.g. "/products/{id}". */
+    path: string;
+    /** Agent-facing input schema (params + flattened request-body properties). */
+    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). */
+    bodyProps: string[];
+    /** True when the request body is not an object (sent verbatim as the payload). */
+    bodyIsWhole: boolean;
+    /** True for POST/PUT/PATCH/DELETE — a write. Consumers may gate these. */
+    mutating: boolean;
+    /** OpenAPI security requirement names referenced by the operation, if any. */
+    security: string[];
+}
+/** The committed source-of-truth artifact the drift gate (`mcp:check`) diffs. */
+interface ToolManifest {
+    /** Bumped on any intentional shape change (mirrors the golden-catalog convention). */
+    version: number;
+    /** Human label for the spec the tools were generated from. */
+    source: string;
+    tools: GeneratedTool[];
+}
+/** Options controlling tool generation from an OpenAPI document. */
+interface GenerateOptions {
+    /** Only include operations whose method is in this set (default: all). */
+    includeMethods?: readonly string[];
+    /** Drop operations tagged with any of these (e.g. "internal"). */
+    excludeTags?: readonly string[];
+    /** Predicate to include/exclude an operation by (method, path). */
+    filter?: (method: string, path: string) => boolean;
+}
+/**
+ * The caller's resolved authorization for a single request. The dispatcher only
+ * ever forwards `bearer` upstream; identity/permission checks happen at the
+ * endpoint. `subject`/`scopes` are surfaced for logging and tool-visibility
+ * decisions, not for authorization.
+ */
+interface RequestAuth {
+    /** The bearer token to forward to the upstream endpoint (verbatim). */
+    bearer: string;
+    /** Token subject (for logging only). */
+    subject?: string;
+    /** Granted scopes (for optional tool visibility filtering). */
+    scopes?: readonly string[];
+}
+/**
+ * App-supplied hook that turns an incoming request into {@link RequestAuth}, or
+ * `null` when unauthenticated. For the OAuth resource-server mode this validates
+ * the access token (signature/audience/scope) and returns the token to forward.
+ */
+type AuthResolver = (request: Request) => Promise<RequestAuth | null>;
+/** Configuration for a proxying dispatch. */
+interface DispatchConfig {
+    /** Origin the tools are proxied to, e.g. "https://app.example.com". */
+    baseUrl: string;
+    /** The caller's bearer, forwarded as `Authorization: Bearer <token>`. */
+    bearer: string;
+    /** Injectable fetch (defaults to global fetch) — eases testing. */
+    fetchImpl?: typeof fetch;
+}
+/** The upstream response, normalized for the MCP layer. */
+interface DispatchResult {
+    status: number;
+    ok: boolean;
+    /** Parsed JSON body when the response was JSON, else the raw text. */
+    body: unknown;
+}
+
+/**
+ * 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).
+ */
+interface OpenApiOperation {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    /** Paladira's required projection of MCP tool annotations into OpenAPI. */
+    "x-mcp-tool-annotations"?: ToolAnnotations;
+    /** Dotted response paths stripped from the result before the agent sees it. */
+    "x-mcp-redact-response"?: readonly string[];
+    parameters?: OpenApiParameter[];
+    requestBody?: OpenApiRequestBody;
+    responses?: Record<string, OpenApiResponse>;
+    security?: Array<Record<string, string[]>>;
+}
+interface OpenApiParameter {
+    name: string;
+    in: string;
+    required?: boolean;
+    schema?: JsonSchema;
+}
+interface OpenApiRequestBody {
+    required?: boolean;
+    content?: Record<string, {
+        schema?: JsonSchema;
+    }>;
+}
+interface OpenApiResponse {
+    content?: Record<string, {
+        schema?: JsonSchema;
+    }>;
+}
+interface OpenApiDocument {
+    paths?: Record<string, Record<string, OpenApiOperation>>;
+    security?: Array<Record<string, string[]>>;
+}
+/**
+ * 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.
+ */
+declare function generateTools(doc: OpenApiDocument, options?: GenerateOptions): GeneratedTool[];
+
+export { type AuthResolver as A, type DispatchConfig as D, type GeneratedTool as G, type JsonSchema as J, type OpenApiDocument as O, type ParameterLocation as P, type RequestAuth as R, type ToolManifest as T, type DispatchResult as a, type ToolAnnotations as b, type GenerateOptions as c, type OpenApiOperation as d, type OpenApiParameter as e, type OpenApiRequestBody as f, type OpenApiResponse as g, type ToolParameter as h, generateTools as i };

package/dist/guide-DV5MQbCg.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 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. */
+type AiHostBrand = "claude" | "openai";
+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.
+ */
+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.
+ */
+type AiProvider = "claude" | "chatgpt" | "codex";
+/** The provider a host id belongs to (claude-desktop shares Claude's provider). */
+declare function providerForHostId(hostId: string): AiProvider | null;
+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;
+}
+/**
+ * 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.
+ *
+ * A FUNCTION of the platform's name, because one step is not generic: the
+ * ChatGPT connector's consent screen shows an OAuth button labelled with
+ * whoever operates the server, and the owner is told which button to click. It
+ * used to name one particular STORE on one particular deployment — not even the
+ * product, a tenant of it — so every other adopter instructed its owners to
+ * click a button that does not exist.
+ */
+declare function aiHostGuides(platformName: string): readonly AiHostGuide[];
+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. */
+declare const AI_CAPABILITIES: readonly AiCapability[];
+/**
+ * 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.
+ */
+declare const AI_PERMISSION_MODEL = "O assistente age em seu nome, com exatamente as suas permiss\u00F5es: ele pode fazer o que voc\u00EA pode fazer na sua loja \u2014 nada al\u00E9m disso. N\u00E3o \u00E9 preciso criar nenhuma chave ou credencial extra; a autoriza\u00E7\u00E3o usa o seu pr\u00F3prio login.";
+/** The two tools the paste-in prompt drives, and what to call the store id. */
+interface AiConnectPromptSpec {
+    /**
+     * The tool that REGISTERS the connection server-side, so the store learns
+     * which assistant connected.
+     */
+    announceTool: string;
+    /** A real READ tool, called straight after, to prove the access works. */
+    probeTool: string;
+    /** What that read returns, in the owner's own words ("o estoque da loja"). */
+    probeSubject: string;
+    /** What the assistant should ask for if it needs to identify the store. */
+    identifierName: string;
+}
+/**
+ * The message the owner pastes into the assistant's chat right after
+ * connecting: announce the connection, then read something real to prove it
+ * works. The owner types nothing.
+ *
+ * BUILT from the host's tool names rather than shipped with them. This was a
+ * constant naming two tools — `announceAiConnection` and `listInventory` — that
+ * THIS PACKAGE does not define or serve; they belong to one adopter's surface.
+ * Any other host handed its owner a prompt instructing the assistant to call
+ * two tools that do not exist, and because nothing registered the connection,
+ * the wizard's confirm step then waited forever for a state that could never
+ * arrive.
+ */
+declare function aiConnectPrompt(spec: AiConnectPromptSpec): string;
+
+export { AI_CAPABILITIES as A, AI_PERMISSION_MODEL as a, type AiCapability as b, type AiConnectPromptSpec as c, type AiHostBrand as d, type AiHostConfigureStage as e, type AiHostGuide as f, type AiHostLink as g, type AiProvider as h, aiConnectPrompt as i, aiHostGuides as j, providerForHostId as p };

package/dist/hono/index.d.ts

@@ -0,0 +1,28 @@
+import { Hono } from 'hono';
+import { A as ApiMcpOauth, M as McpOauthConfig } from '../create-api-mcp-oauth-CwVXKK-A.js';
+import 'jose';
+
+/**
+ * `@12-apps/mcp/hono` — the OAuth authorization server as a mountable router.
+ *
+ * Behind its own subpath with `hono` as an OPTIONAL peer (the report-builder / rbac
+ * precedent), so a host on another framework — or one importing only the tool
+ * generator — never resolves it.
+ *
+ * Mounted at the ORIGIN ROOT, because two of the six paths are `.well-known`
+ * documents and a connector reads them from the origin, not from a prefix:
+ *
+ *   const oauth = mcpOauthRouter({ stores, resolveSession });
+ *   app.route('/', oauth.router);
+ *
+ * The adapter is deliberately thin: each handler already answers a Fetch `Response`
+ * (a 302 with a `Location`, RFC 6749 JSON, an RFC 8414 document), and those shapes
+ * are fixed by specification — there is no envelope to apply, and applying one
+ * would break every client.
+ */
+interface McpOauthHono extends ApiMcpOauth {
+    router: Hono;
+}
+declare function mcpOauthRouter(config: McpOauthConfig): McpOauthHono;
+
+export { type McpOauthHono, mcpOauthRouter };

package/dist/hono/index.js

@@ -0,0 +1,25 @@
+import {
+  createApiMcpOauth
+} from "../chunk-UIILEGAC.js";
+import "../chunk-WJJNKKNS.js";
+import {
+  __name
+} from "../chunk-7QVYU63E.js";
+
+// src/hono/index.ts
+import { Hono } from "hono";
+function mcpOauthRouter(config) {
+  const api = createApiMcpOauth(config);
+  const router = new Hono();
+  for (const route of api.routes) {
+    const handler = /* @__PURE__ */ __name((c) => route.handle(c.req.raw), "handler");
+    if (route.method === "GET") router.get(route.path, handler);
+    else router.post(route.path, handler);
+  }
+  return { ...api, router };
+}
+__name(mcpOauthRouter, "mcpOauthRouter");
+export {
+  mcpOauthRouter
+};
+//# sourceMappingURL=index.js.map

package/dist/hono/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/hono/index.ts"],"sourcesContent":["import { Hono } from \"hono\";\nimport type { Context } from \"hono\";\n\nimport {\n  createApiMcpOauth,\n  type ApiMcpOauth,\n} from \"../oauth/create-api-mcp-oauth\";\nimport type { McpOauthConfig } from \"../oauth/context\";\n\n/**\n * `@12-apps/mcp/hono` — the OAuth authorization server as a mountable router.\n *\n * Behind its own subpath with `hono` as an OPTIONAL peer (the report-builder / rbac\n * precedent), so a host on another framework — or one importing only the tool\n * generator — never resolves it.\n *\n * Mounted at the ORIGIN ROOT, because two of the six paths are `.well-known`\n * documents and a connector reads them from the origin, not from a prefix:\n *\n *   const oauth = mcpOauthRouter({ stores, resolveSession });\n *   app.route('/', oauth.router);\n *\n * The adapter is deliberately thin: each handler already answers a Fetch `Response`\n * (a 302 with a `Location`, RFC 6749 JSON, an RFC 8414 document), and those shapes\n * are fixed by specification — there is no envelope to apply, and applying one\n * would break every client.\n */\nexport interface McpOauthHono extends ApiMcpOauth {\n  router: Hono;\n}\n\nexport function mcpOauthRouter(config: McpOauthConfig): McpOauthHono {\n  const api = createApiMcpOauth(config);\n  const router = new Hono();\n\n  for (const route of api.routes) {\n    const handler = (c: Context): Promise<Response> => route.handle(c.req.raw);\n    if (route.method === \"GET\") router.get(route.path, handler);\n    else router.post(route.path, handler);\n  }\n\n  return { ...api, router };\n}\n"],"mappings":";;;;;;;;;AAAA,SAAS,YAAY;AA+Bd,SAAS,eAAe,QAAsC;AACnE,QAAM,MAAM,kBAAkB,MAAM;AACpC,QAAM,SAAS,IAAI,KAAK;AAExB,aAAW,SAAS,IAAI,QAAQ;AAC9B,UAAM,UAAU,wBAAC,MAAkC,MAAM,OAAO,EAAE,IAAI,GAAG,GAAzD;AAChB,QAAI,MAAM,WAAW,MAAO,QAAO,IAAI,MAAM,MAAM,OAAO;AAAA,QACrD,QAAO,KAAK,MAAM,MAAM,OAAO;AAAA,EACtC;AAEA,SAAO,EAAE,GAAG,KAAK,OAAO;AAC1B;AAXgB;","names":[]}