@emreyc/swagger-mcp 0.1.1 → 0.2.0

package/README.md

@@ -19,19 +19,34 @@ Add it to your MCP client config. No install step — `npx` fetches it on demand
   "mcpServers": {
     "swagger-mcp": {
       "command": "npx",
-      "args": ["-y", "@emreyc/swagger-mcp@latest"],
-      "env": {
-        "API_DOCS_URL": "https://api.example.com/swagger.json"
-      }
+      "args": ["-y", "@emreyc/swagger-mcp@latest"]
     }
   }
 }
 ```
 
-`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
+Every tool takes a `spec` parameter — a URL (or local path) to a Swagger 2.0 or
+OpenAPI 3.x document — so a single server can navigate any number of specs in one
+session. Internal/localhost URLs (e.g. Spring Boot's
 `http://localhost:8080/v3/api-docs`) are supported.
 
+If you mostly work with one spec, set `API_DOCS_URL` as a default so `spec` can be
+omitted:
+
+```json
+{
+  "mcpServers": {
+    "swagger-mcp": {
+      "command": "npx",
+      "args": ["-y", "@emreyc/swagger-mcp@latest"],
+      "env": { "API_DOCS_URL": "https://api.example.com/swagger.json" }
+    }
+  }
+}
+```
+
+Specs are fetched lazily and cached per URL for the process lifetime.
+
 ## Tools
 
 Designed for progressive disclosure — orient, then discover, then drill down —
@@ -49,6 +64,9 @@ so the agent loads only what it needs.
 | `get_schema` | Resolve one named schema. |
 | `get_auth` | Security schemes in full (OAuth2 flows, scopes, API-key locations). |
 
+Every tool also accepts an optional `spec` argument (a spec URL or path); when
+omitted it falls back to `API_DOCS_URL`.
+
 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

package/dist/index.js

