@ceski23/openapi-mcp 1.0.0-beta.1

package/README.md

@@ -0,0 +1,40 @@
+# OpenApi MCP
+
+MCP server for loading and exploring OpenAPI/Swagger specifications. Lets AI assistants browse API contracts dynamically — load any OpenAPI spec, search endpoints, inspect schemas, and retrieve operations — without needing the spec in-context.
+
+## Usage
+
+### Manually
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "openapi-mcp": {
+      "command": "npx",
+      "args": ["-y", "@ceski23/openapi-mcp"]
+    }
+  }
+}
+```
+
+### Via AI agent
+
+Ask your AI assistant to add it:
+
+> Add the MCP server `@ceski23/openapi-mcp` to my config. Run it with `npx -y @ceski23/openapi-mcp` via stdio.
+
+Most assistants can modify your MCP config file directly.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `load_spec` | Load an OpenAPI/Swagger spec from a URL or file path. Returns a `specId` used by other tools. |
+| `find_operations` | Search operations by operationId, path, summary, tags, or description. |
+| `get_operation` | Get full details for a specific operation by operationId. |
+| `get_path` | Get all HTTP methods defined on a specific path. |
+| `find_schemas` | Search schema/definition names. |
+| `get_schema` | Get a fully dereferenced schema by name. |
+| `search_contract` | Search both operations and schemas in one call. |

package/dist/index.js

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/tools/load-spec.ts
+import { z } from "zod";
+import OASNormalize from "oas-normalize";
+import Oas from "oas";
+
+// src/cache.ts
+import { LRUCache } from "lru-cache";
+var specCache = new LRUCache({
+  max: 10,
+  ttl: 1000 * 60 * 60
+});
+function setSpec(id, spec) {
+  specCache.set(id, spec);
+}
+function getSpec(id) {
+  return specCache.get(id);
+}
+
+// src/utils.ts
+var MISSING_SPEC_RESPONSE = {
+  content: [
+    {
+      type: "text",
+      text: "Spec not found. The specId may be invalid or expired. Use load_spec to load a spec."
+    }
+  ],
+  isError: true
+};
+function* iteratePathItem(path, pathItem) {
+  if (pathItem.get)
+    yield { path, method: "GET", operation: pathItem.get };
+  if (pathItem.put)
+    yield { path, method: "PUT", operation: pathItem.put };
+  if (pathItem.post)
+    yield { path, method: "POST", operation: pathItem.post };
+  if (pathItem.delete)
+    yield { path, method: "DELETE", operation: pathItem.delete };
+  if (pathItem.options)
+    yield { path, method: "OPTIONS", operation: pathItem.options };
+  if (pathItem.head)
+    yield { path, method: "HEAD", operation: pathItem.head };
+  if (pathItem.patch)
+    yield { path, method: "PATCH", operation: pathItem.patch };
+  if (pathItem.trace)
+    yield { path, method: "TRACE", operation: pathItem.trace };
+}
+function* iterateOperations(spec) {
+  if (!spec.paths || typeof spec.paths !== "object")
+    return;
+  for (const path of Object.keys(spec.paths)) {
+    const pathItem = spec.paths[path];
+    if (!pathItem)
+      continue;
+    yield* iteratePathItem(path, pathItem);
+  }
+}
+var matchesQuery = (operation, path, lowercaseQuery) => (operation.operationId ?? "").toLowerCase().includes(lowercaseQuery) || path.toLowerCase().includes(lowercaseQuery) || (operation.summary ?? "").toLowerCase().includes(lowercaseQuery) || (operation.description ?? "").toLowerCase().includes(lowercaseQuery) || (operation.tags ?? []).join(" ").toLowerCase().includes(lowercaseQuery);
+var defineTool = (tool) => tool;
+
+// src/tools/load-spec.ts
+var loadSpec = defineTool({
+  name: "load_spec",
+  description: "Load and parse an OpenAPI/Swagger specification from a URL or local file path. Parses and validates the spec, returning a specId for use by other tools.",
+  inputSchema: z.object({
+    source: z.string().describe("URL or local file path to the OpenAPI/Swagger specification (JSON or YAML)")
+  }),
+  execute: async ({ source }) => {
+    try {
+      const normalizer = new OASNormalize(source, { enablePaths: true });
+      const converted = await normalizer.convert();
+      const oas = Oas.init(converted);
+      await oas.dereference();
+      const specId = crypto.randomUUID();
+      setSpec(specId, { oas });
+      const spec = oas.getDefinition();
+      const endpointCount = Object.keys(spec.paths ?? {}).length;
+      const schemaCount = Object.keys(spec.components?.schemas ?? {}).length;
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: true,
+              specId,
+              title: spec.info?.title,
+              version: spec.info?.version,
+              description: spec.info?.description,
+              endpoints: endpointCount,
+              schemas: schemaCount,
+              source
+            }, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Failed to load spec: ${error instanceof Error ? error.message : String(error)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+});
+
+// src/tools/find-operations.ts
+import { z as z2 } from "zod";
+var findOperations = defineTool({
+  name: "find_operations",
+  description: "Search for API operations in the loaded spec by matching against operationId, path, summary, tags, and descriptions. Use when you know approximately what you need but not the exact endpoint.",
+  inputSchema: z2.object({
+    specId: z2.string().describe("The spec ID returned by load_spec"),
+    query: z2.string().describe("Search query to match against operation names, paths, summaries, and tags")
+  }),
+  execute: ({ specId, query }) => {
+    const cached = getSpec(specId);
+    const spec = cached?.oas?.getDefinition();
+    if (!spec)
+      return MISSING_SPEC_RESPONSE;
+    const lowercaseQuery = query.toLowerCase();
+    const results = iterateOperations(spec).filter(({ path, operation }) => matchesQuery(operation, path, lowercaseQuery)).map(({ path, method, operation }) => ({
+      operationId: operation.operationId ?? "",
+      method,
+      path,
+      ...operation.summary ? { summary: operation.summary } : {}
+    })).toArray();
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+});
+
+// src/tools/get-operation.ts
+import { z as z3 } from "zod";
+var getOperation = defineTool({
+  name: "get_operation",
+  description: "Retrieve full details for a single API operation by operationId, including method, path, parameters, requestBody, and responses.",
+  inputSchema: z3.object({
+    specId: z3.string().describe("The spec ID returned by load_spec"),
+    operationId: z3.string().describe("The operationId of the endpoint to retrieve")
+  }),
+  execute: ({ specId, operationId }) => {
+    const cached = getSpec(specId);
+    const oas = cached?.oas;
+    if (!oas)
+      return MISSING_SPEC_RESPONSE;
+    const operation = oas.getOperationById(operationId);
+    if (!operation) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No operation found with operationId "${operationId}".`
+          }
+        ],
+        isError: true
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            method: operation.method.toUpperCase(),
+            path: operation.path,
+            ...operation.schema
+          }, null, 2)
+        }
+      ]
+    };
+  }
+});
+
+// src/tools/get-path.ts
+import { z as z4 } from "zod";
+var getPath = defineTool({
+  name: "get_path",
+  description: "Retrieve all operations (GET, POST, PATCH, DELETE, etc.) for a specific path. Use when you know the exact path and want the full contract for all methods on it.",
+  inputSchema: z4.object({
+    specId: z4.string().describe("The spec ID returned by load_spec"),
+    path: z4.string().describe("The exact path from the spec (e.g. /customers/{id})")
+  }),
+  execute: ({ specId, path }) => {
+    const cached = getSpec(specId);
+    const spec = cached?.oas?.getDefinition();
+    if (!spec)
+      return MISSING_SPEC_RESPONSE;
+    const pathItem = spec.paths?.[path];
+    if (!pathItem) {
+      return {
+        content: [
+          { type: "text", text: `No operations found for path "${path}".` }
+        ],
+        isError: true
+      };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(pathItem, null, 2) }]
+    };
+  }
+});
+
+// src/tools/find-schemas.ts
+import { z as z5 } from "zod";
+var findSchemas = defineTool({
+  name: "find_schemas",
+  description: "Search component/definition schema names in the loaded spec by matching against schema names. Use when you know approximately what a schema is called but not the exact name.",
+  inputSchema: z5.object({
+    specId: z5.string().describe("The spec ID returned by load_spec"),
+    query: z5.string().describe("Search query to match against schema/definition names")
+  }),
+  execute: ({ specId, query }) => {
+    const cached = getSpec(specId);
+    const spec = cached?.oas?.getDefinition();
+    if (!spec)
+      return MISSING_SPEC_RESPONSE;
+    const schemas = spec.components?.schemas;
+    const keys = Object.keys(schemas ?? {});
+    const lowercaseQuery = query.toLowerCase();
+    const results = keys.filter((name) => name.toLowerCase().includes(lowercaseQuery)).toSorted();
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+    };
+  }
+});
+
+// src/tools/get-schema.ts
+import { z as z6 } from "zod";
+var getSchema = defineTool({
+  name: "get_schema",
+  description: "Retrieve a fully dereferenced component/definition schema by name. Use when you need the full structure of a specific schema.",
+  inputSchema: z6.object({
+    specId: z6.string().describe("The spec ID returned by load_spec"),
+    name: z6.string().describe("The schema/definition name (case-sensitive, e.g. Invoice)")
+  }),
+  execute: ({ specId, name }) => {
+    const cached = getSpec(specId);
+    const spec = cached?.oas?.getDefinition();
+    if (!spec)
+      return MISSING_SPEC_RESPONSE;
+    const schema = spec.components?.schemas?.[name];
+    if (!schema) {
+      return {
+        content: [{ type: "text", text: `No schema found with name "${name}".` }],
+        isError: true
+      };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(schema, null, 2) }]
+    };
+  }
+});
+
+// src/tools/search-contract.ts
+import { z as z7 } from "zod";
+var searchContract = defineTool({
+  name: "search_contract",
+  description: "Search across the entire API contract — operations and schemas — by matching against operationIds, summaries, tags, paths, schema names, and schema descriptions. The best first call when exploring an API.",
+  inputSchema: z7.object({
+    specId: z7.string().describe("The spec ID returned by load_spec"),
+    query: z7.string().describe("Search query to match against operationIds, summaries, tags, paths, schema names, and schema descriptions")
+  }),
+  execute: ({ specId, query }) => {
+    const cached = getSpec(specId);
+    const spec = cached?.oas?.getDefinition();
+    if (!spec)
+      return MISSING_SPEC_RESPONSE;
+    const lowercaseQuery = query.toLowerCase();
+    const operations = iterateOperations(spec).filter(({ path, operation }) => matchesQuery(operation, path, lowercaseQuery)).map(({ path, method, operation }) => ({
+      operationId: operation.operationId ?? "",
+      method,
+      path,
+      ...operation.summary ? { summary: operation.summary } : {}
+    })).toArray();
+    const schemas = Object.keys(spec.components?.schemas ?? {}).filter((name) => {
+      const schema = spec.components?.schemas?.[name];
+      if (!schema)
+        return false;
+      if ("$ref" in schema)
+        return false;
+      return name.toLowerCase().includes(lowercaseQuery) || (schema.description ?? "").toLowerCase().includes(lowercaseQuery);
+    }).toSorted();
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            ...operations.length > 0 ? { operations } : {},
+            ...schemas.length > 0 ? { schemas } : {}
+          }, null, 2)
+        }
+      ]
+    };
+  }
+});
+
+// src/index.ts
+var server = new McpServer({
+  name: "openapi-mcp",
+  version: "0.1.0"
+});
+for (const { name, description, inputSchema, execute } of [
+  loadSpec,
+  findOperations,
+  getOperation,
+  getPath,
+  findSchemas,
+  getSchema,
+  searchContract
+]) {
+  server.registerTool(name, { description, inputSchema }, execute);
+}
+var transport = new StdioServerTransport;
+await server.connect(transport);

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "@ceski23/openapi-mcp",
+    "version": "1.0.0-beta.1",
+    "license": "MIT",
+    "author": "Cezary Bober",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ceski23/openapi-mcp.git"
+    },
+    "bin": {
+        "openapi-mcp": "./dist/index.js"
+    },
+    "files": [
+        "dist/"
+    ],
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "lint": "oxlint",
+        "format": "oxfmt",
+        "check": "bun run lint && bun run format --check",
+        "typecheck": "bun run tsc --noEmit",
+        "build": "bun build src/index.ts --target=node --outdir=dist --packages=external",
+        "prepublishOnly": "bun run build",
+        "test": "bun test",
+        "check:config": "publint"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "1.29.0",
+        "lru-cache": "11.5.1",
+        "oas": "36.0.3",
+        "oas-normalize": "16.0.5",
+        "zod": "4.4.3"
+    },
+    "devDependencies": {
+        "@semantic-release/changelog": "6.0.3",
+        "@semantic-release/git": "10.0.1",
+        "@types/bun": "latest",
+        "oxfmt": "0.56.0",
+        "oxlint": "1.71.0",
+        "publint": "0.3.21",
+        "typescript": "6.0.3"
+    },
+    "engines": {
+        "bun": ">=1.0.0",
+        "node": ">=22"
+    }
+}