@emreyc/swagger-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emre Colakoglu
+
+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,68 @@
+# swagger-mcp
+
+A read-only [Model Context Protocol](https://modelcontextprotocol.io) server for
+**navigating** an OpenAPI / Swagger specification. It gives a coding agent tools
+to explore a large API's documentation — search endpoints, read parameters and
+schemas, inspect auth — without dumping the whole spec into context.
+
+It **never calls the described API.** It only reads its documentation.
+
+Works with any MCP-capable harness (Claude Code, Cursor, Cline, Windsurf,
+Zed, opencode, …) over stdio.
+
+## Usage
+
+Add it to your MCP client config. No install step — `npx` fetches it on demand:
+
+```json
+{
+  "mcpServers": {
+    "swagger-mcp": {
+      "command": "npx",
+      "args": ["-y", "@emreyc/swagger-mcp@latest"],
+      "env": {
+        "API_DOCS_URL": "https://api.example.com/swagger.json"
+      }
+    }
+  }
+}
+```
+
+`API_DOCS_URL` is the only configuration — a URL (or local path) to a Swagger 2.0
+or OpenAPI 3.x document. Internal/localhost URLs (e.g. Spring Boot's
+`http://localhost:8080/v3/api-docs`) are supported.
+
+## Tools
+
+Designed for progressive disclosure — orient, then discover, then drill down —
+so the agent loads only what it needs.
+
+| Tool | Purpose |
+| --- | --- |
+| `get_api_overview` | Title, version, servers, global security, counts. Start here. |
+| `list_tags` | Tags (logical groups) with endpoint counts. |
+| `list_endpoints` | Compact index of endpoints; optional `tag` filter. |
+| `search_endpoints` | Substring search over path/summary/description/params. |
+| `list_schemas` | Named schemas with one-line descriptions. |
+| `search_schemas` | Substring search over schema names, fields, descriptions. |
+| `get_endpoint` | Full detail for one `method`+`path`: params, request/response schemas, auth. |
+| `get_schema` | Resolve one named schema. |
+| `get_auth` | Security schemes in full (OAuth2 flows, scopes, API-key locations). |
+
+Swagger 2.0 and OpenAPI 3.x are normalized into one consistent output shape.
+Nested named schemas are shown as `{ "$schema": "Name" }` markers — call
+`get_schema` to expand them. This keeps every response bounded and is safe with
+circular schemas.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,649 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// src/spec/loader.ts
+import SwaggerParser from "@apidevtools/swagger-parser";
+
+// src/spec/normalize.ts
+var HTTP_METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace"
+];
+function isOpenApi3(spec) {
+  return typeof spec.openapi === "string" && spec.openapi.startsWith("3.");
+}
+function schemaFromV2Param(param) {
+  const keys = [
+    "type",
+    "format",
+    "enum",
+    "items",
+    "default",
+    "minimum",
+    "maximum",
+    "minLength",
+    "maxLength",
+    "pattern",
+    "collectionFormat"
+  ];
+  const schema = {};
+  for (const key of keys) {
+    if (param[key] !== void 0) schema[key] = param[key];
+  }
+  return schema;
+}
+function normalizeInfo(spec) {
+  const info = spec.info ?? {};
+  const externalDocs = spec.externalDocs ? { url: spec.externalDocs.url, description: spec.externalDocs.description } : void 0;
+  return {
+    title: info.title ?? "(untitled)",
+    version: info.version ?? "(unversioned)",
+    description: info.description,
+    externalDocs
+  };
+}
+function normalizeServers(spec, v3) {
+  if (v3) {
+    const servers = Array.isArray(spec.servers) ? spec.servers : [];
+    return servers.map((s) => s.url).filter((u) => typeof u === "string");
+  }
+  if (typeof spec.host !== "string" || spec.host.length === 0) return [];
+  const schemes = Array.isArray(spec.schemes) && spec.schemes.length ? spec.schemes : ["https"];
+  const basePath = typeof spec.basePath === "string" ? spec.basePath : "";
+  return schemes.map((scheme) => `${scheme}://${spec.host}${basePath}`);
+}
+function normalizeSecuritySchemes(spec, v3) {
+  const source = v3 ? spec.components?.securitySchemes ?? {} : spec.securityDefinitions ?? {};
+  return Object.entries(source).map(([name, raw]) => {
+    const scheme = raw;
+    return {
+      name,
+      type: scheme.type ?? "unknown",
+      description: scheme.description,
+      raw: scheme
+    };
+  });
+}
+function normalizeParams(raw, v3) {
+  const params = [];
+  let v2Body;
+  const v2FormData = [];
+  for (const p of raw) {
+    if (!v3 && p.in === "body") {
+      v2Body = p;
+      continue;
+    }
+    if (!v3 && p.in === "formData") {
+      v2FormData.push(p);
+      continue;
+    }
+    params.push({
+      name: p.name,
+      in: p.in,
+      required: p.required ?? p.in === "path",
+      description: p.description,
+      deprecated: p.deprecated,
+      schema: v3 ? p.schema ?? {} : schemaFromV2Param(p)
+    });
+  }
+  return { params, v2Body, v2FormData };
+}
+function normalizeRequestBody(operation, v3, v2Body, v2FormData) {
+  if (v3) {
+    const rb = operation.requestBody;
+    if (!rb) return void 0;
+    const content = {};
+    for (const [mediaType, media] of Object.entries(rb.content ?? {})) {
+      content[mediaType] = media.schema ?? {};
+    }
+    return {
+      description: rb.description,
+      required: rb.required ?? false,
+      content
+    };
+  }
+  if (v2Body) {
+    const mediaType = (operation.consumes ?? [])[0] ?? "application/json";
+    return {
+      description: v2Body.description,
+      required: v2Body.required ?? false,
+      content: { [mediaType]: v2Body.schema ?? {} }
+    };
+  }
+  if (v2FormData.length > 0) {
+    const properties = {};
+    const required = [];
+    for (const p of v2FormData) {
+      properties[p.name] = schemaFromV2Param(p);
+      if (p.required) required.push(p.name);
+    }
+    const mediaType = (operation.consumes ?? [])[0] ?? "application/x-www-form-urlencoded";
+    const schema = { type: "object", properties };
+    if (required.length) schema.required = required;
+    return { required: required.length > 0, content: { [mediaType]: schema } };
+  }
+  return void 0;
+}
+function normalizeResponses(operation, v3) {
+  const responses = operation.responses ?? {};
+  return Object.entries(responses).map(([status, raw]) => {
+    const res = raw;
+    let content;
+    if (v3 && res.content) {
+      content = {};
+      for (const [mediaType, media] of Object.entries(res.content)) {
+        content[mediaType] = media.schema ?? {};
+      }
+    } else if (!v3 && res.schema) {
+      const mediaType = (operation.produces ?? [])[0] ?? "application/json";
+      content = { [mediaType]: res.schema };
+    }
+    return { status, description: res.description, content };
+  });
+}
+function mergeParams(pathParams, opParams) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const p of pathParams) byKey.set(`${p.in}:${p.name}`, p);
+  for (const p of opParams) byKey.set(`${p.in}:${p.name}`, p);
+  return [...byKey.values()];
+}
+function normalizeSpec(raw) {
+  const spec = raw;
+  const v3 = isOpenApi3(spec);
+  const schemas = v3 ? spec.components?.schemas ?? {} : spec.definitions ?? {};
+  const globalSecurity = Array.isArray(spec.security) ? spec.security : [];
+  const endpoints = [];
+  const paths = spec.paths ?? {};
+  for (const [path, pathItemRaw] of Object.entries(paths)) {
+    const pathItem = pathItemRaw;
+    const pathParams = Array.isArray(pathItem.parameters) ? pathItem.parameters : [];
+    for (const method of HTTP_METHODS) {
+      const operation = pathItem[method];
+      if (!operation) continue;
+      const merged = mergeParams(
+        pathParams,
+        Array.isArray(operation.parameters) ? operation.parameters : []
+      );
+      const { params, v2Body, v2FormData } = normalizeParams(merged, v3);
+      endpoints.push({
+        method: method.toUpperCase(),
+        path,
+        operationId: operation.operationId,
+        summary: operation.summary,
+        description: operation.description,
+        tags: Array.isArray(operation.tags) ? operation.tags : [],
+        deprecated: operation.deprecated ?? false,
+        parameters: params,
+        requestBody: normalizeRequestBody(operation, v3, v2Body, v2FormData),
+        responses: normalizeResponses(operation, v3),
+        security: Array.isArray(operation.security) ? operation.security : void 0
+      });
+    }
+  }
+  const tags = normalizeTags(spec, endpoints);
+  return {
+    sourceVersion: v3 ? spec.openapi : spec.swagger ?? "2.0",
+    info: normalizeInfo(spec),
+    servers: normalizeServers(spec, v3),
+    globalSecurity,
+    securitySchemes: normalizeSecuritySchemes(spec, v3),
+    tags,
+    endpoints,
+    schemas
+  };
+}
+function normalizeTags(spec, endpoints) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const ep of endpoints) {
+    for (const tag of ep.tags) counts.set(tag, (counts.get(tag) ?? 0) + 1);
+  }
+  const declared = (Array.isArray(spec.tags) ? spec.tags : []).map((t) => ({
+    name: t.name,
+    description: t.description,
+    endpointCount: counts.get(t.name) ?? 0
+  }));
+  const declaredNames = new Set(declared.map((t) => t.name));
+  const undeclared = [...counts.keys()].filter((name) => !declaredNames.has(name)).map((name) => ({ name, endpointCount: counts.get(name) ?? 0 }));
+  return [...declared, ...undeclared];
+}
+
+// src/spec/loader.ts
+var SpecLoadError = class extends Error {
+};
+var cache;
+async function fetchAndNormalize(docsUrl) {
+  let bundled;
+  try {
+    bundled = await SwaggerParser.bundle(docsUrl, {
+      resolve: { http: { safeUrlResolver: false } }
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new SpecLoadError(
+      `Failed to load API spec from ${docsUrl}: ${reason}`
+    );
+  }
+  return normalizeSpec(bundled);
+}
+function loadSpec(docsUrl) {
+  if (!cache) {
+    cache = fetchAndNormalize(docsUrl).catch((err) => {
+      cache = void 0;
+      throw err;
+    });
+  }
+  return cache;
+}
+
+// src/format.ts
+var REF_PREFIXES = ["#/definitions/", "#/components/schemas/"];
+function refName(node) {
+  if (!node || typeof node !== "object") return void 0;
+  const ref = node.$ref;
+  if (typeof ref !== "string") return void 0;
+  for (const prefix of REF_PREFIXES) {
+    if (ref.startsWith(prefix)) return ref.slice(prefix.length);
+  }
+  const parts = ref.split("/");
+  return parts[parts.length - 1];
+}
+function resolveShallow(node, schemas, remaining) {
+  if (Array.isArray(node)) {
+    return node.map((n) => resolveShallow(n, schemas, remaining));
+  }
+  if (node && typeof node === "object") {
+    const name = refName(node);
+    if (name !== void 0) {
+      if (remaining <= 0 || schemas[name] === void 0) {
+        return { $schema: name };
+      }
+      return resolveShallow(schemas[name], schemas, remaining - 1);
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+      out[key] = resolveShallow(value, schemas, remaining);
+    }
+    return out;
+  }
+  return node;
+}
+function fence(value) {
+  return "```json\n" + JSON.stringify(value, null, 2) + "\n```";
+}
+function shortType(schema, schemas) {
+  if (!schema) return "\u2014";
+  const name = refName(schema);
+  if (name) return name;
+  if (typeof schema.$schema === "string") return schema.$schema;
+  if (schema.type === "array") {
+    return `${shortType(schema.items, schemas)}[]`;
+  }
+  if (typeof schema.type === "string") return schema.type;
+  if (schema.properties) return "object";
+  return "\u2014";
+}
+function endpointLine(ep) {
+  const summary = ep.summary ? ` \u2014 ${ep.summary}` : "";
+  const tags = ep.tags.length ? ` [${ep.tags.join(", ")}]` : "";
+  const deprecated = ep.deprecated ? " (deprecated)" : "";
+  return `${ep.method} ${ep.path}${summary}${tags}${deprecated}`;
+}
+function paramTable(params, schemas) {
+  if (params.length === 0) return "";
+  const rows = params.map((p) => {
+    const desc = (p.description ?? "").replace(/\n/g, " ");
+    return `| ${p.name} | ${p.in} | ${p.required ? "yes" : "no"} | ${shortType(p.schema, schemas)} | ${desc} |`;
+  });
+  return [
+    "**Parameters**",
+    "",
+    "| Name | In | Required | Type | Description |",
+    "| --- | --- | --- | --- | --- |",
+    ...rows
+  ].join("\n");
+}
+function securityLines(requirements) {
+  if (!requirements || requirements.length === 0) return "";
+  const parts = requirements.map(
+    (req) => Object.entries(req).map(
+      ([name, scopes]) => scopes.length ? `${name} (${scopes.join(", ")})` : name
+    ).join(" + ")
+  );
+  return `**Security:** ${parts.join(" OR ")}`;
+}
+function endpointDetail(ep, spec) {
+  const sections = [];
+  sections.push(`# ${ep.method} ${ep.path}`);
+  const meta = [];
+  if (ep.operationId) meta.push(`operationId: \`${ep.operationId}\``);
+  if (ep.tags.length) meta.push(`tags: ${ep.tags.join(", ")}`);
+  if (ep.deprecated) meta.push("**deprecated**");
+  if (meta.length) sections.push(meta.join(" \xB7 "));
+  if (ep.summary) sections.push(ep.summary);
+  if (ep.description) sections.push(ep.description);
+  const security = securityLines(ep.security ?? spec.globalSecurity);
+  if (security) sections.push(security);
+  const table = paramTable(ep.parameters, spec.schemas);
+  if (table) sections.push(table);
+  if (ep.requestBody) {
+    const rb = ep.requestBody;
+    const lines = [`**Request body**${rb.required ? " (required)" : ""}`];
+    if (rb.description) lines.push(rb.description);
+    for (const [mediaType, schema] of Object.entries(rb.content)) {
+      lines.push(`
+_${mediaType}_`);
+      lines.push(fence(resolveShallow(schema, spec.schemas, 1)));
+    }
+    sections.push(lines.join("\n"));
+  }
+  if (ep.responses.length) {
+    const lines = ["**Responses**"];
+    for (const res of ep.responses) {
+      const desc = res.description ? ` \u2014 ${res.description}` : "";
+      lines.push(`
+_${res.status}${desc}_`);
+      if (res.content) {
+        for (const [mediaType, schema] of Object.entries(res.content)) {
+          lines.push(`${mediaType}:`);
+          lines.push(fence(resolveShallow(schema, spec.schemas, 1)));
+        }
+      }
+    }
+    sections.push(lines.join("\n"));
+  }
+  return sections.join("\n\n");
+}
+function schemaLine(name, schema) {
+  const desc = typeof schema.description === "string" ? ` \u2014 ${schema.description.replace(/\n/g, " ")}` : "";
+  return `${name}${desc}`;
+}
+function schemaDetail(name, schemas) {
+  const resolved = resolveShallow(schemas[name], schemas, 0);
+  return `# ${name}
+
+${fence(resolved)}`;
+}
+function overview(spec) {
+  const sections = [];
+  sections.push(`# ${spec.info.title} (v${spec.info.version})`);
+  sections.push(`Spec version: ${spec.sourceVersion}`);
+  if (spec.info.description) sections.push(spec.info.description);
+  if (spec.servers.length) {
+    sections.push(
+      `**Servers**
+${spec.servers.map((s) => `- ${s}`).join("\n")}`
+    );
+  }
+  const security = securityLines(spec.globalSecurity);
+  if (security) sections.push(`${security} _(global default)_`);
+  if (spec.securitySchemes.length) {
+    sections.push(
+      `**Security schemes:** ${spec.securitySchemes.map((s) => `${s.name} (${s.type})`).join(", ")}`
+    );
+  }
+  if (spec.info.externalDocs) {
+    const d = spec.info.externalDocs;
+    sections.push(`**External docs:** ${d.description ?? ""} ${d.url}`.trim());
+  }
+  sections.push(
+    `**Counts:** ${spec.endpoints.length} endpoints \xB7 ${spec.tags.length} tags \xB7 ${Object.keys(spec.schemas).length} schemas`
+  );
+  return sections.join("\n\n");
+}
+function authDetail(scheme) {
+  const header = `## ${scheme.name} (${scheme.type})`;
+  const desc = scheme.description ? `
+
+${scheme.description}` : "";
+  return `${header}${desc}
+
+${fence(scheme.raw)}`;
+}
+
+// src/search.ts
+function has(haystack, needle) {
+  return typeof haystack === "string" && haystack.toLowerCase().includes(needle);
+}
+function searchEndpoints(spec, query) {
+  const q = query.toLowerCase();
+  const scored = [];
+  for (const ep of spec.endpoints) {
+    let score = 0;
+    if (has(ep.path, q) || has(ep.operationId, q)) score = Math.max(score, 4);
+    if (has(ep.summary, q)) score = Math.max(score, 3);
+    if (ep.tags.some((t) => has(t, q))) score = Math.max(score, 2);
+    if (has(ep.description, q)) score = Math.max(score, 2);
+    if (ep.parameters.some((p) => has(p.name, q))) score = Math.max(score, 1);
+    if (score > 0) scored.push({ ep, score });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.map((s) => s.ep);
+}
+function searchSchemas(spec, query) {
+  const q = query.toLowerCase();
+  const scored = [];
+  for (const [name, schema] of Object.entries(spec.schemas)) {
+    let score = 0;
+    if (has(name, q)) score = Math.max(score, 3);
+    const props = schema.properties && typeof schema.properties === "object" ? Object.keys(schema.properties) : [];
+    if (props.some((p) => p.toLowerCase().includes(q))) score = Math.max(score, 2);
+    if (has(schema.description, q)) {
+      score = Math.max(score, 1);
+    }
+    if (score > 0) scored.push({ name, schema, score });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.map((s) => ({ name: s.name, schema: s.schema }));
+}
+
+// src/server.ts
+var ok = (text) => ({ content: [{ type: "text", text }] });
+var fail = (text) => ({
+  content: [{ type: "text", text }],
+  isError: true
+});
+var readOnly = { readOnlyHint: true, openWorldHint: false };
+function findEndpoint(spec, method, path) {
+  const m = method.toUpperCase();
+  return spec.endpoints.find((ep) => ep.method === m && ep.path === path);
+}
+function createServer(docsUrl) {
+  const server = new McpServer({
+    name: "swagger-mcp",
+    version: "0.1.0"
+  });
+  const withSpec = (handler) => async () => {
+    try {
+      return handler(await loadSpec(docsUrl));
+    } catch (err) {
+      return fail(err instanceof Error ? err.message : String(err));
+    }
+  };
+  const withSpecArgs = (handler) => async (args) => {
+    try {
+      return handler(await loadSpec(docsUrl), args);
+    } catch (err) {
+      return fail(err instanceof Error ? err.message : String(err));
+    }
+  };
+  server.registerTool(
+    "get_api_overview",
+    {
+      title: "API overview",
+      description: "Top-level API metadata: title, version, description, servers, global security, and counts. Start here on an unfamiliar API.",
+      inputSchema: {},
+      annotations: readOnly
+    },
+    withSpec((spec) => ok(overview(spec)))
+  );
+  server.registerTool(
+    "list_tags",
+    {
+      title: "List tags",
+      description: "List the API's tags (logical groups) with descriptions and endpoint counts.",
+      inputSchema: {},
+      annotations: readOnly
+    },
+    withSpec((spec) => {
+      if (spec.tags.length === 0) return ok("No tags declared in this spec.");
+      const lines = spec.tags.map(
+        (t) => `${t.name} (${t.endpointCount})${t.description ? ` \u2014 ${t.description}` : ""}`
+      );
+      return ok(lines.join("\n"));
+    })
+  );
+  server.registerTool(
+    "list_endpoints",
+    {
+      title: "List endpoints",
+      description: "Compact index of endpoints (method, path, summary, tags). Optionally filter by tag.",
+      inputSchema: {
+        tag: z.string().optional().describe("Only list endpoints with this tag.")
+      },
+      annotations: readOnly
+    },
+    withSpecArgs((spec, { tag }) => {
+      let endpoints = spec.endpoints;
+      if (tag) endpoints = endpoints.filter((ep) => ep.tags.includes(tag));
+      if (endpoints.length === 0) {
+        return ok(tag ? `No endpoints with tag "${tag}".` : "No endpoints found.");
+      }
+      return ok(endpoints.map(endpointLine).join("\n"));
+    })
+  );
+  server.registerTool(
+    "search_endpoints",
+    {
+      title: "Search endpoints",
+      description: "Substring search over endpoint path, summary, description, tags, and parameter names. Returns matches ranked by relevance.",
+      inputSchema: {
+        query: z.string().describe("Case-insensitive substring to match.")
+      },
+      annotations: readOnly
+    },
+    withSpecArgs((spec, { query }) => {
+      const matches = searchEndpoints(spec, query);
+      if (matches.length === 0) return ok(`No endpoints match "${query}".`);
+      return ok(matches.map(endpointLine).join("\n"));
+    })
+  );
+  server.registerTool(
+    "list_schemas",
+    {
+      title: "List schemas",
+      description: "List named component/definition schemas with one-line descriptions.",
+      inputSchema: {},
+      annotations: readOnly
+    },
+    withSpec((spec) => {
+      const names = Object.keys(spec.schemas);
+      if (names.length === 0) return ok("No named schemas in this spec.");
+      const lines = names.map((n) => schemaLine(n, spec.schemas[n]));
+      return ok(lines.join("\n"));
+    })
+  );
+  server.registerTool(
+    "search_schemas",
+    {
+      title: "Search schemas",
+      description: "Substring search over schema names, property names, and descriptions. Returns matches ranked by relevance.",
+      inputSchema: {
+        query: z.string().describe("Case-insensitive substring to match.")
+      },
+      annotations: readOnly
+    },
+    withSpecArgs((spec, { query }) => {
+      const matches = searchSchemas(spec, query);
+      if (matches.length === 0) return ok(`No schemas match "${query}".`);
+      return ok(matches.map((m) => schemaLine(m.name, m.schema)).join("\n"));
+    })
+  );
+  server.registerTool(
+    "get_endpoint",
+    {
+      title: "Get endpoint",
+      description: "Full detail for one endpoint: parameters, request/response schemas, and required auth. Named schemas are shown by name \u2014 resolve them with get_schema.",
+      inputSchema: {
+        method: z.string().describe("HTTP method, e.g. GET, POST."),
+        path: z.string().describe("Exact path as it appears in the spec, e.g. /pets/{id}.")
+      },
+      annotations: readOnly
+    },
+    withSpecArgs((spec, { method, path }) => {
+      const ep = findEndpoint(spec, method, path);
+      if (!ep) {
+        return fail(
+          `No endpoint ${method.toUpperCase()} ${path}. Call list_endpoints to see available paths.`
+        );
+      }
+      return ok(endpointDetail(ep, spec));
+    })
+  );
+  server.registerTool(
+    "get_schema",
+    {
+      title: "Get schema",
+      description: 'Resolve one named schema. Nested named schemas are shown as { "$schema": "Name" } markers \u2014 call get_schema again to expand them.',
+      inputSchema: {
+        name: z.string().describe("Schema name as shown by list_schemas.")
+      },
+      annotations: readOnly
+    },
+    withSpecArgs((spec, { name }) => {
+      if (spec.schemas[name] === void 0) {
+        return fail(
+          `No schema named "${name}". Call list_schemas to see available schemas.`
+        );
+      }
+      return ok(schemaDetail(name, spec.schemas));
+    })
+  );
+  server.registerTool(
+    "get_auth",
+    {
+      title: "Get auth",
+      description: "Full security schemes for the API (OAuth2 flows, scopes, API-key locations) plus the global security requirement.",
+      inputSchema: {},
+      annotations: readOnly
+    },
+    withSpec((spec) => {
+      if (spec.securitySchemes.length === 0) {
+        return ok("This spec declares no security schemes.");
+      }
+      const parts = spec.securitySchemes.map(authDetail);
+      return ok(`# Security schemes
+
+${parts.join("\n\n")}`);
+    })
+  );
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  const docsUrl = process.env.API_DOCS_URL;
+  if (!docsUrl) {
+    console.error("swagger-mcp: API_DOCS_URL environment variable is required.");
+    process.exit(1);
+  }
+  const server = createServer(docsUrl);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("swagger-mcp: ready (stdio).");
+}
+main().catch((err) => {
+  console.error("swagger-mcp: fatal error:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@emreyc/swagger-mcp",
+  "version": "0.1.0",
+  "description": "Read-only MCP server for navigating OpenAPI/Swagger specifications.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "openapi",
+    "swagger",
+    "api-docs"
+  ],
+  "type": "module",
+  "bin": {
+    "swagger-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "openapi-types": "^12.1.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.10"
+  }
+}