rapidoc 12.0.0 → 12.1.0

package/src/utils/curl-utils.js

@@ -34,6 +34,7 @@ export function deduplicateHeaderValues(value) {
  * @param {Headers|Map|Array<[string, string]>|object} [options.headers] - Request headers
  * @param {URLSearchParams|FormData|File|string|object} [options.body] - Request body payload
  * @param {string} [options.contentType=''] - Content type of the payload
+ * @param {Object<string, string>} [options.partContentTypes] - Content-Type of multipart parts, by field name
  * @param {string} [options.baseLocation] - Optional base location to resolve relative URLs
  * @returns {string} Formatted cURL snippet
  */
@@ -43,6 +44,7 @@ export function generateCurlCommand({
   headers,
   body,
   contentType = "",
+  partContentTypes = {},
   baseLocation = typeof location !== "undefined" ? location.href : "",
 } = {}) {
   let curlUrl = url;
@@ -87,12 +89,13 @@ export function generateCurlCommand({
   } else if (typeof FormData !== "undefined" && body instanceof FormData) {
     curlForm = Array.from(body)
       .map(([key, value]) => {
+        const type = partContentTypes?.[key] ? `;type=${partContentTypes[key]}` : "";
         if (typeof File !== "undefined" && value instanceof File) {
-          return ` -F "${key}=@${value.name}"`;
+          return ` -F "${key}=@${value.name}${value.type ? "" : type}"`;
         }
         const sanitizedVal =
           typeof value === "string" ? value.replace(/\\/g, "\\\\").replace(/"/g, '\\"') : value;
-        return ` -F "${key}=${sanitizedVal}"`;
+        return ` -F "${key}=${sanitizedVal}${type}"`;
       })
       .join("\\\n");
     if (curlForm) {

package/src/utils/highlighter.js

@@ -407,6 +407,9 @@ export const highlightAllCode = (rootNode = document) => {
 };
 
 export const scheduleHighlight = (rootNode = document) => {
+  if (typeof window === "undefined" || typeof CSS === "undefined" || !CSS.highlights) {
+    return;
+  }
   if (highlightScheduled) return;
   highlightScheduled = true;
   requestAnimationFrame(() => {

package/src/utils/mcp/README.md

@@ -0,0 +1,155 @@
+# MCP Manifest, Runtime and Export
+
+## Overview
+
+Turns an OpenAPI document into an **MCP manifest** (plain JSON: one tool per operation, with
+JSON Schema arguments and MCP safety annotations) and executes that manifest with `fetch`. The
+exported MCP server is the manifest plus two fixed files: `runtime.js` (this folder's runtime,
+copied verbatim) and `project/server.ts` (a stdio server on `@modelcontextprotocol/sdk` that
+registers the manifest's tools and hands calls to the runtime). The entry point is
+`src/utils/mcp-generator.js`; `<rapi-doc>` (`src/rapidoc.ts`, `src/templates/downloads-template.js`)
+uses it for its Export MCP Server button, and `packages/rapidoc-mcp/src/index.js` re-exports it as `@rapidoc/mcp`
+(a separate package, Node only, no Lit) for the portal build, `@rapidoc/server` and the CLI.
+
+Arazzo workflows become tools too: `workflows.js` compiles a parsed Arazzo document into
+`manifest.workflows` (steps resolved to operations) and one tool per workflow, and
+`workflow-runtime.js` runs them on top of `runtime.js`. The two runtimes are separate files so
+`dist/rapidoc-min.js` (operation tools only) carries no Arazzo runtime, while
+`dist/rapidoc-flow-min.js` and `@rapidoc/mcp` include both. Not owned here: Arazzo parsing and validation (`../arazzo/`), the `<rapi-doc>` attribute and
+methods, and the network calls themselves (the runtime only builds and sends requests).
+
+## Interface
+
+- `compileWorkflows(arazzo, { sources, onProblem }) -> { tools, workflows }` [workflows.js]:
+  `sources` are operation indexes by Arazzo source name (`../arazzo/operations.js`). A workflow the
+  runtime cannot run is reported once through `onProblem` and left out. `buildMcpManifest` calls
+  it for `options.arazzo`, naming the manifest's source after the Arazzo document's first OpenAPI
+  source so steps resolve; `generateMcpServer` collects the problems into its result.
+
+- `buildMcpManifest(spec, options) -> manifest` [manifest.js]: `spec` is a raw OpenAPI 3.x /
+  Swagger 2.0 object or `ProcessSpec`'s result (`tags[].paths[]`). Options: `serverName`,
+  `sourceName` (default `api`), `includeInternal`, `includeDeprecated`, `includeOperations` (`false`:
+  only the Arazzo workflows' tools, for a manifest of workflows). `toJsonSchema(schema,
+  root)` is the schema converter on its own; `MANIFEST_VERSION` is `1`.
+- `createMcpRuntime(manifest, { fetch, credentials, baseUrls, runWorkflow })` [runtime.js]:
+  `listTools()`, `listResources()`, `callTool(name, args, hooks) -> { content, structuredContent?,
+  isError? }`, `execute(operation, args, { headers? })` (one request, for workflow runners; the
+  headers are added to the request). A workflow tool is handed to `runWorkflow`; without it the
+  call is an error result. `callTool`'s hooks reach the workflow runner: `onStepStart`, `onStep`,
+  `sleep`, and `requestHeaders({ workflowId, stepId, attempt, operation })`, whose result is sent
+  with that step's request (how `<rapi-flow>` asks `rapidoc mock` for a status with
+  `Prefer: code=`).
+- `runWorkflow(runtime, tool, args, { onStepStart, onStep, sleep })` and
+  `createMcpWorkflowRuntime(manifest, options)` (createMcpRuntime with `runWorkflow` plugged in;
+  `options.sleep` waits between retries) [workflow-runtime.js], plus `evaluateExpression`,
+  `resolveValue` and `evaluateCondition`. `@rapidoc/mcp` exports `createMcpWorkflowRuntime` as its
+  `createMcpRuntime`.
+  `readResource(uri) -> { contents }`. `buildRequest(manifest, operation, args, options)` returns
+  the request without sending it; `credentialsFromEnv(manifest, env)` and `envNameFor(id)` map
+  security schemes to environment variables.
+- `writeMcpProject(manifest, { serverName, workflowRuntime }) -> { [path]: text }` [project.js]:
+  `manifest.json`, `server.ts`, `runtime.js`, `package.json`, `README.md`,
+  `claude_desktop_config.json`, and `workflow-runtime.js` when the manifest has workflows and
+  `workflowRuntime` (its text) is given: `@rapidoc/mcp` and `<rapi-flow>` supply it,
+  `dist/rapidoc-min.js` does not carry it. `server.ts` imports it dynamically when present.
+- `createZip(files) -> Uint8Array` [zip.js]: a stored (uncompressed) ZIP of text files.
+- `generateMcpServer(spec, options) -> { manifest, files, budget, hostConfig }`
+  [../mcp-generator.js]: the three above in one call.
+- `common.js`: `parseMcpEnabled(val)` (the `mcp` attribute), `toSnakeCase`, `sanitizeDescription`,
+  `deriveToolName`, `AUTH_TRANSPORT_HEADERS`, `estimateTokenCost(manifest)` and
+  `generateHostConfigs(serverName, { schemes })`.
+
+## Invariants
+
+- **Manifest shape.** `{ manifestVersion, server: { name, version, description }, sources:
+  { [name]: { baseUrl, securitySchemes } }, tools, resources, workflows }`. A workflow tool has
+  `workflow` (its id) instead of `operation`; `workflows[id]` is `{ workflowId, summary,
+  description, inputs, steps, outputs }`, each step `{ stepId, operation, parameters, requestBody,
+  successCriteria, onSuccess, onFailure, outputs }` with the operation resolved (source, method,
+  path, params from the step's parameters and body, security from the OpenAPI operation) and
+  values kept as Arazzo expressions. A tool is
+  `{ name, description, inputSchema, annotations, operation }` with `operation = { source, method,
+  path, params: [{ name, in, arg?, contentType? }], security }`; `arg` names the argument when it
+  differs from the wire name, `contentType` is set for `in: "body"`. A resource has `uri`
+  (`reference://...`) and `mimeType` instead of `inputSchema` and `annotations`.
+- **Exclusion** (`[manifest.js:buildMcpManifest]`): an operation is skipped when `x-internal` or
+  `x-hidden` is `true` on it or its path item (unless `includeInternal`), when `deprecated` (unless
+  `includeDeprecated`), or when it is a webhook.
+- **Arguments.** Path, query, header and cookie parameters become properties by name (a clash
+  across locations gets `_<in>`); path parameters are required. The request body is one `body`
+  property with the first JSON content type's schema (else form-urlencoded, multipart, or the first
+  listed). Path-level parameters are merged unless the operation redefines them. Headers in
+  `AUTH_TRANSPORT_HEADERS` and any parameter that matches an `apiKey` scheme's `in` and `name`
+  are never arguments: the runtime sends them.
+- **JSON Schema** (`[manifest.js:toJsonSchema]`): `$ref`s are inlined from the raw document;
+  a schema met again on the same branch is cut to `{ type }`; `nullable` folds into `type`;
+  `readOnly` properties (and their `required` entries) are dropped; OpenAPI 3.0 boolean
+  `exclusiveMinimum/Maximum` become numbers; `example`, `xml`, `x-*` and other non-schema keys
+  are dropped.
+- **Naming**: `toSnakeCase(operationId)`, else `deriveToolName(method, path)`; workflow tools are
+  `toSnakeCase(workflowId)`, after the operations; a repeated name gets `_2`, `_3`, ... in that
+  order. `sanitizeDescription` deletes every `_`.
+- **Annotations**: `readOnlyHint` for GET; `destructiveHint` for PUT, PATCH and DELETE;
+  `idempotentHint` for GET, PUT and DELETE. A workflow tool is read-only when every step is a
+  GET, destructive when any step is PUT, PATCH or DELETE, never idempotent. `estimateTokenCost.consequentialCount` counts tools
+  without `readOnlyHint`.
+- **Resources**: a GET with no required argument whose path contains one of `/reference`,
+  `/currencies`, `/countries`, `/tiers`, `/categories`, `/status`, `/schema`.
+- **Security.** `securitySchemes` keeps `type, description, in, name, scheme, bearerFormat,
+  openIdConnectUrl` and OAuth 2 `flows`; `<rapi-doc>`'s injected `_rapidoc_api_key` scheme is
+  left out. A tool's `security` is the operation's, else the document's. The runtime uses the
+  first alternative all of whose credentials are known; with none, nothing is sent when an
+  alternative is empty, else the first alternative as far as credentials go.
+- **Runtime.** `runtime.js` imports nothing and uses only `fetch`, `URLSearchParams`,
+  `TextEncoder` and `btoa`, and `workflow-runtime.js` imports only `./runtime.js`, because the
+  project writer embeds their text (`?raw` imports, supported by Vite and
+  `scripts/test-loader.mjs`). Path parameters are percent-encoded; array query values
+  repeat the key; objects elsewhere are JSON; `Accept: application/json` unless set; a missing path
+  parameter is an error result, as is a transport failure or a non-2xx status (text `HTTP <status>`
+  plus the body). JSON responses are pretty-printed and, for objects, also `structuredContent`.
+- **Workflows the runtime runs** (`[workflows.js:compileWorkflows]`): steps that name an
+  operation found in the sources, parameters in path, query, header or cookie, a request body
+  with `payload` and `replacements`, simple criteria only (`regex`, `jsonpath` and `xpath` are
+  reported), actions `end`, `goto` to a step and `retry` (`retryLimit` default 1, `retryAfter`
+  seconds) with simple criteria, and `$inputs` / `$steps` expressions. Steps that call another
+  workflow, actions that go to one, and `$workflows` expressions are reported. A step's actions
+  are its own `onSuccess` / `onFailure` followed by the workflow's it does not override by name.
+- **Running a workflow** (`[workflow-runtime.js:runWorkflow]`): required inputs are checked first.
+  Each step's parameters and payload are evaluated against `$inputs` and earlier steps' outputs
+  (`resolveValue`: a whole-string expression keeps its type, `{$expr}` inside text is
+  interpolated), the request is sent, and every criterion must hold (`evaluateCondition`: `==`,
+  `!=`, `<`, `>`, `<=`, `>=`, `&&`, `||`, `!`, parentheses, quoted strings, numbers, `true`,
+  `false`, `null`; `==` compares numbers and strings as text and treats a missing value as
+  `null`). A step without criteria succeeds on a 2xx response. The first action whose criteria all hold runs: on success
+  `end` finishes, `goto` jumps, none falls through; on failure none or `end` fails the workflow
+  (the result names the step, the criterion and the response), `goto` jumps, `retry` re-runs the
+  step (or `stepId`) after `retryAfter` seconds up to `retryLimit` times. A transport error is a
+  failure with no response. More than 1000 step runs is an error. The result is the workflow's
+  `outputs` as `structuredContent`; `onStepStart` gets `{ workflowId, stepId, attempt }` before
+  each request and `onStep` gets `{ workflowId, stepId, attempt, outcome, request, response,
+  outputs, failedCriterion, action }` after it.
+- **Environment.** `envNameFor("petstore_auth")` is `PETSTORE_AUTH`; `API_KEY` is the fallback
+  for every scheme; HTTP Basic reads `<NAME>` as `user:password` or `<NAME>_USERNAME` /
+  `<NAME>_PASSWORD`. `API_BASE_URL` in `server.ts` overrides every source's base URL.
+- **Project.** `server.ts` and `runtime.js` are identical for every API; only `manifest.json`,
+  `package.json`, `README.md` and `claude_desktop_config.json` vary. The zip stores entries
+  uncompressed with a fixed 1980-01-01 timestamp and UTF-8 names.
+
+## Side Effects
+
+- None in this folder: no network, DOM, storage or console. The exported `server.ts` reads
+  `manifest.json`, the environment and stdio, and the runtime it calls makes HTTP requests.
+
+## Verification
+
+- `npm run test:unit` from the repo root. `tests/unit/mcp-generator.test.js` covers the manifest
+  (from `docs/public/specs/petstore.yaml` and small documents), the schema converter, the runtime
+  with a fake `fetch`, credentials from the environment, the project files and the zip.
+  `tests/unit/mcp-workflows.test.js` covers compiling `docs/public/specs/petstore.arazzo.yaml`,
+  expressions, conditions, and runs (outputs between steps, retry, goto, failure) with a fake
+  `fetch`. `tests/unit/mcp-project.test.js` runs the exported project for real: it starts `server.ts`
+  (through `scripts/test-loader.mjs` instead of `tsx`) under `.test-tmp/`, drives it with the MCP
+  SDK's stdio client (`@modelcontextprotocol/sdk`, a root dev dependency) and points
+  `API_BASE_URL` at `@rapidoc/mock` serving the same Petstore spec, workflow tools included.
+- `/examples/mcp-server` on the docs site shows the manifest, `server.ts` and `runtime.js` and
+  downloads the project. After editing, `npm run lint` and `npm run format-fix`.

package/src/utils/mcp/common.js

@@ -1,8 +1,11 @@
 /**
- * MCP (Model Context Protocol) Common Utilities and Spec Extraction
+ * MCP (Model Context Protocol) helpers shared by the manifest builder and the project writer.
  */
+import { envNameFor } from "./runtime.js";
 
-// Common authentication and transport headers to strip from LLM parameter schemas
+export { envNameFor };
+
+// Auth and transport headers never exposed as tool arguments
 export const AUTH_TRANSPORT_HEADERS = new Set([
   "authorization",
   "cookie",
@@ -10,6 +13,7 @@ export const AUTH_TRANSPORT_HEADERS = new Set([
   "x-api-key",
   "api-key",
   "apikey",
+  "api_key",
   "user-agent",
   "host",
   "content-length",
@@ -18,56 +22,20 @@ export const AUTH_TRANSPORT_HEADERS = new Set([
   "connection",
 ]);
 
-export const VALID_MCP_TARGETS = ["typescript", "python", "go", "csharp", "rust", "java"];
-export const VALID_TARGET_SET = new Set(VALID_MCP_TARGETS);
-
-export const MCP_TARGET_LABELS = {
-  typescript: "TypeScript",
-  python: "Python",
-  go: "Go",
-  csharp: "C#",
-  rust: "Rust",
-  java: "Java",
-};
-
 /**
- * Normalizes and parses the `mcp` attribute/property value.
- * Supports:
- *   - Comma-separated strings: "typescript, python"
- *   - Arrays of strings: ["typescript", "python"]
- *   - JSON string arrays: '["typescript", "python"]'
- * If 'none' or 'false' is included anywhere in the value (or if empty/falsy),
- * it acts as a complete kill-switch, returning [].
- * Wildcards like '*' or 'all' are intentionally NOT supported.
+ * Reads the `mcp` attribute: export is off for an empty value, `false`, `none` or a list that
+ * contains one of them (the old kill-switch), and on for anything else, including the old
+ * language names.
  *
  * @param {string|string[]|boolean} val
- * @returns {string[]} Array of normalized target names (e.g. ['typescript', 'python'])
+ * @returns {boolean}
  */
-export function parseMcpTargets(val) {
-  if (!val || val === false || val === "false") return [];
-  let items = [];
-  if (Array.isArray(val)) {
-    items = val;
-  } else if (typeof val === "string") {
-    const trimmed = val.trim();
-    if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
-      try {
-        items = JSON.parse(trimmed);
-      } catch {
-        items = trimmed.slice(1, -1).split(",");
-      }
-    } else {
-      items = trimmed.split(",");
-    }
-  }
+export function parseMcpEnabled(val) {
+  if (!val || val === "false") return false;
+  const items = Array.isArray(val) ? val : String(val).split(",");
   const normalized = items.map((s) => String(s).trim().toLowerCase()).filter(Boolean);
-  if (normalized.includes("none") || normalized.includes("false")) {
-    return [];
-  }
-  const validTargets = normalized
-    .map((t) => (t === "c#" ? "csharp" : t))
-    .filter((t) => VALID_TARGET_SET.has(t));
-  return [...new Set(validTargets)];
+  if (!normalized.length) return false;
+  return !normalized.some((s) => s === "none" || s === "false");
 }
 
 /**
@@ -83,28 +51,6 @@ export function toSnakeCase(str) {
     .toLowerCase();
 }
 
-/**
- * Converts text into PascalCase (e.g. for C#, Java, Go types).
- */
-export function toPascalCase(str) {
-  if (!str) return "Tool";
-  const snake = toSnakeCase(str);
-  return snake
-    .split("_")
-    .filter(Boolean)
-    .map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1))
-    .join("");
-}
-
-/**
- * Converts text into camelCase (e.g. for Go, Java, C# method arguments).
- */
-export function toCamelCase(str) {
-  const pascal = toPascalCase(str);
-  if (!pascal) return "param";
-  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
-}
-
 /**
  * Sanitizes markdown/HTML descriptions into clean, concise single or multi-line agent instructions.
  */
@@ -138,269 +84,38 @@ export function deriveToolName(method, path) {
 }
 
 /**
- * Extracts and maps parameters from path parameters, query parameters, and requestBody.
- */
-export function extractParameters(pathObj, xMcp = {}) {
-  const params = [];
-  const excludedNames = new Set(
-    (xMcp.parameters?.exclude || [])
-      .concat(pathObj["x-ignoredHeaderParameters"] || [])
-      .map((s) => s.toLowerCase()),
-  );
-  const includedNames = xMcp.parameters?.include
-    ? new Set(xMcp.parameters.include.map((s) => s.toLowerCase()))
-    : null;
-  const customDescriptions = xMcp.parameters?.descriptions || {};
-  const defaults = xMcp.parameters?.defaults || {};
-
-  // 1. Process query, path, and header parameters
-  if (Array.isArray(pathObj.parameters)) {
-    for (const p of pathObj.parameters) {
-      if (!p || !p.name) continue;
-      const lowerName = p.name.toLowerCase();
-
-      // Automatically strip auth & transport headers
-      if (p.in === "header" && AUTH_TRANSPORT_HEADERS.has(lowerName)) {
-        continue;
-      }
-      if (p["x-speakeasy-param-ignore"] === true || excludedNames.has(lowerName)) {
-        continue;
-      }
-      if (includedNames && !includedNames.has(lowerName)) {
-        continue;
-      }
-
-      const schema = p.schema || {};
-      const type = schema.type || (schema.enum ? "string" : "string");
-      params.push({
-        name: p.name,
-        in: p.in || "query",
-        type,
-        format: schema.format,
-        enum: schema.enum,
-        description: customDescriptions[p.name] || p.description || schema.description || "",
-        required: Boolean(p.required || p.in === "path"),
-        default: defaults[p.name] !== undefined ? defaults[p.name] : schema.default,
-      });
-    }
-  }
-
-  // 2. Process requestBody schema properties
-  if (pathObj.requestBody && pathObj.requestBody.content) {
-    const jsonContent =
-      pathObj.requestBody.content["application/json"] ||
-      pathObj.requestBody.content["application/x-www-form-urlencoded"] ||
-      Object.values(pathObj.requestBody.content)[0];
-
-    const bodySchema = jsonContent?.schema;
-    if (bodySchema && bodySchema.properties) {
-      const requiredProps = new Set(bodySchema.required || []);
-      for (const [propName, propDef] of Object.entries(bodySchema.properties)) {
-        const lowerName = propName.toLowerCase();
-        if (excludedNames.has(lowerName)) continue;
-        if (includedNames && !includedNames.has(lowerName)) continue;
-
-        params.push({
-          name: propName,
-          in: "body",
-          type: propDef.type || "string",
-          format: propDef.format,
-          enum: propDef.enum,
-          description: customDescriptions[propName] || propDef.description || "",
-          required: requiredProps.has(propName),
-          default: defaults[propName] !== undefined ? defaults[propName] : propDef.default,
-        });
-      }
-    } else if (bodySchema) {
-      // Single object body without top-level exploded properties
-      params.push({
-        name: "payload",
-        in: "body",
-        type: bodySchema.type || "object",
-        description: pathObj.requestBody.description || "Request payload",
-        required: Boolean(pathObj.requestBody.required),
-        default: undefined,
-      });
-    }
-  }
-
-  return params;
-}
-
-/**
- * Inspects an operation and extracts curated MCP tool/resource metadata.
- */
-export function extractMcpOperations(parsedSpec, options = {}) {
-  const tools = [];
-  const resources = [];
-  const { includeInternal = false, includeDeprecated = false } = options;
-
-  const rawSpec = parsedSpec?.spec || parsedSpec || {};
-  const tags = parsedSpec?.tags || [];
-
-  // Collect all path operations across tags or direct spec.paths
-  const operations = [];
-  if (tags.length > 0) {
-    for (const tag of tags) {
-      if (Array.isArray(tag.paths)) {
-        for (const p of tag.paths) {
-          operations.push({ ...p, tagName: tag.name });
-        }
-      }
-    }
-  } else if (rawSpec.paths) {
-    for (const [pathStr, pathItem] of Object.entries(rawSpec.paths)) {
-      for (const [methodStr, opObj] of Object.entries(pathItem)) {
-        if (["get", "post", "put", "delete", "patch"].includes(methodStr.toLowerCase())) {
-          operations.push({
-            ...opObj,
-            method: methodStr.toLowerCase(),
-            path: pathStr,
-            rawOperation: opObj,
-          });
-        }
-      }
-    }
-  }
-
-  for (const op of operations) {
-    const raw = op.rawOperation || op;
-    const xMcp = raw["x-mcp"] || raw["x-mcp-tool"] || {};
-
-    // 1. Check exclusion rules
-    if (xMcp.enabled === false || xMcp.type === "skip") {
-      continue;
-    }
-    if (!includeInternal && (raw["x-internal"] === true || raw["x-hidden"] === true)) {
-      continue;
-    }
-    if (!includeDeprecated && op.deprecated === true) {
-      continue;
-    }
-    if (op.isWebhook) {
-      continue;
-    }
-
-    const method = (op.method || "get").toLowerCase();
-    const path = op.path || "";
-    const params = extractParameters(op, xMcp);
-
-    // 2. Classify as Tool vs Resource
-    let isResource = false;
-    if (xMcp.type === "resource") {
-      isResource = true;
-    } else if (
-      xMcp.type !== "tool" &&
-      method === "get" &&
-      params.filter((p) => p.required).length === 0 &&
-      (path.includes("/reference") ||
-        path.includes("/currencies") ||
-        path.includes("/countries") ||
-        path.includes("/tiers") ||
-        path.includes("/categories") ||
-        path.includes("/status") ||
-        path.includes("/schema"))
-    ) {
-      isResource = true;
-    }
-
-    // 3. Resolve Tool Name
-    const toolName = toSnakeCase(
-      xMcp.name ||
-        raw["x-speakeasy-name-override"] ||
-        op.operationId ||
-        deriveToolName(method, path),
-    );
-
-    // 4. Resolve Description
-    const rawDesc =
-      xMcp.description || op.summary || op.description || `${method.toUpperCase()} ${path}`;
-    const description = sanitizeDescription(rawDesc);
-
-    // 5. Resolve Consequential/Safety Flag
-    const isConsequential = Boolean(
-      xMcp.requireConfirmation ??
-      raw["x-openai-isConsequential"] ??
-      ["post", "put", "delete", "patch"].includes(method.toUpperCase()),
-    );
-
-    // 6. Response Filter
-    const responseFilter = xMcp.response?.filter || "";
-    const responseMaxItems = xMcp.response?.maxItems || 0;
-
-    const opItem = {
-      name: toolName,
-      method: method.toUpperCase(),
-      path,
-      description,
-      parameters: params,
-      isConsequential,
-      readOnly: Boolean(xMcp.readOnly ?? method === "get"),
-      responseFilter,
-      responseMaxItems,
-      tag: op.tagName || "",
-    };
-
-    if (isResource) {
-      resources.push({
-        ...opItem,
-        uri: xMcp.uri || `reference://${toolName.replace(/^get_/, "").replace(/_/g, "-")}`,
-        mimeType: xMcp.mimeType || "application/json",
-      });
-    } else {
-      tools.push(opItem);
-    }
-  }
-
-  // Extract root-level composite workflows
-  const workflows = rawSpec["x-mcp-workflows"] || [];
-
-  const metadata = {
-    title: rawSpec.info?.title || "OpenAPI MCP Server",
-    description: sanitizeDescription(rawSpec.info?.description || ""),
-    version: rawSpec.info?.version || "1.0.0",
-    servers: rawSpec.servers || [{ url: "http://localhost:3000" }],
-  };
-
-  return { metadata, tools, resources, workflows };
-}
-
-/**
- * Calculates estimated token overhead for LLM tool definitions.
+ * Estimates the prompt context a manifest's tool definitions cost an agent on every turn.
+ *
+ * @param {object} manifest from buildMcpManifest()
+ * @returns {{ totalTools: number, totalResources: number, estimatedTokens: number,
+ *   consequentialCount: number, warnings: string[] }} `consequentialCount` is the number of
+ *   tools that are not read-only
  */
-export function estimateTokenCost(tools = [], resources = [], workflows = []) {
+export function estimateTokenCost(manifest) {
+  const tools = manifest?.tools || [];
+  const resources = manifest?.resources || [];
   let estimatedTokens = 0;
   let consequentialCount = 0;
 
   for (const t of tools) {
-    // Tool name + description: ~4 chars per token
-    estimatedTokens += Math.ceil((t.name.length + t.description.length) / 4);
-    // Base JSON Schema overhead per function tool
+    // Name, description and the JSON Schema: ~4 chars per token, plus the envelope
+    estimatedTokens += Math.ceil(
+      (t.name.length + (t.description || "").length + JSON.stringify(t.inputSchema || {}).length) /
+        4,
+    );
     estimatedTokens += 25;
-    if (t.isConsequential) consequentialCount++;
-
-    for (const p of t.parameters) {
-      estimatedTokens += Math.ceil((p.name.length + (p.description || "").length) / 4);
-      estimatedTokens += 10; // type, required, structure tokens
-      if (p.enum) estimatedTokens += p.enum.length * 3;
-    }
+    if (!t.annotations?.readOnlyHint) consequentialCount++;
   }
 
   for (const r of resources) {
-    estimatedTokens += Math.ceil((r.name.length + r.description.length + r.uri.length) / 4) + 20;
-  }
-
-  for (const w of workflows) {
-    estimatedTokens += Math.ceil((w.name.length + (w.description || "").length) / 4) + 40;
-    if (w.parameters) {
-      estimatedTokens += Object.keys(w.parameters).length * 15;
-    }
+    estimatedTokens +=
+      Math.ceil((r.name.length + (r.description || "").length + r.uri.length) / 4) + 20;
   }
 
   const warnings = [];
   if (estimatedTokens > 5000) {
     warnings.push(
-      `Context overhead (~${estimatedTokens.toLocaleString()} tokens/turn) is high. Consider pruning unused tools with x-mcp.enabled: false.`,
+      `Context overhead (~${estimatedTokens.toLocaleString()} tokens/turn) is high. Consider hiding unused operations with x-internal: true.`,
     );
   }
   if (tools.length > 30) {
@@ -412,7 +127,6 @@ export function estimateTokenCost(tools = [], resources = [], workflows = []) {
   return {
     totalTools: tools.length,
     totalResources: resources.length,
-    totalWorkflows: workflows.length,
     estimatedTokens,
     consequentialCount,
     warnings,
@@ -420,40 +134,25 @@ export function estimateTokenCost(tools = [], resources = [], workflows = []) {
 }
 
 /**
- * Generates Claude Desktop and Cursor JSON configuration snippets.
+ * Generates Claude Desktop and Cursor JSON configuration snippets for the exported project.
+ *
+ * @param {string} serverName
+ * @param {object} [options]
+ * @param {string[]} [options.schemes] security scheme ids; one `env` entry each (`API_KEY` when none)
  */
 export function generateHostConfigs(serverName, options = {}) {
   const safeName = toSnakeCase(serverName || "api_mcp_server");
-  const target = (options.target || "typescript").toLowerCase();
-
-  let command = "npx";
-  let args = ["-y", "tsx", "server.ts"];
-
-  if (target === "python") {
-    command = "fastmcp";
-    args = ["run", "server.py"];
-  } else if (target === "go") {
-    command = `./${safeName}`;
-    args = [];
-  } else if (target === "csharp" || target === "c#") {
-    command = "dotnet";
-    args = ["run"];
-  } else if (target === "rust") {
-    command = `./target/release/${safeName}`;
-    args = [];
-  } else if (target === "java") {
-    command = "java";
-    args = ["-jar", "target/mcp-server.jar"];
-  }
+  const schemes = options.schemes?.length ? options.schemes : [];
+  const env = {};
+  for (const id of schemes) env[envNameFor(id)] = `your-${toSnakeCase(id).replace(/_/g, "-")}`;
+  if (!schemes.length) env.API_KEY = "your-api-key-here";
 
   const claudeConfig = {
     mcpServers: {
       [safeName]: {
-        command,
-        args,
-        env: {
-          API_KEY: "your-api-key-here",
-        },
+        command: "npx",
+        args: ["-y", "tsx", "server.ts"],
+        env,
       },
     },
   };