api2ai 1.0.28 → 1.0.29

package/src/cli.js

@@ -1,103 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * api2ai CLI — generate an mcp-use MCP server from an OpenAPI spec.
- *
- *   npx api2ai <openapi-spec> [output-folder] [options]
- */
-
-import { realpathSync } from 'fs';
-import { fileURLToPath } from 'url';
-import { generateMcpServer } from './generate.js';
-
-const HELP = `
-OpenAPI to MCP Server Generator (mcp-use framework)
-
-Usage:
-  npx api2ai <openapi-spec> [output-folder] [options]
-
-Arguments:
-  openapi-spec    Path or URL of an OpenAPI 3.x spec (JSON or YAML)
-  output-folder   Directory to create the server in (default: ./mcp-server)
-
-Options:
-  --name <name>            Server name (default: api-mcp-server)
-  --base-url <url>         Override API base URL from the spec
-  --port <port>            Server port (default: 3000)
-  --allow-mutations        Enable medium-risk POST/PUT/PATCH/DELETE tools by default
-  --include-tags <tags>    Only include tools with these tags (comma-separated)
-  --exclude-tags <tags>    Exclude tools with these tags (comma-separated)
-  --exclude-ops <ids>      Exclude these operationIds (comma-separated)
-  --approve-writes         Write REQUIRE_APPROVALS=false into the generated .env
-  --help, -h               Show this help message
-
-Examples:
-  npx api2ai ./petstore.json ./my-server
-  npx api2ai https://petstore3.swagger.io/api/v3/openapi.json ./petstore-mcp \\
-    --name petstore-api --port 8080
-`;
-
-const list = (value) => value.split(',').map(s => s.trim()).filter(Boolean);
-
-/** Parse argv (without node + script) into generateMcpServer options. */
-export function parseArgs(args) {
-  const options = {
-    specPath: args[0],
-    outputFolder: './mcp-server',
-    baseUrl: undefined,
-    serverName: 'api-mcp-server',
-    port: 3000,
-  };
-
-  const takesValue = new Set(['--base-url', '--name', '--port', '--include-tags', '--exclude-tags', '--exclude-ops']);
-
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (takesValue.has(arg)) {
-      const value = args[++i];
-      if (value === undefined) throw new Error(`${arg} needs a value`);
-      if (arg === '--base-url') options.baseUrl = value;
-      else if (arg === '--name') options.serverName = value;
-      else if (arg === '--port') {
-        options.port = Number.parseInt(value, 10);
-        if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
-          throw new Error(`Invalid --port: ${value}`);
-        }
-      }
-      else if (arg === '--include-tags') options.includeTags = list(value);
-      else if (arg === '--exclude-tags') options.excludeTags = list(value);
-      else if (arg === '--exclude-ops') options.excludeOperationIds = list(value);
-    } else if (arg === '--allow-mutations') {
-      options.allowMutations = true;
-    } else if (arg === '--approve-writes') {
-      options.requireApprovals = false;
-    } else if (arg.startsWith('-')) {
-      throw new Error(`Unknown option: ${arg} (see --help)`);
-    } else {
-      options.outputFolder = arg;
-    }
-  }
-
-  return options;
-}
-
-export async function main(args = process.argv.slice(2)) {
-  if (args.length < 1 || args.includes('--help') || args.includes('-h')) {
-    console.log(HELP);
-    return;
-  }
-  const options = parseArgs(args);
-  await generateMcpServer(options.specPath, options.outputFolder, options);
-}
-
-// realpathSync follows the npm/npx bin symlink so this still matches when
-// invoked as `npx api2ai` (argv[1] is the symlink in node_modules/.bin).
-export const isMainModule = (metaUrl) =>
-  Boolean(process.argv[1]) && realpathSync(process.argv[1]) === fileURLToPath(metaUrl);
-
-if (isMainModule(import.meta.url)) {
-  main().catch(e => {
-    console.error('❌ Error:', e.message);
-    process.exit(1);
-  });
-}

package/src/generate-mcp-use-server.js

