@autoview/cli 0.1.0

package/lib/agent/emitMcpServer.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitMcpServer = emitMcpServer;
+const toolSurface_1 = require("./toolSurface");
+/**
+ * Emit a runnable MCP (Model Context Protocol) server from an OpenAPI document —
+ * the agent-facing counterpart of the generated frontend. The server exposes the
+ * shaped tool surface (read/write annotations + producer hints) and, on a tool
+ * call, executes the real API over HTTP against the configured backend.
+ *
+ * Returns a flat `path → content` project map (server + package.json + README),
+ * the same shape the frontend scaffold returns, so the CLI writes it the same
+ * way. Deterministic: same document → same server.
+ */
+function emitMcpServer(document, options = { backend: null }) {
+    var _a, _b, _c;
+    const tools = (0, toolSurface_1.buildToolSurface)(document);
+    const coverage = (0, toolSurface_1.coverToolSurface)(tools);
+    const appName = ((_c = (_a = options.title) !== null && _a !== void 0 ? _a : (_b = document.info) === null || _b === void 0 ? void 0 : _b.title) !== null && _c !== void 0 ? _c : "API").trim() || "API";
+    // Only the fields the server needs at runtime (keep the bundle lean).
+    const runtimeTools = tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+        annotations: t.annotations,
+        operation: t.operation,
+    }));
+    return {
+        "server.mjs": renderServer(appName, options.backend, runtimeTools),
+        "package.json": renderPackageJson(appName),
+        "README.md": renderReadme(appName, options.backend, coverage),
+    };
+}
+function renderServer(appName, backend, tools) {
+    return `#!/usr/bin/env node
+// MCP server generated by AutoView from the OpenAPI document of "${appName}".
+// Exposes the API as agent-callable tools and executes calls against the live
+// backend. Configure the backend with API_HOST / API_TOKEN env vars.
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const TOOLS = ${JSON.stringify(tools, null, 2)};
+
+const BASE = (process.env.API_HOST ?? ${JSON.stringify(backend !== null && backend !== void 0 ? backend : "")}).replace(/\\/$/, "");
+const AUTH = process.env.API_TOKEN ?? "";
+
+if (BASE.length === 0) {
+  console.error("Set API_HOST to the backend base URL (e.g. https://api.example.com).");
+  process.exit(1);
+}
+
+const server = new Server(
+  { name: ${JSON.stringify(appName + " (AutoView MCP)")}, version: "1.0.0" },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema,
+    annotations: t.annotations,
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const tool = TOOLS.find((t) => t.name === req.params.name);
+  if (tool === undefined) {
+    return { content: [{ type: "text", text: "Unknown tool: " + req.params.name }], isError: true };
+  }
+  const args = req.params.arguments ?? {};
+  let path = tool.operation.path;
+  for (const p of tool.operation.pathParams) {
+    path = path.replace("{" + p + "}", encodeURIComponent(String(args[p] ?? "")));
+  }
+  const url = new URL(BASE + path);
+  if (tool.operation.hasQuery && args.query && typeof args.query === "object") {
+    for (const [k, v] of Object.entries(args.query)) {
+      if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+    }
+  }
+  const method = tool.operation.method;
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: { "content-type": "application/json", ...(AUTH ? { authorization: AUTH } : {}) },
+      body: ["GET", "HEAD", "DELETE"].includes(method) ? undefined : JSON.stringify(args.body ?? {}),
+    });
+    const text = await res.text();
+    return { content: [{ type: "text", text: text.length > 0 ? text : "(empty) status " + res.status }], isError: !res.ok };
+  } catch (err) {
+    return { content: [{ type: "text", text: "Request failed: " + (err && err.message ? err.message : String(err)) }], isError: true };
+  }
+});
+
+await server.connect(new StdioServerTransport());
+console.error(${JSON.stringify(appName)} + " MCP server ready (" + TOOLS.length + " tools) → " + BASE);
+`;
+}
+function renderPackageJson(appName) {
+    const slug = appName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "api";
+    return JSON.stringify({
+        name: `${slug}-mcp`,
+        version: "1.0.0",
+        private: true,
+        type: "module",
+        bin: { [`${slug}-mcp`]: "./server.mjs" },
+        scripts: { start: "node server.mjs" },
+        dependencies: { "@modelcontextprotocol/sdk": "^1.0.0" },
+    }, null, 2);
+}
+function renderReadme(appName, backend, coverage) {
+    return [
+        `# ${appName} — MCP server`,
+        "",
+        "Generated by AutoView. Exposes the API as agent-callable tools (read/write",
+        "annotated, with producer hints) and executes calls against the live backend.",
+        "",
+        "## Run",
+        "",
+        "```bash",
+        "npm install",
+        `API_HOST=${backend !== null && backend !== void 0 ? backend : "https://api.example.com"} \\`,
+        '  API_TOKEN="Bearer <token>" \\',
+        "  npm start",
+        "```",
+        "",
+        "## Wire into an agent (Claude Desktop / Cursor / Claude Code)",
+        "",
+        "```json",
+        JSON.stringify({
+            mcpServers: {
+                [appName.toLowerCase().replace(/[^a-z0-9]+/g, "-")]: {
+                    command: "node",
+                    args: ["server.mjs"],
+                    env: { API_HOST: backend !== null && backend !== void 0 ? backend : "https://api.example.com", API_TOKEN: "Bearer <token>" },
+                },
+            },
+        }, null, 2),
+        "```",
+        "",
+        "## Surface",
+        "",
+        `- **${coverage.tools}** tools (${coverage.readTools} read, ${coverage.writeTools} write)`,
+        `- **${coverage.resolvedInputs}/${coverage.referenceInputs}** id inputs have a declared producer (navigable)`,
+        coverage.orphanInputs > 0
+            ? `- ⚠️ **${coverage.orphanInputs}** id inputs have NO producer in the API — an agent cannot obtain them from any tool (an API-design gap; see \`--report\`).`
+            : "- ✅ every id input is obtainable from another tool (fully navigable).",
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=emitMcpServer.js.map

package/lib/agent/emitMcpServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitMcpServer.js","sourceRoot":"","sources":["../../src/agent/emitMcpServer.ts"],"names":[],"mappings":"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"}

package/lib/agent/emitReport.d.ts

@@ -0,0 +1,14 @@
+import { OpenApi } from "@typia/interface";
+/**
+ * Consumability report — the deterministic, LLM-free verdict on whether an API
+ * can actually be driven as a product (by an agent or a generated UI).
+ *
+ * Unlike a contract test (which checks each endpoint in isolation), this checks
+ * the API as a *navigable graph*: every id input a tool needs should be
+ * obtainable from another tool. It is honest about its own limits — an id whose
+ * producing endpoint returns an un-introspectable inline schema is reported as
+ * "undetermined", not as a defect, so the report never falsely accuses an API.
+ *
+ * Returns Markdown. Pure and deterministic.
+ */
+export declare function emitConsumabilityReport(document: OpenApi.IDocument): string;

package/lib/agent/emitReport.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitConsumabilityReport = emitConsumabilityReport;
+const toEndpoints_1 = require("../utils/toEndpoints");
+const toolSurface_1 = require("./toolSurface");
+/**
+ * Consumability report — the deterministic, LLM-free verdict on whether an API
+ * can actually be driven as a product (by an agent or a generated UI).
+ *
+ * Unlike a contract test (which checks each endpoint in isolation), this checks
+ * the API as a *navigable graph*: every id input a tool needs should be
+ * obtainable from another tool. It is honest about its own limits — an id whose
+ * producing endpoint returns an un-introspectable inline schema is reported as
+ * "undetermined", not as a defect, so the report never falsely accuses an API.
+ *
+ * Returns Markdown. Pure and deterministic.
+ */
+function emitConsumabilityReport(document) {
+    var _a, _b;
+    const title = ((_b = (_a = document.info) === null || _a === void 0 ? void 0 : _a.title) !== null && _b !== void 0 ? _b : "API").trim() || "API";
+    const a = (0, toolSurface_1.analyzeConsumability)(document);
+    // Judgeable id inputs = those we can rule on: obtainable (resolved + nested)
+    // vs a genuine gap (orphan). userInput/untraceable are not entity-id gaps.
+    const obtainable = a.resolved + a.nested;
+    const denom = obtainable + a.orphan.length;
+    const navigable = denom > 0 ? Math.round((100 * obtainable) / denom) : 100;
+    const dropped = (0, toEndpoints_1.unsupportedOperations)(document);
+    const lines = [
+        `# Consumability report — ${title}`,
+        "",
+        "Can this API be driven as a product? Checked deterministically (no LLM) by",
+        "projecting the spec into an agent tool surface and verifying the call graph —",
+        "every id a tool needs should be obtainable from another tool.",
+        "",
+        "## Summary",
+        "",
+        `- **${a.tools}** operations (${a.readTools} read, ${a.writeTools} write); **${a.referenceInputs}** id inputs.`,
+        `- ✅ **${a.resolved}** inputs resolved — a list/search tool produces the id, and the surface tells the agent which one.`,
+        a.nested > 0
+            ? `- ✅ **${a.nested}** obtainable nested — the id appears inside a parent read's response (e.g. \`order\` → \`goods[].id\`); navigable, just not via a dedicated list tool.`
+            : null,
+        a.orphan.length === 0
+            ? "- ✅ **0** genuine orphan inputs."
+            : `- ⚠️ **${a.orphan.length}** orphan inputs — a required id NO endpoint can supply (design gap).`,
+        a.untraceable.length > 0
+            ? `- ❔ **${a.untraceable.length}** undetermined — the resource is read but no id could be traced in its (often inline) response; navigability not provable either way.`
+            : null,
+        a.userInputs.length > 0
+            ? `- 👤 **${a.userInputs.length}** caller-supplied keys (\`*_name\` / \`*_key\` / \`scope\` …) — not entity ids, so a missing producer is expected, not a gap.`
+            : null,
+        `- **Navigability (of judgeable inputs): ${navigable}%** (${obtainable}/${denom}).`,
+        dropped.length > 0
+            ? `- **${dropped.length}** operation(s) could not be exposed at all (unsupported shape).`
+            : null,
+        "",
+    ].filter((l) => l !== null);
+    if (a.orphan.length > 0) {
+        lines.push("## ⚠️ Orphan inputs (genuine design gaps)", "", "These tools require an id, but **no endpoint reads that resource** — nothing", "in the API can supply the value. An agent or UI cannot call them without an", "out-of-band id. Usually a missing list/detail endpoint, or an id named", "inconsistently with its resource.", "");
+        for (const o of a.orphan.slice(0, 50)) {
+            lines.push(`- \`${o.tool}\` needs \`${o.param}\` (a \`${o.resource}\` id) — no endpoint produces it.`);
+        }
+        if (a.orphan.length > 50)
+            lines.push(`- …and ${a.orphan.length - 50} more.`);
+        lines.push("");
+    }
+    if (a.untraceable.length > 0) {
+        lines.push("## ❔ Undetermined inputs", "", "The resource has a read endpoint, but its response is an inline schema this", "analysis does not model, so the producer link could not be traced. Not a", "reported defect — likely fine, just not machine-verified here.", "", `- ${a.untraceable.length} inputs across ${new Set(a.untraceable.map((u) => u.resource)).size} resources (e.g. ${[...new Set(a.untraceable.slice(0, 5).map((u) => u.resource))].join(", ")}).`, "");
+    }
+    if (a.userInputs.length > 0) {
+        lines.push("## 👤 Caller-supplied keys", "", "These path params are human-known keys (a name, a `scope`, a `template_key`),", "not entity ids chained from another endpoint. The caller already knows the", "value, so the absence of a producing tool is by design — not a gap.", "", `- ${a.userInputs.length} inputs across ${new Set(a.userInputs.map((u) => u.param)).size} key(s) (e.g. ${[...new Set(a.userInputs.slice(0, 6).map((u) => `\`${u.param}\``))].join(", ")}).`, "");
+    }
+    if (dropped.length > 0) {
+        lines.push("## Unexposed operations", "");
+        for (const d of dropped.slice(0, 20))
+            lines.push(`- \`${d.method} ${d.path}\` — ${d.reason}`);
+        if (dropped.length > 20)
+            lines.push(`- …and ${dropped.length - 20} more.`);
+        lines.push("");
+    }
+    lines.push("## Verdict", "", a.orphan.length === 0
+        ? "✅ No genuine consumability gaps found — every id a tool needs is obtainable from the API (within what could be analyzed)."
+        : `⚠️ ${a.orphan.length} input(s) cannot be supplied by the API. Add the missing list/detail endpoints (or align id field names) so every id is obtainable, then re-run.`, "");
+    return lines.join("\n");
+}
+//# sourceMappingURL=emitReport.js.map

