@avidian/mcp-openapi 0.1.3 → 0.2.0

package/dist/index.js

@@ -5,56 +5,51 @@ import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 // src/config.ts
+import { readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
-var DEFAULT_REQUEST_TIMEOUT_MS = 30000;
-function resolveConfig(argv, env) {
-  const { values, positionals } = parseArgs({
-    args: argv,
-    allowPositionals: true,
-    options: {
-      "base-url": { type: "string" },
-      timeout: { type: "string" }
-    }
-  });
-  const source = positionals[0] ?? env.OPENAPI_URL;
-  if (!source) {
-    throw new Error(`Missing OpenAPI source. Pass it as the first argument or set OPENAPI_URL, e.g.:
-` + "  mcp-openapi https://example.com/openapi.json");
-  }
-  const baseUrlOverride = values["base-url"] ?? env.OPENAPI_BASE_URL;
-  const requestTimeoutMs = parseTimeout(values.timeout ?? env.OPENAPI_REQUEST_TIMEOUT_MS);
-  return {
-    source,
-    requestTimeoutMs,
-    ...baseUrlOverride !== undefined && { baseUrlOverride }
-  };
-}
-function parseTimeout(raw) {
-  if (raw === undefined)
-    return DEFAULT_REQUEST_TIMEOUT_MS;
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new Error(`Invalid request timeout "${raw}". Pass a positive number of milliseconds.`);
-  }
-  return parsed;
-}
+import { z } from "zod/v4";
 
 // src/errors.ts
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+// src/registry.ts
+import { ulid } from "ulid";
+
 // src/openapi/load.ts
 import SwaggerParser from "@apidevtools/swagger-parser";