@@ -1,18 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Former single-file entry point, kept so `node src/generate-mcp-use-server.js`
- * and imports of this path keep working. The code now lives in ./index.js
- * (library) and ./cli.js (command).
- */
-
-import { main, isMainModule } from './cli.js';
-
-export * from './index.js';
-
-if (isMainModule(import.meta.url)) {
-  main().catch(e => {
-    console.error('❌ Error:', e.message);
-    process.exit(1);
-  });
-}

package/src/generate.js

@@ -1,90 +0,0 @@
-import fs from 'fs/promises';
-import path from 'path';
-import { loadOpenApiSpec } from './spec/load-spec.js';
-import { extractTools } from './spec/extract-tools.js';
-import { generatePackageJson } from './templates/package-json.js';
-import { generateEnvFile } from './templates/env.js';
-import { generatePolicy } from './templates/policy.js';
-import { generateHttpClient } from './templates/http-client.js';
-import { generateToolsConfig } from './templates/tools-config.js';
-import { generateServerIndex } from './templates/server-index.js';
-import { generateReadme } from './templates/readme.js';
-
-/**
- * Render every file of the server without touching the disk.
- * @returns {{ files: Array<{ path: string, content: string }>, tools: object[], baseUrl?: string }}
- */
-export function renderMcpServer(spec, options = {}) {
-  const {
-    serverName = 'openapi-mcp-server',
-    port = 3000,
-    specPath = '(in-memory spec)',
-    requireApprovals = true,
-  } = options;
-
-  const tools = extractTools(spec, { ...options, specUrl: options.specUrl ?? specPath });
-  const baseUrl = options.baseUrl || tools[0]?.baseUrl;
-
-  const files = [
-    { path: 'package.json', content: generatePackageJson(serverName, tools) },
-    { path: '.env', content: generateEnvFile({ baseUrl, port, requireApprovals }) },
-    { path: '.env.example', content: generateEnvFile({ baseUrl, port, requireApprovals, example: true }) },
-    { path: 'src/policy.js', content: generatePolicy(baseUrl) },
-    { path: 'src/http-client.js', content: generateHttpClient() },
-    { path: 'src/tools-config.js', content: generateToolsConfig(tools) },
-    { path: 'src/index.js', content: generateServerIndex(serverName, tools, baseUrl, port) },
-    { path: 'README.md', content: generateReadme(serverName, tools, specPath, baseUrl, port) },
-    { path: '.gitignore', content: 'node_modules/\n.env\n*.log\n.mcp-use/\n' },
-  ];
-
-  return { files, tools, baseUrl };
-}
-
-/**
- * Load a spec, generate an mcp-use server from it and write it to `outputFolder`.
- *
- * @param {string} specPathOrUrl local file or http(s) URL (JSON or YAML)
- * @param {string} outputFolder
- * @param {object} [options] see extractTools; plus serverName, port, requireApprovals, quiet
- */
-export async function generateMcpServer(specPathOrUrl, outputFolder, options = {}) {
-  const { port = 3000, quiet = false } = options;
-  const log = quiet ? () => {} : console.log;
-
-  log(`\n📖 Loading OpenAPI spec: ${specPathOrUrl}`);
-  const spec = await loadOpenApiSpec(specPathOrUrl);
-  log(`   Title: ${spec.info?.title || 'Unknown'}`);
-  log(`   Version: ${spec.info?.version || 'Unknown'}`);
-
-  const { files, tools } = renderMcpServer(spec, { ...options, specPath: specPathOrUrl });
-  log(`✅ Extracted ${tools.length} tools\n`);
-
-  for (const file of files) {
-    const target = path.join(outputFolder, file.path);
-    await fs.mkdir(path.dirname(target), { recursive: true });
-    // An existing .env holds the user's credentials; regenerating must not wipe them.
-    if (file.path === '.env' && await fs.access(target).then(() => true, () => false)) {
-      log(`  • .env (kept existing)`);
-      continue;
-    }
-    await fs.writeFile(target, file.content);
-    log(`  ✓ ${file.path}`);
-  }
-
-  log(`
-🎉 MCP server generated
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  cd ${outputFolder}
-  npm install
-  npm start        # http://localhost:${port}/mcp
-  npm run dev      # hot reload + Inspector at /mcp/inspector
-`);
-
-  return {
-    outputFolder,
-    toolCount: tools.length,
-    tools: tools.map(t => t.name),
-    port,
-  };
-}