package/lib/agent/emitReport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitReport.js","sourceRoot":"","sources":["../../src/agent/emitReport.ts"],"names":[],"mappings":";;AAiBA,0DAmGC;AAlHD,sDAA6D;AAC7D,+CAAqD;AAErD;;;;;;;;;;;GAWG;AACH,SAAgB,uBAAuB,CAAC,QAA2B;;IACjE,MAAM,KAAK,GAAG,CAAC,MAAA,MAAA,QAAQ,CAAC,IAAI,0CAAE,KAAK,mCAAI,KAAK,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,IAAA,kCAAoB,EAAC,QAAQ,CAAC,CAAC;IACzC,6EAA6E;IAC7E,2EAA2E;IAC3E,MAAM,UAAU,GAAG,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;IAC3C,MAAM,SAAS,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,UAAU,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC3E,MAAM,OAAO,GAAG,IAAA,mCAAqB,EAAC,QAAQ,CAAC,CAAC;IAEhD,MAAM,KAAK,GAAa;QACtB,4BAA4B,KAAK,EAAE;QACnC,EAAE;QACF,4EAA4E;QAC5E,+EAA+E;QAC/E,+DAA+D;QAC/D,EAAE;QACF,YAAY;QACZ,EAAE;QACF,OAAO,CAAC,CAAC,KAAK,kBAAkB,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,UAAU,cAAc,CAAC,CAAC,eAAe,eAAe;QAC/G,SAAS,CAAC,CAAC,QAAQ,qGAAqG;QACxH,CAAC,CAAC,MAAM,GAAG,CAAC;YACV,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,yJAAyJ;YAC5K,CAAC,CAAC,IAAI;QACR,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;YACnB,CAAC,CAAC,kCAAkC;YACpC,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,MAAM,uEAAuE;QACpG,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;YACtB,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,CAAC,MAAM,wIAAwI;YACvK,CAAC,CAAC,IAAI;QACR,CAAC,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;YACrB,CAAC,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,MAAM,gIAAgI;YAC/J,CAAC,CAAC,IAAI;QACR,2CAA2C,SAAS,QAAQ,UAAU,IAAI,KAAK,IAAI;QACnF,OAAO,CAAC,MAAM,GAAG,CAAC;YAChB,CAAC,CAAC,OAAO,OAAO,CAAC,MAAM,kEAAkE;YACzF,CAAC,CAAC,IAAI;QACR,EAAE;KACH,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IAEzC,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CACR,2CAA2C,EAC3C,EAAE,EACF,8EAA8E,EAC9E,6EAA6E,EAC7E,wEAAwE,EACxE,mCAAmC,EACnC,EAAE,CACH,CAAC;QACF,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC,QAAQ,mCAAmC,CAAC,CAAC;QACzG,CAAC;QACD,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC7E,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CACR,0BAA0B,EAC1B,EAAE,EACF,6EAA6E,EAC7E,0EAA0E,EAC1E,gEAAgE,EAChE,EAAE,EACF,KAAK,CAAC,CAAC,WAAW,CAAC,MAAM,kBAAkB,IAAI,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,oBAAoB,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAC9L,EAAE,CACH,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CACR,4BAA4B,EAC5B,EAAE,EACF,+EAA+E,EAC/E,4EAA4E,EAC5E,qEAAqE,EACrE,EAAE,EACF,KAAK,CAAC,CAAC,UAAU,CAAC,MAAM,kBAAkB,IAAI,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,iBAAiB,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAC3L,EAAE,CACH,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,CAAC,CAAC;QAC1C,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9F,IAAI,OAAO,CAAC,MAAM,GAAG,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,UAAU,OAAO,CAAC,MAAM,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC3E,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,IAAI,CACR,YAAY,EACZ,EAAE,EACF,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;QACnB,CAAC,CAAC,2HAA2H;QAC7H,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,kJAAkJ,EAC3K,EAAE,CACH,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/lib/agent/toolSurface.d.ts

