swagger-digest 0.1.2 → 0.2.0

package/README.md

@@ -45,6 +45,52 @@ 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.
+
 ### 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:
@@ -179,6 +225,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-2NORV6KM.js

@@ -0,0 +1,143 @@
+import {
+  VERSION,
+  estimateTokens,
+  fetchOpenApiSpec,
+  mergeHeaders,
+  parseHeaderPairs,
+  transformOpenApiToMarkdown,
+  writeDigest
+} from "./chunk-U7OLLL6J.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,
+    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)"
+        ),
+        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-U7OLLL6J.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}`;
@@ -2103,6 +2104,61 @@ function transformOpenApiToMarkdown(spec, sourceUrl, options = {}) {
   return appendTrimNote(markdown, allActions, options.maxTokens);
 }
 
+// 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
 import { mkdir, writeFile } from "fs/promises";
 import os from "os";
@@ -2141,6 +2197,9 @@ export {
   fetchOpenApiSpec,
   estimateTokens,
   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-U7OLLL6J.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);

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,65 @@ 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;
+    /** 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 {
@@ -91,5 +153,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 { 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,3 +1,8 @@
+import {
+  buildRequestHeaders,
+  createMcpServer,
+  runSwaggerDigest
+} from "./chunk-2NORV6KM.js";
 import {
   defaultFilename,
   defaultOutputDirectory,
@@ -10,8 +15,10 @@ import {
   toTypeScriptIdentifier,
   transformOpenApiToMarkdown,
   writeDigest
-} from "./chunk-CBSDTIKN.js";
+} from "./chunk-U7OLLL6J.js";
 export {
+  buildRequestHeaders,
+  createMcpServer,
   defaultFilename,
   defaultOutputDirectory,
   estimateTokens,
@@ -20,6 +27,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-2NORV6KM.js";
+import "../chunk-U7OLLL6J.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.2.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",