package/src/index.js

@@ -1,15 +0,0 @@
-/**
- * api2ai — generate an mcp-use MCP server from any OpenAPI specification.
- *
- *   spec/       load a spec, convert schemas to Zod, classify risk, extract tools
- *   templates/  one module per file of the generated server
- *   generate.js render + write the server
- *   cli.js      the `api2ai` command
- */
-
-export { generateMcpServer, renderMcpServer } from './generate.js';
-export { loadOpenApiSpec } from './spec/load-spec.js';
-export { extractTools, resolveServerUrl } from './spec/extract-tools.js';
-export { classifyRisk, toolAnnotations } from './spec/classify-risk.js';
-export { schemaToZod, buildZodSchema, sanitizePropertyName } from './spec/schema-to-zod.js';
-export { DEPENDENCY_VERSIONS, NODE_ENGINE } from './versions.js';

package/src/spec/classify-risk.js

@@ -1,53 +0,0 @@
-const READ_ONLY_METHODS = ['get', 'head', 'options'];
-
-// Matched against operationId, summary, description, path and tags. Broad on
-// purpose: a false "high" only costs an env flag, a false "low" exposes a
-// destructive endpoint to an agent with no approval step.
-const DANGEROUS_PATTERNS = [
-  'delete', 'remove', 'destroy', 'purge',
-  'payment', 'payout', 'billing', 'invoice',
-  'admin', 'role', 'permission', 'token', 'secret', 'key',
-  'webhook', 'auth', 'oauth', 'user', 'member',
-];
-
-/**
- * Classify an operation as low / medium / high risk.
- *
- * low    — read-only method and no dangerous keyword: enabled, no approval
- * medium — mutating method: disabled unless ALLOW_RESTRICTED_TOOLS=true
- * high   — any dangerous keyword, whatever the method
- */
-export function classifyRisk(operation, method, pathTemplate) {
-  const tags = operation.tags || [];
-  const haystack = [operation.operationId, operation.summary, operation.description, pathTemplate, ...tags]
-    .filter(Boolean)
-    .join(' ')
-    .toLowerCase();
-
-  const isMutation = !READ_ONLY_METHODS.includes(method);
-  const matchedDanger = DANGEROUS_PATTERNS.some(p => haystack.includes(p));
-  const riskLevel = matchedDanger ? 'high' : isMutation ? 'medium' : 'low';
-
-  return {
-    tags,
-    isMutation,
-    riskLevel,
-    requiresApproval: riskLevel !== 'low',
-    allowedInInspector: riskLevel === 'low',
-    enabledByDefault: riskLevel === 'low',
-  };
-}
-
-/**
- * MCP tool annotations (hints a client may show or act on). They describe
- * the HTTP semantics, independent of the risk policy above.
- */
-export function toolAnnotations(method, title) {
-  return {
-    title,
-    readOnlyHint: READ_ONLY_METHODS.includes(method),
-    destructiveHint: method === 'delete',
-    idempotentHint: ['get', 'head', 'options', 'put', 'delete'].includes(method),
-    openWorldHint: true,
-  };
-}

package/src/spec/extract-tools.js

