swagger-digest 0.3.1 → 0.4.0

package/README.md

@@ -1,3 +1,5 @@
+<img width="1376" height="768" alt="Image" src="https://github.com/user-attachments/assets/6a9e4eb3-fea8-47b3-9296-e57b4a702c7c" />
+
 # swagger-digest
 
 [![npm version](https://img.shields.io/npm/v/swagger-digest)](https://www.npmjs.com/package/swagger-digest)
@@ -22,7 +24,7 @@ swagger-digest solves this at two levels: a **digest** (compact, complete, token
 
 ### Option 1: MCP server — recommended for AI coding agents
 
-Run it as an [MCP](https://modelcontextprotocol.io) server and your agent explores APIs on its own: it calls the `swagger_digest` tool with a Swagger UI page or spec URL and receives a compact digest directly in its context — discovery, filtering and token budgets handled for it.
+Run it as an [MCP](https://modelcontextprotocol.io) server and your agent explores APIs on its own: it calls the `swagger_digest` tool with a Swagger UI page or spec URL and receives a compact digest directly in its context — discovery, filtering and token budgets handled for it. Optionally, it can also execute requests against a trusted API with the `api_call` tool (see [Live API execution](#live-api-execution-api_call)).
 
 - **On-demand:** the agent fetches API context only when the task needs it.
 - **Scoped:** filter to specific tags or paths so only relevant operations enter context.
@@ -255,6 +257,57 @@ The `swagger_digest` tool:
 | `auto_trim`     | boolean          | Default-cap digests without `max_tokens` (default true)      |
 | `write_to_file` | object           | `{ directory, filename }` — save instead of returning inline |
 
+### Live API execution (`api_call`)
+
+Beyond reading documentation, the server can execute requests against **one trusted API origin**, turning the workflow from _read → implement → hope_ into _read → call → inspect → correct_. Non-2xx responses are returned as results (not errors) so error bodies can be inspected, and large response bodies are trimmed to a token budget.
+
+It is inactive until configured. Set the trusted origin when starting the server:
+
+```json
+{
+  "mcpServers": {
+    "swagger-digest": {
+      "command": ["npx", "-y", "swagger-digest-mcp"],
+      "environment": {
+        "SWAGGER_DIGEST_API_BASE_URL": "https://staging.example.com",
+        "SWAGGER_DIGEST_API_HEADER": "Authorization: Bearer sk-…",
+        "SWAGGER_DIGEST_API_METHODS": "get"
+      }
+    }
+  }
+}
+```
+
+The `api_call` tool:
+
+| Argument     | Type   | Description                                                       |
+| ------------ | ------ | ----------------------------------------------------------------- |
+| `path`       | string | API path starting with `/`, resolved against the trusted base URL |
+| `url`        | string | Absolute URL; its origin must equal the trusted base URL origin   |
+| `method`     | string | HTTP method (default `get`; writes need explicit opt-in)          |
+| `query`      | object | Query parameters; array values become repeated keys               |
+| `headers`    | object | Extra headers; credential-bearing names are rejected              |
+| `body`       | any    | JSON-serializable body (POST/PUT/PATCH/DELETE only)               |
+| `max_tokens` | number | Trim large response bodies to an approximate token budget         |
+
+Either `path` or `url` is required. Provide one, not both.
+
+Security model — enforced server-side, not by client approval:
+
+- **Single trusted origin.** Requests resolve only against `SWAGGER_DIGEST_API_BASE_URL`. Server URLs declared inside an OpenAPI spec are **never trusted implicitly** — a malicious spec could point at an attacker-controlled host, so absolute `url` arguments must match the configured origin and are refused otherwise.
+- **GET only by default.** Write methods require `SWAGGER_DIGEST_API_METHODS` (e.g. `get,post`); every method name is validated.
+- **Credentials never enter the conversation.** Authentication is injected server-side from `SWAGGER_DIGEST_API_HEADER`; tool arguments containing `authorization`, `cookie`, `x-api-key` and similar are rejected outright. Response bodies are scanned and any echoed credential is redacted.
+- **SSRF guard.** Private/loopback/metadata addresses are rejected per hop, including across redirects (same `SWAGGER_DIGEST_ALLOW_PRIVATE=1` escape hatch as the digest tool, for internal corporate APIs).
+- **Bounded.** Mandatory timeout (default 15 s, hard max 60 s), 1 MB request/response body cap (configurable), token-capped output.
+
+`api_call` environment variables:
+
+- `SWAGGER_DIGEST_API_BASE_URL` — the single trusted API origin (required; without it the tool explains how to configure itself).
+- `SWAGGER_DIGEST_API_HEADER` — newline-separated `Name: value` authentication headers (same format as `SWAGGER_DIGEST_HEADER`).
+- `SWAGGER_DIGEST_API_METHODS` — comma-separated enabled methods; default `get`.
+- `SWAGGER_DIGEST_API_TIMEOUT_MS` — request timeout (default 15000, hard max 60000).
+- `SWAGGER_DIGEST_API_MAX_BYTES` — request/response body cap in bytes (default 1048576).
+
 MCP environment variables:
 
 - `SWAGGER_DIGEST_HEADER` — newline-separated `Name: value` pairs, merged with (and overridden by) the call's `headers`. Keeps secrets out of the conversation.

package/dist/{chunk-MXTHI25H.js → chunk-2MQ33ITZ.js}

@@ -265,15 +265,19 @@ async function follow(url, defaultHeaders, userHeaders, options, maxBytes, redir
     options.onCrossOriginHeadersDropped?.(target.origin);
   }
   const requestHeaders = sameOrigin ? { ...defaultHeaders, ...userHeaders } : defaultHeaders;
+  const method = (options.method ?? "GET").toUpperCase();
+  const carriesBody = options.body !== void 0 && method !== "GET" && method !== "HEAD" && method !== "OPTIONS" && method !== "TRACE";
   const controller = new AbortController();
   const timeout = AbortSignal.timeout(options.timeoutMs);
   timeout.addEventListener("abort", () => controller.abort(), { once: true });
   let response;
   try {
     response = await fetch(target, {
+      method,
       headers: requestHeaders,
       redirect: "manual",
-      signal: controller.signal
+      signal: controller.signal,
+      ...carriesBody ? { body: options.body } : {}
     });
   } catch (error) {
     if (error instanceof FetchError) throw error;
@@ -293,9 +297,11 @@ async function follow(url, defaultHeaders, userHeaders, options, maxBytes, redir
     } catch {
     }
     const next = new URL(response.headers.get("location") ?? "", target);
-    return follow(next.toString(), defaultHeaders, userHeaders, options, maxBytes, redirectsLeft - 1);
+    const downgraded = response.status === 301 || response.status === 302 || response.status === 303;
+    const nextOptions = downgraded ? { ...options, method: "GET", body: void 0 } : { ...options };
+    return follow(next.toString(), defaultHeaders, userHeaders, nextOptions, maxBytes, redirectsLeft - 1);
   }
-  if (!response.ok) {
+  if (!response.ok && options.throwOnHttpError !== false) {
     await discardBodySafely(response);
     throw new FetchHttpError(`HTTP ${response.status} ${response.statusText} for ${url}`, response.status);
   }
@@ -314,6 +320,7 @@ async function follow(url, defaultHeaders, userHeaders, options, maxBytes, redir
     text,
     contentType: response.headers.get("content-type") ?? "",
     status: response.status,
+    statusText: response.statusText ?? "",
     url: target.toString()
   };
 }
@@ -2188,6 +2195,21 @@ function parseHeaderPairs(raw) {
   }
   return result;
 }
+var SENSITIVE_HEADER_NAMES = /* @__PURE__ */ new Set([
+  "authorization",
+  "proxy-authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "api-key",
+  "apikey",
+  "x-auth-token",
+  "x-access-token",
+  "x-session-token"
+]);
+function isSensitiveHeaderName(name) {
+  return SENSITIVE_HEADER_NAMES.has(name.trim().toLowerCase());
+}
 function mergeHeaders(...sources) {
   const result = {};
   for (const source of sources) {
@@ -2234,6 +2256,7 @@ async function writeDigest(options) {
 
 export {
   VERSION,
+  fetchWithLimits,
   toTypeScriptIdentifier,
   isOpenApiSpec,
   parseSpecText,
@@ -2243,6 +2266,7 @@ export {
   transformOpenApiToMarkdown,
   parseHeaderArgument,
   parseHeaderPairs,
+  isSensitiveHeaderName,
   mergeHeaders,
   defaultOutputDirectory,
   defaultFilename,

package/dist/chunk-UBR7FEJX.js

@@ -0,0 +1,392 @@
+import {
+  VERSION,
+  estimateTokens,
+  fetchOpenApiSpec,
+  fetchWithLimits,
+  isSensitiveHeaderName,
+  mergeHeaders,
+  parseHeaderPairs,
+  transformOpenApiToMarkdown,
+  writeDigest
+} from "./chunk-2MQ33ITZ.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";
+
+// src/mcp/api-call.ts
+var DEFAULT_TIMEOUT_MS = 15e3;
+var HARD_MAX_TIMEOUT_MS = 6e4;
+var DEFAULT_MAX_BYTES = 1024 * 1024;
+var ALL_METHODS = /* @__PURE__ */ new Set(["get", "head", "post", "put", "patch", "delete"]);
+var BODY_METHODS = /* @__PURE__ */ new Set(["post", "put", "patch", "delete"]);
+function parsePositiveInt(raw) {
+  if (raw === void 0 || raw.trim() === "") return void 0;
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function parseMethodsEnv(raw) {
+  if (raw === void 0 || raw.trim() === "") return void 0;
+  return raw.split(",").map((entry) => entry.trim().toLowerCase()).filter((entry) => entry !== "");
+}
+function isHttpUrl2(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function resolveApiCallConfig(options = {}, env = process.env) {
+  const baseUrlRaw = options.baseUrl ?? env.SWAGGER_DIGEST_API_BASE_URL;
+  if (baseUrlRaw === void 0 || baseUrlRaw.trim() === "") {
+    return {
+      error: 'api_call is not configured. Set SWAGGER_DIGEST_API_BASE_URL to the trusted API origin (for example "https://staging.example.com") when starting the MCP server. Requests are only ever sent to this origin \u2014 spec-declared server URLs are not trusted implicitly.'
+    };
+  }
+  let baseUrl;
+  try {
+    baseUrl = new URL(baseUrlRaw);
+  } catch {
+    return {
+      error: `Invalid SWAGGER_DIGEST_API_BASE_URL "${baseUrlRaw}": use an absolute http:// or https:// URL.`
+    };
+  }
+  if (baseUrl.protocol !== "http:" && baseUrl.protocol !== "https:") {
+    return { error: `Invalid SWAGGER_DIGEST_API_BASE_URL "${baseUrlRaw}": use an http:// or https:// URL.` };
+  }
+  const methodList = options.methods ?? parseMethodsEnv(env.SWAGGER_DIGEST_API_METHODS) ?? ["get"];
+  for (const method of methodList) {
+    if (!ALL_METHODS.has(method)) {
+      return {
+        error: `Unknown method "${method}" in the api_call method list. Allowed: ${[...ALL_METHODS].join(", ")}.`
+      };
+    }
+  }
+  const methods = new Set(methodList);
+  let authHeaders = {};
+  if (options.authHeaders !== void 0) {
+    authHeaders = options.authHeaders;
+  } else if (env.SWAGGER_DIGEST_API_HEADER !== void 0) {
+    try {
+      authHeaders = parseHeaderPairs(env.SWAGGER_DIGEST_API_HEADER);
+    } catch (error) {
+      return {
+        error: `Invalid SWAGGER_DIGEST_API_HEADER: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
+  }
+  const requestedTimeout = options.timeoutMs ?? parsePositiveInt(env.SWAGGER_DIGEST_API_TIMEOUT_MS) ?? DEFAULT_TIMEOUT_MS;
+  const timeoutMs = Math.min(Math.max(requestedTimeout, 1), HARD_MAX_TIMEOUT_MS);
+  const maxBytes = options.maxBytes ?? parsePositiveInt(env.SWAGGER_DIGEST_API_MAX_BYTES) ?? DEFAULT_MAX_BYTES;
+  const blockPrivateNetworks = options.blockPrivateNetworks ?? env.SWAGGER_DIGEST_ALLOW_PRIVATE !== "1";
+  return { config: { baseUrl, methods, authHeaders, timeoutMs, maxBytes, blockPrivateNetworks } };
+}
+function textContent2(text) {
+  return [{ type: "text", text }];
+}
+function asError2(message) {
+  return { content: textContent2(message), isError: true };
+}
+function estimateResponseTokens(text) {
+  const heuristic = estimateTokens(text).models.claude.tokens;
+  return Math.max(heuristic, Math.ceil(text.length / 4));
+}
+function trimToTokenBudget(text, maxTokens) {
+  const estimated = estimateResponseTokens(text);
+  if (estimated <= maxTokens) return { text, trimmed: false };
+  const marker = "\n\u2026[response truncated to fit the max_tokens budget]";
+  const keep = Math.max(0, Math.floor(text.length * maxTokens / estimated) - marker.length);
+  return { text: text.slice(0, keep) + marker, trimmed: true };
+}
+function redactSecrets(text, secrets) {
+  let result = text;
+  for (const secret of secrets) {
+    if (secret.length >= 8) result = result.split(secret).join("[REDACTED]");
+  }
+  return result;
+}
+async function runApiCall(args, options = {}) {
+  const { config, error } = resolveApiCallConfig(options);
+  if (error !== void 0 || config === void 0) return asError2(error ?? "api_call configuration error.");
+  if (args.max_tokens !== void 0 && (!Number.isInteger(args.max_tokens) || args.max_tokens <= 0)) {
+    return asError2(`Invalid max_tokens ${args.max_tokens}: use a positive integer.`);
+  }
+  const method = (args.method ?? "get").trim().toLowerCase();
+  if (!ALL_METHODS.has(method)) {
+    return asError2(
+      `Unknown method "${method}". Allowed: ${[...ALL_METHODS].join(", ")}. Enabled methods are controlled by SWAGGER_DIGEST_API_METHODS (default: get).`
+    );
+  }
+  if (!config.methods.has(method)) {
+    return asError2(
+      `Method "${method}" is not enabled. Enabled methods: ${[...config.methods].sort().join(", ")}. Write methods require an explicit opt-in: set SWAGGER_DIGEST_API_METHODS (e.g. "get,post") when starting the server.`
+    );
+  }
+  let target;
+  if (args.url !== void 0 && args.path !== void 0) {
+    return asError2("Provide either `url` or `path`, not both.");
+  }
+  if (args.url !== void 0) {
+    if (!isHttpUrl2(args.url)) {
+      return asError2(`Invalid url "${args.url}": use an http:// or https:// URL.`);
+    }
+    target = new URL(args.url);
+  } else if (typeof args.path === "string") {
+    if (!args.path.startsWith("/")) {
+      return asError2(
+        `Invalid path "${args.path}": paths must start with "/" and are resolved against the configured base URL.`
+      );
+    }
+    target = new URL(args.path, config.baseUrl);
+  } else {
+    return asError2(
+      'Provide a target: `path` (e.g. "/v1/refunds", resolved against SWAGGER_DIGEST_API_BASE_URL) or an absolute `url` on the configured trusted origin.'
+    );
+  }
+  if (target.origin !== config.baseUrl.origin) {
+    return asError2(
+      `Refusing to call ${target.origin}: api_call only sends requests to the configured trusted origin ${config.baseUrl.origin} (SWAGGER_DIGEST_API_BASE_URL). Origins declared inside an OpenAPI specification are never trusted implicitly \u2014 a malicious spec could otherwise redirect credentials.`
+    );
+  }
+  for (const [key, value] of Object.entries(args.query ?? {})) {
+    if (Array.isArray(value)) {
+      for (const item of value) target.searchParams.append(key, String(item));
+    } else {
+      target.searchParams.set(key, String(value));
+    }
+  }
+  let bodyText;
+  if (args.body !== void 0) {
+    if (!BODY_METHODS.has(method)) {
+      return asError2(`Method "${method}" cannot carry a request body.`);
+    }
+    try {
+      bodyText = JSON.stringify(args.body);
+    } catch {
+      return asError2("Invalid body: it must be JSON-serializable.");
+    }
+    if (bodyText.length > 0 && Buffer.byteLength(bodyText) > config.maxBytes) {
+      return asError2(
+        `Request body is ${Buffer.byteLength(bodyText)} bytes, exceeding the ${config.maxBytes} byte limit (SWAGGER_DIGEST_API_MAX_BYTES).`
+      );
+    }
+  }
+  for (const name of Object.keys(args.headers ?? {})) {
+    if (isSensitiveHeaderName(name)) {
+      return asError2(
+        `Refusing to send "${name}" from tool arguments: authentication headers are injected server-side via SWAGGER_DIGEST_API_HEADER so credentials never enter tool-call transcripts.`
+      );
+    }
+  }
+  const requestHeaders = mergeHeaders(config.authHeaders, args.headers);
+  if (bodyText !== void 0) {
+    requestHeaders["content-type"] = args.headers?.["content-type"] ?? args.headers?.["Content-Type"] ?? "application/json";
+  }
+  const warnings = [];
+  let result;
+  try {
+    result = await fetchWithLimits(target.toString(), {
+      timeoutMs: config.timeoutMs,
+      maxBytes: config.maxBytes,
+      blockPrivateNetworks: config.blockPrivateNetworks,
+      headers: requestHeaders,
+      allowedHeaderOrigin: config.baseUrl.origin,
+      onCrossOriginHeadersDropped: (origin) => warnings.push(`Request redirected cross-origin to ${origin}; authentication headers were withheld.`),
+      method,
+      body: bodyText,
+      throwOnHttpError: false
+    });
+  } catch (requestError) {
+    const message = requestError instanceof Error ? requestError.message : String(requestError);
+    return asError2(`api_call failed: ${message}`);
+  }
+  let responseBody = redactSecrets(result.text, Object.values(config.authHeaders));
+  let wasTrimmed = false;
+  if (args.max_tokens !== void 0) {
+    const trimmedResult = trimToTokenBudget(responseBody, args.max_tokens);
+    responseBody = trimmedResult.text;
+    wasTrimmed = trimmedResult.trimmed;
+  }
+  const tokens = estimateResponseTokens(responseBody);
+  const bytes = Buffer.byteLength(result.text);
+  const head = [`status: ${result.status}${result.statusText ? ` ${result.statusText}` : ""}`];
+  head.push(`url: ${result.url}`);
+  head.push(`content-type: ${result.contentType || "unknown"}`);
+  const nonOkNote = result.status >= 400 ? `
+
+_Non-OK response returned as a result (not an error) so the body can be inspected._` : "";
+  const warningBlock = warnings.length > 0 ? `
+
+_Warnings:_
+${warnings.map((w) => `- ${w}`).join("\n")}` : "";
+  const metadata = `${bytes.toLocaleString("en-US")} bytes \xB7 ~${tokens.toLocaleString("en-US")} tokens estimated` + (wasTrimmed ? " \xB7 trimmed to max_tokens" : "");
+  return {
+    content: textContent2(
+      `${head.join("\n")}
+
+${responseBody}${nonOkNote}
+
+---
+_api_call metadata: ${metadata}_${warningBlock}`
+    )
+  };
+}
+
+// src/mcp/server.ts
+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)
+  );
+  server.registerTool(
+    "api_call",
+    {
+      title: "Execute an API request",
+      description: "Execute an HTTP request against the trusted API origin configured via SWAGGER_DIGEST_API_BASE_URL (set when the MCP server starts; the tool returns a clear configuration error when it is unset). Use it after swagger_digest to verify how the real API behaves: send GET (default) or, when write methods were enabled via SWAGGER_DIGEST_API_METHODS, POST/PUT/PATCH/DELETE. Provide either `path` (resolved against the trusted origin) or an absolute `url` on that same origin \u2014 other origins are refused, and server URLs declared inside an OpenAPI spec are never trusted implicitly. Authentication headers are injected server-side; credential headers in arguments are rejected. Non-2xx responses are returned as results (not errors) so error bodies can be inspected. Responses are size- and token-capped.",
+      inputSchema: {
+        url: z.string().optional().describe("Absolute http(s) URL whose origin must equal the configured trusted API origin"),
+        path: z.string().optional().describe('API path starting with "/", e.g. "/v1/refunds" \u2014 resolved against SWAGGER_DIGEST_API_BASE_URL'),
+        method: z.string().optional().describe('HTTP method (default "get"). Write methods require SWAGGER_DIGEST_API_METHODS opt-in'),
+        query: z.record(
+          z.string(),
+          z.union([z.string(), z.number(), z.boolean(), z.array(z.union([z.string(), z.number(), z.boolean()]))])
+        ).optional().describe("Query parameters; array values become repeated keys"),
+        headers: z.record(z.string(), z.string()).optional().describe(
+          "Extra request headers. Credential-bearing names (authorization, cookie, x-api-key, \u2026) are rejected; authentication comes from SWAGGER_DIGEST_API_HEADER"
+        ),
+        body: z.unknown().optional().describe("JSON-serializable request body (POST/PUT/PATCH/DELETE only)"),
+        max_tokens: z.number().int().positive().optional().describe("Trim large response bodies to approximately this token budget")
+      }
+    },
+    (args) => runApiCall(args, options.apiCall)
+  );
+  return server;
+}
+
+export {
+  buildRequestHeaders,
+  runSwaggerDigest,
+  createMcpServer
+};

package/dist/cli.js

@@ -10,7 +10,7 @@ import {
   parseHeaderPairs,
   transformOpenApiToMarkdown,
   writeDigest
-} from "./chunk-MXTHI25H.js";
+} from "./chunk-2MQ33ITZ.js";
 
 // src/cli.ts
 import { input } from "@inquirer/prompts";

package/dist/index.d.ts

@@ -97,13 +97,40 @@ declare function buildRequestHeaders(args: Pick<McpDigestArgs, 'headers'>): Reco
 declare function runSwaggerDigest(args: McpDigestArgs, options?: DigestServerOptions): Promise<CallToolResult>;
 
 /**
- * Builds the MCP server exposing the `swagger_digest` tool.
+ * Server-wide configuration for `api_call`. Tests pass these explicitly; the
+ * stdio entry point derives them from the environment (see resolveApiCallConfig).
+ */
+interface ApiCallServerOptions {
+    /** Reject URLs resolving to loopback/private/metadata addresses. Defaults to true. */
+    blockPrivateNetworks?: boolean;
+    /** Trusted API origin. Overrides SWAGGER_DIGEST_API_BASE_URL. */
+    baseUrl?: string;
+    /** Enabled HTTP methods (lowercase). Overrides SWAGGER_DIGEST_API_METHODS. */
+    methods?: string[];
+    /** Server-injected authentication headers. Overrides SWAGGER_DIGEST_API_HEADER. */
+    authHeaders?: Record<string, string>;
+    /** Request timeout in ms. Overrides SWAGGER_DIGEST_API_TIMEOUT_MS (hard max 60 s). */
+    timeoutMs?: number;
+    /** Maximum response/request body size in bytes. Overrides SWAGGER_DIGEST_API_MAX_BYTES. */
+    maxBytes?: number;
+}
+
+/** Options for the whole MCP server: shared behavior plus per-tool overrides. */
+interface SwaggerDigestMcpOptions extends DigestServerOptions {
+    /**
+     * Configuration overrides for the `api_call` tool. Tests inject these;
+     * production derives them from SWAGGER_DIGEST_API_* environment variables.
+     */
+    apiCall?: ApiCallServerOptions;
+}
+/**
+ * Builds the MCP server exposing the `swagger_digest` and `api_call` tools.
  *
  * 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 createMcpServer(options?: SwaggerDigestMcpOptions): McpServer;
 
 declare function toTypeScriptIdentifier(value: string): string;
 

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   buildRequestHeaders,
   createMcpServer,
   runSwaggerDigest
-} from "./chunk-DJES77HX.js";
+} from "./chunk-UBR7FEJX.js";
 import {
   DEFAULT_MAX_TOKENS,
   defaultFilename,
@@ -16,7 +16,7 @@ import {
   toTypeScriptIdentifier,
   transformOpenApiToMarkdown,
   writeDigest
-} from "./chunk-MXTHI25H.js";
+} from "./chunk-2MQ33ITZ.js";
 export {
   DEFAULT_MAX_TOKENS,
   buildRequestHeaders,

package/dist/mcp/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import {
   createMcpServer
-} from "../chunk-DJES77HX.js";
-import "../chunk-MXTHI25H.js";
+} from "../chunk-UBR7FEJX.js";
+import "../chunk-2MQ33ITZ.js";
 
 // src/mcp/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swagger-digest",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Turn Swagger UI pages and OpenAPI specs into compact, AI-friendly Markdown API digests.",
   "type": "module",
   "main": "dist/index.js",

package/dist/chunk-DJES77HX.js

@@ -1,147 +0,0 @@
-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
-};