@avidian/mcp-openapi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Michael Manlupig
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @avidian/mcp-openapi
+
+MCP server for OpenAPI/Swagger — gives AI agents the ability to discover, search, and call any REST API described by an OpenAPI or Swagger document.
+
+Point it at a single OpenAPI/Swagger document (URL or local file, 2.0/3.0/3.1) and it exposes:
+
+- The full, dereferenced document as a readable MCP resource
+- A keyword search tool for finding the right operation when a spec defines many of them
+- One MCP tool per operation, which proxies a real HTTP request to the underlying API
+
+## Installation
+
+### npm (requires Node.js ≥ 20)
+
+```bash
+npm install -g @avidian/mcp-openapi
+```
+
+### Compiled binary (no runtime needed)
+
+Download from [GitHub Releases](https://github.com/avidianity/mcp-openapi/releases).
+
+## Usage
+
+```bash
+mcp-openapi <openapi-url-or-path> [--base-url <url>] [--timeout <ms>]
+```
+
+```bash
+mcp-openapi https://petstore3.swagger.io/api/v3/openapi.json
+mcp-openapi ./openapi.yaml --base-url https://api.internal.example.com --timeout 10000
+```
+
+The source may also come from `OPENAPI_URL` instead of the positional argument, which is convenient for MCP client configs.
+
+### MCP client configuration
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "command": "mcp-openapi",
+      "args": ["https://api.example.com/openapi.json"]
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable                     | Description                                                                   |
+| ---------------------------- | ----------------------------------------------------------------------------- |
+| `OPENAPI_URL`                | OpenAPI/Swagger source (URL or local path), if not passed as the CLI argument |
+| `OPENAPI_BASE_URL`           | Overrides every server URL declared in the spec                               |
+| `OPENAPI_REQUEST_TIMEOUT_MS` | Per-request timeout in milliseconds (default `30000`)                         |
+
+### Authentication
+
+For each security scheme declared in the OpenAPI document, credentials are read from environment variables named after the scheme (converted to `SCREAMING_SNAKE_CASE`) — e.g. a scheme called `apiKeyAuth` reads `OPENAPI_AUTH_API_KEY_AUTH`.
+
+| Scheme type                    | Environment variables                                                 |
+| ------------------------------ | --------------------------------------------------------------------- |
+| HTTP bearer                    | `OPENAPI_AUTH_<SCHEME>_TOKEN` (or bare `OPENAPI_AUTH_<SCHEME>`)       |
+| HTTP basic                     | `OPENAPI_AUTH_<SCHEME>_USERNAME` and `OPENAPI_AUTH_<SCHEME>_PASSWORD` |
+| apiKey (header, query, cookie) | `OPENAPI_AUTH_<SCHEME>`                                               |
+
+Schemes with no matching environment variable, and unsupported types (OAuth2, OpenID Connect), are skipped with a warning rather than failing startup.
+
+## What it exposes
+
+- **Resource** `openapi://spec` — the full, dereferenced OpenAPI/Swagger document.
+- **Tool** `search_operations` — keyword search across every operation's name, summary, description, tags, and path. Use this first when a spec defines many operations.
+- **One tool per operation** — named after its `operationId` (sanitized and deduplicated), taking the operation's path/query/header parameters and request body as arguments.
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run in dev mode
+bun run dev <openapi-url-or-path>
+
+# Type check
+bun run typecheck
+
+# Lint
+bun run lint
+
+# Format
+bun run format
+
+# Test
+bun run test
+
+# Build for npm
+bun run build
+
+# Compile native binary
+bun run compile
+```
+
+`ajv` is listed as a direct devDependency even though nothing in `src/` imports it. It's a workaround: `@apidevtools/swagger-parser` depends on `ajv-draft-04`, which only declares `ajv` as a peer dependency, and Bun's bundler fails to statically resolve that peer dependency when producing standalone binaries (`bun run compile`) unless `ajv` is also resolvable as a direct dependency somewhere in the root of the tree. Not needed for `bun run build` (the npm-published bundle), which keeps `@apidevtools/swagger-parser` external and lets Node resolve it normally at install time.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,815 @@
+#!/usr/bin/env node
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { fileURLToPath } from "node:url";
+
+// src/config.ts
+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;
+}
+
+// src/errors.ts
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/openapi/load.ts
+import SwaggerParser from "@apidevtools/swagger-parser";
+async function loadOpenApiDocument(source) {
+  try {
+    return await SwaggerParser.dereference(source);
+  } catch (cause) {
+    throw new Error(`Failed to load OpenAPI document from "${source}": ${errorMessage(cause)}`, {
+      cause
+    });
+  }
+}
+function isSwagger2Document(doc) {
+  return "swagger" in doc;
+}
+
+// src/openapi/operations.ts
+var HTTP_METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace"
+];
+function extractOperations(doc, reservedNames = []) {
+  const drafts = isSwagger2Document(doc) ? extractSwagger2Operations(doc) : extractOpenApi3Operations(doc);
+  return assignToolNames(drafts, reservedNames);
+}
+function extractOpenApi3Operations(doc) {
+  const docServers = serverUrls(doc.servers);
+  const operations = [];
+  for (const [path, pathItem] of Object.entries(doc.paths ?? {})) {
+    if (!pathItem)
+      continue;
+    const pathServers = serverUrls(pathItem.servers);
+    const pathParams = pathItem.parameters ?? [];
+    for (const method of HTTP_METHODS) {
+      const operation = pathItem[method];
+      if (!operation)
+        continue;
+      const opServers = serverUrls(operation.servers);
+      const servers = opServers.length > 0 ? opServers : pathServers.length > 0 ? pathServers : docServers;
+      const rawParams = mergeParameterObjects(pathParams, operation.parameters ?? []);
+      const requestBody = buildRequestBodyV3(operation.requestBody);
+      operations.push({
+        method,
+        path,
+        deprecated: operation.deprecated ?? false,
+        parameters: buildParameters(rawParams),
+        servers,
+        tags: operation.tags ?? [],
+        ...requestBody !== undefined && { requestBody },
+        ...operation.operationId !== undefined && { operationId: operation.operationId },
+        ...operation.summary !== undefined && { summary: operation.summary },
+        ...operation.description !== undefined && { description: operation.description }
+      });
+    }
+  }
+  return operations;
+}
+function mergeParameterObjects(pathParams, opParams) {
+  const byKey = new Map;
+  for (const param of [...pathParams, ...opParams]) {
+    byKey.set(`${param.in}:${param.name}`, param);
+  }
+  return [...byKey.values()];
+}
+function buildParameters(raw) {
+  const used = new Set;
+  return raw.map((param) => {
+    const location = param.in;
+    const argName = used.has(param.name) ? `${location}_${param.name}` : param.name;
+    used.add(argName);
+    return {
+      name: param.name,
+      in: location,
+      required: param.required ?? location === "path",
+      schema: param.schema ?? {},
+      argName,
+      ...param.description !== undefined && { description: param.description }
+    };
+  });
+}
+function buildRequestBodyV3(requestBody) {
+  if (!requestBody)
+    return;
+  const content = requestBody.content;
+  const jsonMedia = content["application/json"] ?? Object.entries(content).find(([type]) => /\bjson\b/i.test(type))?.[1];
+  if (jsonMedia) {
+    return {
+      required: requestBody.required ?? false,
+      schema: jsonMedia.schema ?? {},
+      encoding: "json",
+      ...requestBody.description !== undefined && { description: requestBody.description }
+    };
+  }
+  const multipart = content["multipart/form-data"];
+  if (multipart) {
+    return {
+      required: requestBody.required ?? false,
+      schema: multipart.schema ?? {},
+      encoding: "multipart",
+      ...requestBody.description !== undefined && { description: requestBody.description }
+    };
+  }
+  const formUrlEncoded = content["application/x-www-form-urlencoded"];
+  if (formUrlEncoded) {
+    return {
+      required: requestBody.required ?? false,
+      schema: formUrlEncoded.schema ?? {},
+      encoding: "form-urlencoded",
+      ...requestBody.description !== undefined && { description: requestBody.description }
+    };
+  }
+  return;
+}
+function serverUrls(servers) {
+  if (!servers)
+    return [];
+  return servers.map((server) => substituteServerVariables(server.url, server.variables));
+}
+function substituteServerVariables(url, variables) {
+  if (!variables)
+    return url;
+  return url.replace(/\{(\w+)\}/g, (match, name) => variables[name]?.default ?? match);
+}
+function extractSwagger2Operations(doc) {
+  const servers = swagger2ServerUrls(doc);
+  const operations = [];
+  for (const [path, pathItem] of Object.entries(doc.paths)) {
+    const pathParams = pathItem.parameters ?? [];
+    for (const method of HTTP_METHODS) {
+      if (method === "trace")
+        continue;
+      const operation = pathItem[method];
+      if (!operation)
+        continue;
+      const rawParams = mergeSwagger2Parameters(pathParams, operation.parameters ?? []);
+      const consumesMultipart = (operation.consumes ?? doc.consumes ?? []).includes("multipart/form-data");
+      const requestBody = buildRequestBodySwagger2(rawParams, consumesMultipart);
+      operations.push({
+        method,
+        path,
+        deprecated: operation.deprecated ?? false,
+        parameters: buildSwagger2Parameters(rawParams),
+        servers,
+        tags: operation.tags ?? [],
+        ...requestBody !== undefined && { requestBody },
+        ...operation.operationId !== undefined && { operationId: operation.operationId },
+        ...operation.summary !== undefined && { summary: operation.summary },
+        ...operation.description !== undefined && { description: operation.description }
+      });
+    }
+  }
+  return operations;
+}
+function mergeSwagger2Parameters(pathParams, opParams) {
+  const byKey = new Map;
+  for (const param of [...pathParams, ...opParams]) {
+    byKey.set(`${param.in}:${param.name}`, param);
+  }
+  return [...byKey.values()];
+}
+function buildSwagger2Parameters(raw) {
+  const used = new Set;
+  const result = [];
+  for (const param of raw) {
+    if (param.in === "body" || param.in === "formData")
+      continue;
+    const location = param.in;
+    const argName = used.has(param.name) ? `${location}_${param.name}` : param.name;
+    used.add(argName);
+    result.push({
+      name: param.name,
+      in: location,
+      required: param.required ?? location === "path",
+      schema: itemsObjectToJsonSchema(param),
+      argName,
+      ...param.description !== undefined && { description: param.description }
+    });
+  }
+  return result;
+}
+function itemsObjectToJsonSchema(param) {
+  const { name: _name, in: _in, description: _description, required: _required, ...rest } = param;
+  return rest;
+}
+function buildRequestBodySwagger2(raw, consumesMultipart) {
+  const bodyParam = raw.find((param) => param.in === "body");
+  if (bodyParam) {
+    return {
+      required: bodyParam.required ?? false,
+      schema: bodyParam.schema,
+      encoding: "json",
+      ...bodyParam.description !== undefined && { description: bodyParam.description }
+    };
+  }
+  const formParams = raw.filter((param) => param.in === "formData");
+  if (formParams.length === 0)
+    return;
+  const properties = {};
+  const required = [];
+  for (const param of formParams) {
+    properties[param.name] = itemsObjectToJsonSchema(param);
+    if (param.required)
+      required.push(param.name);
+  }
+  return {
+    required: required.length > 0,
+    schema: { type: "object", properties, ...required.length > 0 && { required } },
+    encoding: consumesMultipart ? "multipart" : "form-urlencoded"
+  };
+}
+function swagger2ServerUrls(doc) {
+  const schemes = doc.schemes && doc.schemes.length > 0 ? doc.schemes : ["https"];
+  const host = doc.host ?? "localhost";
+  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)) {
+      name = `${base}_${counter}`;
+      counter += 1;
+    }
+    used.add(name);
+    return { ...draft, toolName: name };
+  });
+}
+
+// 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 }
+    }
+  });
+  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);
+}
+function toSearchMatch(result) {
+  const summary = typeof result.summary === "string" && result.summary.length > 0 ? result.summary : undefined;
+  return {
+    toolName: String(result.toolName),
+    method: String(result.method),
+    path: String(result.path),
+    deprecated: result.deprecated === true,
+    score: result.score,
+    ...summary !== undefined && { summary }
+  };
+}
+
+// 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);
+  const resolved = [];
+  for (const [name, scheme] of Object.entries(schemes)) {
+    const credential = resolveSchemeCredential(name, scheme, env);
+    if (credential)
+      resolved.push(credential);
+  }
+  return resolved;
+}
+function applyAuth(auth, target) {
+  for (const entry of auth) {
+    switch (entry.kind) {
+      case "bearer":
+        target.headers.set("Authorization", `Bearer ${entry.token}`);
+        break;
+      case "basic":
+        target.headers.set("Authorization", `Basic ${btoa(`${entry.username}:${entry.password}`)}`);
+        break;
+      case "apiKey":
+        applyApiKey(entry, target);
+        break;
+    }
+  }
+}
+function applyApiKey(entry, target) {
+  if (entry.in === "query") {
+    target.url.searchParams.set(entry.name, entry.value);
+  } else if (entry.in === "cookie") {
+    target.cookies.set(entry.name, entry.value);
+  } else {
+    target.headers.set(entry.name, entry.value);
+  }
+}
+function resolveSchemeCredential(name, scheme, env) {
+  const base = envVarName(name);
+  switch (scheme.kind) {
+    case "bearer": {
+      const token = env[`${base}_TOKEN`] ?? env[base];
+      return token !== undefined ? { kind: "bearer", token } : undefined;
+    }
+    case "basic": {
+      const username = env[`${base}_USERNAME`];
+      const password = env[`${base}_PASSWORD`];
+      return username !== undefined && password !== undefined ? { kind: "basic", username, password } : undefined;
+    }
+    case "apiKey": {
+      const value = env[base];
+      return value !== undefined ? { kind: "apiKey", in: scheme.in, name: scheme.name, value } : undefined;
+    }
+  }
+}
+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 openApi3SecuritySchemes(doc) {
+  const schemes = doc.components?.securitySchemes ?? {};
+  const normalized = {};
+  for (const [name, scheme] of Object.entries(schemes)) {
+    if (scheme.type === "http" && scheme.scheme.toLowerCase() === "bearer") {
+      normalized[name] = { kind: "bearer" };
+    } else if (scheme.type === "http" && scheme.scheme.toLowerCase() === "basic") {
+      normalized[name] = { kind: "basic" };
+    } else if (scheme.type === "apiKey") {
+      normalized[name] = { kind: "apiKey", in: scheme.in, name: scheme.name };
+    } else {
+      console.warn(`mcp-openapi: security scheme "${name}" has unsupported type "${scheme.type}" and will be ignored.`);
+    }
+  }
+  return normalized;
+}
+function swagger2SecuritySchemes(doc) {
+  const schemes = doc.securityDefinitions ?? {};
+  const normalized = {};
+  for (const [name, scheme] of Object.entries(schemes)) {
+    if (scheme.type === "basic") {
+      normalized[name] = { kind: "basic" };
+    } else if (scheme.type === "apiKey") {
+      normalized[name] = { kind: "apiKey", in: scheme.in, name: scheme.name };
+    } else {
+      console.warn(`mcp-openapi: security scheme "${name}" has unsupported type "${scheme.type}" and will be ignored.`);
+    }
+  }
+  return normalized;
+}
+
+// src/openapi/request.ts
+var MAX_RESPONSE_BODY_BYTES = 1e5;
+async function executeOperation(options) {
+  const { operation, args, auth, requestTimeoutMs } = options;
+  const baseUrl = resolveBaseUrl(operation, options.baseUrlOverride);
+  const target = {
+    url: buildUrl(operation, args, baseUrl),
+    headers: new Headers,
+    cookies: new Map
+  };
+  applyAuth(auth, target);
+  applyHeaderParams(operation, args, target.headers);
+  const body = buildBody(operation, args, target.headers);
+  if (target.cookies.size > 0) {
+    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);
+  return {
+    ok: response.ok,
+    status: response.status,
+    statusText: response.statusText,
+    truncated,
+    body: decodeBody(bytes, truncated, response.headers.get("content-type"))
+  };
+}
+async function performFetch(url, operation, headers, body, requestTimeoutMs) {
+  try {
+    return await fetch(url, {
+      method: operation.method.toUpperCase(),
+      headers,
+      signal: AbortSignal.timeout(requestTimeoutMs),
+      ...body !== undefined && { body }
+    });
+  } 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 error;
+  }
+}
+async function readBoundedBody(response, maxBytes) {
+  const stream = response.body;
+  if (!stream)
+    return { bytes: new Uint8Array(0), truncated: false };
+  const reader = stream.getReader();
+  const chunks = [];
+  let total = 0;
+  let truncated = false;
+  try {
+    for (;; ) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      const remaining = maxBytes - total;
+      const chunk = value.length > remaining ? value.subarray(0, remaining) : value;
+      chunks.push(chunk);
+      total += chunk.length;
+      if (chunk.length < value.length) {
+        truncated = true;
+        break;
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => {
+      return;
+    });
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return { bytes, truncated };
+}
+function isTextContentType(contentType) {
+  if (!contentType)
+    return true;
+  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) {
+  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;
+  }
+  const base64 = Buffer.from(bytes).toString("base64");
+  const label = contentType ?? "application/octet-stream";
+  return `[base64-encoded ${label} response, ${bytes.length} bytes${truncated ? ", truncated" : ""}]
+${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.`);
+  }
+  return base;
+}
+function buildUrl(operation, args, baseUrl) {
+  let path = operation.path;
+  for (const param of operation.parameters) {
+    if (param.in !== "path")
+      continue;
+    path = path.replace(`{${param.name}}`, encodeURIComponent(serializeSimpleValue(args[param.argName])));
+  }
+  const url = new URL(trimTrailingSlash(baseUrl) + path);
+  for (const param of operation.parameters) {
+    if (param.in !== "query")
+      continue;
+    const value = args[param.argName];
+    if (value !== undefined)
+      appendQueryParam(url.searchParams, param.name, value);
+  }
+  return url;
+}
+function trimTrailingSlash(url) {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+function appendQueryParam(searchParams, name, value) {
+  if (Array.isArray(value)) {
+    for (const item of value)
+      searchParams.append(name, stringifyPrimitive(item));
+  } else if (value !== null && typeof value === "object") {
+    searchParams.append(name, JSON.stringify(value));
+  } else {
+    searchParams.append(name, stringifyPrimitive(value));
+  }
+}
+function serializeSimpleValue(value) {
+  if (value === undefined || value === null)
+    return "";
+  if (Array.isArray(value))
+    return value.map((item) => stringifyPrimitive(item)).join(",");
+  if (typeof value === "object") {
+    return Object.entries(value).map(([key, item]) => `${key},${stringifyPrimitive(item)}`).join(",");
+  }
+  return stringifyPrimitive(value);
+}
+function stringifyPrimitive(value) {
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  if (value === null || value === undefined)
+    return "";
+  return JSON.stringify(value);
+}
+function applyHeaderParams(operation, args, headers) {
+  for (const param of operation.parameters) {
+    if (param.in !== "header")
+      continue;
+    const value = args[param.argName];
+    if (value !== undefined)
+      headers.set(param.name, serializeSimpleValue(value));
+  }
+}
+function buildBody(operation, args, headers) {
+  const requestBody = operation.requestBody;
+  const value = args.requestBody;
+  if (!requestBody || value === undefined)
+    return;
+  switch (requestBody.encoding) {
+    case "json":
+      headers.set("Content-Type", "application/json");
+      return JSON.stringify(value);
+    case "form-urlencoded":
+      headers.set("Content-Type", "application/x-www-form-urlencoded");
+      return new URLSearchParams(flattenToStrings(value)).toString();
+    case "multipart":
+      return buildFormData(value, requestBody.schema);
+  }
+}
+function flattenToStrings(value) {
+  if (value === null || typeof value !== "object")
+    return {};
+  const result = {};
+  for (const [key, item] of Object.entries(value)) {
+    result[key] = stringifyPrimitive(item);
+  }
+  return result;
+}
+function buildFormData(value, schema) {
+  const form = new FormData;
+  if (value === null || typeof value !== "object")
+    return form;
+  const properties = schema.properties ?? {};
+  for (const [key, item] of Object.entries(value)) {
+    const format = properties[key]?.format;
+    if ((format === "binary" || format === "byte") && typeof item === "string") {
+      form.append(key, base64ToBlob(item));
+    } else if (Array.isArray(item)) {
+      for (const entry of item)
+        form.append(key, stringifyPrimitive(entry));
+    } else {
+      form.append(key, stringifyPrimitive(item));
+    }
+  }
+  return form;
+}
+function base64ToBlob(base64) {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0;i < binary.length; i += 1)
+    bytes[i] = binary.charCodeAt(i);
+  return new Blob([bytes]);
+}
+
+// src/openapi/schema.ts
+import { z } from "zod/v4";
+import { convertJsonSchemaToZod } from "zod-from-json-schema";
+function normalizeJsonSchema(schema) {
+  return normalizeNode(schema);
+}
+function normalizeNode(node) {
+  if (Array.isArray(node)) {
+    return node.map((item) => normalizeNode(item));
+  }
+  if (node === null || typeof node !== "object") {
+    return node;
+  }
+  const source = node;
+  const normalized = {};
+  for (const [key, value] of Object.entries(source)) {
+    normalized[key] = normalizeNode(value);
+  }
+  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"];
+    }
+  }
+  return normalized;
+}
+function toZodType(schema, options) {
+  const base = schema ? convertJsonSchemaToZod(normalizeJsonSchema(schema)) : z.unknown();
+  const described = options.description !== undefined ? base.describe(options.description) : base;
+  return options.required ? described : described.optional();
+}
+
+// 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);
+  }
+  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.",
+    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).")
+    },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+  }, (args) => {
+    const matches = searchOperations(index, args.query, args.limit ?? 10);
+    return { content: [{ type: "text", text: formatSearchResults(args.query, matches) }] };
+  });
+}
+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}":
+
+${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
+    }
+  }, async (args) => {
+    try {
+      const result = await executeOperation({
+        operation,
+        args,
+        auth,
+        baseUrlOverride: config.baseUrlOverride,
+        requestTimeoutMs: config.requestTimeoutMs
+      });
+      return { isError: !result.ok, content: [{ type: "text", text: formatResult(result) }] };
+    } catch (error) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Request failed: ${errorMessage(error)}` }]
+      };
+    }
+  });
+}
+function buildInputShape(operation) {
+  const shape = {};
+  for (const param of operation.parameters) {
+    shape[param.argName] = toZodType(param.schema, {
+      required: param.required,
+      ...param.description !== undefined && { description: param.description }
+    });
+  }
+  if (operation.requestBody) {
+    shape.requestBody = toZodType(operation.requestBody.schema, {
+      required: operation.requestBody.required,
+      ...operation.requestBody.description !== undefined && {
+        description: operation.requestBody.description
+      }
+    });
+  }
+  return shape;
+}
+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 formatResult(result) {
+  const header = `HTTP ${result.status} ${result.statusText}`;
+  return result.body.length > 0 ? `${header}
+
+${result.body}` : header;
+}
+
+// src/index.ts
+var LARGE_TOOL_COUNT_WARNING_THRESHOLD = 200;
+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 transport = new StdioServerTransport;
+  await server.connect(transport);
+}
+var isMainModule = process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1];
+if (isMainModule) {
+  main().catch((error) => {
+    console.error(`mcp-openapi: ${errorMessage(error)}`);
+    process.exit(1);
+  });
+}
+export {
+  main
+};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@avidian/mcp-openapi",
+  "version": "0.1.0",
+  "description": "MCP server for OpenAPI/Swagger — gives AI agents the ability to discover, search, and call any REST API described by an OpenAPI document.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-openapi": "dist/index.js"
+  },
+  "imports": {
+    "#*": "./src/*"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "bun --watch src/index.ts",
+    "start": "bun run dist/index.js",
+    "build": "bun scripts/build.ts",
+    "compile": "bun build src/index.ts --compile --outfile dist/mcp-openapi",
+    "compile:linux-x64": "bun build src/index.ts --compile --target=bun-linux-x64 --outfile dist/mcp-openapi-linux-x64",
+    "compile:macos-arm64": "bun build src/index.ts --compile --target=bun-darwin-arm64 --outfile dist/mcp-openapi-macos-arm64",
+    "compile:macos-x64": "bun build src/index.ts --compile --target=bun-darwin-x64 --outfile dist/mcp-openapi-macos-x64",
+    "compile:all": "bun run compile:linux-x64 && bun run compile:macos-arm64 && bun run compile:macos-x64",
+    "typecheck": "tsc -b",
+    "test": "bun test",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check": "bun run typecheck && bun run lint && bun run format:check && bun run test",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.0.1",
+    "ajv": "^8.17.1",
+    "eslint": "^10.6.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.7.0",
+    "openapi-types": "^12.1.3",
+    "prettier": "^3.9.4",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.1"
+  },
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "minisearch": "^7.2.0",
+    "zod": "^4.4.3",
+    "zod-from-json-schema": "^0.5.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "openapi",
+    "swagger",
+    "api",
+    "rest",
+    "ai",
+    "model-context-protocol",
+    "agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/avidianity/mcp-openapi.git"
+  },
+  "author": "avidian",
+  "publishConfig": {
+    "access": "public"
+  }
+}