@@ -1,110 +0,0 @@
-import { classifyRisk, toolAnnotations } from './classify-risk.js';
-import { buildZodSchema, deref, mergeParameters } from './schema-to-zod.js';
-
-const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
-
-/**
- * The API base URL from `servers[0]`, with `{variables}` replaced by their
- * defaults and a relative URL ("/api/v3") resolved against the spec's own URL.
- */
-export function resolveServerUrl(spec, specUrl) {
-  const server = spec.servers?.[0];
-  if (!server?.url) return undefined;
-  let url = server.url.replace(/\{([^}]+)\}/g, (match, name) => server.variables?.[name]?.default ?? match);
-  if (!/^https?:\/\//i.test(url)) {
-    if (!specUrl || !/^https?:\/\//i.test(specUrl)) return undefined;
-    url = new URL(url, specUrl).toString();
-  }
-  return url.replace(/\/+$/, '');
-}
-
-const toToolName = (operationId) =>
-  operationId.replace(/[^a-zA-Z0-9_-]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '').slice(0, 64) || 'tool';
-
-/**
- * Turn every operation in the spec into a tool description.
- *
- * @param {object} spec parsed OpenAPI document
- * @param {object} [options]
- * @param {string} [options.baseUrl] override `servers[0].url`
- * @param {string} [options.specUrl] where the spec came from, for relative server URLs
- * @param {string[]} [options.excludeOperationIds]
- * @param {string[]} [options.includeTags] keep only operations carrying one of these tags
- * @param {string[]} [options.excludeTags] drop operations carrying any of these tags
- * @param {boolean} [options.allowMutations] enable medium-risk tools by default
- * @param {(tool: object) => boolean} [options.filterFn]
- */
-export function extractTools(spec, options = {}) {
-  const {
-    excludeOperationIds = [],
-    filterFn,
-    allowMutations = false,
-    includeTags = [],
-    excludeTags = [],
-  } = options;
-  const baseUrl = options.baseUrl || resolveServerUrl(spec, options.specUrl);
-
-  const tools = [];
-  const usedNames = new Set();
-
-  for (const [pathTemplate, pathItem] of Object.entries(spec.paths || {})) {
-    for (const method of HTTP_METHODS) {
-      const operation = pathItem[method];
-      if (!operation) continue;
-
-      const operationId = operation.operationId || `${method}_${pathTemplate.replace(/[^a-zA-Z0-9]/g, '_')}`;
-      if (excludeOperationIds.includes(operationId)) continue;
-
-      const risk = classifyRisk(operation, method, pathTemplate);
-      if (allowMutations && risk.isMutation && risk.riskLevel === 'medium') {
-        risk.enabledByDefault = true;
-        risk.requiresApproval = false;
-      }
-
-      if (includeTags.length > 0 && !risk.tags.some(t => includeTags.includes(t))) continue;
-      if (excludeTags.length > 0 && risk.tags.some(t => excludeTags.includes(t))) continue;
-
-      // Two operationIds can sanitize to the same name; MCP requires unique names.
-      let name = toToolName(operationId);
-      for (let n = 2; usedNames.has(name); n++) name = `${toToolName(operationId).slice(0, 60)}_${n}`;
-
-      const description = (operation.summary && operation.description && operation.description !== operation.summary
-        ? `${operation.summary}\n\n${operation.description}`
-        : operation.summary || operation.description || `${method.toUpperCase()} ${pathTemplate}`
-      ).substring(0, 1024);
-
-      const parameters = mergeParameters(pathItem.parameters, operation.parameters, spec)
-        .filter(p => p.in !== 'cookie');
-      const requestBody = deref(operation.requestBody, spec);
-
-      const tool = {
-        name,
-        title: operation.summary || name,
-        description,
-        zodSchema: buildZodSchema(operation, pathItem.parameters, spec),
-        annotations: toolAnnotations(method, operation.summary || name),
-        method,
-        pathTemplate,
-        executionParameters: parameters.map(p => ({ name: p.name, in: p.in })),
-        // Must match the media type buildZodSchema took the body schema from.
-        requestBodyContentType: requestBody?.content
-          ? ('application/json' in requestBody.content ? 'application/json' : Object.keys(requestBody.content)[0])
-          : undefined,
-        operationId,
-        baseUrl,
-        tags: risk.tags,
-        isMutation: risk.isMutation,
-        riskLevel: risk.riskLevel,
-        requiresApproval: risk.requiresApproval,
-        allowedInInspector: risk.allowedInInspector,
-        enabledByDefault: risk.enabledByDefault,
-      };
-
-      if (filterFn && !filterFn(tool)) continue;
-      usedNames.add(name);
-      tools.push(tool);
-    }
-  }
-
-  return tools;
-}