@@ -222,7 +222,7 @@ function normalizeTags(spec, endpoints) {
 // src/spec/loader.ts
 var SpecLoadError = class extends Error {
 };
-var cache;
+var cache = /* @__PURE__ */ new Map();
 async function fetchAndNormalize(docsUrl) {
   let bundled;
   try {
@@ -238,13 +238,15 @@ async function fetchAndNormalize(docsUrl) {
   return normalizeSpec(bundled);
 }
 function loadSpec(docsUrl) {
-  if (!cache) {
-    cache = fetchAndNormalize(docsUrl).catch((err) => {
-      cache = void 0;
+  let entry = cache.get(docsUrl);
+  if (!entry) {
+    entry = fetchAndNormalize(docsUrl).catch((err) => {
+      cache.delete(docsUrl);
       throw err;
     });
+    cache.set(docsUrl, entry);
   }
-  return cache;
+  return entry;
 }
 
 // src/format.ts
@@ -459,21 +461,26 @@ function findEndpoint(spec, method, path) {
   const m = method.toUpperCase();
   return spec.endpoints.find((ep) => ep.method === m && ep.path === path);
 }
-function createServer(docsUrl) {
+function createServer(defaultDocsUrl) {
   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 specParam = z.string().optional().describe(
+    defaultDocsUrl ? "URL or local path of the OpenAPI/Swagger spec. Defaults to the server's configured API_DOCS_URL." : "URL or local path of the OpenAPI/Swagger spec to read."
+  );
+  function resolveUrl(spec) {
+    const url = spec ?? defaultDocsUrl;
+    if (!url) {
+      throw new Error(
+        "No spec specified. Pass `spec` (an OpenAPI/Swagger URL or path), or set API_DOCS_URL when launching the server."
+      );
     }
-  };
-  const withSpecArgs = (handler) => async (args) => {
+    return url;
+  }
+  const tool = (handler) => async (args) => {
     try {
-      return handler(await loadSpec(docsUrl), args);
+      return handler(await loadSpec(resolveUrl(args.spec)), args);
     } catch (err) {
       return fail(err instanceof Error ? err.message : String(err));
     }
@@ -483,20 +490,20 @@ function createServer(docsUrl) {
     {
       title: "API overview",
       description: "Top-level API metadata: title, version, description, servers, global security, and counts. Start here on an unfamiliar API.",
-      inputSchema: {},
+      inputSchema: { spec: specParam },
       annotations: readOnly
     },
-    withSpec((spec) => ok(overview(spec)))
+    tool((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: {},
+      inputSchema: { spec: specParam },
       annotations: readOnly
     },
-    withSpec((spec) => {
+    tool((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}` : ""}`
@@ -510,11 +517,12 @@ function createServer(docsUrl) {
       title: "List endpoints",
       description: "Compact index of endpoints (method, path, summary, tags). Optionally filter by tag.",
       inputSchema: {
+        spec: specParam,
         tag: z.string().optional().describe("Only list endpoints with this tag.")
       },
       annotations: readOnly
     },
-    withSpecArgs((spec, { tag }) => {
+    tool((spec, { tag }) => {
       let endpoints = spec.endpoints;
       if (tag) endpoints = endpoints.filter((ep) => ep.tags.includes(tag));
       if (endpoints.length === 0) {
@@ -529,11 +537,12 @@ function createServer(docsUrl) {
       title: "Search endpoints",
       description: "Substring search over endpoint path, summary, description, tags, and parameter names. Returns matches ranked by relevance.",
       inputSchema: {
+        spec: specParam,
         query: z.string().describe("Case-insensitive substring to match.")
       },
       annotations: readOnly
     },
-    withSpecArgs((spec, { query }) => {
+    tool((spec, { query }) => {
       const matches = searchEndpoints(spec, query);
       if (matches.length === 0) return ok(`No endpoints match "${query}".`);
       return ok(matches.map(endpointLine).join("\n"));
@@ -544,10 +553,10 @@ function createServer(docsUrl) {
     {
       title: "List schemas",
       description: "List named component/definition schemas with one-line descriptions.",
-      inputSchema: {},
+      inputSchema: { spec: specParam },
       annotations: readOnly
     },
-    withSpec((spec) => {
+    tool((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]));
@@ -560,11 +569,12 @@ function createServer(docsUrl) {
       title: "Search schemas",
       description: "Substring search over schema names, property names, and descriptions. Returns matches ranked by relevance.",
       inputSchema: {
+        spec: specParam,
         query: z.string().describe("Case-insensitive substring to match.")
       },
       annotations: readOnly
     },
-    withSpecArgs((spec, { query }) => {
+    tool((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"));
@@ -576,20 +586,23 @@ function createServer(docsUrl) {
       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: {
+        spec: specParam,
         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.`
-        );
+    tool(
+      (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));
       }
-      return ok(endpointDetail(ep, spec));
-    })
+    )
   );
   server.registerTool(
     "get_schema",
@@ -597,11 +610,12 @@ function createServer(docsUrl) {
       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: {
+        spec: specParam,
         name: z.string().describe("Schema name as shown by list_schemas.")
       },
       annotations: readOnly
     },
-    withSpecArgs((spec, { name }) => {
+    tool((spec, { name }) => {
       if (spec.schemas[name] === void 0) {
         return fail(
           `No schema named "${name}". Call list_schemas to see available schemas.`
@@ -615,10 +629,10 @@ function createServer(docsUrl) {
     {
       title: "Get auth",
       description: "Full security schemes for the API (OAuth2 flows, scopes, API-key locations) plus the global security requirement.",
-      inputSchema: {},
+      inputSchema: { spec: specParam },
       annotations: readOnly
     },
-    withSpec((spec) => {
+    tool((spec) => {
       if (spec.securitySchemes.length === 0) {
         return ok("This spec declares no security schemes.");
       }
@@ -633,15 +647,13 @@ ${parts.join("\n\n")}`);
 
 // 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 defaultDocsUrl = process.env.API_DOCS_URL;
+  const server = createServer(defaultDocsUrl);
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error("swagger-mcp: ready (stdio).");
+  console.error(
+    defaultDocsUrl ? `swagger-mcp: ready (stdio), default spec ${defaultDocsUrl}` : "swagger-mcp: ready (stdio), pass `spec` per tool call"
+  );
 }
 main().catch((err) => {
   console.error("swagger-mcp: fatal error:", err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emreyc/swagger-mcp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Read-only MCP server for navigating OpenAPI/Swagger specifications.",
   "keywords": [
     "mcp",