mcp-context-cost 0.2.0 → 0.4.0

package/README.md

@@ -3,11 +3,142 @@
 [![npm](https://img.shields.io/npm/v/mcp-context-cost)](https://www.npmjs.com/package/mcp-context-cost)
 [![CI](https://github.com/athakur3/mcp-context-cost/actions/workflows/ci.yml/badge.svg)](https://github.com/athakur3/mcp-context-cost/actions/workflows/ci.yml)
 
-**Reproducible context-cost badges for MCP servers.**
+**What do the MCP servers in your config cost you before you type anything — and what did
+that last config change add to every session you will ever run?**
 
-Every MCP server you wire into an agent injects its tool schemas into the model's context
-before any work happens. That cost is invisible — and it varies by **1,700×** across
-popular servers:
+Every MCP server you wire into an agent injects its tool schemas into the model's context on
+every single request. You pay that whether or not the agent ends up using the tools, and no
+client shows you the number. Point `audit` at your own MCP config:
+
+```bash
+npx -y mcp-context-cost audit
+```
+
+```
+claude-desktop  ~/Library/Application Support/Claude/claude_desktop_config.json
+  server               tools  tokens   share
+  filesystem              14   2,823   35.7%
+  memory                   9   2,378   30.1%
+  everything              13   1,708   21.6%
+  sequential-thinking      1     992   12.6%
+  ────────────────────────────────────────────
+  total                   37   7,901
+
+  Every request in this client carries 7,901 tokens of tool schemas — 4.0% of a
+  200,000-token context window, before you type anything.
+
+  heaviest tools
+    sequential-thinking · sequentialthinking      990
+    memory · search_nodes                         323
+
+  trim: disabling 3 tools (sequential-thinking·sequentialthinking, memory·search_nodes,
+  memory·open_nodes) would recover 1,635 tokens (20.7% of this config) — if your client
+  supports per-tool filtering.
+```
+
+It finds configs for Claude Desktop, Claude Code (`~/.claude.json`, `.mcp.json`), Cursor,
+VS Code (`.vscode/mcp.json`), and Windsurf — or pass `--config <path>`. Servers are measured
+by the same path as the published leaderboard (dual `tools/list` capture, `o200k_base` over
+canonical JSON), so a server in both places gets the same number. Nothing is written to your
+project, and env var **values** are never read into the output — only their names.
+
+Totals are reported per config file, never merged: a context window belongs to one client
+session, so summing Cursor's servers into Claude Desktop's total would describe a session
+nobody runs.
+
+One nuance: Claude Code's tool search (default-on in recent versions) defers full MCP
+schemas until used, loading only tool names at session start. Audit totals are the weight
+of the schema surface itself — what loads upfront in clients without deferral (Claude
+Desktop, Cursor, VS Code, Windsurf today), and what Claude Code's documented fallback
+modes still load. Deferral-aware reporting is on the roadmap.
+
+**In CI**, make it a gate — the bundlesize move for agents:
+
+```bash
+npx -y mcp-context-cost audit --config .mcp.json --budget 20000
+# exits 1 when the stack exceeds the budget, so a PR adding a 25K-token server fails
+```
+
+The budget is an absolute ceiling. What a reviewer actually wants to know is what *this pull
+request* did, so record a baseline and diff against it:
+
+```bash
+npx -y mcp-context-cost audit --config .mcp.json --json > baseline.json          # on main
+npx -y mcp-context-cost audit --config .mcp.json --baseline baseline.json --max-increase 2000
+```
+
+```
+diff vs baseline measured 2026-08-18T01:51:49.555Z (methodology 1.0)
+
+  .mcp.json
+    2,378  →  5,201   +2,823
+
+    added             filesystem          — →     2,823  +2,823
+    (1 server unchanged)
+
+    This change adds 2,823 tokens to every request in this client — 1.2% → 2.6% of a
+    200,000-token context window.
+
+INCREASE FAIL:
+  .mcp.json: +2,823 tokens per request, over the 2,000 allowed
+```
+
+> **Version note.** `--baseline` and `--max-increase` are **not in the published 0.3.0** —
+> they are on `main` and ship in the next release. This matters more than a normal
+> unreleased-feature note: 0.3.0 ignores flags it does not recognise, so running the command
+> above against it produces a plain audit and **exit 0** — a passing CI check on a gate that
+> never ran. Builds after 0.3.0 reject unknown flags with exit 2 instead. Until the next
+> release, pin the gate to a version that has it, or it is not gating anything.
+
+A baseline is just a stored `audit --json` report, so any artifact store works. Without
+`--max-increase` the diff is informational and the exit code is unchanged.
+
+[`examples/github-actions.yml`](examples/github-actions.yml) is the whole thing as a workflow:
+measure the base branch, measure the PR, fail on the difference.
+
+`--max-increase` fails on more than the number — it also fails whenever the increase could
+not be established. A server that measured yesterday and won't start today takes its tokens
+out of the total in exactly the way uninstalling it would, and reporting that as a saving is
+the one mistake this tool must not make. So a server that crossed the measured/unmeasured
+line, a config with no baseline, or a baseline config this run never found each fail the
+gate and name themselves:
+
+```
+    Not a clean comparison: a server changed measured-ness between the two runs.
+    The measured total moved −2,378, but that is not what your config did.
+
+      memory: measured 2,378 in the baseline and could not be measured now — its cost is
+              missing from the total, not gone from your config
+      → true cost is at least 2,378 higher than the 0 measured now.
+
+INCREASE FAIL:
+  .mcp.json: a server changed measured-ness, so the change could not be established exactly
+```
+
+Add `--claude` to annotate each server with its Anthropic-request cost from the published
+[Claude divergence](docs/METHODOLOGY.md#claude-divergence) run — an exact number when the
+published capture hash matches what you have installed, `—` (silence, not a stale guess)
+when it doesn't (today the run covers the top 15 measured servers, so most installs will
+show a mix):
+
+```
+  server               tools  tokens   share   claude
+  github                  44  54,422   95.8%   18,406
+  memory                   9   2,378    4.2%       —
+```
+
+Flags: `--json` (full report on stdout, progress on stderr), `--budget N`,
+`--baseline <report.json>`, `--max-increase N`, `--context N` (default 200,000),
+`--timeout ms`, `--concurrency N`, `--docker`, `--claude`.
+
+## Where the numbers come from
+
+The number `audit` gives you is the same measurement, run across a curated set of public
+servers — which is how you can tell it is a measurement and not this tool's opinion. It also
+shows what you are choosing between: across the 65 servers measured, cost spans **1,700×**,
+from the 32-token `postgres` reference server to github's 54,422. The table below starts at
+markitdown's 64 tokens, an 850× spread; the full range is in
+[results/leaderboard.md](results/leaderboard.md).
 
 | server | context cost | tools |
 |---|---:|---:|
@@ -18,12 +149,13 @@ popular servers:
 | filesystem (reference) | 2,823 | 14 |
 | markitdown | 64 | 1 |
 
-*(57 of 82 popular servers measured, 2026-08-16 sweep — full table in
+*(65 of 82 popular servers measured, 2026-08-18 sweep — full table in
 [results/leaderboard.md](results/leaderboard.md); every failure is listed with its reason.
 Each measured server also has a [detail page](https://athakur3.github.io/mcp-context-cost/servers/)
 showing which tools its tokens are in.)*
 
-This project makes that cost **legible and disputable**:
+If you publish a server, the same measurement is available as a badge, so your users can see
+the cost before they install rather than after:
 
 ```
 [context cost | 12,430 tokens]   ← shields.io badge, linked to the methodology
@@ -46,9 +178,9 @@ the method is [Claude divergence](docs/METHODOLOGY.md#claude-divergence).
 
 ## Why trust the number?
 
-Every badge is backed by a `measurement.json` containing the raw `tools/list` capture, the
-SHA-256 of its canonical bytes, the pinned tokenizer (`o200k_base`), and the exact launch
-command. Disputes reduce to a byte-level diff:
+Every published number is backed by a `measurement.json` containing the raw `tools/list`
+capture, the SHA-256 of its canonical bytes, the pinned tokenizer (`o200k_base`), and the
+exact launch command. Disputes reduce to a byte-level diff:
 
 ```bash
 npx -y mcp-context-cost verify results/github/measurement.json
@@ -62,6 +194,11 @@ Add `--json` for scripting (`{ ok, serverName, rederivedTokens, rederivedSha, pr
 on stdout, `badge` omitted on failure). Exit codes: `0` ok, `1` verification/measurement
 failed, `2` usage error.
 
+`audit` runs that same code path on your own machine and reports each server's
+`canonicalSha256` in `--json`, so you can check that the version you installed is byte-identical
+to the one that was published — which is exactly what `--claude` uses to decide whether it is
+allowed to show you a number.
+
 Full definition: [docs/METHODOLOGY.md](docs/METHODOLOGY.md) — what is counted, what the
 number is *not*, config policy, failure taxonomy, frozen color bands, known divergences.
 
@@ -71,7 +208,8 @@ number is *not*, config policy, failure taxonomy, frozen color bands, known dive
 |---|---|
 | `src/core/` | the measurement spec, executable — canonical form, tokenizer, bands, badge JSON |
 | `src/sweep/` | raw-wire MCP stdio client + Dockerized batch sweep + leaderboard/dashboard generators |
-| `src/cli.ts` | `verify` (re-derive any published number) and `measure` |
+| `src/audit/` | client-config discovery (5 clients, JSONC-tolerant), the per-stack report, and the baseline diff |
+| `src/cli.ts` | `audit` (measure your own stack), `verify` (re-derive any published number), `measure` |
 | `spec/fixtures/` | golden vectors shared by the TypeScript and bash implementations |
 | `tools/` | the one script that calls a network API (Claude divergence); kept out of the package so the library stays offline |
 | `upstream/` | staged contribution to [sd2k/mcp-tokens-action](https://github.com/sd2k/mcp-tokens-action): `badge.sh` + action patch + tests |
@@ -103,7 +241,7 @@ Or self-serve from CI via the (staged) mcp-tokens-action badge inputs — see
 ## Development
 
 ```bash
-npm test                        # 53 TS tests incl. golden fixtures + dispute drills
+npm test                        # 158 TS tests incl. golden fixtures + dispute drills
 npx tsc --noEmit                # typecheck
 ./upstream/tests/badge-test.sh  # 21 bash tests — byte-identical to the TS reference
 npm run sweep:all -- --docker   # full curated sweep (Docker isolation)
@@ -116,7 +254,11 @@ color bands are frozen against the observed distribution of the first full sweep
 
 ## Status
 
-Active. The leaderboard refreshes weekly; badge PRs are open across the ecosystem and
+Active. 56 of the 65 numbers come from a single sweep on 2026-08-16, 3 from 2026-08-17, and
+6 from 2026-08-18 (an upstream `mcp` package bump broke the old low-level-`Server` API these
+six relied on; pinning `mcp<2` in their launch commands fixed startup, not this project's code);
+the weekly job currently re-measures one server (`memory`), so treat the leaderboard as a
+dated snapshot rather than a live feed. Badge PRs are open across the ecosystem and
 [sd2k/mcp-tokens-action#5](https://github.com/sd2k/mcp-tokens-action/pull/5) proposes the
 self-serve badge path upstream. See [ROADMAP.md](ROADMAP.md) for what's next —
 contributions welcome, especially new `servers.yaml` entries.

package/dist/audit/audit.d.ts

@@ -0,0 +1,129 @@
+import { type DivergenceRun } from '../core/divergence.js';
+import type { Measurement, MeasurementStatus, ToolMeasurement } from '../core/types.js';
+import type { ConfiguredServer, LoadedConfig } from './config.js';
+import { type AuditDiff, type IncreaseGate } from './diff.js';
+export declare const DEFAULT_CONTEXT_WINDOW = 200000;
+export type AuditStatus = MeasurementStatus | 'remote-not-measurable';
+export interface AuditServerResult {
+    name: string;
+    transport: 'stdio' | 'remote';
+    status: AuditStatus;
+    tokens: number | null;
+    toolCount: number | null;
+    /** Share of this config's measured total, 0–1. */
+    share: number | null;
+    command?: string;
+    url?: string;
+    /** Names only — a server's env values never enter a report. */
+    envVarNames: string[];
+    canonicalSha256?: string | null;
+    /**
+     * Anthropic-request cost from the published Claude divergence run, only when
+     * its captured hash matches this install (`--claude`). `null` means the
+     * install doesn't match what was published — silence, not a stale guess.
+     * `undefined` means `--claude` wasn't requested at all.
+     */
+    claudeTokens?: number | null;
+    notes?: string;
+}
+export interface HeaviestTool {
+    server: string;
+    tool: string;
+    tokens: number;
+}
+/**
+ * What turning off the heaviest few tools would recover, for clients that let
+ * you disable individual tools rather than whole servers (Claude Code's
+ * per-tool permission rules, Cursor's per-tool toggles). `null` when there's
+ * nothing worth trimming (one tool total, or no measured tokens).
+ */
+export interface TrimAdvice {
+    tools: HeaviestTool[];
+    recoverableTokens: number;
+    recoverableShare: number;
+}
+export interface AuditConfigResult {
+    client: string;
+    source: string;
+    totalTokens: number;
+    toolCount: number;
+    serverCount: number;
+    contextShare: number;
+    servers: AuditServerResult[];
+    skipped: AuditServerResult[];
+    heaviestTools: HeaviestTool[];
+    trimAdvice: TrimAdvice | null;
+}
+export interface BudgetFitStep {
+    name: string;
+    tokens: number;
+    /** What the config still costs after removing this one and everything above it. */
+    remaining: number;
+}
+export interface BudgetFit {
+    /** How far over the limit the worst config starts. */
+    overBy: number;
+    /** Heaviest-first removals until the remainder fits. Empty if nothing can be removed. */
+    drop: BudgetFitStep[];
+    keptCount: number;
+    keptTokens: number;
+    /** False when removing every measured server still would not fit — a limit set too low. */
+    feasible: boolean;
+}
+/**
+ * The smallest heaviest-first set of servers that gets a config under its budget.
+ *
+ * `--budget` used to print "BUDGET FAIL: 84,455 > 20,000" and stop, which tells a reader
+ * they have a problem and nothing about the shape of it. The whole point of the audit
+ * surface is that the person running it is the person paying the tokens, and "you are over"
+ * is a measurement where "these two are why" is a decision.
+ *
+ * Heaviest-first is ONE ordering, not a recommendation: this cannot know which servers you
+ * need, and dropping by weight will sometimes name the one you cannot live without. That
+ * caveat is printed with the result rather than left implied.
+ */
+export declare function planBudgetFit(config: AuditConfigResult, limit: number): BudgetFit;
+export interface AuditReport {
+    methodologyVersion: string;
+    encoding: 'o200k_base';
+    generatedAt: string;
+    contextWindow: number;
+    configs: AuditConfigResult[];
+    budget?: {
+        limit: number;
+        worstTotal: number;
+        worstSource: string;
+        over: boolean;
+        /** Present only when over budget: the arithmetic of getting back under it. */
+        fit?: BudgetFit;
+    };
+    /** Present only when a divergence run was supplied (`--claude`). */
+    claudeDivergence?: {
+        model: string;
+        measuredAt: string;
+    };
+    /** Present only when a baseline report was supplied (`--baseline`). */
+    diff?: AuditDiff;
+    /** Present only when `--max-increase` was supplied alongside a baseline. */
+    increaseGate?: IncreaseGate;
+    problems: string[];
+}
+/** Cache key for measurement reuse: the exact argv two configs would spawn. */
+export declare function serverKey(s: ConfiguredServer): string;
+/**
+ * Assemble the report from configs + measurements. Pure: `runAudit` does the
+ * spawning, this does the arithmetic, so totals and shares are testable without
+ * launching a single server.
+ */
+export declare function buildReport(configs: LoadedConfig[], measured: Map<string, Measurement>, opts?: {
+    contextWindow?: number;
+    budget?: number;
+    generatedAt?: string;
+    /** Published `tools-delta/v1` run to join against (`--claude`); omit to skip the join. */
+    divergence?: DivergenceRun | null;
+}): AuditReport;
+/** Human output. JSON output is the report object itself. */
+export declare function formatReport(report: AuditReport): string;
+/** Top-level tool list across every config — used by nothing yet, handy for --json consumers. */
+export declare function allHeaviestTools(report: AuditReport, limit?: number): HeaviestTool[];
+export type { ToolMeasurement };

package/dist/audit/audit.js

@@ -0,0 +1,312 @@
+/**
+ * `audit` — measure the MCP servers a person actually has installed.
+ *
+ * The leaderboard answers "what does server X cost?". This answers the question
+ * the person paying the bill has: "what do MY servers cost, together, before I
+ * type anything?" Same measurement path as the sweep (dual tools/list capture,
+ * o200k_base over canonical JSON, full status taxonomy), pointed at a client
+ * config instead of servers.yaml.
+ *
+ * Totals are per config file, never merged across clients: a context window
+ * belongs to one client session, so summing Cursor's servers into Claude
+ * Desktop's total would describe a session nobody is running. Identical launch
+ * commands shared by two configs are still only measured once.
+ */
+import { METHODOLOGY_VERSION } from '../core/canonical.js';
+import { isCurrent } from '../core/divergence.js';
+import { formatDiff, formatGate } from './diff.js';
+export const DEFAULT_CONTEXT_WINDOW = 200_000;
+const TRIM_TOOL_COUNT = 3;
+function buildTrimAdvice(sortedTools, totalTokens) {
+    if (totalTokens <= 0 || sortedTools.length < 2)
+        return null;
+    const trimmed = sortedTools.slice(0, TRIM_TOOL_COUNT);
+    const recoverableTokens = trimmed.reduce((a, t) => a + t.tokens, 0);
+    return { tools: trimmed, recoverableTokens, recoverableShare: recoverableTokens / totalTokens };
+}
+/**
+ * The smallest heaviest-first set of servers that gets a config under its budget.
+ *
+ * `--budget` used to print "BUDGET FAIL: 84,455 > 20,000" and stop, which tells a reader
+ * they have a problem and nothing about the shape of it. The whole point of the audit
+ * surface is that the person running it is the person paying the tokens, and "you are over"
+ * is a measurement where "these two are why" is a decision.
+ *
+ * Heaviest-first is ONE ordering, not a recommendation: this cannot know which servers you
+ * need, and dropping by weight will sometimes name the one you cannot live without. That
+ * caveat is printed with the result rather than left implied.
+ */
+export function planBudgetFit(config, limit) {
+    const measured = config.servers
+        .filter((srv) => typeof srv.tokens === 'number' && srv.tokens > 0)
+        .sort((a, b) => b.tokens - a.tokens);
+    const overBy = config.totalTokens - limit;
+    const drop = [];
+    let remaining = config.totalTokens;
+    for (const srv of measured) {
+        if (remaining <= limit)
+            break;
+        remaining -= srv.tokens;
+        drop.push({ name: srv.name, tokens: srv.tokens, remaining });
+    }
+    return {
+        overBy,
+        drop,
+        keptCount: measured.length - drop.length,
+        keptTokens: remaining,
+        // Removing everything measured still leaves unmeasured/base cost behind, so the
+        // honest test is whether the remainder actually landed under the limit.
+        feasible: remaining <= limit,
+    };
+}
+/** Cache key for measurement reuse: the exact argv two configs would spawn. */
+export function serverKey(s) {
+    return JSON.stringify(s.argv ?? [s.url ?? s.name]);
+}
+function measuredOk(m) {
+    return (m.status === 'measured' || m.status === 'dynamic') && typeof m.totalTokens === 'number';
+}
+/**
+ * Assemble the report from configs + measurements. Pure: `runAudit` does the
+ * spawning, this does the arithmetic, so totals and shares are testable without
+ * launching a single server.
+ */
+export function buildReport(configs, measured, opts = {}) {
+    const contextWindow = opts.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
+    const problems = [];
+    const results = [];
+    for (const cfg of configs) {
+        if (cfg.error) {
+            problems.push(`${cfg.source}: ${cfg.error}`);
+            continue;
+        }
+        const ok = [];
+        const skipped = [];
+        const tools = [];
+        for (const s of cfg.servers) {
+            const base = {
+                name: s.name,
+                transport: s.transport,
+                command: s.command,
+                url: s.url,
+                envVarNames: s.envVarNames,
+            };
+            if (s.transport === 'remote') {
+                skipped.push({
+                    ...base,
+                    status: 'remote-not-measurable',
+                    tokens: null,
+                    toolCount: null,
+                    share: null,
+                    notes: `remote endpoint (${s.url ?? 'url'}) — stdio measurement does not apply`,
+                });
+                continue;
+            }
+            const m = measured.get(serverKey(s));
+            if (!m) {
+                skipped.push({ ...base, status: 'startup-failure', tokens: null, toolCount: null, share: null, notes: 'not measured' });
+                continue;
+            }
+            if (!measuredOk(m)) {
+                skipped.push({
+                    ...base,
+                    status: m.status,
+                    tokens: null,
+                    toolCount: null,
+                    share: null,
+                    notes: m.notes?.split('\n')[0]?.slice(0, 200),
+                });
+                continue;
+            }
+            const divRow = opts.divergence?.servers[s.name];
+            ok.push({
+                ...base,
+                status: m.status,
+                tokens: m.totalTokens,
+                toolCount: m.toolCount,
+                share: null, // filled once the total is known
+                canonicalSha256: m.canonicalSha256,
+                claudeTokens: opts.divergence ? (isCurrent(divRow, m.canonicalSha256 ?? null) ? divRow.claudeDelta : null) : undefined,
+                notes: m.status === 'dynamic' ? m.notes : undefined,
+            });
+            for (const t of m.tools)
+                tools.push({ server: s.name, tool: t.name, tokens: t.tokens });
+        }
+        const totalTokens = ok.reduce((a, s) => a + (s.tokens ?? 0), 0);
+        const toolCount = ok.reduce((a, s) => a + (s.toolCount ?? 0), 0);
+        ok.sort((a, b) => (b.tokens ?? 0) - (a.tokens ?? 0));
+        for (const s of ok)
+            s.share = totalTokens > 0 ? (s.tokens ?? 0) / totalTokens : 0;
+        tools.sort((a, b) => b.tokens - a.tokens);
+        results.push({
+            client: cfg.client,
+            source: cfg.source,
+            totalTokens,
+            toolCount,
+            serverCount: ok.length,
+            // Deliberately no band: the color bands were frozen against the per-server
+            // distribution (n=57). A config total is a different population, so calling
+            // a 7,901-token *stack* "moderate" would borrow a scale that doesn't mean
+            // that here. Share of the context window is the honest framing.
+            contextShare: totalTokens / contextWindow,
+            servers: ok,
+            skipped,
+            heaviestTools: tools.slice(0, 5),
+            trimAdvice: buildTrimAdvice(tools, totalTokens),
+        });
+    }
+    results.sort((a, b) => b.totalTokens - a.totalTokens);
+    const report = {
+        methodologyVersion: METHODOLOGY_VERSION,
+        encoding: 'o200k_base',
+        generatedAt: opts.generatedAt ?? new Date().toISOString(),
+        contextWindow,
+        configs: results,
+        problems,
+    };
+    if (opts.divergence) {
+        report.claudeDivergence = { model: opts.divergence.model, measuredAt: opts.divergence.measuredAt };
+    }
+    if (typeof opts.budget === 'number') {
+        // The worst config is the gate: passing because your *lightest* client fits
+        // would be a green check on a session you don't run.
+        const worst = results[0];
+        const over = (worst?.totalTokens ?? 0) > opts.budget;
+        report.budget = {
+            limit: opts.budget,
+            worstTotal: worst?.totalTokens ?? 0,
+            worstSource: worst?.source ?? '(none)',
+            over,
+            fit: over && worst ? planBudgetFit(worst, opts.budget) : undefined,
+        };
+    }
+    return report;
+}
+const n = (x) => x.toLocaleString('en-US');
+const pct = (x) => `${(x * 100).toFixed(1)}%`;
+/** Human output. JSON output is the report object itself. */
+export function formatReport(report) {
+    const lines = [];
+    lines.push(`mcp-context-cost audit · methodology ${report.methodologyVersion} · ${report.encoding} · context window ${n(report.contextWindow)}`);
+    const showClaude = !!report.claudeDivergence;
+    for (const cfg of report.configs) {
+        lines.push('');
+        lines.push(`${cfg.client}  ${cfg.source}`);
+        const rows = cfg.servers.map((s) => ({
+            name: s.name,
+            tools: s.toolCount === null ? '—' : String(s.toolCount),
+            tokens: s.tokens === null ? '—' : n(s.tokens),
+            share: s.share === null ? '—' : pct(s.share),
+            claude: s.claudeTokens == null ? '—' : n(s.claudeTokens),
+        }));
+        const w = {
+            name: Math.max(6, ...rows.map((r) => r.name.length), 'total'.length),
+            tools: Math.max(5, ...rows.map((r) => r.tools.length)),
+            tokens: Math.max(6, ...rows.map((r) => r.tokens.length), n(cfg.totalTokens).length),
+            claude: Math.max(6, ...rows.map((r) => r.claude.length)),
+        };
+        const line = (name, tools, tokens, share, claude) => `  ${name.padEnd(w.name)}  ${tools.padStart(w.tools)}  ${tokens.padStart(w.tokens)}  ${share.padStart(6)}` +
+            (showClaude ? `  ${claude.padStart(w.claude)}` : '');
+        lines.push(line('server', 'tools', 'tokens', 'share', 'claude'));
+        for (const r of rows)
+            lines.push(line(r.name, r.tools, r.tokens, r.share, r.claude));
+        lines.push(`  ${'─'.repeat(w.name + w.tools + w.tokens + 14 + (showClaude ? w.claude + 2 : 0))}`);
+        lines.push(line('total', String(cfg.toolCount), n(cfg.totalTokens), '', ''));
+        lines.push('');
+        lines.push(`  Every request in this client carries ${n(cfg.totalTokens)} tokens of tool schemas — ` +
+            `${pct(cfg.contextShare)} of a ${n(report.contextWindow)}-token context window, before you type anything.`);
+        if (cfg.heaviestTools.length) {
+            lines.push('');
+            lines.push('  heaviest tools');
+            const tw = Math.max(...cfg.heaviestTools.map((t) => `${t.server} · ${t.tool}`.length));
+            for (const t of cfg.heaviestTools) {
+                lines.push(`    ${`${t.server} · ${t.tool}`.padEnd(tw)}  ${n(t.tokens).padStart(7)}`);
+            }
+        }
+        if (cfg.trimAdvice) {
+            const names = cfg.trimAdvice.tools.map((t) => `${t.server}·${t.tool}`).join(', ');
+            lines.push('');
+            lines.push(`  trim: disabling ${cfg.trimAdvice.tools.length} tool${cfg.trimAdvice.tools.length === 1 ? '' : 's'} ` +
+                `(${names}) would recover ${n(cfg.trimAdvice.recoverableTokens)} tokens ` +
+                `(${pct(cfg.trimAdvice.recoverableShare)} of this config) — if your client supports per-tool filtering.`);
+        }
+        if (cfg.skipped.length) {
+            lines.push('');
+            lines.push('  not measured');
+            const sw = Math.max(...cfg.skipped.map((s) => s.name.length));
+            for (const s of cfg.skipped) {
+                lines.push(`    ${s.name.padEnd(sw)}  ${s.status}${s.notes ? ` — ${s.notes}` : ''}`);
+            }
+        }
+    }
+    if (showClaude) {
+        lines.push('');
+        lines.push(`  claude = Anthropic-request cost from the ${report.claudeDivergence.measuredAt} ${report.claudeDivergence.model} ` +
+            `divergence run, shown only where the published capture hash matches this install; '—' means no current match.`);
+    }
+    if (report.problems.length) {
+        lines.push('');
+        lines.push('problems');
+        for (const p of report.problems)
+            lines.push(`  ${p}`);
+    }
+    if (report.budget) {
+        const b = report.budget;
+        lines.push('');
+        if (!b.over) {
+            const headroom = b.limit - b.worstTotal;
+            lines.push(`budget ok: ${n(b.worstTotal)} ≤ ${n(b.limit)} — ${n(headroom)} to spare`);
+        }
+        else {
+            lines.push(`BUDGET FAIL: ${n(b.worstTotal)} > ${n(b.limit)} (${b.worstSource})`);
+            const fit = b.fit;
+            if (fit && fit.drop.length) {
+                lines.push('');
+                lines.push(`  over by ${n(fit.overBy)}. Heaviest-first, this is what gets you under:`);
+                for (const step of fit.drop) {
+                    const verdict = step.remaining <= b.limit ? 'fits' : 'still over';
+                    lines.push(`    drop  ${step.name.padEnd(22)} ${n(step.tokens).padStart(9)}  →  ${n(step.remaining).padStart(9)}  ${verdict}`);
+                }
+                lines.push('');
+                if (fit.feasible && fit.keptCount === 0) {
+                    // Arithmetically it fits, and the answer is useless: the only way under this
+                    // limit is to run no servers at all. Saying "fits" here would be true and
+                    // misleading, which is the pair this whole tool exists to keep apart.
+                    lines.push(`  no subset fits: every measured server would have to go. The limit is below`);
+                    lines.push(`  what any one of these servers costs.`);
+                }
+                else if (fit.feasible) {
+                    const share = b.limit > 0 ? ` (${pct(fit.keptTokens / b.limit)} of budget)` : '';
+                    lines.push(`  keeps ${fit.keptCount} server(s) at ${n(fit.keptTokens)} tokens${share}`);
+                }
+                else {
+                    lines.push(`  even removing every measured server leaves ${n(fit.keptTokens)} — the limit is below this config's floor`);
+                }
+                lines.push('');
+                lines.push('  This is arithmetic, not advice: it cannot know which servers you need, and by');
+                lines.push('  weight alone it will sometimes name the one you cannot work without. Use --json');
+                lines.push('  for the full per-server list and pick your own order.');
+            }
+            else if (fit) {
+                lines.push('  nothing measured could be removed to get under the limit.');
+            }
+        }
+    }
+    if (report.diff)
+        lines.push(formatDiff(report.diff, report.contextWindow));
+    if (report.increaseGate) {
+        lines.push('');
+        lines.push(formatGate(report.increaseGate));
+    }
+    lines.push('');
+    lines.push('These are wire tokens — what the server puts on the wire, counted with o200k_base. What your model is billed');
+    lines.push('differs per provider: measured ratios run 0.34×–1.92× on Anthropic requests. See docs/METHODOLOGY.md §claude-divergence.');
+    return lines.map((l) => l.replace(/\s+$/, '')).join('\n');
+}
+/** Top-level tool list across every config — used by nothing yet, handy for --json consumers. */
+export function allHeaviestTools(report, limit = 10) {
+    return report.configs
+        .flatMap((c) => c.heaviestTools)
+        .sort((a, b) => b.tokens - a.tokens)
+        .slice(0, limit);
+}