package/src/spec/load-spec.js

@@ -1,55 +0,0 @@
-import fs from 'fs/promises';
-
-const isUrl = (s) => s.startsWith('http://') || s.startsWith('https://');
-const looksLikeYaml = (name) => /\.ya?ml($|\?)/i.test(name);
-
-async function parseYaml(content) {
-  const yaml = await import('js-yaml').catch(() => null);
-  if (!yaml) {
-    throw new Error('YAML spec detected but js-yaml is not installed. Run: npm install js-yaml');
-  }
-  return (yaml.default || yaml).load(content);
-}
-
-/**
- * Parse spec text as JSON, falling back to YAML when the source says it is
- * YAML (extension or content-type) or when the JSON parse fails — remote
- * specs are often served as text/plain whatever their format.
- */
-async function parseSpecText(content, { source, contentType = '' }) {
-  if (looksLikeYaml(source) || /yaml/i.test(contentType)) {
-    return parseYaml(content);
-  }
-  try {
-    return JSON.parse(content);
-  } catch (jsonError) {
-    try {
-      return await parseYaml(content);
-    } catch {
-      throw new Error(`Could not parse spec ${source} as JSON: ${jsonError.message}`);
-    }
-  }
-}
-
-/** Load an OpenAPI document from a local path or an http(s) URL. */
-export async function loadOpenApiSpec(specPathOrUrl) {
-  let spec;
-  if (isUrl(specPathOrUrl)) {
-    const response = await fetch(specPathOrUrl, { headers: { Accept: 'application/json, application/yaml, text/yaml, */*' } });
-    if (!response.ok) {
-      throw new Error(`Failed to fetch spec: ${response.status} ${response.statusText}`);
-    }
-    spec = await parseSpecText(await response.text(), {
-      source: specPathOrUrl,
-      contentType: response.headers.get('content-type') || '',
-    });
-  } else {
-    const content = await fs.readFile(specPathOrUrl, 'utf-8');
-    spec = await parseSpecText(content, { source: specPathOrUrl });
-  }
-
-  if (!spec || typeof spec !== 'object' || !spec.paths) {
-    throw new Error(`${specPathOrUrl} is not an OpenAPI document (no "paths" object)`);
-  }
-  return spec;
-}

package/src/spec/schema-to-zod.js