@@ -0,0 +1,130 @@
+import { OpenApi } from "@typia/interface";
+/**
+ * Agent tool surface — the deterministic projection of the API's semantic model
+ * (IR) into a set of agent-callable tools (MCP / function-calling shape).
+ *
+ * The same IR that drives the human frontend drives this: resource roles
+ * (read vs write), the resource hierarchy, and the producer→consumer chain (which
+ * tool's output supplies a given tool's id input). A naive OpenAPI→tools dump
+ * has none of that — it emits a flat bag of operations. This emits tools that
+ * carry:
+ *
+ * - `annotations.readOnlyHint` / `destructiveHint` — safety, so an agent (or its
+ *   guardrails) can tell a read from a mutation without parsing prose.
+ * - per-input producer hints — "this `saleId` comes from the `sales.index`
+ *   tool's `id` field" — so the chain is explicit, not inferred.
+ * - only renderable operations (path fragments like `/x#y` that nestia cannot
+ *   express as a typed call are dropped — `toEndpoints` already excludes them).
+ *
+ * Pure and deterministic: same document → same tool surface.
+ */
+export interface IAgentTool {
+    /** Dotted accessor, unique and a valid tool name (`shoppings.sales.index`). */
+    name: string;
+    description: string;
+    /** JSON Schema for the call arguments. */
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required: string[];
+    };
+    /** MCP-style behavior hints. */
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+    };
+    /** Execution descriptor — how an MCP server / executor invokes the real API. */
+    operation: {
+        method: string;
+        path: string;
+        pathParams: string[];
+        hasQuery: boolean;
+        hasBody: boolean;
+    };
+    /**
+     * Producer links: for each id-like path param, the tool + field that produces
+     * its value. Empty when the surface could not resolve a producer.
+     */
+    producers: Array<{
+        param: string;
+        tool: string;
+        field: string;
+    }>;
+}
+/**
+ * Build the agent tool surface from an OpenAPI document.
+ */
+export declare function buildToolSurface(document: OpenApi.IDocument): IAgentTool[];
+/**
+ * Honest consumability analysis with a 4-way split per path-param input, so the
+ * report never accuses an API of a design gap it cannot actually prove:
+ *
+ * - `resolved`   — a collection read (list/search) produces the id; the tool
+ *   surface declares that producer. Directly navigable, and the agent is told
+ *   exactly where the id comes from.
+ * - `nested`     — the id is obtainable nested inside a parent read's response
+ *   (`order` → `goods[].id`, `sale` → `units[].stocks[].id`), but no dedicated
+ *   list tool produces it. Navigable, just not via a single tool — counted
+ *   honestly, separate from `resolved` so the report matches the tool surface.
+ * - `untraceable`— the resource HAS a read endpoint, but no id could be found in
+ *   its response (e.g. an inline schema this analysis can't fully introspect).
+ *   Undetermined, not blamed.
+ * - `userInput`  — the param is not an entity id but a human-known key
+ *   (`repository_name`, `template_key`, a `scope`/`slug`), supplied by the
+ *   caller — a missing producer is expected, NOT a defect.
+ * - `orphan`     — an entity id (`*_id` / `uuid`) that NO endpoint produces. A
+ *   genuine consumability defect.
+ */
+export interface IConsumabilityAnalysis {
+    tools: number;
+    readTools: number;
+    writeTools: number;
+    referenceInputs: number;
+    resolved: number;
+    nested: number;
+    untraceable: Array<{
+        tool: string;
+        param: string;
+        resource: string;
+    }>;
+    userInputs: Array<{
+        tool: string;
+        param: string;
+        resource: string;
+    }>;
+    orphan: Array<{
+        tool: string;
+        param: string;
+        resource: string;
+    }>;
+}
+export declare function analyzeConsumability(document: OpenApi.IDocument): IConsumabilityAnalysis;
+/** Coverage summary of a tool surface — how navigable it is for an agent. */
+export interface IToolSurfaceCoverage {
+    tools: number;
+    /** Tools tagged read vs write. */
+    readTools: number;
+    writeTools: number;
+    /** id-like path-param inputs across the surface. */
+    referenceInputs: number;
+    /** reference inputs with a declared producer (the navigable fraction). */
+    resolvedInputs: number;
+    /** reference inputs with no producer — an agent must guess where they come from. */
+    orphanInputs: number;
+    /**
+     * The orphan inputs in detail: a required id with no tool in the API that
+     * produces it. An agent (or a human) cannot obtain this value from any
+     * endpoint — a consumability defect in the API design.
+     */
+    orphans: Array<{
+        tool: string;
+        param: string;
+    }>;
+}
+/**
+ * Deterministic structural coverage of a tool surface — the LLM-independent
+ * verification: is the tool graph navigable (every id input has a declared
+ * producer)? Reported as a report card, distinct from running an agent.
+ */
+export declare function coverToolSurface(tools: IAgentTool[]): IToolSurfaceCoverage;