swagger-digest 0.1.1 → 0.2.0

package/dist/cli.js

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 import {
+  VERSION,
   defaultFilename,
   defaultOutputDirectory,
   estimateTokens,
   fetchOpenApiSpec,
+  mergeHeaders,
+  parseHeaderArgument,
+  parseHeaderPairs,
   transformOpenApiToMarkdown,
   writeDigest
-} from "./chunk-UZQM2SHL.js";
+} from "./chunk-U7OLLL6J.js";
 
 // src/cli.ts
 import { input } from "@inquirer/prompts";
@@ -25,11 +29,65 @@ function validateUrl(value) {
 function isInteractive() {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
+function parseMaxBytes(value) {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
+    throw new Error(`Invalid --max-bytes value: ${value}. Use a positive integer number of bytes.`);
+  }
+  return parsed;
+}
+function parseMaxTokens(value) {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
+    throw new Error(`Invalid --max-tokens value: ${value}. Use a positive integer number of tokens.`);
+  }
+  return parsed;
+}
+function collectOption(value, previous) {
+  return [...previous ?? [], value];
+}
+function buildRequestHeaders(options) {
+  const fromEnv = process.env.SWAGGER_DIGEST_HEADER ? parseHeaderPairs(process.env.SWAGGER_DIGEST_HEADER) : {};
+  const fromFlags = (options.headers ?? []).map(parseHeaderArgument);
+  const cookieHeader = options.cookie !== void 0 ? parseHeaderArgument(`Cookie: ${options.cookie}`) : {};
+  return mergeHeaders(fromEnv, ...fromFlags, cookieHeader);
+}
 async function main() {
   const program = new Command();
-  program.name("swagger-digest").description("Convert a Swagger UI page or OpenAPI URL into compact, AI-friendly Markdown.").version("0.1.1").option("-u, --url <url>", "Swagger UI page URL or direct OpenAPI spec URL").option("-d, --out-dir <directory>", "Directory where the Markdown digest will be saved").option("-f, --filename <filename>", "Output filename (defaults to <api-title>-digest.md)").option("--no-browser", "Disable the optional Playwright headless-browser fallback").addHelpText(
+  program.name("swagger-digest").description("Convert a Swagger UI page or OpenAPI URL into compact, AI-friendly Markdown.").version(VERSION).option("-u, --url <url>", "Swagger UI page URL or direct OpenAPI spec URL").option("-d, --out-dir <directory>", "Directory where the Markdown digest will be saved").option("-f, --filename <filename>", "Output filename (defaults to <api-title>-digest.md)").option("--no-browser", "Disable the optional Playwright headless-browser fallback").option("--max-bytes <bytes>", "Maximum response size in bytes (default 10000000 = 10 MB)", "10000000").option(
+    '-H, --header <"Name: value">',
+    "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(
     "after",
-    "\nExamples:\n  npx swagger-digest\n  npx swagger-digest --url https://petstore.swagger.io/ --out-dir ./docs\n  npx swagger-digest -u https://example.com/openapi.yaml -f payments-api.md"
+    [
+      "",
+      "Examples:",
+      "  npx swagger-digest",
+      "  npx swagger-digest --url https://petstore.swagger.io/ --out-dir ./docs",
+      "  npx swagger-digest -u https://example.com/openapi.yaml -f payments-api.md",
+      '  npx swagger-digest -u https://api.example.com/swagger-ui -H "Authorization: Bearer <token>"',
+      "",
+      "Authentication:",
+      "  -H/--header and --cookie values are sent ONLY to the origin of --url.",
+      '  You can also set SWAGGER_DIGEST_HEADER with newline-separated "Name: value" pairs;',
+      "  -H flags override it on conflicts. Avoid passing secrets on the command line if",
+      "  your shell saves history \u2014 prefer the environment variable.",
+      "",
+      "Filtering and token budget:",
+      "  --include-tag/--exclude-tag/--path-prefix remove operations (and the data",
+      "  models only they referenced) before rendering.",
+      "  --max-tokens trims the digest in this order until the estimate fits:",
+      "  1. drop declared example payloads \u2192 2. shorten descriptions \u2192",
+      "  3. collapse parameter/response detail per tag (lowest-priority tag first:",
+      "  the tag that appears last in the document is collapsed first) \u2192",
+      '  4. keep only the Quick index entries. A "Trimmed" note records what was',
+      "  removed. The estimator is a heuristic, NOT tokenizer-accurate \u2014 treat the",
+      "  budget as a guide, not a guarantee."
+    ].join("\n")
   );
   program.parse(process.argv);
   const options = program.opts();
@@ -42,22 +100,45 @@ async function main() {
   });
   const validUrl = validateUrl(url);
   if (validUrl !== true) throw new Error(validUrl);
-  const outputDirectory = options.outDir ?? (isInteractive() ? await input({
+  if (options.stdout && (options.outDir !== void 0 || options.filename !== void 0)) {
+    throw new Error(
+      "--stdout cannot be combined with --out-dir or --filename: it prints the digest to standard output instead of writing a file. Drop --stdout, or remove --out-dir/--filename."
+    );
+  }
+  const outputDirectory = options.outDir ?? (isInteractive() && !options.stdout ? await input({
     message: "Destination directory",
     default: defaultOutputDirectory(),
     validate: (value) => value.trim() ? true : "Enter a destination directory."
   }) : defaultOutputDirectory());
+  const maxBytes = parseMaxBytes(options.maxBytes);
+  const requestHeaders = buildRequestHeaders(options);
   const spinner = ora({ text: "Fetching and parsing OpenAPI definition\u2026", color: "cyan" }).start();
   let result;
   try {
-    result = await fetchOpenApiSpec(url, { useBrowserFallback: options.browser !== false });
+    result = await fetchOpenApiSpec(url, {
+      useBrowserFallback: options.browser !== false,
+      maxBytes,
+      headers: requestHeaders,
+      specUrl: options.spec,
+      warn: (message) => console.error(chalk.yellow(`Warning: ${message}`))
+    });
   } catch (error) {
     spinner.fail("Could not extract an OpenAPI definition");
     throw error;
   }
   const title = typeof result.spec.info?.title === "string" ? result.spec.info.title : "API";
-  const markdown = transformOpenApiToMarkdown(result.spec, result.sourceUrl);
+  const markdown = transformOpenApiToMarkdown(result.spec, result.sourceUrl, {
+    includeTags: options.includeTag,
+    excludeTags: options.excludeTag,
+    pathPrefix: options.pathPrefix,
+    maxTokens: parseMaxTokens(options.maxTokens),
+    onWarning: (message) => console.error(chalk.yellow(`Warning: ${message}`))
+  });
   spinner.succeed(`Parsed ${title} (${result.retrievalMethod})`);
+  if (options.stdout) {
+    process.stdout.write(markdown);
+    return;
+  }
   const filename = options.filename ?? (isInteractive() ? await input({
     message: "Output filename",
     default: defaultFilename(title),
@@ -71,7 +152,8 @@ async function main() {
     const endpointCount = Object.values(result.spec.paths ?? {}).reduce((count, pathItem) => {
       if (!pathItem || typeof pathItem !== "object") return count;
       const methods = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
-      return count + methods.filter((method) => pathItem[method] && typeof pathItem[method] === "object").length;
+      const operations = pathItem;
+      return count + methods.filter((method) => operations[method] && typeof operations[method] === "object").length;
     }, 0);
     const modelCount = Object.keys(result.spec.components?.schemas ?? result.spec.definitions ?? {}).length;
     console.log("");
@@ -82,7 +164,7 @@ async function main() {
     }
     console.log(`  ${chalk.dim("\u2022")} Characters:      ${chalk.dim(report.characters.toLocaleString())}`);
     console.log("");
-    console.log(chalk.bold("Estimated token usage (5 Frontier Models):"));
+    console.log(chalk.bold("Estimated token usage (approximate):"));
     for (const model of Object.values(report.models)) {
       const windowLabel = model.contextWindow >= 1e6 ? `${model.contextWindow / 1e6}M` : `${model.contextWindow / 1e3}k`;
       const paddedName = `${model.name}:`.padEnd(30, " ");

package/dist/index.d.ts

@@ -1,7 +1,33 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
 type JsonObject = Record<string, any>;
 interface FetchOptions {
     timeoutMs?: number;
     useBrowserFallback?: boolean;
+    /** Maximum response body size in bytes (default 10 MB). */
+    maxBytes?: number;
+    /** Maximum number of redirects to follow (default 5). */
+    maxRedirects?: number;
+    /** Opt-in: reject hostnames resolving to private/loopback/metadata addresses. */
+    blockPrivateNetworks?: boolean;
+    /** Timeout for fallback-path probes (default 5000ms; main requests use timeoutMs). */
+    probeTimeoutMs?: number;
+    /**
+     * Custom request headers (e.g. Authorization or Cookie). These are sent ONLY
+     * to the origin of the URL passed to fetchOpenApiSpec; cross-origin requests
+     * (including cross-origin redirects and third-party browser requests) never
+     * receive them.
+     */
+    headers?: Record<string, string>;
+    /** Receives non-fatal notices, e.g. headers withheld on a cross-origin fetch. */
+    warn?: (message: string) => void;
+    /**
+     * Explicit spec URL that overrides discovery entirely: it is fetched first
+     * (with the same header scoping as the main URL) and the page is never
+     * consulted when it parses successfully.
+     */
+    specUrl?: string;
 }
 interface FetchResult {
     spec: JsonObject;
@@ -15,9 +41,84 @@ 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 {
+    /** Keep only operations carrying at least one of these tags. Repeatable. */
+    includeTags?: string[];
+    /** Drop operations carrying any of these tags. Repeatable. */
+    excludeTags?: string[];
+    /** Keep only operations whose path starts with this prefix. */
+    pathPrefix?: string;
+    /**
+     * Trim the digest until the (approximate, heuristic) token estimate fits this
+     * budget. The estimator is not tokenizer-accurate; treat the budget as a guide.
+     */
+    maxTokens?: number;
+    /** Receives non-fatal notices, e.g. unknown tag names. */
+    onWarning?: (message: string) => void;
+}
 /** Convert an OpenAPI 2.0, 3.0, or 3.1 document to a compact Markdown digest. */
-declare function transformOpenApiToMarkdown(spec: JsonObject, sourceUrl?: string): string;
+declare function transformOpenApiToMarkdown(spec: JsonObject, sourceUrl?: string, options?: TransformOptions): string;
 
 interface ModelTokenEstimate {
     name: string;
@@ -36,8 +137,9 @@ interface DigestTokenReport {
     };
 }
 /**
- * Estimates token counts for Markdown/code across 5 frontier model tokenizers.
- * Accurately models differences between cl100k/o200k, Claude BPE, SentencePiece 256k, and 128k BPE.
+ * Produces ROUGH token-count estimates for Markdown/code. The numbers are a
+ * heuristic (word + symbol density with per-model multipliers), not accurate
+ * tokenizer counts — use them as an order-of-magnitude guide only.
  */
 declare function estimateTokens(text: string): DigestTokenReport;
 
@@ -51,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 };
+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-UZQM2SHL.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,7 +1,7 @@
 {
   "name": "swagger-digest",
-  "version": "0.1.1",
-  "description": "Interactive CLI that converts Swagger UI pages and OpenAPI specs into compact Markdown for AI coding agents.",
+  "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",
   "types": "dist/index.d.ts",
@@ -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",
@@ -39,18 +40,20 @@
     "lint": "eslint .",
     "prepare": "husky",
     "prepack": "npm run build",
-    "prepublishOnly": "npm run build && npm test && npm run lint"
+    "prepublishOnly": "npm test"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20"
   },
   "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",
@@ -73,14 +76,12 @@
     }
   },
   "keywords": [
-    "swagger",
     "openapi",
-    "cli",
-    "ai",
-    "llm",
+    "swagger",
     "markdown",
-    "docs",
-    "ai-coding-agent"
+    "llm",
+    "ai-coding-agent",
+    "cli"
   ],
   "license": "MIT"
 }