@@ -1,213 +0,0 @@
-/**
- * OpenAPI schema → Zod source code (a string the generated server evaluates).
- *
- * Every user-controlled string that lands in generated code goes through
- * `literal()` (JSON.stringify): a description containing a newline, a
- * backslash or `*\/` used to produce a server that failed to parse.
- */
-
-/** A JS string literal safe to splice into generated source. */
-export const literal = (value) => JSON.stringify(String(value));
-
-/** A JS object key: bare when it is an identifier, quoted otherwise. */
-export function sanitizePropertyName(name) {
-  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : literal(name);
-}
-
-const describe = (text) => (text ? `.describe(${literal(text)})` : '');
-
-/** Follow a local `#/components/...` JSON pointer. External refs are not fetched. */
-function resolveRef(ref, spec) {
-  if (!ref.startsWith('#/')) return null;
-  let node = spec;
-  for (const raw of ref.slice(2).split('/')) {
-    const key = raw.replace(/~1/g, '/').replace(/~0/g, '~');
-    node = node?.[key];
-    if (node === undefined) return null;
-  }
-  return node;
-}
-
-function literalUnion(values) {
-  const nonNull = values.filter(v => v !== null);
-  const parts = nonNull.map(v => `z.literal(${JSON.stringify(v)})`);
-  let zod = parts.length === 0 ? 'z.null()' : parts.length === 1 ? parts[0] : `z.union([${parts.join(', ')}])`;
-  if (nonNull.length !== values.length && parts.length > 0) zod += '.nullable()';
-  return zod;
-}
-
-function stringZod(schema) {
-  switch (schema.format) {
-    // offset: true — LLMs routinely send `2024-01-01T00:00:00+02:00`.
-    case 'date-time': return 'z.iso.datetime({ offset: true })';
-    case 'date': return 'z.iso.date()';
-    case 'email': return 'z.email()';
-    case 'uri':
-    case 'url': return 'z.url()';
-    case 'uuid': return 'z.uuid()';
-    default: return 'z.string()';
-  }
-}
-
-function objectZod(schema, ctx, depth) {
-  const pad = '  '.repeat(depth + 2);
-  const closePad = '  '.repeat(depth + 1);
-  const props = Object.entries(schema.properties || {});
-
-  if (props.length === 0) {
-    if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
-      return `z.record(z.string(), ${toZod(schema.additionalProperties, ctx, true, depth + 1)})`;
-    }
-    return 'z.record(z.string(), z.unknown())';
-  }
-
-  const body = props
-    .map(([key, val]) => {
-      const isReq = (schema.required || []).includes(key);
-      const resolved = val?.$ref ? resolveRef(val.$ref, ctx.spec) || val : val;
-      return `${pad}${sanitizePropertyName(key)}: ${toZod(val, ctx, isReq, depth + 1)}${describe(resolved?.description)}`;
-    })
-    .join(',\n');
-
-  // zod 4's z.object() strips unknown keys; keep them when the spec allows extras.
-  const ctor = schema.additionalProperties ? 'z.looseObject' : 'z.object';
-  return `${ctor}({\n${body}\n${closePad}})`;
-}
-
-/** Merge `allOf` members that are plain objects into one object schema. */
-function mergeAllOf(members, ctx) {
-  const resolved = members.map(m => (m?.$ref ? resolveRef(m.$ref, ctx.spec) : m));
-  if (!resolved.every(m => m && (m.type === 'object' || m.properties) && !m.allOf && !m.oneOf && !m.anyOf)) {
-    return null;
-  }
-  return {
-    type: 'object',
-    properties: Object.assign({}, ...resolved.map(m => m.properties || {})),
-    required: resolved.flatMap(m => m.required || []),
-    additionalProperties: resolved.some(m => m.additionalProperties),
-  };
-}
-
-function toZod(schema, ctx, required, depth) {
-  let zod = baseZod(schema, ctx, depth);
-  if (!required) zod += '.optional()';
-  return zod;
-}
-
-function baseZod(schema, ctx, depth) {
-  if (!schema || typeof schema !== 'object') return 'z.unknown()';
-
-  if (schema.$ref) {
-    // A cycle (Node.children: Node[]) is cut to z.unknown() rather than
-    // expanding forever; z.lazy would need named declarations in the output.
-    if (ctx.seen.has(schema.$ref)) return 'z.unknown()';
-    const target = resolveRef(schema.$ref, ctx.spec);
-    if (!target) return 'z.unknown()';
-    ctx.seen.add(schema.$ref);
-    try {
-      return baseZod(target, ctx, depth);
-    } finally {
-      ctx.seen.delete(schema.$ref);
-    }
-  }
-
-  // OpenAPI 3.1: `type: ['string', 'null']`; 3.0: `nullable: true`.
-  let type = schema.type;
-  let nullable = schema.nullable === true;
-  if (Array.isArray(type)) {
-    nullable = nullable || type.includes('null');
-    const rest = type.filter(t => t !== 'null');
-    if (rest.length !== 1) {
-      return rest.length === 0 ? 'z.null()' : `z.union([${rest.map(t => baseZod({ ...schema, type: t }, ctx, depth)).join(', ')}])${nullable ? '.nullable()' : ''}`;
-    }
-    type = rest[0];
-  }
-  if (!type && schema.properties) type = 'object';
-  if (!type && schema.items) type = 'array';
-
-  let zod;
-  if (schema.const !== undefined) {
-    zod = `z.literal(${JSON.stringify(schema.const)})`;
-  } else if (Array.isArray(schema.enum) && schema.enum.length > 0) {
-    zod = schema.enum.every(v => typeof v === 'string')
-      ? `z.enum([${schema.enum.map(v => literal(v)).join(', ')}])`
-      : literalUnion(schema.enum);
-  } else if (schema.allOf) {
-    const merged = mergeAllOf(schema.allOf, ctx);
-    zod = merged
-      ? objectZod(merged, ctx, depth)
-      : schema.allOf.map(s => baseZod(s, ctx, depth)).reduce((a, b) => `z.intersection(${a}, ${b})`);
-  } else if (schema.anyOf || schema.oneOf) {
-    const options = (schema.anyOf || schema.oneOf).map(s => baseZod(s, ctx, depth));
-    zod = options.length === 1 ? options[0] : `z.union([${options.join(', ')}])`;
-  } else {
-    switch (type) {
-      case 'string': zod = stringZod(schema); break;
-      case 'integer': zod = 'z.int()'; break;
-      case 'number': zod = 'z.number()'; break;
-      case 'boolean': zod = 'z.boolean()'; break;
-      case 'null': zod = 'z.null()'; break;
-      case 'array': zod = `z.array(${baseZod(schema.items, ctx, depth)})`; break;
-      case 'object': zod = objectZod(schema, ctx, depth); break;
-      default: zod = 'z.unknown()';
-    }
-  }
-
-  return nullable && !zod.endsWith('.nullable()') ? `${zod}.nullable()` : zod;
-}
-
-/**
- * Zod source for one schema.
- * @param {object} schema OpenAPI schema object (may be a `$ref`)
- * @param {boolean} [required=false] omit `.optional()`
- * @param {object} [spec] the whole document, for resolving local `$ref`s
- */
-export function schemaToZod(schema, required = false, spec = {}) {
-  return toZod(schema, { spec, seen: new Set() }, required, 0);
-}
-
-/** Resolve a `$ref`'d parameter or request body; returns the input otherwise. */
-export function deref(node, spec) {
-  return node?.$ref ? resolveRef(node.$ref, spec) || node : node;
-}
-
-/**
- * The `z.object({...})` source for a tool's input: every path/query/header
- * parameter, plus `requestBody` when the operation takes one.
- */
-export function buildZodSchema(operation, pathParams = [], spec = {}) {
-  const ctx = { spec, seen: new Set() };
-  const properties = [];
-
-  for (const param of mergeParameters(pathParams, operation.parameters, spec)) {
-    if (param.in === 'cookie') continue; // the HTTP client never sends cookies
-    const zodType = toZod(param.schema || { type: 'string' }, ctx, param.in === 'path' || param.required, 1);
-    properties.push(`    ${sanitizePropertyName(param.name)}: ${zodType}${describe(param.description)}`);
-  }
-
-  const body = deref(operation.requestBody, spec);
-  if (body?.content) {
-    const mediaType = body.content['application/json'] || Object.values(body.content)[0];
-    if (mediaType?.schema) {
-      const zodType = toZod(mediaType.schema, ctx, Boolean(body.required), 1);
-      properties.push(`    requestBody: ${zodType}${describe(body.description || 'Request body')}`);
-    }
-  }
-
-  return properties.length === 0 ? 'z.object({})' : `z.object({\n${properties.join(',\n')}\n  })`;
-}
-
-/**
- * Path-item parameters merged with operation parameters. Per the OpenAPI
- * spec an operation parameter overrides a path-level one with the same
- * name + location (it used to be emitted twice — a duplicate object key).
- */
-export function mergeParameters(pathParams = [], operationParams = [], spec = {}) {
-  const byKey = new Map();
-  for (const raw of [...pathParams, ...operationParams]) {
-    const param = deref(raw, spec);
-    if (!param?.name) continue;
-    byKey.set(`${param.in}:${param.name}`, param);
-  }
-  return [...byKey.values()];
-}