swagger-digest 0.3.0 → 0.4.0

package/README.md

@@ -1,101 +1,143 @@
+<img width="1376" height="768" alt="Image" src="https://github.com/user-attachments/assets/6a9e4eb3-fea8-47b3-9296-e57b4a702c7c" />
+
 # swagger-digest
 
-`swagger-digest` is an interactive Node.js CLI that converts a Swagger UI page or raw OpenAPI/Swagger spec into a compact Markdown reference designed for AI coding agents and LLM context windows.
+[![npm version](https://img.shields.io/npm/v/swagger-digest)](https://www.npmjs.com/package/swagger-digest)
+[![license](https://img.shields.io/npm/l/swagger-digest)](https://github.com/VladLegkowski/swagger-digest)
+[![node](https://img.shields.io/badge/node-%3E%3D20-blue)](https://www.npmjs.com/package/swagger-digest)
+[![MCP server](https://img.shields.io/badge/MCP-server-8a5cf5)](https://modelcontextprotocol.io)
 
-## Quick start
+**An API context engine for AI coding agents.** Turn large Swagger/OpenAPI specifications into compact, structured, searchable API context — as Markdown digests or through an on-demand MCP server.
 
-```bash
-npx swagger-digest
-```
+A 600-operation spec like Stripe's is ~2M tokens of raw JSON — several times most models' context windows, and mostly noise even when it fits. swagger-digest reduces it to ~560k tokens of structured Markdown (benchmark below), and its MCP server lets your agent pull in only the endpoints and schemas it needs, when it needs them.
 
-The CLI asks for a URL, a destination directory (Downloads by default), and an output filename such as `payments-api-digest.md`.
+## The problem
 
-You can also provide arguments:
+- Real specifications contain hundreds of endpoints and thousands of lines of JSON/YAML.
+- Pasting a raw spec into an AI coding agent burns context on boilerplate — descriptions repeated per operation, example payloads, schema trees.
+- Finding the endpoints relevant to your task — and understanding their parameters and response shapes — means manually wading through the contract.
+- Agents generating frontend code need accurate API contracts. Guessing field names from partial context produces broken integrations.
 
-```bash
-npx swagger-digest \
-  --url https://petstore.swagger.io/ \
-  --out-dir ./docs \
-  --filename petstore-digest.md
-```
+swagger-digest solves this at two levels: a **digest** (compact, complete, token-budgeted Markdown) and an **MCP server** (on-demand API context for agents).
+
+## Two ways to use it
+
+### Option 1: MCP server — recommended for AI coding agents
 
-For a direct spec URL:
+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.
+- **Discovery built in:** point it at a Swagger UI page — it finds the spec automatically (initializer scripts, multi-spec dropdowns, common spec paths).
+- **Ideal for ongoing development work**, where the agent revisits the same API repeatedly without you re-pasting documentation.
+
+Install in your MCP client (stdio transport; the client spawns the process):
 
 ```bash
-npx swagger-digest --url https://example.com/openapi.yaml --out-dir ./docs
+# OpenCode
+opencode mcp add swagger-digest -- npx -y swagger-digest-mcp
 ```
 
-If the Swagger UI initializer lists several spec definitions (`urls: [{ url, name }, …]`), the tool probes them in the order they appear and uses the first one that parses, printing a notice to stderr naming the pick and the alternatives. To choose a specific spec yourself, pass it explicitly:
+```json
+// JSON-configured clients (Claude Desktop, Cursor, …)
+{
+  "mcpServers": {
+    "swagger-digest": {
+      "command": ["npx", "-y", "swagger-digest-mcp"]
+    }
+  }
+}
+```
+
+Tool arguments and environment variables are documented in [MCP configuration](#mcp-configuration).
+
+### Option 2: Markdown digest
+
+Generate a compact Markdown reference from any Swagger UI page or OpenAPI/Swagger spec — for documentation, sharing, or feeding API context into agents that don't use MCP.
 
 ```bash
-npx swagger-digest --url https://api.example.com/swagger-ui \
-  --spec https://api.example.com/v2/tenant-a.json --out-dir ./docs
+# Interactive
+npx swagger-digest
+
+# Direct: fetch, digest, save
+npx swagger-digest --url https://petstore.swagger.io/ --out-dir ./docs
+
+# To stdout (pipes stay clean; progress goes to stderr)
+npx swagger-digest --url https://petstore.swagger.io/ --stdout | pbcopy
+
+# Keep only the operations you need
+npx swagger-digest --url https://api.example.com/openapi.json \
+  --include-tag Subscriptions --path-prefix /v1/ --out-dir ./docs
 ```
 
-`--spec` overrides all discovery: the given URL is fetched directly (with the same header scoping and size limits) and the Swagger UI page is never consulted when it parses successfully.
+Output is a structured Markdown document: endpoint index, per-tag operation details (auth, parameters, request/response bodies, examples), and TypeScript-like data type declarations. Save it next to your code, paste it into a PR, or drop it into your agent's context manually.
 
-### Writing to stdout
+## Quick start
 
 ```bash
-npx swagger-digest --url https://petstore.swagger.io/ --stdout > petstore.md
-npx swagger-digest --url https://api.example.com/openapi.json --stdout | pbcopy
+# 1. Generate a digest from a public API (interactive prompts, saved to ~/Downloads)
+npx swagger-digest --url https://petstore.swagger.io/
+
+# 2. Or generate to stdout
+npx swagger-digest --url https://petstore.swagger.io/ --stdout > petstore-digest.md
+
+# 3. Register the MCP server (OpenCode example)
+opencode mcp add swagger-digest -- npx -y swagger-digest-mcp
 ```
 
-`--stdout` prints the digest to standard output instead of saving a file — handy for piping into other tools or copying to the clipboard. Progress and warnings go to stderr, so the pipe receives only the Markdown. `--stdout` cannot be combined with `--out-dir` or `--filename`; the CLI exits with a clear error if you try.
+Requires Node.js 20+. Run `npx swagger-digest --help` for all options.
 
-Run `npx swagger-digest --help` for all CLI options. The package requires Node.js 20 or newer.
+## Real-world example: building a subscriptions page
 
-## MCP server
+A React/TypeScript developer asks their AI coding agent:
 
-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.
+> "Implement a subscription management page against our billing API — docs are at https://api.example.com/swagger-ui"
 
-```bash
-npx swagger-digest-mcp
-```
+**Without swagger-digest**, the agent either guesses the API contract or you paste thousands of lines of raw JSON into the conversation.
 
-It speaks the stdio transport: the MCP client spawns the process and communicates over stdin/stdout. Register it in your client's configuration:
+**With the MCP server**, the agent calls the tool itself:
 
 ```json
 {
-  "mcp": {
-    "swagger-digest": {
-      "command": ["npx", "-y", "swagger-digest-mcp"]
-    }
-  }
+  "url": "https://api.example.com/swagger-ui",
+  "include_tags": ["Subscriptions"]
 }
 ```
 
-### The `swagger_digest` tool
+and receives only the relevant slice — in this illustrative excerpt of digest output:
 
-| 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 |
+```markdown
+#### `GET /v1/subscriptions/{id}`
 
-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.
+**Authentication:** Bearer
 
-### Environment variables
+**Parameters**
 
-- `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).
+- `id` (`path`, required) · `string` — Subscription identifier.
+- `expand` (`query`, optional) · `string[]` — Fields to expand.
 
-### Security differences from the CLI
+**Responses**
 
-- **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.
+- **200 OK** — `Subscription` (application/json)
+
+## Data types
+
+export interface Subscription {
+id?: string;
+status?: "active" | "canceled" | "past_due";
+current_period_end?: number;
+items?: SubscriptionItems;
+[key: string]: unknown;
+}
+```
+
+From there the agent can: confirm the exact path, method and required parameters; read the `Subscription` schema and its referenced types; generate TypeScript types that match the contract; and implement the page without guessing. If the digest is too large, the agent re-calls with `path_prefix` or `max_tokens` to narrow it further.
 
 ## 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**
+**7/10 wins · 100% operation coverage on every digest produced · 1.6–3.7× lighter · 1 tool call vs 1–5 fetch/guess attempts**
 
 | Spec                | Ops   | Raw tokens             | Digest tokens           | Compression | Op coverage | Winner  |
 | ------------------- | ----- | ---------------------- | ----------------------- | ----------- | ----------- | ------- |
@@ -112,6 +154,8 @@ Ten public APIs, digest vs. raw spec JSON in an LLM context, ground truth from t
 
 > 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.
 
+**Why token efficiency matters:** an agent's context window is shared between your codebase, the conversation, and every tool result. A raw spec that consumes 500k tokens crowds out everything else; the same API as a 150k-token digest leaves room to work — and smaller digests mean faster, cheaper, more focused generations.
+
 \* 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)
@@ -122,134 +166,225 @@ Ten public APIs, digest vs. raw spec JSON in an LLM context, ground truth from t
 | 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
+Not every specification benefits: very large kitchen-sink specs are where compression can invert — handled by the default cap, but worth knowing.
 
-Large specs produce large digests. The CLI can remove whole operations before rendering and/or trim the remaining digest to an approximate token budget:
+## Feature overview
 
-```bash
-# Keep only operations tagged "Payments", plus everything under /invoices
-npx swagger-digest --url https://api.example.com/openapi.json \
-  --include-tag Payments --path-prefix /payments/ --out-dir ./docs
+**Ingestion and discovery**
 
-# Drop a noisy tag
-npx swagger-digest --url https://api.example.com/openapi.json --exclude-tag Internal
+- Fetches direct OpenAPI JSON/YAML URLs and Swagger UI pages (OpenAPI 2.0, 3.0, 3.1).
+- Multi-strategy discovery: direct spec URL → page script configuration (`url:`, `urls:` dropdown, inline `spec:`, dynamically computed initializer URLs) → common spec paths (`/v3/api-docs`, `/swagger.json`, …) → optional headless-browser fallback.
+- Multi-spec Swagger UI dropdowns: probes candidates in order, uses the first that parses, names the pick.
+- External `$ref` bundling: references to other HTTP(S) documents are fetched and inlined under namespaced names (one level deep, at most 5 documents).
 
-# Fit the digest into a model's context window
-npx swagger-digest --url https://api.example.com/openapi.json --max-tokens 50000
-```
+**Markdown generation**
+
+- Endpoint index plus per-tag operation details: auth requirements, path/query/header parameters, request bodies, success/error responses, examples.
+- TypeScript-like type declarations for reachable schemas; `allOf`/`oneOf`/`anyOf`, enums, arrays, nullable fields, `additionalProperties` get compact representations.
+- Unknown schema constructs render as `unknown` instead of failing the digest.
+- Synthetic examples generated from schemas when none are declared, clearly marked as illustrative.
+
+**MCP server**
 
-How `--max-tokens` trims (in this fixed order, re-checked against the estimate after each step):
+- Single `swagger_digest` tool over stdio; digest returned inline in the tool result with metadata (retrieval method, operation/model counts, token estimate), or written to a file.
+- Same discovery and filtering pipeline as the CLI; optional Playwright fallback disabled.
+- Private-network (SSRF) guard on by default, because URLs come from the model.
 
-1. Drop declared example payloads (synthetic examples are never emitted).
-2. Shorten long descriptions.
-3. Collapse parameter/response detail per tag — the **tag priority rule** is that the tag appearing **last in the document** is collapsed first (lowest priority), one tag per step.
-4. Keep only the Quick index entries (no endpoint detail, no data types).
+**Filtering and token management**
 
-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.
+- Filter by tags (`include_tags`/`exclude_tags`) and path prefix, before rendering.
+- `max_tokens` budget with deterministic trim order; `## Trimmed` note records exactly what was removed.
+- Automatic 250,000-token default cap for unbounded digests.
 
-**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).
+**Authentication and remote access**
 
-The same options are available programmatically via the third argument of `transformOpenApiToMarkdown(spec, sourceUrl, { includeTags, excludeTags, pathPrefix, maxTokens, onWarning })`.
+- Origin-scoped custom headers and cookies: sent only to the origin you supply, never logged, never written to the digest.
+- `SWAGGER_DIGEST_HEADER` environment variable for secrets outside the command line.
+- Hardened fetching: response size cap (10 MB), redirect limit (5), timeouts, optional private-network blocking.
 
-## What it extracts
+## Configuration and advanced usage
 
-The retrieval strategy deliberately avoids scraping rendered operation accordions or simulating UI clicks:
+### CLI reference
 
-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, 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.
+| Option                         | Description                                               |
+| ------------------------------ | --------------------------------------------------------- |
+| `-u, --url <url>`              | Swagger UI page URL or direct OpenAPI spec URL            |
+| `-d, --out-dir <directory>`    | Destination directory for the digest file                 |
+| `-f, --filename <filename>`    | Output filename (defaults to `<api-title>-digest.md`)     |
+| `--stdout`                     | Print to stdout instead of writing a file                 |
+| `--spec <url>`                 | Explicit spec URL; overrides all discovery                |
+| `--include-tag <tag>`          | Keep only operations with this tag (repeatable)           |
+| `--exclude-tag <tag>`          | Drop operations with this tag (repeatable)                |
+| `--path-prefix <prefix>`       | Keep only operations whose path starts with this prefix   |
+| `--max-tokens <n>`             | Trim the digest until the token estimate fits this budget |
+| `--no-auto-trim`               | Disable the automatic 250,000-token default cap           |
+| `--max-bytes <bytes>`          | Maximum response size (default 10,000,000)                |
+| `-H, --header <"Name: value">` | Custom request header, repeatable; origin-scoped          |
+| `--cookie <string>`            | Convenience for a Cookie header; origin-scoped            |
+| `--no-browser`                 | Disable the optional Playwright fallback                  |
 
-The first three paths use ordinary HTTP requests. The browser fallback is optional so the normal install stays lightweight. To enable it for a difficult JavaScript-initialized Swagger UI deployment:
+### MCP configuration
+
+Register the server (stdio transport):
 
 ```bash
-npm install playwright
-npx playwright install chromium
+# OpenCode
+opencode mcp add swagger-digest -- npx -y swagger-digest-mcp
 ```
 
-Then run the CLI again. Use `--no-browser` to disable the fallback.
+```json
+// JSON-configured clients
+{
+  "mcpServers": {
+    "swagger-digest": {
+      "command": ["npx", "-y", "swagger-digest-mcp"]
+    }
+  }
+}
+```
 
-### Authentication headers
+The `swagger_digest` tool:
 
-Some Swagger UI pages and spec URLs live behind authentication. Pass custom headers with `-H`/`--header` (repeatable) or `--cookie`:
+| Argument        | Type             | Description                                                  |
+| --------------- | ---------------- | ------------------------------------------------------------ |
+| `url`           | string, required | Swagger UI page URL or direct OpenAPI spec URL               |
+| `spec_url`      | string           | Explicit spec URL; overrides discovery                       |
+| `headers`       | object           | Request headers; 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               |
+| `auto_trim`     | boolean          | Default-cap digests without `max_tokens` (default true)      |
+| `write_to_file` | object           | `{ directory, filename }` — save instead of returning inline |
 
-```bash
-npx swagger-digest \
-  --url https://api.example.com/swagger-ui \
-  --header "Authorization: Bearer eyJhbGciOi..." \
-  --out-dir ./docs
-```
+### Live API execution (`api_call`)
 
-Or with a session cookie:
+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.
 
-```bash
-npx swagger-digest --url https://api.example.com/swagger-ui --cookie "session=abc123"
+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"
+      }
+    }
+  }
+}
 ```
 
-You can also supply headers through the `SWAGGER_DIGEST_HEADER` environment variable, with one `Name: value` pair per line. `-H` flags override environment entries on conflicting header names:
+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.
+- `SWAGGER_DIGEST_ALLOW_PRIVATE=1` — opt out of the private-network guard; only for hosts you trust, e.g. internal corporate APIs.
+
+MCP-specific behavior: URLs resolving to loopback/private/link-local addresses are rejected by default (MCP clients supply URLs on the model's behalf); diagnostics go to stderr, protocol frames to stdout.
+
+### Authentication headers (CLI)
 
 ```bash
+npx swagger-digest --url https://api.example.com/swagger-ui \
+  --header "Authorization: Bearer eyJhbGciOi..." --out-dir ./docs
+
+# or a session cookie
+npx swagger-digest --url https://api.example.com/swagger-ui --cookie "session=abc123"
+
+# or the environment variable (-H flags win on conflicts)
 export SWAGGER_DIGEST_HEADER=$'Authorization: Bearer eyJ…\nX-Tenant: acme'
 npx swagger-digest --url https://api.example.com/swagger-ui
 ```
 
-**Scoping and safety:**
+**Scoping and safety:** custom headers are sent **only** to the origin of the URL you supply; cross-origin requests (redirects, discovered specs on other origins) proceed without them and produce a warning naming the other origin. In the headless-browser fallback, headers are injected per-request for your origin only — they never reach CDNs or third-party scripts. Header values are never logged, written to the digest, or included in error messages. Secrets passed with `-H` can end up in shell history — prefer the environment variable.
 
-- Custom headers are sent **only** to the origin of the URL you supply. If the discovered spec, a redirect, or a Swagger UI script lives on a different origin, that request is made without your headers and a warning naming the other origin is printed to stderr.
-- In the headless-browser fallback, headers are injected per-request (only for your origin) — they never reach CDNs or third-party scripts loaded by the page.
-- Header values are never logged, written to the digest, or included in error messages.
-- ⚠️ **Shell history:** secrets passed with `-H` can end up in your shell history file (`~/.bash_history`, `~/.zsh_history`). Prefer the `SWAGGER_DIGEST_HEADER` environment variable, or prefix the command with a space if your shell is configured to ignore leading-space entries.
+### Programmatic API
 
-### Troubleshooting access through a VPN
+```ts
+import { fetchOpenApiSpec, transformOpenApiToMarkdown, estimateTokens } from 'swagger-digest';
 
-The ordinary HTTP fetches use Node.js networking; they do not automatically reuse a browser's VPN extension, cookies, or signed-in session. If the Swagger page works in Chrome but not in the CLI, first test the same URL from the terminal:
-
-```bash
-curl -v -L 'https://your-host.example/path/to/swagger-ui' -o /tmp/swagger-page.html
+const { spec, sourceUrl } = await fetchOpenApiSpec('https://api.example.com/openapi.json', {
+  blockPrivateNetworks: true, // recommended when URLs come from untrusted input
+  headers: { Authorization: 'Bearer …' },
+});
+const markdown = transformOpenApiToMarkdown(spec, sourceUrl, {
+  includeTags: ['Subscriptions'],
+  maxTokens: 50_000,
+  onWarning: console.warn,
+});
+console.log(estimateTokens(markdown).models.claude.tokens);
 ```
 
-If `curl` cannot connect or receives `401`/`403`, connect a system-level VPN that also routes terminal applications, or configure the relevant corporate proxy/authentication for the terminal. Installing Playwright alone does not make a browser-only VPN extension available to its separate Chromium instance. If terminal access succeeds, the extractor now also reads same-origin Swagger UI initializer/config scripts and tries spec paths relative to the supplied page's context path.
-
-## Security notes
+`transformOpenApiToMarkdown` options: `includeTags`, `excludeTags`, `pathPrefix`, `maxTokens`, `autoTrim` (default true), `onWarning`. `fetchOpenApiSpec` options include `specUrl`, `headers`, `maxBytes`, `blockPrivateNetworks`, `useBrowserFallback`.
 
-**What the tool fetches:** the URL you supply (a Swagger UI page or direct OpenAPI JSON/YAML URL), same-origin Swagger UI initializer/config scripts, the spec URL referenced by that page, and a short list of common spec paths on the same origin (`/v3/api-docs`, `/swagger.json`, …). The optional Playwright fallback loads the same page in a headless browser.
+### Trimming order
 
-**What it does not forward:** cookies or Authorization headers are never sent automatically. Custom headers you pass with `--header`/`--cookie` (see below) are sent **only** to the origin of the URL you supplied. If the page redirects to another origin, or the discovered spec lives on a different origin, those requests are made without your headers and a warning naming the other origin is printed to stderr. Response bodies are capped (10 MB by default, configurable with `--max-bytes`), and redirects are followed at most 5 times.
+When a budget applies (explicit `--max_tokens` or the default cap), the digest is trimmed in this fixed order, re-checked after each step: 1) drop declared example payloads → 2) shorten long descriptions → 3) collapse parameter/response detail per tag (the tag appearing last in the document is collapsed first) → 4) keep only the Quick index. A `## Trimmed` note records exactly which steps applied; schemas referenced only by removed operations are dropped. The estimator is a heuristic — treat budgets as a guide, not a guarantee.
 
-**Embedding in a server:** if you call `fetchOpenApiSpec` from a server that accepts user-supplied URLs, enable `blockPrivateNetworks: true` in the fetch options. Without it, a caller can point the tool at `http://169.254.169.254/…` or other internal addresses from your infrastructure (SSRF). The check rejects loopback, link-local (including the cloud-metadata address 169.254.169.254), private, and unique-local addresses, and applies after redirects. Note the documented DNS-rebinding limitation in the code — for hostile multi-tenant input, use a dedicated egress proxy.
+## Supported specifications and limitations
 
-## Markdown format
+**Supported:** OpenAPI 2.0, 3.0 and 3.1, in JSON or YAML, fetched over HTTP(S) from direct spec URLs or discovered through Swagger UI pages.
 
-The generated document includes:
+**Limitations:**
 
-- API title, OpenAPI/Swagger version, API version, base URL(s), and authentication schemes.
-- A compact endpoint index (`Method`, `Path`, `Summary`, and `Tags`).
-- Endpoint details grouped by tag, including auth requirements, path/query/header parameters, request bodies, success/error responses, and JSON example values.
-- TypeScript-like interface/type declarations for schemas reachable from the documented operations, with local `$ref` dependencies expanded as named type references rather than copied JSON Schema trees.
+- The tool downloads specs exposed by the supplied server. It does not bypass authentication, browser access controls, or network restrictions. Ordinary HTTP fetches use Node.js networking — they do not reuse a browser's VPN extension, cookies, or signed-in session. If a page works in Chrome but not here, test `curl -v -L '<url>'` from the terminal; if that fails too, route the terminal through your VPN/proxy.
+- External `$ref` documents are bundled best-effort (one level deep, at most 5 documents); unreachable references degrade to named type references and the digest still succeeds.
+- Very large specs: fetches are capped at 10 MB by default (`--max-bytes`), and digests are capped at ~250k estimated tokens by default (see trimming above).
+- A generated digest is a compact developer reference, not a replacement for the source OpenAPI contract.
 
-OpenAPI 2.0, 3.0, and 3.1 documents are handled through format normalization in the transformer. Schema combinations (`allOf`, `oneOf`, `anyOf`), enums, arrays, nullable fields, and `additionalProperties` receive compact TypeScript-like representations. Unknown or unsupported schema constructs are represented as `unknown` rather than causing the entire digest to fail.
+**Security notes:** the tool fetches the URL you supply, same-origin Swagger UI initializer/config scripts, the spec URL referenced by that page, and a short list of common spec paths on the same origin. Cookies and Authorization headers are never sent automatically. If you call `fetchOpenApiSpec` from a server that accepts user-supplied URLs, enable `blockPrivateNetworks: true` — without it a caller can point the tool at cloud-metadata or other internal addresses (SSRF); the check rejects loopback, link-local, private, and unique-local addresses after redirects, but has a documented DNS-rebinding limitation — for hostile multi-tenant input, use a dedicated egress proxy. The MCP server enables this guard by default.
 
-## Development
+## Development and contribution
 
 ```bash
 npm install
 npm run build
-npm test
+npm test        # typecheck + test suite (runs offline against fixtures)
 npm run lint
-npm link
-swagger-digest
+npm link        # then: swagger-digest / swagger-digest-mcp
 ```
 
-Test against the public Petstore UI:
+Manual check against a live API:
 
 ```bash
 npm run build
 node dist/cli.js --url https://petstore.swagger.io/ --out-dir ./tmp --filename petstore-digest.md
 ```
 
-The test suite runs locally against fixtures and does not require a network connection. Network-based checks such as the Petstore example depend on that service being reachable from your environment.
-
-## Project layout
+Project layout:
 
 ```text
 src/
@@ -264,13 +399,6 @@ src/
     digest.ts     Tool handler: fetch → transform → tool result
 ```
 
-## Limitations
-
-- The tool downloads specs exposed by the supplied server. It does not bypass authentication, browser access controls, or network restrictions.
-- External `$ref` documents are bundled best-effort: references to other HTTP(S) documents are fetched (one level deep, at most 5 documents) and their schemas inlined under namespaced names such as `meta_SharedMeta`. If an external document is unreachable or unparsable, the reference degrades to a named type reference and the digest still succeeds.
-- Declared request/response examples are preserved. When an example is absent but a schema exists, a representative JSON example is generated from that schema and clearly marked as illustrative rather than spec-authored. The transformer includes the primary success response and applicable common error responses to balance useful payload context against digest size.
-- A generated digest is a compact developer reference, not a replacement for the source OpenAPI contract.
-
 ## License
 
 MIT

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.0",
+  "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
-};