+import { parse as parseYaml } from "yaml";
+function detectSourceKind(source) {
+  const trimmed = source.trimStart();
+  if (/^https?:\/\//i.test(trimmed))
+    return "url";
+  if (trimmed.startsWith("{") || trimmed.startsWith("["))
+    return "inline";
+  if (source.includes(`
+`))
+    return "inline";
+  return "file";
+}
 async function loadOpenApiDocument(source) {
   try {
-    return await SwaggerParser.dereference(source);
+    if (detectSourceKind(source) === "inline") {
+      const parsed = parseYaml(source);
+      if (parsed === null || typeof parsed !== "object") {
+        throw new Error("inline content did not parse to an OpenAPI/Swagger object");
+      }
+      return await SwaggerParser.dereference(parsed);
+    }
+    return await SwaggerParser.dereference(source.trim());
   } catch (cause) {
-    throw new Error(`Failed to load OpenAPI document from "${source}": ${errorMessage(cause)}`, {
+    throw new Error(`Failed to load OpenAPI document from "${describeSource(source)}": ${errorMessage(cause)}`, {
       cause
     });
   }
 }
+function describeSource(source) {
+  return detectSourceKind(source) === "inline" ? `inline content (${source.length} chars)` : source;
+}
 function isSwagger2Document(doc) {
   return "swagger" in doc;
 }
@@ -70,9 +65,11 @@ var HTTP_METHODS = [
   "patch",
   "trace"
 ];
-function extractOperations(doc, reservedNames = []) {
-  const drafts = isSwagger2Document(doc) ? extractSwagger2Operations(doc) : extractOpenApi3Operations(doc);
-  return assignToolNames(drafts, reservedNames);
+function extractOperations(doc) {
+  return isSwagger2Document(doc) ? extractSwagger2Operations(doc) : extractOpenApi3Operations(doc);
+}
+function extractDocumentServers(doc) {
+  return isSwagger2Document(doc) ? swagger2ServerUrls(doc) : serverUrls(doc.servers);
 }
 function extractOpenApi3Operations(doc) {
   const docServers = serverUrls(doc.servers);
@@ -95,6 +92,7 @@ function extractOpenApi3Operations(doc) {
         path,
         deprecated: operation.deprecated ?? false,
         parameters: buildParameters(rawParams),
+        responses: buildResponsesV3(operation.responses),
         servers,
         tags: operation.tags ?? [],
         ...requestBody !== undefined && { requestBody },
@@ -129,6 +127,23 @@ function buildParameters(raw) {
     };
   });
 }
+function buildResponsesV3(responses) {
+  if (!responses)
+    return [];
+  return Object.entries(responses).map(([status, response]) => {
+    const resp = response;
+    const content = resp.content ?? {};
+    const contentTypes = Object.keys(content);
+    const jsonMedia = content["application/json"] ?? Object.entries(content).find(([type]) => /\bjson\b/i.test(type))?.[1];
+    const schema = jsonMedia?.schema;
+    return {
+      status,
+      contentTypes,
+      ...resp.description !== undefined && { description: resp.description },
+      ...schema !== undefined && { schema }
+    };
+  });
+}
 function buildRequestBodyV3(requestBody) {
   if (!requestBody)
     return;
@@ -186,11 +201,13 @@ function extractSwagger2Operations(doc) {
       const rawParams = mergeSwagger2Parameters(pathParams, operation.parameters ?? []);
       const consumesMultipart = (operation.consumes ?? doc.consumes ?? []).includes("multipart/form-data");
       const requestBody = buildRequestBodySwagger2(rawParams, consumesMultipart);
+      const produces = operation.produces ?? doc.produces ?? [];
       operations.push({
         method,
         path,
         deprecated: operation.deprecated ?? false,
         parameters: buildSwagger2Parameters(rawParams),
+        responses: buildResponsesSwagger2(operation.responses, produces),
         servers,
         tags: operation.tags ?? [],
         ...requestBody !== undefined && { requestBody },
@@ -233,6 +250,20 @@ function itemsObjectToJsonSchema(param) {
   const { name: _name, in: _in, description: _description, required: _required, ...rest } = param;
   return rest;
 }
+function buildResponsesSwagger2(responses, produces) {
+  if (!responses)
+    return [];
+  return Object.entries(responses).map(([status, response]) => {
+    const resp = response;
+    const schema = resp.schema;
+    return {
+      status,
+      contentTypes: schema !== undefined ? produces : [],
+      ...resp.description !== undefined && { description: resp.description },
+      ...schema !== undefined && { schema }
+    };
+  });
+}
 function buildRequestBodySwagger2(raw, consumesMultipart) {
   const bodyParam = raw.find((param) => param.in === "body");
   if (bodyParam) {
@@ -265,83 +296,118 @@ function swagger2ServerUrls(doc) {
   const basePath = doc.basePath ?? "";
   return schemes.map((scheme) => `${scheme}://${host}${basePath}`);
 }
-function sanitizeToolName(raw) {
-  const cleaned = raw.replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
-  const truncated = cleaned.slice(0, 128);
-  return truncated.length > 0 ? truncated : "operation";
-}
-function assignToolNames(drafts, reservedNames) {
-  const used = new Set(reservedNames);
-  return drafts.map((draft) => {
-    const base = sanitizeToolName(draft.operationId ?? `${draft.method}_${draft.path}`);
-    let name = base;
-    let counter = 2;
-    while (used.has(name)) {
-      const suffix = `_${counter}`;
-      name = `${base.slice(0, 128 - suffix.length)}${suffix}`;
-      counter += 1;
-    }
-    used.add(name);
-    return { ...draft, toolName: name };
-  });
+
+// src/registry.ts
+var DEFAULT_MAX_SPECS = 20;
+function maxSpecsReachedMessage(maxSpecs) {
+  return `The maximum of ${maxSpecs} loaded specs has been reached. ` + "Unload a spec with unload_spec (see list_specs) before loading another.";
 }
 
-// src/openapi/search.ts
-import MiniSearch from "minisearch";
-var SEARCH_TOOL_NAME = "search_operations";
-function buildSearchIndex(operations) {
-  const index = new MiniSearch({
-    idField: "id",
-    fields: ["toolName", "summary", "description", "tags", "path"],
-    storeFields: ["toolName", "method", "path", "summary", "deprecated"],
-    searchOptions: {
-      prefix: true,
-      fuzzy: 0.2,
-      boost: { toolName: 3, summary: 2, tags: 1.5 }
+class SpecRegistry {
+  specs = new Map;
+  maxSpecs;
+  constructor(options = {}) {
+    const maxSpecs = options.maxSpecs ?? DEFAULT_MAX_SPECS;
+    if (!Number.isInteger(maxSpecs) || maxSpecs < 1) {
+      throw new Error(`maxSpecs must be a positive integer, got ${maxSpecs}.`);
     }
-  });
-  index.addAll(operations.map((operation) => ({
-    id: operation.toolName,
-    toolName: operation.toolName,
-    method: operation.method,
-    path: operation.path,
-    summary: operation.summary ?? "",
-    description: operation.description ?? "",
-    tags: operation.tags.join(" "),
-    deprecated: operation.deprecated
-  })));
-  return index;
-}
-function searchOperations(index, query, limit) {
-  return index.search(query).slice(0, limit).map(toSearchMatch);
+    this.maxSpecs = maxSpecs;
+  }
+  async load(source, options = {}) {
+    this.assertHasCapacity();
+    const doc = await loadOpenApiDocument(source);
+    const spec = this.buildSpec(doc, options);
+    this.assertHasCapacity();
+    this.specs.set(spec.id, spec);
+    return spec;
+  }
+  assertHasCapacity() {
+    if (this.specs.size >= this.maxSpecs) {
+      throw new Error(maxSpecsReachedMessage(this.maxSpecs));
+    }
+  }
+  get(id) {
+    return this.specs.get(id);
+  }
+  unload(id) {
+    return this.specs.delete(id);
+  }
+  get isFull() {
+    return this.specs.size >= this.maxSpecs;
+  }
+  list() {
+    return [...this.specs.values()];
+  }
+  get size() {
+    return this.specs.size;
+  }
+  buildSpec(doc, options) {
+    const operations = extractOperations(doc);
+    const servers = extractDocumentServers(doc);
+    const info = doc.info;
+    const title = typeof info === "object" && info !== null && typeof info.title === "string" ? info.title : "Untitled API";
+    const version = typeof info === "object" && info !== null && typeof info.version === "string" ? info.version : "unknown";
+    return {
+      id: ulid().toLowerCase(),
+      doc,
+      operations,
+      title,
+      version,
+      servers,
+      ...options.baseUrl !== undefined && { baseUrl: options.baseUrl },
+      ...options.credential !== undefined && { credential: options.credential }
+    };
+  }
 }
-function toSearchMatch(result) {
-  const summary = typeof result.summary === "string" && result.summary.length > 0 ? result.summary : undefined;
+function specSummary(spec) {
   return {
-    toolName: String(result.toolName),
-    method: String(result.method),
-    path: String(result.path),
-    deprecated: result.deprecated === true,
-    score: result.score,
-    ...summary !== undefined && { summary }
+    id: spec.id,
+    title: spec.title,
+    version: spec.version,
+    operationCount: spec.operations.length,
+    servers: spec.baseUrl !== undefined ? [spec.baseUrl] : spec.servers
   };
 }
 
-// src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z as z2 } from "zod/v4";
-
 // src/openapi/auth.ts
-function resolveAuth(doc, env) {
-  const schemes = isSwagger2Document(doc) ? swagger2SecuritySchemes(doc) : openApi3SecuritySchemes(doc);
+function resolveAuth(doc, env, credentialRef) {
+  const schemes = normalizedSchemes(doc);
+  const names = credentialRef !== undefined ? requiredSchemeNames(doc) : undefined;
   const resolved = [];
   for (const [name, scheme] of Object.entries(schemes)) {
-    const credential = resolveSchemeCredential(name, scheme, env);
+    if (names && !names.has(name))
+      continue;
+    const base = credentialRef !== undefined ? credentialEnvBase(credentialRef) : authEnvBase(name);
+    const credential = resolveSchemeCredential(base, scheme, env);
     if (credential)
       resolved.push(credential);
   }
   return resolved;
 }
+function hasSupportedSecuritySchemes(doc) {
+  return Object.keys(normalizedSchemes(doc)).length > 0;
+}
+function normalizedSchemes(doc) {
+  return isSwagger2Document(doc) ? swagger2SecuritySchemes(doc) : openApi3SecuritySchemes(doc);
+}
+function requiredSchemeNames(doc) {
+  const security = doc.security;
+  if (!security || security.length === 0)
+    return;
+  const names = new Set;
+  for (const requirement of security) {
+    for (const name of Object.keys(requirement))
+      names.add(name);
+  }
+  return names;
+}
+function hasConfiguredCredential(env, ref) {
+  const base = credentialEnvBase(ref);
+  return [base, `${base}_TOKEN`, `${base}_USERNAME`, `${base}_PASSWORD`].some((key) => env[key] !== undefined);
+}
+function credentialEnvBase(ref) {
+  return `OPENAPI_CRED_${screamingSnake(ref)}`;
+}
 function applyAuth(auth, target) {
   for (const entry of auth) {
     switch (entry.kind) {
@@ -366,8 +432,7 @@ function applyApiKey(entry, target) {
     target.headers.set(entry.name, entry.value);
   }
 }
-function resolveSchemeCredential(name, scheme, env) {
-  const base = envVarName(name);
+function resolveSchemeCredential(base, scheme, env) {
   switch (scheme.kind) {
     case "bearer": {
       const token = env[`${base}_TOKEN`] ?? env[base];
@@ -384,9 +449,11 @@ function resolveSchemeCredential(name, scheme, env) {
     }
   }
 }
-function envVarName(schemeName) {
-  const upper = schemeName.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^a-zA-Z0-9]+/g, "_").toUpperCase();
-  return `OPENAPI_AUTH_${upper}`;
+function authEnvBase(schemeName) {
+  return `OPENAPI_AUTH_${screamingSnake(schemeName)}`;
+}
+function screamingSnake(value) {
+  return value.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^a-zA-Z0-9]+/g, "_").toUpperCase();
 }
 function openApi3SecuritySchemes(doc) {
   const schemes = doc.components?.securitySchemes ?? {};
@@ -423,6 +490,7 @@ function swagger2SecuritySchemes(doc) {
 var MAX_RESPONSE_BODY_BYTES = 1e5;
 async function executeOperation(options) {
   const { operation, args, auth, requestTimeoutMs } = options;
+  const maxResponseBytes = options.maxResponseBytes ?? MAX_RESPONSE_BODY_BYTES;
   const baseUrl = resolveBaseUrl(operation, options.baseUrlOverride);
   const target = {
     url: buildUrl(operation, args, baseUrl),
@@ -436,13 +504,13 @@ async function executeOperation(options) {
     target.headers.set("Cookie", [...target.cookies].map(([name, value]) => `${name}=${value}`).join("; "));
   }
   const response = await performFetch(target.url, operation, target.headers, body, requestTimeoutMs);
-  const { bytes, truncated } = await readBoundedBody(response, MAX_RESPONSE_BODY_BYTES);
+  const { bytes, truncated } = await readBoundedBody(response, maxResponseBytes);
   return {
     ok: response.ok,
     status: response.status,
     statusText: response.statusText,
     truncated,
-    body: decodeBody(bytes, truncated, response.headers.get("content-type"))
+    body: decodeBody(bytes, truncated, maxResponseBytes, response.headers.get("content-type"))
   };
 }
 async function performFetch(url, operation, headers, body, requestTimeoutMs) {
@@ -455,9 +523,7 @@ async function performFetch(url, operation, headers, body, requestTimeoutMs) {
     });
   } catch (error) {
     if (error instanceof DOMException && (error.name === "TimeoutError" || error.name === "AbortError")) {
-      throw new Error(`Request to ${url.toString()} timed out after ${requestTimeoutMs}ms.`, {
-        cause: error
-      });
+      throw new Error(`Request to ${url.origin}${url.pathname} timed out after ${requestTimeoutMs}ms.`, { cause: error });
     }
     throw error;
   }
@@ -503,13 +569,13 @@ function isTextContentType(contentType) {
   const type = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
   return type.startsWith("text/") || type === "application/json" || type === "application/xml" || type === "application/x-www-form-urlencoded" || type.endsWith("+json") || type.endsWith("+xml");
 }
-function decodeBody(bytes, truncated, contentType) {
+function decodeBody(bytes, truncated, maxResponseBytes, contentType) {
   if (bytes.length === 0)
     return "";
   if (isTextContentType(contentType)) {
     const text = new TextDecoder().decode(bytes);
     return truncated ? `${text}
-...[response truncated, exceeded the ${MAX_RESPONSE_BODY_BYTES} byte cap]` : text;
+...[response truncated, exceeded the ${maxResponseBytes} byte cap]` : text;
   }
   const base64 = Buffer.from(bytes).toString("base64");
   const label = contentType ?? "application/octet-stream";
@@ -519,7 +585,7 @@ ${base64}`;
 function resolveBaseUrl(operation, baseUrlOverride) {
   const base = baseUrlOverride ?? operation.servers[0];
   if (base === undefined) {
-    throw new Error(`No server URL is available for operation "${operation.toolName}". Set OPENAPI_BASE_URL or pass --base-url.`);
+    throw new Error(`No server URL is available for operation "${operation.method} ${operation.path}". Set a base URL when loading the spec.`);
   }
   return base;
 }
@@ -632,172 +698,360 @@ function base64ToBlob(base64) {
   return new Blob([bytes]);
 }
 
-// src/openapi/schema.ts
-import { z } from "zod/v4";
-import { convertJsonSchemaToZod } from "zod-from-json-schema";
-function normalizeJsonSchema(schema) {
-  const seen = new WeakSet;
-  return normalizeNode(schema, seen);
-}
-function normalizeNode(node, seen) {
-  if (Array.isArray(node)) {
-    if (seen.has(node))
-      return node;
-    seen.add(node);
-    return node.map((item) => normalizeNode(item, seen));
-  }
-  if (node === null || typeof node !== "object") {
-    return node;
-  }
-  if (seen.has(node))
-    return node;
-  seen.add(node);
-  const source = node;
-  const normalized = {};
-  for (const [key, value] of Object.entries(source)) {
-    normalized[key] = normalizeNode(value, seen);
-  }
-  const nullable = normalized.nullable === true || normalized["x-nullable"] === true;
-  delete normalized.nullable;
-  delete normalized["x-nullable"];
-  if (nullable) {
-    const { type } = normalized;
-    if (typeof type === "string") {
-      normalized.type = [type, "null"];
-    } else if (Array.isArray(type)) {
-      const types = type;
-      normalized.type = types.includes("null") ? types : [...types, "null"];
-    } else if (type === undefined) {
-      normalized.type = ["null"];
+// src/config.ts
+var DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+var ConfigFileSchema = z.strictObject({
+  specs: z.array(z.strictObject({
+    source: z.string().min(1),
+    base_url: z.string().min(1).optional(),
+    credential: z.string().min(1).optional()
+  })).optional(),
+  max_specs: z.number().int().positive().optional(),
+  request_timeout_ms: z.number().positive().optional(),
+  max_response_bytes: z.number().int().positive().optional()
+});
+function resolveConfig(argv, env) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      "base-url": { type: "string" },
+      credential: { type: "string" },
+      timeout: { type: "string" },
+      config: { type: "string" }
     }
+  });
+  const configPath = clean(values.config ?? env.OPENAPI_CONFIG);
+  const configFile = configPath !== undefined ? readConfigFile(configPath) : {};
+  const preloads = [...(configFile.specs ?? []).map(fromFileSpec)];
+  const shorthandSource = clean(positionals[0] ?? env.OPENAPI_URL);
+  if (shorthandSource !== undefined) {
+    const baseUrl = clean(values["base-url"] ?? env.OPENAPI_BASE_URL);
+    const credential = clean(values.credential ?? env.OPENAPI_CREDENTIAL);
+    preloads.push({
+      source: shorthandSource,
+      ...baseUrl !== undefined && { baseUrl },
+      ...credential !== undefined && { credential }
+    });
   }
-  return normalized;
+  return {
+    preloads,
+    requestTimeoutMs: parsePositive(clean(values.timeout ?? env.OPENAPI_REQUEST_TIMEOUT_MS), configFile.request_timeout_ms, DEFAULT_REQUEST_TIMEOUT_MS, "request timeout", false),
+    maxResponseBytes: parsePositive(clean(env.OPENAPI_MAX_RESPONSE_BYTES), configFile.max_response_bytes, MAX_RESPONSE_BODY_BYTES, "OPENAPI_MAX_RESPONSE_BYTES", true),
+    maxSpecs: parsePositive(clean(env.OPENAPI_MAX_SPECS), configFile.max_specs, DEFAULT_MAX_SPECS, "OPENAPI_MAX_SPECS", true)
+  };
 }
-function toZodType(schema, options) {
-  let base;
-  if (!schema) {
-    base = z.unknown();
-  } else {
-    try {
-      base = convertJsonSchemaToZod(normalizeJsonSchema(schema));
-    } catch {
-      base = z.unknown();
+function clean(value) {
+  return value === undefined || value === "" ? undefined : value;
+}
+function fromFileSpec(spec) {
+  return {
+    source: spec.source,
+    ...spec.base_url !== undefined && { baseUrl: spec.base_url },
+    ...spec.credential !== undefined && { credential: spec.credential }
+  };
+}
+function readConfigFile(path) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (cause) {
+    throw new Error(`Failed to read config file "${path}": ${errorMessage(cause)}`, { cause });
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    throw new Error(`Config file "${path}" is not valid JSON: ${errorMessage(cause)}`, { cause });
+  }
+  const result = ConfigFileSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new Error(`Config file "${path}" is invalid: ${result.error.message}`);
+  }
+  return result.data;
+}
+function parsePositive(raw, fromConfig, fallback, label, integer) {
+  if (raw !== undefined) {
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0 || integer && !Number.isInteger(parsed)) {
+      throw new Error(`Invalid ${label} "${raw}". Pass a positive ${integer ? "integer" : "number"}.`);
     }
+    return parsed;
   }
-  const described = options.description !== undefined ? base.describe(options.description) : base;
-  return options.required ? described : described.optional();
+  return fromConfig ?? fallback;
 }
 
 // src/server.ts
-function buildServer(doc, operations, config, env) {
-  const server = new McpServer({ name: "mcp-openapi", version: "0.1.0", title: specTitle(doc) });
-  registerSpecResource(server, doc);
-  if (operations.length > 0)
-    registerSearchTool(server, operations);
-  const auth = resolveAuth(doc, env);
-  for (const operation of operations) {
-    registerOperationTool(server, operation, auth, config);
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools/describe.ts
+import { z as z2 } from "zod/v4";
+
+// src/openapi/lookup.ts
+function findOperation(spec, method, path) {
+  const wanted = method.toLowerCase();
+  return spec.operations.find((op) => op.method === wanted && op.path === path);
+}
+
+// src/openapi/render-schema.ts
+var MAX_SCHEMA_DEPTH = 6;
+var MAX_ARRAY_ITEMS = 50;
+var MAX_SCHEMA_NODES = 500;
+var MAX_SCHEMA_CHARS = 4000;
+var NOISY_KEYS = new Set(["example", "examples", "xml", "externalDocs", "discriminator"]);
+function renderSchema(schema) {
+  const capped = capSchema(schema, 0, new WeakSet, { nodes: 0 });
+  const json = JSON.stringify(capped, null, 2);
+  if (json.length <= MAX_SCHEMA_CHARS)
+    return json;
+  return `${json.slice(0, MAX_SCHEMA_CHARS)}
+... [schema truncated: exceeded ${MAX_SCHEMA_CHARS} chars]`;
+}
+function capSchema(node, depth, seen, budget) {
+  if (node === null || typeof node !== "object")
+    return node;
+  if (seen.has(node))
+    return "[circular reference]";
+  if (depth >= MAX_SCHEMA_DEPTH)
+    return "[truncated: schema nested too deeply]";
+  if (budget.nodes >= MAX_SCHEMA_NODES)
+    return "[truncated: schema too large]";
+  budget.nodes += 1;
+  seen.add(node);
+  try {
+    if (Array.isArray(node)) {
+      const capped = node.slice(0, MAX_ARRAY_ITEMS).map((item) => capSchema(item, depth + 1, seen, budget));
+      if (node.length > MAX_ARRAY_ITEMS)
+        capped.push(`[+${node.length - MAX_ARRAY_ITEMS} more]`);
+      return capped;
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(node)) {
+      if (NOISY_KEYS.has(key) || key.startsWith("x-"))
+        continue;
+      if (budget.nodes >= MAX_SCHEMA_NODES) {
+        result["..."] = "[truncated: schema too large]";
+        break;
+      }
+      result[key] = capSchema(value, depth + 1, seen, budget);
+    }
+    return result;
+  } finally {
+    seen.delete(node);
   }
-  return server;
 }
-function specTitle(doc) {
-  return doc.info.title;
-}
-function registerSpecResource(server, doc) {
-  server.registerResource("openapi-spec", "openapi://spec", {
-    title: "OpenAPI document",
-    description: "The full, dereferenced OpenAPI/Swagger document this server exposes tools for.",
-    mimeType: "application/json"
-  }, (uri) => ({
-    contents: [
-      { uri: uri.href, mimeType: "application/json", text: JSON.stringify(doc, null, 2) }
-    ]
-  }));
-}
-function registerSearchTool(server, operations) {
-  const index = buildSearchIndex(operations);
-  server.registerTool(SEARCH_TOOL_NAME, {
-    title: "Search API operations",
-    description: "Search the available API operations by keyword (matches operation names, summaries, descriptions, tags, and paths). " + "Use this to find the right tool when there are many operations, then call that tool directly by name.",
+
+// src/tools/describe.ts
+var MAX_TYPE_LABEL_DEPTH = 4;
+function registerDescribeTool(server, registry) {
+  server.registerTool("describe_operation", {
+    title: "Describe one operation",
+    description: "Return the full detail needed to call one operation of a loaded spec, identified by " + "spec_id + method + path (as shown by search_operations). Parameters and the request-body " + "schema are returned in full; responses are summarized (status codes and content types, " + "plus the schema of the 2xx success response only). Large or deeply nested schemas are " + "truncated with a marker.",
     inputSchema: {
-      query: z2.string().min(1).describe('Keywords to search for, e.g. "create pet" or "delete order".'),
-      limit: z2.number().int().positive().max(50).optional().describe("Maximum number of results to return (default 10).")
+      spec_id: z2.string().min(1).describe("The id of a loaded spec (from load_spec/list_specs)."),
+      method: z2.string().min(1).describe('HTTP method, e.g. "get" or "post".'),
+      path: z2.string().min(1).describe('Raw path template, e.g. "/pets/{petId}".')
     },
-    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    annotations: { readOnlyHint: true, openWorldHint: false }
   }, (args) => {
-    const matches = searchOperations(index, args.query, args.limit ?? 10);
-    return { content: [{ type: "text", text: formatSearchResults(args.query, matches) }] };
+    const spec = registry.get(args.spec_id);
+    if (!spec) {
+      return errorResult(`No spec is loaded with id "${args.spec_id}". Call list_specs to see loaded specs.`);
+    }
+    const operation = findOperation(spec, args.method, args.path);
+    if (!operation) {
+      return errorResult(`No operation ${args.method.toUpperCase()} ${args.path} in spec "${args.spec_id}". ` + "Use search_operations to find the exact method and path.");
+    }
+    return { content: [{ type: "text", text: formatOperation(operation) }] };
   });
 }
-function formatSearchResults(query, matches) {
-  if (matches.length === 0)
-    return `No operations matched "${query}".`;
-  const lines = matches.map((match, index) => {
-    const flags = match.deprecated ? " [deprecated]" : "";
-    const summary = match.summary ? `
-   ${match.summary}` : "";
-    return `${index + 1}. ${match.toolName} (${match.method.toUpperCase()} ${match.path})${flags}${summary}`;
-  });
-  return `Found ${matches.length} matching operation(s) for "${query}":
+function errorResult(text) {
+  return { isError: true, content: [{ type: "text", text }] };
+}
+function formatOperation(operation) {
+  const sections = [];
+  const heading = `${operation.method.toUpperCase()} ${operation.path}`;
+  const idPart = operation.operationId !== undefined ? ` [${operation.operationId}]` : "";
+  const deprecatedPart = operation.deprecated ? " (deprecated)" : "";
+  sections.push(`${heading}${idPart}${deprecatedPart}`);
+  if (operation.summary !== undefined)
+    sections.push(operation.summary);
+  if (operation.description !== undefined && operation.description !== operation.summary) {
+    sections.push(operation.description);
+  }
+  sections.push(formatParameters(operation.parameters));
+  if (operation.requestBody) {
+    const rb = operation.requestBody;
+    const required = rb.required ? "required" : "optional";
+    const descLine = rb.description !== undefined ? `${rb.description}
+` : "";
+    sections.push(`Request body (${rb.encoding}, ${required}):
+${descLine}${renderSchema(rb.schema)}`);
+  }
+  sections.push(formatResponses(operation.responses));
+  return sections.join(`
 
+`);
+}
+function formatParameters(parameters) {
+  if (parameters.length === 0)
+    return "Parameters: none";
+  const lines = parameters.map((param) => {
+    const required = param.required ? "required" : "optional";
+    const desc = param.description !== undefined ? ` - ${param.description}` : "";
+    return `- ${param.name} (${param.in}, ${required}): ${schemaTypeLabel(param.schema)}${desc}`;
+  });
+  return `Parameters:
 ${lines.join(`
 `)}`;
 }
-function registerOperationTool(server, operation, auth, config) {
-  server.registerTool(operation.toolName, {
-    title: operation.summary ?? operation.toolName,
-    description: toolDescription(operation),
-    inputSchema: buildInputShape(operation),
-    annotations: {
-      readOnlyHint: operation.method === "get" || operation.method === "head",
-      destructiveHint: operation.method === "delete",
-      idempotentHint: ["get", "put", "delete", "head"].includes(operation.method),
-      openWorldHint: true
-    }
+function formatResponses(responses) {
+  if (responses.length === 0)
+    return "Responses: none documented";
+  const lines = responses.map((response) => {
+    const types = response.contentTypes.length > 0 ? ` (${response.contentTypes.join(", ")})` : "";
+    const desc = response.description !== undefined ? ` - ${response.description}` : "";
+    return `- ${response.status}${types}${desc}`;
+  });
+  const success = responses.find((r) => /^2(\d\d|xx)$/i.test(r.status) && r.schema !== undefined);
+  const successBlock = success?.schema !== undefined ? `
+
+Success response body (${success.status}):
+${renderSchema(success.schema)}` : "";
+  return `Responses:
+${lines.join(`
+`)}${successBlock}`;
+}
+function schemaTypeLabel(schema, depth = 0) {
+  if (Array.isArray(schema.enum))
+    return `enum(${schema.enum.map((v) => JSON.stringify(v)).join(", ")})`;
+  const type = schema.type;
+  if (type === "array") {
+    const items = schema.items;
+    if (!items || depth >= MAX_TYPE_LABEL_DEPTH)
+      return "array<any>";
+    return `array<${schemaTypeLabel(items, depth + 1)}>`;
+  }
+  if (typeof type === "string")
+    return type;
+  if (Array.isArray(type))
+    return type.join("|");
+  return "any";
+}
+
+// src/tools/execute.ts
+import { z as z3 } from "zod/v4";
+function registerExecuteTool(server, registry, context) {
+  server.registerTool("execute_operation", {
+    title: "Execute one operation",
+    description: "Perform the real HTTP request for one operation of a loaded spec, identified by spec_id " + "+ method + path (as shown by search_operations). Supply arguments grouped by location: " + "path_params, query, headers (each an object of name -> value) and body (the request body). " + "Only parameters declared by the operation are sent; the body is sent as-is, so extra body " + "fields pass through to the API. Required parameters and body must be present. Returns the " + "HTTP status and response body.",
+    inputSchema: {
+      spec_id: z3.string().min(1).describe("The id of a loaded spec (from load_spec/list_specs)."),
+      method: z3.string().min(1).describe('HTTP method, e.g. "get" or "post".'),
+      path: z3.string().min(1).describe('Raw path template, e.g. "/pets/{petId}".'),
+      path_params: z3.record(z3.string(), z3.unknown()).optional().describe('Path template values, keyed by parameter name, e.g. { "petId": 42 }.'),
+      query: z3.record(z3.string(), z3.unknown()).optional().describe("Query string parameters, keyed by name."),
+      headers: z3.record(z3.string(), z3.unknown()).optional().describe("Request header parameters, keyed by name."),
+      body: z3.unknown().optional().describe("Request body, matching the operation’s schema.")
+    },
+    annotations: { openWorldHint: true }
   }, async (args) => {
+    const spec = registry.get(args.spec_id);
+    if (!spec) {
+      return errorResult2(`No spec is loaded with id "${args.spec_id}". Call list_specs to see loaded specs.`);
+    }
+    const operation = findOperation(spec, args.method, args.path);
+    if (!operation) {
+      return errorResult2(`No operation ${args.method.toUpperCase()} ${args.path} in spec "${args.spec_id}". ` + "Use search_operations to find the exact method and path.");
+    }
+    const groups = args;
+    const requiredCookies = operation.parameters.filter((p) => p.in === "cookie" && p.required);
+    if (requiredCookies.length > 0) {
+      return errorResult2(`Operation ${operation.method.toUpperCase()} ${operation.path} requires cookie ` + `parameter(s) (${requiredCookies.map((p) => p.name).join(", ")}), which ` + "execute_operation does not support.");
+    }
+    const missing = missingRequired(operation, groups);
+    if (missing.length > 0) {
+      return errorResult2(`Missing required argument(s): ${missing.join(", ")}. ` + "Call describe_operation for this operation’s parameters.");
+    }
     try {
       const result = await executeOperation({
         operation,
-        args,
-        auth,
-        baseUrlOverride: config.baseUrlOverride,
-        requestTimeoutMs: config.requestTimeoutMs
+        args: toFlatArgs(operation, groups),
+        baseUrlOverride: spec.baseUrl,
+        auth: resolveAuth(spec.doc, context.env, spec.credential),
+        requestTimeoutMs: context.requestTimeoutMs,
+        maxResponseBytes: context.maxResponseBytes
       });
       return { isError: !result.ok, content: [{ type: "text", text: formatResult(result) }] };
     } catch (error) {
-      return {
-        isError: true,
-        content: [{ type: "text", text: `Request failed: ${errorMessage(error)}` }]
-      };
+      return errorResult2(`Request failed: ${errorMessage(error)}`);
     }
   });
 }
-function buildInputShape(operation) {
-  const shape = {};
+function errorResult2(text) {
+  return { isError: true, content: [{ type: "text", text }] };
+}
+function groupFor(location, groups) {
+  switch (location) {
+    case "path":
+      return groups.path_params;
+    case "query":
+      return groups.query;
+    case "header":
+      return groups.headers;
+    case "cookie":
+      return;
+  }
+}
+function missingRequired(operation, groups) {
+  const missing = [];
   for (const param of operation.parameters) {
-    shape[param.argName] = toZodType(param.schema, {
-      required: param.required,
-      ...param.description !== undefined && { description: param.description }
-    });
+    if (!param.required || param.in === "cookie")
+      continue;
+    if (groupFor(param.in, groups)?.[param.name] === undefined) {
+      missing.push(`${param.name} (${param.in})`);
+    }
   }
-  if (operation.requestBody) {
-    shape.requestBody = toZodType(operation.requestBody.schema, {
-      required: operation.requestBody.required,
-      ...operation.requestBody.description !== undefined && {
-        description: operation.requestBody.description
-      }
-    });
+  if (operation.requestBody?.required && groups.body === undefined)
+    missing.push("body");
+  return missing;
+}
+function toFlatArgs(operation, groups) {
+  const flat = {};
+  for (const param of operation.parameters) {
+    const value = groupFor(param.in, groups)?.[param.name];
+    if (value !== undefined)
+      flat[param.argName] = coerceScalar(value, param);
   }
-  return shape;
+  if (groups.body !== undefined)
+    flat.requestBody = groups.body;
+  return flat;
 }
-function toolDescription(operation) {
-  const summary = operation.description ?? operation.summary ?? `${operation.method.toUpperCase()} ${operation.path}`;
-  const parts = [summary, `HTTP ${operation.method.toUpperCase()} ${operation.path}`];
-  if (operation.deprecated)
-    parts.push("This operation is marked deprecated in the OpenAPI document.");
-  return parts.join(`
-
-`);
+function coerceScalar(value, param) {
+  if (typeof value !== "string")
+    return value;
+  const type = schemaType(param.schema);
+  if (type === "number" || type === "integer") {
+    const trimmed = value.trim();
+    const num = Number(trimmed);
+    if (trimmed === "" || String(num) !== trimmed)
+      return value;
+    if (type === "integer" && !Number.isSafeInteger(num))
+      return value;
+    return num;
+  }
+  if (type === "boolean" && (value === "true" || value === "false")) {
+    return value === "true";
+  }
+  return value;
+}
+function schemaType(schema) {
+  const type = schema.type;
+  if (typeof type === "string")
+    return type;
+  if (Array.isArray(type))
+    return type.find((t) => typeof t === "string" && t !== "null");
+  return;
 }
 function formatResult(result) {
   const header = `HTTP ${result.status} ${result.statusText}`;
@@ -806,18 +1060,303 @@ function formatResult(result) {
 ${result.body}` : header;
 }
 
+// src/tools/search.ts
+import { z as z4 } from "zod/v4";
+
+// src/openapi/search.ts
+import MiniSearch from "minisearch";
+function operationKey(operation) {
+  return `${operation.method} ${operation.path}`;
+}
+function buildSearchIndex(operations) {
+  const index = new MiniSearch({
+    idField: "id",
+    fields: ["operationId", "summary", "description", "tags", "path"],
+    storeFields: ["operationId", "method", "path", "summary", "deprecated"],
+    searchOptions: {
+      prefix: true,
+      fuzzy: 0.2,
+      boost: { operationId: 3, summary: 2, tags: 1.5 }
+    }
+  });
+  index.addAll(operations.map((operation) => ({
+    id: operationKey(operation),
+    operationId: operation.operationId ?? "",
+    method: operation.method,
+    path: operation.path,
+    summary: operation.summary ?? "",
+    description: operation.description ?? "",
+    tags: operation.tags.join(" "),
+    deprecated: operation.deprecated
+  })));
+  return index;
+}
+function searchOperations(index, query) {
+  return index.search(query).map(toSearchMatch);
+}
+function toSearchMatch(result) {
+  const summary = typeof result.summary === "string" && result.summary.length > 0 ? result.summary : undefined;
+  const operationId = typeof result.operationId === "string" && result.operationId.length > 0 ? result.operationId : undefined;
+  return {
+    method: String(result.method),
+    path: String(result.path),
+    deprecated: result.deprecated === true,
+    score: result.score,
+    ...operationId !== undefined && { operationId },
+    ...summary !== undefined && { summary }
+  };
+}
+
+// src/tools/search.ts
+var DEFAULT_LIMIT = 20;
+var indexCache = new WeakMap;
+function getIndex(spec) {
+  let index = indexCache.get(spec);
+  if (!index) {
+    index = buildSearchIndex(spec.operations);
+    indexCache.set(spec, index);
+  }
+  return index;
+}
+function registerSearchTool(server, registry) {
+  server.registerTool("search_operations", {
+    title: "Search a spec’s operations",
+    description: "Find operations within one loaded spec (identified by spec_id). With a query, ranks " + "operations by keyword match against their operationId, summary, description, tags, and " + "path. Without a query, browses every operation in natural order. Results are compact " + "one-liners (method, path, operationId, summary) with no parameter or response schemas; " + "call describe_operation for the full detail of a specific operation. Use limit/offset " + "to page through large specs.",
+    inputSchema: {
+      spec_id: z4.string().min(1).describe("The id of a loaded spec (from load_spec/list_specs)."),
+      query: z4.string().optional().describe('Keywords, e.g. "create pet". Omit or leave empty to browse all operations.'),
+      limit: z4.number().int().positive().max(100).optional().describe(`Maximum results to return (default ${DEFAULT_LIMIT}).`),
+      offset: z4.number().int().nonnegative().optional().describe("Number of results to skip, for pagination (default 0).")
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false }
+  }, (args) => {
+    const spec = registry.get(args.spec_id);
+    if (!spec) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `No spec is loaded with id "${args.spec_id}". Call list_specs to see loaded specs.`
+          }
+        ]
+      };
+    }
+    const query = args.query?.trim() ?? "";
+    const limit = args.limit ?? DEFAULT_LIMIT;
+    const offset = args.offset ?? 0;
+    const all = query ? searchOperations(getIndex(spec), query) : spec.operations.map(toLine);
+    const page = all.slice(offset, offset + limit);
+    return {
+      content: [
+        { type: "text", text: formatResults(page, { total: all.length, offset, query }) }
+      ]
+    };
+  });
+}
+function toLine(operation) {
+  return {
+    method: operation.method,
+    path: operation.path,
+    deprecated: operation.deprecated,
+    ...operation.operationId !== undefined && { operationId: operation.operationId },
+    ...operation.summary !== undefined && { summary: operation.summary }
+  };
+}
+function formatResults(lines, ctx) {
+  const scope = ctx.query ? `matching "${ctx.query}"` : "in this spec";
+  if (ctx.total === 0) {
+    return ctx.query ? `No operations matched "${ctx.query}".` : "This spec has no operations.";
+  }
+  if (lines.length === 0) {
+    return `Offset ${ctx.offset} is past the ${ctx.total} operation(s) ${scope}. Use a smaller offset.`;
+  }
+  const first = ctx.offset + 1;
+  const last = ctx.offset + lines.length;
+  const header = `${ctx.total} operation(s) ${scope} (showing ${first}-${last}):`;
+  const body = lines.map(formatLine).join(`
+`);
+  const shownThrough = ctx.offset + lines.length;
+  const footer = shownThrough < ctx.total ? `
+
+${ctx.total - shownThrough} more. Pass offset: ${shownThrough} to see the next page.` : "";
+  return `${header}
+
+${body}${footer}`;
+}
+function formatLine(line) {
+  const parts = [`${line.method.toUpperCase()} ${line.path}`];
+  if (line.operationId !== undefined)
+    parts.push(`[${line.operationId}]`);
+  if (line.summary !== undefined)
+    parts.push(`- ${line.summary}`);
+  if (line.deprecated)
+    parts.push("(deprecated)");
+  return parts.join(" ");
+}
+
+// src/tools/specs.ts
+import { z as z5 } from "zod/v4";
+function registerSpecTools(server, registry, env) {
+  registerLoadSpec(server, registry, env);
+  registerListSpecs(server, registry);
+  registerUnloadSpec(server, registry);
+}
+function registerLoadSpec(server, registry, env) {
+  server.registerTool("load_spec", {
+    title: "Load an OpenAPI/Swagger spec",
+    description: "Load an OpenAPI/Swagger document (2.0/3.0/3.1) so its operations can be searched, " + "described, and executed. The source may be an http(s) URL, a local file path, or the " + "raw JSON/YAML content itself. Returns a generated spec_id (a lowercase ULID) plus a " + "compact summary; pass that spec_id to the other tools. Loading the same document twice " + "produces two independent specs with different ids.",
+    inputSchema: {
+      source: z5.string().min(1).describe("An http(s) URL, a local file path, or the raw JSON/YAML content of the document."),
+      base_url: z5.string().min(1).optional().describe("Override the base URL this spec's operations are called against (wins over the " + "servers declared in the document)."),
+      credential: z5.string().min(1).optional().describe('Name of a credential the operator provisioned in the environment (e.g. "github" for ' + "OPENAPI_CRED_GITHUB). Pass the reference name only, never a secret value. When " + "omitted, credentials are matched by the document's security scheme names.")
+    },
+    annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true }
+  }, async (args) => {
+    if (registry.isFull) {
+      return {
+        isError: true,
+        content: [
+          { type: "text", text: `Cannot load. ${maxSpecsReachedMessage(registry.maxSpecs)}` }
+        ]
+      };
+    }
+    if (args.credential !== undefined && !hasConfiguredCredential(env, args.credential)) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `No credential named "${args.credential}" is configured on this server. ` + `Ask the operator to provision it (e.g. ${credentialEnvBase(args.credential)}), ` + "or omit the credential argument."
+          }
+        ]
+      };
+    }
+    try {
+      const spec = await registry.load(args.source, {
+        ...args.base_url !== undefined && { baseUrl: args.base_url },
+        ...args.credential !== undefined && { credential: args.credential }
+      });
+      if (args.credential !== undefined && hasSupportedSecuritySchemes(spec.doc) && resolveAuth(spec.doc, env, args.credential).length === 0) {
+        registry.unload(spec.id);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Credential "${args.credential}" is configured but does not provide what any of ` + `this spec's security schemes require. Check the variant under ${credentialEnvBase(args.credential)} ` + "(bearer needs _TOKEN or the bare value, basic needs _USERNAME and _PASSWORD, apiKey needs the bare value)."
+            }
+          ]
+        };
+      }
+      return { content: [{ type: "text", text: formatLoaded(specSummary(spec)) }] };
+    } catch (error) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Failed to load spec: ${errorMessage(error)}` }]
+      };
+    }
+  });
+}
+function registerUnloadSpec(server, registry) {
+  server.registerTool("unload_spec", {
+    title: "Unload a spec",
+    description: "Remove a loaded spec from the server, freeing its operations and cached search index. " + "Use this to reclaim capacity when the maximum number of loaded specs is reached, or to " + "drop a spec you no longer need.",
+    inputSchema: {
+      spec_id: z5.string().min(1).describe("The id of the loaded spec to unload.")
+    },
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false }
+  }, (args) => {
+    if (!registry.unload(args.spec_id)) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `No spec is loaded with id "${args.spec_id}". Call list_specs to see loaded specs.`
+          }
+        ]
+      };
+    }
+    return { content: [{ type: "text", text: `Unloaded spec ${args.spec_id}.` }] };
+  });
+}
+function registerListSpecs(server, registry) {
+  server.registerTool("list_specs", {
+    title: "List loaded specs",
+    description: "List every OpenAPI/Swagger spec currently loaded into this server, with its spec_id " + "and a compact summary. Use this to discover the spec_id to pass to the other tools.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, openWorldHint: false }
+  }, () => {
+    const summaries = registry.list().map(specSummary);
+    return { content: [{ type: "text", text: formatList(summaries) }] };
+  });
+}
+function formatLoaded(summary) {
+  return `Loaded spec.
+
+${formatSummary(summary)}
+
+Pass this spec_id to the other meta-tools to work with its operations.`;
+}
+function formatList(summaries) {
+  if (summaries.length === 0) {
+    return "No specs are currently loaded. Use load_spec to load one.";
+  }
+  const blocks = summaries.map((summary, index) => `${index + 1}. ${formatSummary(summary)}`);
+  return `${summaries.length} spec(s) loaded:
+
+${blocks.join(`
+
+`)}`;
+}
+function formatSummary(summary) {
+  const servers = summary.servers.length > 0 ? summary.servers.join(", ") : "(none declared)";
+  return [
+    `spec_id: ${summary.id}`,
+    `${summary.title} (v${summary.version}) - ${summary.operationCount} operation(s)`,
+    `base URL(s): ${servers}`
+  ].join(`
+`);
+}
+
+// src/server.ts
+function buildServer(registry, options) {
+  const server = new McpServer({ name: "mcp-openapi", version: "0.2.0" });
+  const env = options.env ?? {};
+  registerSpecTools(server, registry, env);
+  registerSearchTool(server, registry);
+  registerDescribeTool(server, registry);
+  registerExecuteTool(server, registry, {
+    requestTimeoutMs: options.requestTimeoutMs,
+    maxResponseBytes: options.maxResponseBytes ?? MAX_RESPONSE_BODY_BYTES,
+    env
+  });
+  return server;
+}
+
 // src/index.ts
-var LARGE_TOOL_COUNT_WARNING_THRESHOLD = 200;
+async function preloadSpecs(registry, preloads) {
+  for (const preload of preloads) {
+    try {
+      await registry.load(preload.source, {
+        ...preload.baseUrl !== undefined && { baseUrl: preload.baseUrl },
+        ...preload.credential !== undefined && { credential: preload.credential }
+      });
+    } catch (error) {
+      console.warn(`mcp-openapi: failed to preload "${preload.source}": ${errorMessage(error)}`);
+    }
+  }
+}
 async function main() {
   const config = resolveConfig(process.argv.slice(2), process.env);
-  const doc = await loadOpenApiDocument(config.source);
-  const operations = extractOperations(doc, [SEARCH_TOOL_NAME]);
-  if (operations.length === 0) {
-    console.warn(`mcp-openapi: no operations were found in "${config.source}".`);
-  } else if (operations.length > LARGE_TOOL_COUNT_WARNING_THRESHOLD) {
-    console.warn(`mcp-openapi: "${config.source}" defines ${operations.length} operations, which will register that many tools and may overwhelm the connected agent.`);
-  }
-  const server = buildServer(doc, operations, config, process.env);
+  const registry = new SpecRegistry({ maxSpecs: config.maxSpecs });
+  await preloadSpecs(registry, config.preloads);
+  const server = buildServer(registry, {
+    requestTimeoutMs: config.requestTimeoutMs,
+    maxResponseBytes: config.maxResponseBytes,
+    env: process.env
+  });
   const transport = new StdioServerTransport;
   await server.connect(transport);
 }
@@ -837,5 +1376,6 @@ if (isMainModule()) {
   });
 }
 export {
+  preloadSpecs,
   main
 };