swagger-digest 0.1.2 → 0.3.0

package/README.md

@@ -45,6 +45,83 @@ npx swagger-digest --url https://api.example.com/openapi.json --stdout | pbcopy
 
 Run `npx swagger-digest --help` for all CLI options. The package requires Node.js 20 or newer.
 
+## MCP server
+
+The package ships an [MCP](https://modelcontextprotocol.io) server exposing the same pipeline as a tool for AI agents, so they can fetch and digest API docs on their own instead of being handed a Markdown file.
+
+```bash
+npx swagger-digest-mcp
+```
+
+It speaks the stdio transport: the MCP client spawns the process and communicates over stdin/stdout. Register it in your client's configuration:
+
+```json
+{
+  "mcp": {
+    "swagger-digest": {
+      "command": ["npx", "-y", "swagger-digest-mcp"]
+    }
+  }
+}
+```
+
+### The `swagger_digest` tool
+
+| Argument        | Type             | Description                                                                |
+| --------------- | ---------------- | -------------------------------------------------------------------------- |
+| `url`           | string, required | Swagger UI page URL or direct OpenAPI spec URL                             |
+| `spec_url`      | string, optional | Explicit spec URL; overrides discovery from the page                       |
+| `headers`       | object, optional | Request headers (e.g. `Authorization`); sent only to the origin of `url`   |
+| `include_tags`  | string[]         | Keep only operations with these tags                                       |
+| `exclude_tags`  | string[]         | Drop operations with these tags                                            |
+| `path_prefix`   | string           | Keep only paths starting with this prefix                                  |
+| `max_tokens`    | number           | Trim the digest to an approximate token budget                             |
+| `write_to_file` | object, optional | `{ directory, filename }` — save the digest instead of returning it inline |
+
+By default the digest is returned directly in the tool result (so it lands in the agent's context), with a metadata footer: retrieval method, operation/model counts, and a token estimate.
+
+### Environment variables
+
+- `SWAGGER_DIGEST_HEADER` — newline-separated `Name: value` pairs, merged with (and overridden by) the tool call's `headers` argument. Keeps secrets out of the conversation.
+- `SWAGGER_DIGEST_ALLOW_PRIVATE=1` — opt out of the private-network guard (see below).
+
+### Security differences from the CLI
+
+- **SSRF guard on by default:** URLs resolving to loopback, private, or link-local (cloud metadata) addresses are rejected, because MCP clients supply URLs on the model's behalf. Opt out with `SWAGGER_DIGEST_ALLOW_PRIVATE=1` — for example to digest an internal corporate API — only if you trust the hosts involved.
+- **No headless-browser fallback:** the optional Playwright fallback is disabled in the MCP server.
+- Diagnostics go to stderr only; stdout carries protocol frames exclusively.
+
+## Benchmarks
+
+Ten public APIs, digest vs. raw spec JSON in an LLM context, ground truth from the parsed raw specs. Run in November 2026 against swagger-digest 0.2.0; token counts are heuristic estimates, not tokenizer-exact.
+
+**7/10 wins · 100% operation coverage on every digest produced · 1.6–3.7× lighter · 1 call vs 1–5**
+
+| Spec                | Ops   | Raw tokens             | Digest tokens           | Compression | Op coverage | Winner  |
+| ------------------- | ----- | ---------------------- | ----------------------- | ----------- | ----------- | ------- |
+| Petstore v2         | 20    | 3,461                  | 2,202                   | 1.6×        | 20/20       | 🟢 MCP  |
+| Petstore v3         | 19    | 4,277                  | 2,624                   | 1.6×        | 19/19       | 🟢 MCP  |
+| Petstore v3 UI page | 19    | 4,277 (+4 URL guesses) | ❌ failed*              | —           | —           | 🟡 Raw* |
+| Azure Compute       | 157   | 157,568                | 72,549                  | 2.2×        | 157/157     | 🟢 MCP  |
+| X/Twitter v2        | 259   | 333,985                | 105,719                 | 3.2×        | 259/259     | 🟢 MCP  |
+| Box                 | 297   | 453,200                | 162,829                 | 2.8×        | 297/297     | 🟢 MCP  |
+| Twilio              | 197   | 469,913                | 155,709                 | 3.0×        | 197/197     | 🟢 MCP  |
+| Stripe              | 612   | 2,079,211              | 564,308                 | 3.7×        | 612/612     | 🟢 MCP  |
+| Kubernetes          | 1,172 | 1,085,939              | 1,341,885 (expanded!)   | ❌ 0.8×*    | 1172/1172   | 🔴 Raw  |
+| GitHub (full)       | 1,272 | 3,551,639              | ❌ failed (14 MB fetch) | —           | —           | 🟡 Raw* |
+
+> For its target use case — understanding an API in an LLM context — the digest wins on the spec class that actually matters (up to ~600 operations): 100% endpoint coverage, never truncated, one call, and 1.6–3.7× lighter. The bigger the spec, the bigger the win.
+
+\* Raw's three "wins" carry heavy caveats: the Petstore UI-page case needed brute-forced candidate URLs (the digest's discovery has since been fixed for that class of pages); GitHub's 3.55M-token raw spec would truncate in any model's context anyway; and the Kubernetes expansion is now prevented by the default token cap described below.
+
+### Known failure modes (and their mitigations)
+
+| Case                                                         | What happens                                                           | Mitigation                                                                                                                             |
+| ------------------------------------------------------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| JS-only Swagger UI pages with dynamically computed spec URLs | Literal extraction finds nothing after `url:`                          | **Fixed in 0.3.0** (embedded spec-URL scan). Otherwise pass `spec_url` / `--spec` explicitly                                           |
+| Mega-specs (Kubernetes-class, ≥1M tokens)                    | Digest can _expand_ past raw size — descriptions inlined per operation | **Default in 0.3.0**: automatic 250k-token cap (opt out with `--no-auto-trim` / `auto_trim: false`). Explicit `max_tokens` always wins |
+| Huge fetches (14 MB GitHub spec)                             | Fetch fails at the 10 MB response cap                                  | Use a filtered direct spec URL                                                                                                         |
+
 ### Filtering and token budget
 
 Large specs produce large digests. The CLI can remove whole operations before rendering and/or trim the remaining digest to an approximate token budget:
@@ -70,6 +147,8 @@ How `--max-tokens` trims (in this fixed order, re-checked against the estimate a
 
 A `## Trimmed` note at the end of the digest records exactly which steps were applied. After every step, schemas that became unreachable (referenced only by collapsed/removed operations) are dropped from the Data types section. The token estimator is a heuristic, **not** a real tokenizer — treat `--max-tokens` as a guide, not a guarantee. Unknown tag names passed to `--include-tag`/`--exclude-tag` produce a warning on stderr listing the tags that exist in the spec.
 
+**Default token cap:** without an explicit `--max-tokens`, digests are automatically trimmed to an estimated 250,000 tokens (a warning names the untrimmed estimate). Mega-specs can otherwise expand _past_ their raw size once descriptions are inlined per operation. Opt out with `--no-auto-trim`; an explicit `--max-tokens` always takes precedence. The MCP server behaves the same via its `auto_trim` argument (default true).
+
 The same options are available programmatically via the third argument of `transformOpenApiToMarkdown(spec, sourceUrl, { includeTags, excludeTags, pathPrefix, maxTokens, onWarning })`.
 
 ## What it extracts
@@ -77,7 +156,7 @@ The same options are available programmatically via the third argument of `trans
 The retrieval strategy deliberately avoids scraping rendered operation accordions or simulating UI clicks:
 
 1. Fetch and parse a direct `.json`, `.yaml`, or `.yml` URL.
-2. Fetch the Swagger UI page and inspect script configuration for `url: "..."` or an inline `spec: { ... }` object.
+2. Fetch the Swagger UI page and inspect script configuration for `url: "..."` or an inline `spec: { ... }` object, plus any spec-like URLs embedded in same-origin initializer scripts (covers initializers that compute the spec URL dynamically).
 3. Try common spec endpoints on the same origin: `/v3/api-docs`, `/swagger/v1/swagger.json`, `/swagger.json`, `/openapi.json`, and `/api-docs`.
 4. Optionally launch a headless Chromium browser and read the parsed specification from Swagger UI's in-memory state.
 
@@ -179,6 +258,10 @@ src/
   transformer.ts  OpenAPI/Swagger to compact Markdown and TypeScript-like types
   writer.ts       Output path, filename defaults and file writing
   index.ts        Public exports
+  mcp/
+    index.ts      MCP stdio entry point (`swagger-digest-mcp` bin)
+    server.ts     MCP server and tool registration (transport-agnostic)
+    digest.ts     Tool handler: fetch → transform → tool result
 ```
 
 ## Limitations

package/dist/chunk-DJES77HX.js

@@ -0,0 +1,147 @@
+import {
+  VERSION,
+  estimateTokens,
+  fetchOpenApiSpec,
+  mergeHeaders,
+  parseHeaderPairs,
+  transformOpenApiToMarkdown,
+  writeDigest
+} from "./chunk-MXTHI25H.js";
+
+// src/mcp/digest.ts
+var TOKEN_HINT_THRESHOLD = 8e4;
+function textContent(text) {
+  return [{ type: "text", text }];
+}
+function asError(message) {
+  return { content: textContent(message), isError: true };
+}
+function isHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function countDigestOperations(markdown) {
+  return (markdown.match(/^\| \*\*(?:GET|PUT|POST|DELETE|OPTIONS|HEAD|PATCH|TRACE)\*\* \|/gm) ?? []).length;
+}
+function countDigestModels(markdown) {
+  return (markdown.match(/^export (?:interface|type) \w+/gm) ?? []).length;
+}
+function buildRequestHeaders(args) {
+  const fromEnv = process.env.SWAGGER_DIGEST_HEADER ? parseHeaderPairs(process.env.SWAGGER_DIGEST_HEADER) : {};
+  return mergeHeaders(fromEnv, args.headers);
+}
+async function runSwaggerDigest(args, options = {}) {
+  if (!isHttpUrl(args.url)) {
+    return asError(`Invalid url "${args.url}": use an http:// or https:// URL.`);
+  }
+  if (args.spec_url !== void 0 && !isHttpUrl(args.spec_url)) {
+    return asError(`Invalid spec_url "${args.spec_url}": use an http:// or https:// URL.`);
+  }
+  if (args.max_tokens !== void 0 && (!Number.isInteger(args.max_tokens) || args.max_tokens <= 0)) {
+    return asError(`Invalid max_tokens ${args.max_tokens}: use a positive integer.`);
+  }
+  const blockPrivateNetworks = options.blockPrivateNetworks ?? process.env.SWAGGER_DIGEST_ALLOW_PRIVATE !== "1";
+  const warnings = [];
+  const warn = (message) => {
+    warnings.push(message);
+  };
+  let fetchResult;
+  try {
+    const fetchOptions = {
+      useBrowserFallback: false,
+      maxBytes: 1e7,
+      headers: buildRequestHeaders(args),
+      specUrl: args.spec_url,
+      blockPrivateNetworks,
+      warn
+    };
+    fetchResult = await fetchOpenApiSpec(args.url, fetchOptions);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return asError(`Could not extract an OpenAPI definition from ${args.url}: ${message}`);
+  }
+  const markdown = transformOpenApiToMarkdown(fetchResult.spec, fetchResult.sourceUrl, {
+    includeTags: args.include_tags,
+    excludeTags: args.exclude_tags,
+    pathPrefix: args.path_prefix,
+    maxTokens: args.max_tokens,
+    autoTrim: args.auto_trim !== false,
+    onWarning: warn
+  });
+  const operationCount = countDigestOperations(markdown);
+  const modelCount = countDigestModels(markdown);
+  const tokens = estimateTokens(markdown).models.claude.tokens;
+  const metadata = [
+    `source: ${fetchResult.sourceUrl} (via ${fetchResult.retrievalMethod})`,
+    `${operationCount} operation${operationCount === 1 ? "" : "s"}`,
+    `${modelCount} data model${modelCount === 1 ? "" : "s"}`,
+    `~${tokens.toLocaleString("en-US")} tokens estimated`
+  ].join(" \xB7 ");
+  const warningBlock = warnings.length > 0 ? `
+
+_Warnings:_
+${warnings.map((w) => `- ${w}`).join("\n")}` : "";
+  const budgetHint = tokens > TOKEN_HINT_THRESHOLD && args.max_tokens === void 0 ? "\n\n_This digest is large. Consider re-running with max_tokens, include_tags, exclude_tags or path_prefix to fit it into context._" : "";
+  if (args.write_to_file) {
+    try {
+      const outputPath = await writeDigest({
+        markdown,
+        directory: args.write_to_file.directory,
+        filename: args.write_to_file.filename
+      });
+      return { content: textContent(`Digest written to ${outputPath}
+
+_${metadata}_${warningBlock}`) };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return asError(`Could not write digest: ${message}`);
+    }
+  }
+  return { content: textContent(`${markdown}
+
+---
+_Digest metadata: ${metadata}_${warningBlock}${budgetHint}`) };
+}
+
+// src/mcp/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+function createMcpServer(options = {}) {
+  const server = new McpServer({ name: "swagger-digest", version: VERSION });
+  server.registerTool(
+    "swagger_digest",
+    {
+      title: "Generate API digest",
+      description: "Fetch a Swagger UI page or an OpenAPI/Swagger spec (JSON or YAML, versions 2.0/3.0/3.1) and convert it into a compact Markdown API reference optimized for LLM context: endpoint index, request/response details, authentication schemes, and TypeScript-like data types. Handles Swagger UI discovery automatically (initializer scripts, multi-spec dropdowns, common spec paths). Use this whenever the user asks to understand, summarize, or work against an API documented with Swagger/OpenAPI.",
+      inputSchema: {
+        url: z.string().describe("Swagger UI page URL or direct OpenAPI spec URL (http/https)"),
+        spec_url: z.string().optional().describe("Explicit OpenAPI spec URL; overrides discovery from the Swagger UI page"),
+        headers: z.record(z.string(), z.string()).optional().describe(
+          "Request headers (e.g. Authorization or Cookie). Sent ONLY to the origin of url; cross-origin requests never receive them. Values are not logged."
+        ),
+        include_tags: z.array(z.string()).optional().describe("Keep only operations carrying at least one of these tags"),
+        exclude_tags: z.array(z.string()).optional().describe("Drop operations carrying any of these tags"),
+        path_prefix: z.string().optional().describe("Keep only operations whose path starts with this prefix"),
+        max_tokens: z.number().int().positive().optional().describe(
+          "Trim the digest until an approximate token estimate fits this budget (heuristic, not tokenizer-accurate)"
+        ),
+        auto_trim: z.boolean().optional().describe(
+          "Auto-trim digests exceeding the 250,000-token default budget when max_tokens is not given. Defaults to true."
+        ),
+        write_to_file: z.object({ directory: z.string(), filename: z.string() }).optional().describe("Save the digest to a file instead of returning it inline")
+      }
+    },
+    (args) => runSwaggerDigest(args, options)
+  );
+  return server;
+}
+
+export {
+  buildRequestHeaders,
+  runSwaggerDigest,
+  createMcpServer
+};

package/dist/{chunk-CBSDTIKN.js → chunk-MXTHI25H.js}

@@ -1,14 +1,15 @@
 // src/version.ts
 import { createRequire } from "module";
 function readPackageVersion(moduleUrl) {
-  try {
-    const require2 = createRequire(moduleUrl);
-    const pkg = require2("../package.json");
-    if (typeof pkg?.version === "string" && pkg.version) return pkg.version;
-    return "unknown";
-  } catch {
-    return "unknown";
+  const require2 = createRequire(moduleUrl);
+  for (const candidate of ["../package.json", "../../package.json"]) {
+    try {
+      const pkg = require2(candidate);
+      if (typeof pkg?.version === "string" && pkg.version) return pkg.version;
+    } catch {
+    }
   }
+  return "unknown";
 }
 var VERSION = readPackageVersion(import.meta.url);
 var USER_AGENT = `swagger-digest/${VERSION}`;
@@ -585,6 +586,35 @@ function extractSpecUrlsFromScripts(scripts, pageUrl) {
   }
   return found;
 }
+function extractEmbeddedSpecUrlsFromScripts(scripts, pageUrl) {
+  const found = [];
+  const push = (raw) => {
+    try {
+      const url = new URL(raw);
+      if (url.protocol !== "http:" && url.protocol !== "https:") return;
+      if (!/\.(?:json|ya?ml)$/i.test(url.pathname)) return;
+      if (!/(?:openapi|swagger|api[-._]?docs)/i.test(url.pathname)) return;
+      const resolved = url.toString();
+      if (!found.includes(resolved)) found.push(resolved);
+    } catch {
+    }
+  };
+  for (const script of scripts) {
+    for (const match of script.matchAll(/https?:\/\/[^\s"'`<>(){}[\]\\,=]+/gi)) {
+      push(match[0]);
+    }
+  }
+  const sameOrigin = found.filter((url) => {
+    try {
+      return new URL(url).origin === pageUrl.origin;
+    } catch {
+      return false;
+    }
+  });
+  const crossOrigin = found.filter((url) => !sameOrigin.includes(url));
+  return [...sameOrigin, ...crossOrigin].slice(0, MAX_EMBEDDED_SPEC_URLS);
+}
+var MAX_EMBEDDED_SPEC_URLS = 8;
 function findObjectLiteralArrayAfterKey(source, key) {
   const keyPattern = new RegExp(`\\b${key}\\s*:`);
   const match = keyPattern.exec(source);
@@ -702,7 +732,7 @@ async function fetchExternalConfigScripts(srcs, pageUrl, ctx, errors) {
     try {
       const response = await fetchText(candidate.toString(), ctx);
       scripts.push(response.text);
-      if (extractSpecUrlFromScripts(scripts, pageUrl) || scripts.some((script) => findObjectLiteralAfterKey(script, "spec"))) {
+      if (extractSpecUrlFromScripts(scripts, pageUrl) || extractEmbeddedSpecUrlsFromScripts(scripts, pageUrl).length > 0 || scripts.some((script) => findObjectLiteralAfterKey(script, "spec"))) {
         break;
       }
     } catch (error) {
@@ -982,6 +1012,13 @@ async function fetchOpenApiSpec(input, options = {}) {
     const externalUrls = extractSpecUrls(externalScripts, pageUrl).filter((url) => !inlineUrls.includes(url));
     const fromExternal = await probeSpecUrls([...inlineUrls, ...externalUrls], ctx, recordFailure, noteMultiple);
     if (fromExternal) return fromExternal;
+    const triedUrls = /* @__PURE__ */ new Set([...inlineUrls, ...externalUrls]);
+    const embeddedUrls = [
+      ...extractEmbeddedSpecUrlsFromScripts(scripts, pageUrl),
+      ...extractEmbeddedSpecUrlsFromScripts(externalScripts, pageUrl)
+    ].filter((url) => !triedUrls.has(url));
+    const fromEmbedded = await probeSpecUrls(embeddedUrls, ctx, recordFailure);
+    if (fromEmbedded) return fromEmbedded;
     for (const script of scripts) {
       const literal = findObjectLiteralAfterKey(script, "spec");
       if (!literal) continue;
@@ -1903,6 +1940,7 @@ function normalizeInlinePayloadSchemas(spec) {
 }
 
 // src/transformer/index.ts
+var DEFAULT_MAX_TOKENS = 25e4;
 var HTTP_METHODS2 = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
 function tagsOfEndpoint(endpoint) {
   const tags = endpoint.operation.tags;
@@ -2075,16 +2113,22 @@ function transformOpenApiToMarkdown(spec, sourceUrl, options = {}) {
     collapsedTags: /* @__PURE__ */ new Set(),
     indexOnly: false
   };
-  if (options.maxTokens === void 0) {
-    return renderDigest(normalizedSpec, sourceUrl, endpoints, tags, fullStage);
-  }
   const worst = (markdown2) => {
     const report = estimateTokens(markdown2);
     return Math.max(...Object.values(report.models).map((model) => model.tokens));
   };
-  const fits = (markdown2) => worst(markdown2) <= options.maxTokens;
+  const effectiveMaxTokens = options.maxTokens ?? (options.autoTrim === false ? void 0 : DEFAULT_MAX_TOKENS);
+  if (effectiveMaxTokens === void 0) {
+    return renderDigest(normalizedSpec, sourceUrl, endpoints, tags, fullStage);
+  }
+  const fits = (markdown2) => worst(markdown2) <= effectiveMaxTokens;
   const full = renderDigest(normalizedSpec, sourceUrl, endpoints, tags, fullStage);
   if (fits(full)) return full;
+  if (options.maxTokens === void 0) {
+    options.onWarning?.(
+      `Untrimmed digest \u2248 ${worst(full).toLocaleString()} tokens (estimated), over the ${DEFAULT_MAX_TOKENS.toLocaleString()} default budget; auto-trimming. Pass maxTokens to control the budget or autoTrim: false to disable.`
+    );
+  }
   const stages = buildTrimStages(endpoints, tags);
   for (let i = 1; i < stages.length; i += 1) {
     const stage = stages[i];
@@ -2093,14 +2137,69 @@ function transformOpenApiToMarkdown(spec, sourceUrl, options = {}) {
       return appendTrimNote(
         markdown2,
         stages.slice(1, i + 1).map((entry) => entry.action).filter((action) => Boolean(action)),
-        options.maxTokens
+        effectiveMaxTokens
       );
     }
   }
   const last = stages[stages.length - 1];
   const markdown = renderDigest(normalizedSpec, sourceUrl, endpoints, tags, last);
   const allActions = stages.slice(1).map((stage) => stage.action).filter((action) => Boolean(action));
-  return appendTrimNote(markdown, allActions, options.maxTokens);
+  return appendTrimNote(markdown, allActions, effectiveMaxTokens);
+}
+
+// src/headers.ts
+var HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+function validateHeaderName(name) {
+  if (!name) throw new Error('Header name must not be empty. Expected "Name: value".');
+  if (/[\r\n]/.test(name)) {
+    throw new Error(`Invalid header name: header names must not contain CR/LF characters.`);
+  }
+  if (!HEADER_NAME_PATTERN.test(name)) {
+    throw new Error(`Invalid header name "${name}": use a valid HTTP header token (letters, digits and -_).`);
+  }
+}
+function validateHeaderValue(name, value) {
+  if (/[\r\n]/.test(value)) {
+    throw new Error(`Invalid value for header "${name}": values must not contain CR/LF.`);
+  }
+  if (/\0/.test(value)) {
+    throw new Error(`Invalid value for header "${name}": values must not contain NUL bytes.`);
+  }
+}
+function parseHeaderArgument(raw) {
+  const separator = raw.indexOf(":");
+  if (separator === -1) {
+    if (/[\r\n]/.test(raw)) {
+      throw new Error(`Invalid header: names and values must not contain CR/LF.`);
+    }
+    throw new Error(`Invalid header \u2014 expected "Name: value" format (for example "Authorization: Bearer <token>").`);
+  }
+  const name = raw.slice(0, separator).trim();
+  const value = raw.slice(separator + 1).trim();
+  validateHeaderName(name);
+  validateHeaderValue(name, value);
+  return { [name.toLowerCase()]: value };
+}
+function parseHeaderPairs(raw) {
+  const result = {};
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    Object.assign(result, parseHeaderArgument(line));
+  }
+  return result;
+}
+function mergeHeaders(...sources) {
+  const result = {};
+  for (const source of sources) {
+    if (!source) continue;
+    for (const [name, value] of Object.entries(source)) {
+      if (/[\r\n]/.test(name) || /[\r\n]/.test(value)) {
+        throw new Error(`Invalid header "${name}": CR/LF is not allowed in header names or values.`);
+      }
+      result[name.toLowerCase()] = value;
+    }
+  }
+  return result;
 }
 
 // src/writer.ts
@@ -2140,7 +2239,11 @@ export {
   parseSpecText,
   fetchOpenApiSpec,
   estimateTokens,
+  DEFAULT_MAX_TOKENS,
   transformOpenApiToMarkdown,
+  parseHeaderArgument,
+  parseHeaderPairs,
+  mergeHeaders,
   defaultOutputDirectory,
   defaultFilename,
   resolveOutputDirectory,

package/dist/cli.js

@@ -5,72 +5,18 @@ import {
   defaultOutputDirectory,
   estimateTokens,
   fetchOpenApiSpec,
+  mergeHeaders,
+  parseHeaderArgument,
+  parseHeaderPairs,
   transformOpenApiToMarkdown,
   writeDigest
-} from "./chunk-CBSDTIKN.js";
+} from "./chunk-MXTHI25H.js";
 
 // src/cli.ts
 import { input } from "@inquirer/prompts";
 import chalk from "chalk";
 import { Command } from "commander";
 import ora from "ora";
-
-// src/headers.ts
-var HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
-function validateHeaderName(name) {
-  if (!name) throw new Error('Header name must not be empty. Expected "Name: value".');
-  if (/[\r\n]/.test(name)) {
-    throw new Error(`Invalid header name: header names must not contain CR/LF characters.`);
-  }
-  if (!HEADER_NAME_PATTERN.test(name)) {
-    throw new Error(`Invalid header name "${name}": use a valid HTTP header token (letters, digits and -_).`);
-  }
-}
-function validateHeaderValue(name, value) {
-  if (/[\r\n]/.test(value)) {
-    throw new Error(`Invalid value for header "${name}": values must not contain CR/LF.`);
-  }
-  if (/\0/.test(value)) {
-    throw new Error(`Invalid value for header "${name}": values must not contain NUL bytes.`);
-  }
-}
-function parseHeaderArgument(raw) {
-  const separator = raw.indexOf(":");
-  if (separator === -1) {
-    if (/[\r\n]/.test(raw)) {
-      throw new Error(`Invalid header: names and values must not contain CR/LF.`);
-    }
-    throw new Error(`Invalid header \u2014 expected "Name: value" format (for example "Authorization: Bearer <token>").`);
-  }
-  const name = raw.slice(0, separator).trim();
-  const value = raw.slice(separator + 1).trim();
-  validateHeaderName(name);
-  validateHeaderValue(name, value);
-  return { [name.toLowerCase()]: value };
-}
-function parseHeaderPairs(raw) {
-  const result = {};
-  for (const line of raw.split(/\r?\n/)) {
-    if (!line.trim()) continue;
-    Object.assign(result, parseHeaderArgument(line));
-  }
-  return result;
-}
-function mergeHeaders(...sources) {
-  const result = {};
-  for (const source of sources) {
-    if (!source) continue;
-    for (const [name, value] of Object.entries(source)) {
-      if (/[\r\n]/.test(name) || /[\r\n]/.test(value)) {
-        throw new Error(`Invalid header "${name}": CR/LF is not allowed in header names or values.`);
-      }
-      result[name.toLowerCase()] = value;
-    }
-  }
-  return result;
-}
-
-// src/cli.ts
 function validateUrl(value) {
   try {
     const url = new URL(value);
@@ -115,7 +61,7 @@ async function main() {
     "Custom request header, repeatable. Sent only to the URL you supplied.",
     collectOption,
     []
-  ).option("--cookie <string>", "Convenience for a Cookie request header (same-origin scoping applies)").option("--include-tag <tag>", "Keep only operations with this tag, repeatable", collectOption, []).option("--exclude-tag <tag>", "Drop operations with this tag, repeatable", collectOption, []).option("--path-prefix <prefix>", "Keep only operations whose path starts with this prefix").option("--max-tokens <n>", "Trim the digest until the approximate token estimate fits this budget").option("--spec <url>", "Explicit OpenAPI spec URL; overrides discovery from the Swagger UI page").option("--stdout", "Print the digest to standard output instead of writing a file").addHelpText(
+  ).option("--cookie <string>", "Convenience for a Cookie request header (same-origin scoping applies)").option("--include-tag <tag>", "Keep only operations with this tag, repeatable", collectOption, []).option("--exclude-tag <tag>", "Drop operations with this tag, repeatable", collectOption, []).option("--path-prefix <prefix>", "Keep only operations whose path starts with this prefix").option("--max-tokens <n>", "Trim the digest until the approximate token estimate fits this budget").option("--no-auto-trim", "Disable the automatic 250,000-token default cap for digests without --max-tokens").option("--spec <url>", "Explicit OpenAPI spec URL; overrides discovery from the Swagger UI page").option("--stdout", "Print the digest to standard output instead of writing a file").addHelpText(
     "after",
     [
       "",
@@ -186,6 +132,7 @@ async function main() {
     excludeTags: options.excludeTag,
     pathPrefix: options.pathPrefix,
     maxTokens: parseMaxTokens(options.maxTokens),
+    autoTrim: options.autoTrim !== false,
     onWarning: (message) => console.error(chalk.yellow(`Warning: ${message}`))
   });
   spinner.succeed(`Parsed ${title} (${result.retrievalMethod})`);

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
 type JsonObject = Record<string, any>;
 interface FetchOptions {
     timeoutMs?: number;
@@ -38,6 +41,70 @@ declare function parseSpecText(text: string, source?: string): JsonObject;
 /** Resolve a Swagger UI page or a direct OpenAPI JSON/YAML URL into a parsed spec. */
 declare function fetchOpenApiSpec(input: string, options?: FetchOptions): Promise<FetchResult>;
 
+/** Arguments of the `swagger_digest` MCP tool (mirrors the zod schema in server.ts). */
+interface McpDigestArgs {
+    /** Swagger UI page URL or direct OpenAPI spec URL. */
+    url: string;
+    /** Explicit spec URL; overrides discovery from the Swagger UI page. */
+    spec_url?: string;
+    /** Request headers (e.g. Authorization). Sent only to the origin of `url`. */
+    headers?: Record<string, string>;
+    /** Keep only operations carrying at least one of these tags. */
+    include_tags?: string[];
+    /** Drop operations carrying any of these tags. */
+    exclude_tags?: string[];
+    /** Keep only operations whose path starts with this prefix. */
+    path_prefix?: string;
+    /** Trim the digest until the approximate token estimate fits this budget. */
+    max_tokens?: number;
+    /**
+     * Auto-trim digests exceeding the 250,000-token default budget when
+     * max_tokens is not given. Defaults to true.
+     */
+    auto_trim?: boolean;
+    /** Save the digest to a file instead of returning it inline. */
+    write_to_file?: {
+        directory: string;
+        filename: string;
+    };
+}
+/**
+ * Server-wide behavior switches. Tests pass these explicitly; the stdio entry
+ * point derives them from the environment.
+ */
+interface DigestServerOptions {
+    /**
+     * Reject URLs resolving to loopback/private/metadata addresses. Defaults to
+     * true: an MCP client supplies URLs on the model's behalf, which is exactly
+     * the "server that accepts user-supplied URLs" case from the security notes.
+     * Users can opt out per deployment with SWAGGER_DIGEST_ALLOW_PRIVATE=1.
+     */
+    blockPrivateNetworks?: boolean;
+}
+/**
+ * Builds the request headers for a digest call: SWAGGER_DIGEST_HEADER
+ * environment entries first, then tool-call arguments (arguments win on
+ * conflicting names — same precedence as -H flags over the environment in the
+ * CLI). Header validation and origin scoping happen in headers.ts / fetcher.ts.
+ */
+declare function buildRequestHeaders(args: Pick<McpDigestArgs, 'headers'>): Record<string, string>;
+/**
+ * Runs one digest request and renders it as an MCP tool result. Expected
+ * failures (unreachable URLs, unparsable specs, invalid header arguments)
+ * become `isError` results carrying the message; unexpected errors propagate
+ * to the SDK, which converts them into protocol-level tool errors.
+ */
+declare function runSwaggerDigest(args: McpDigestArgs, options?: DigestServerOptions): Promise<CallToolResult>;
+
+/**
+ * Builds the MCP server exposing the `swagger_digest` tool.
+ *
+ * The instance is transport-agnostic: `src/mcp/index.ts` connects it to a
+ * StdioServerTransport, while tests connect it to an InMemoryTransport pair.
+ * No I/O happens at module scope or during construction.
+ */
+declare function createMcpServer(options?: DigestServerOptions): McpServer;
+
 declare function toTypeScriptIdentifier(value: string): string;
 
 interface TransformOptions {
@@ -52,9 +119,24 @@ interface TransformOptions {
      * budget. The estimator is not tokenizer-accurate; treat the budget as a guide.
      */
     maxTokens?: number;
+    /**
+     * When no explicit `maxTokens` is given, cap the digest at
+     * {@link DEFAULT_MAX_TOKENS} estimated tokens by running the same trim
+     * pipeline, warning when it engages. Defaults to true. Mega-specs
+     * (Kubernetes-class) otherwise produce digests *larger* than the raw spec.
+     */
+    autoTrim?: boolean;
     /** Receives non-fatal notices, e.g. unknown tag names. */
     onWarning?: (message: string) => void;
 }
+/**
+ * Default token budget applied when `maxTokens` is undefined and `autoTrim`
+ * is not disabled. Chosen from benchmark data: large real-world specs
+ * (Stripe-class, ~600 operations) digest to ~560k tokens untrimmed, while
+ * kitchen-sink specs expand past their raw size — 250k keeps the largest
+ * useful full-detail digests intact and trims only true outliers.
+ */
+declare const DEFAULT_MAX_TOKENS = 250000;
 /** Convert an OpenAPI 2.0, 3.0, or 3.1 document to a compact Markdown digest. */
 declare function transformOpenApiToMarkdown(spec: JsonObject, sourceUrl?: string, options?: TransformOptions): string;
 
@@ -91,5 +173,5 @@ declare function writeDigest(options: {
     filename: string;
 }): Promise<string>;
 
-export { defaultFilename, defaultOutputDirectory, estimateTokens, fetchOpenApiSpec, isOpenApiSpec, normalizeFilename, parseSpecText, resolveOutputDirectory, toTypeScriptIdentifier, transformOpenApiToMarkdown, writeDigest };
-export type { DigestTokenReport, FetchOptions, FetchResult, JsonObject, ModelTokenEstimate, TransformOptions };
+export { DEFAULT_MAX_TOKENS, buildRequestHeaders, createMcpServer, defaultFilename, defaultOutputDirectory, estimateTokens, fetchOpenApiSpec, isOpenApiSpec, normalizeFilename, parseSpecText, resolveOutputDirectory, runSwaggerDigest, toTypeScriptIdentifier, transformOpenApiToMarkdown, writeDigest };
+export type { DigestServerOptions, DigestTokenReport, FetchOptions, FetchResult, JsonObject, McpDigestArgs, ModelTokenEstimate, TransformOptions };

package/dist/index.js

@@ -1,4 +1,10 @@
 import {
+  buildRequestHeaders,
+  createMcpServer,
+  runSwaggerDigest
+} from "./chunk-DJES77HX.js";
+import {
+  DEFAULT_MAX_TOKENS,
   defaultFilename,
   defaultOutputDirectory,
   estimateTokens,
@@ -10,8 +16,11 @@ import {
   toTypeScriptIdentifier,
   transformOpenApiToMarkdown,
   writeDigest
-} from "./chunk-CBSDTIKN.js";
+} from "./chunk-MXTHI25H.js";
 export {
+  DEFAULT_MAX_TOKENS,
+  buildRequestHeaders,
+  createMcpServer,
   defaultFilename,
   defaultOutputDirectory,
   estimateTokens,
@@ -20,6 +29,7 @@ export {
   normalizeFilename,
   parseSpecText,
   resolveOutputDirectory,
+  runSwaggerDigest,
   toTypeScriptIdentifier,
   transformOpenApiToMarkdown,
   writeDigest

package/dist/mcp/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/mcp/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import {
+  createMcpServer
+} from "../chunk-DJES77HX.js";
+import "../chunk-MXTHI25H.js";
+
+// src/mcp/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+async function main() {
+  const server = createMcpServer();
+  await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+  console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swagger-digest",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Turn Swagger UI pages and OpenAPI specs into compact, AI-friendly Markdown API digests.",
   "type": "module",
   "main": "dist/index.js",
@@ -12,7 +12,8 @@
     }
   },
   "bin": {
-    "swagger-digest": "./dist/cli.js"
+    "swagger-digest": "./dist/cli.js",
+    "swagger-digest-mcp": "./dist/mcp/index.js"
   },
   "author": "VladLegkowski <VladLegkowski@users.noreply.github.com>",
   "repository": {
@@ -30,7 +31,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/cli.ts src/mcp/index.ts --format esm --dts --clean",
     "dev": "tsx src/cli.ts",
     "start": "node dist/cli.js",
     "typecheck": "tsc --noEmit",
@@ -46,11 +47,13 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^7.3.2",
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "chalk": "^5.4.1",
     "cheerio": "^1.0.0",
     "commander": "^13.1.0",
     "ora": "^8.2.0",
-    "yaml": "^2.7.0"
+    "yaml": "^2.7.0",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",