mcp-context-cost 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,10 @@
 # mcp-context-cost
 
-**Reproducible context-cost badges for MCP servers.**
+[![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 measurement for MCP servers — for the one you publish, and for
+the stack you actually 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
@@ -16,7 +20,9 @@ popular servers:
 | markitdown | 64 | 1 |
 
 *(57 of 82 popular servers measured, 2026-08-16 sweep — full table in
-[results/leaderboard.md](results/leaderboard.md); every failure is listed with its reason.)*
+[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**:
 
@@ -24,6 +30,68 @@ This project makes that cost **legible and disputable**:
 [context cost | 12,430 tokens]   ← shields.io badge, linked to the methodology
 ```
 
+## What does *your* setup cost?
+
+The leaderboard measures one server at a time. You don't run one server — you run a stack.
+Point `audit` at your own MCP config and it measures every server you actually have installed:
+
+```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
+```
+
+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.
+
+**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
+```
+
+Flags: `--json` (full report on stdout, progress on stderr), `--budget N`, `--context N`
+(default 200,000), `--timeout ms`, `--concurrency N`, `--docker`.
+
+## What it costs on Claude
+
+The badge counts every byte a server returns. An Anthropic request carries only `name`,
+`description`, and `input_schema` — and counts them with a denser tokenizer. Both effects are
+now measured against a pinned model and published beside the badge, and they do not cancel:
+
+| server | badge (o200k) | Claude (`claude-opus-5`) | |
+|---|---:|---:|---|
+| github | 54,422 | **18,406** | 81% of the capture is `annotations`/`outputSchema` metadata Claude never sees |
+| notion | 17,500 | **33,560** | almost no metadata to drop, so the tokenizer difference dominates |
+
+So the heaviest server on the badge is not the heaviest server on Claude. Per-server
+breakdowns are on each [detail page](https://athakur3.github.io/mcp-context-cost/servers/);
+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
@@ -31,10 +99,17 @@ SHA-256 of its canonical bytes, the pinned tokenizer (`o200k_base`), and the exa
 command. Disputes reduce to a byte-level diff:
 
 ```bash
-npx tsx src/cli.ts verify results/github/measurement.json
+npx -y mcp-context-cost verify results/github/measurement.json
 # OK github-mcp-server: 54422 tokens (o200k_base, methodology 1.0) — capture, hash, and count all agree
+
+# or point it at a published measurement.json directly, no clone required
+npx -y mcp-context-cost verify --remote https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/github/measurement.json
 ```
 
+Add `--json` for scripting (`{ ok, serverName, rederivedTokens, rederivedSha, problems, badge }`
+on stdout, `badge` omitted on failure). Exit codes: `0` ok, `1` verification/measurement
+failed, `2` usage error.
+
 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.
 
@@ -44,11 +119,14 @@ 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 |
+| `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 |
 | `servers.yaml` | 82 curated candidates with live install metrics and provenance |
-| `results/` · `badges/` | measurements, leaderboard, shields endpoint JSONs |
+| `results/` · `badges/` | measurements, leaderboard, history series, shields endpoint JSONs |
+| `docs/` | methodology, dashboard, and a generated page per measured server |
 
 ## Measure your own server
 
@@ -61,16 +139,20 @@ cat badges/my-server.json   # strict shields.io endpoint JSON
 Then in your README:
 
 ```markdown
-[![context cost](https://img.shields.io/endpoint?url=<raw URL of badges/my-server.json>)](<methodology URL>)
+[![context cost](https://img.shields.io/endpoint?url=<raw URL of badges/my-server.json>)](<link target>)
 ```
 
+Point the link at the measurement behind the number — for servers in this sweep that is
+`https://athakur3.github.io/mcp-context-cost/servers/<name>.html`; otherwise the
+methodology page. A badge nobody can audit is decoration.
+
 Or self-serve from CI via the (staged) mcp-tokens-action badge inputs — see
 [upstream/action-patch.md](upstream/action-patch.md).
 
 ## Development
 
 ```bash
-npm test                        # 24 TS tests incl. golden fixtures + dispute drills
+npm test                        # 105 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)
@@ -83,8 +165,9 @@ color bands are frozen against the observed distribution of the first full sweep
 
 ## Status
 
-Pre-launch. Measurement pipeline, leaderboard, methodology, and upstream contribution are
-complete; the badge-adoption campaign and launch posts are drafted in `campaign/` awaiting
-go-ahead. Build log: [PROGRESS.md](PROGRESS.md).
+Active. The leaderboard refreshes weekly; 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.
 
 MIT © 2026

package/dist/audit/audit.d.ts

@@ -0,0 +1,66 @@
+import type { Measurement, MeasurementStatus, ToolMeasurement } from '../core/types.js';
+import type { ConfiguredServer, LoadedConfig } from './config.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;
+    notes?: string;
+}
+export interface HeaviestTool {
+    server: string;
+    tool: string;
+    tokens: number;
+}
+export interface AuditConfigResult {
+    client: string;
+    source: string;
+    totalTokens: number;
+    toolCount: number;
+    serverCount: number;
+    contextShare: number;
+    servers: AuditServerResult[];
+    skipped: AuditServerResult[];
+    heaviestTools: HeaviestTool[];
+}
+export interface AuditReport {
+    methodologyVersion: string;
+    encoding: 'o200k_base';
+    generatedAt: string;
+    contextWindow: number;
+    configs: AuditConfigResult[];
+    budget?: {
+        limit: number;
+        worstTotal: number;
+        worstSource: string;
+        over: boolean;
+    };
+    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;
+}): 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,201 @@
+/**
+ * `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';
+export const DEFAULT_CONTEXT_WINDOW = 200_000;
+/** 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;
+            }
+            ok.push({
+                ...base,
+                status: m.status,
+                tokens: m.totalTokens,
+                toolCount: m.toolCount,
+                share: null, // filled once the total is known
+                canonicalSha256: m.canonicalSha256,
+                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),
+        });
+    }
+    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 (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];
+        report.budget = {
+            limit: opts.budget,
+            worstTotal: worst?.totalTokens ?? 0,
+            worstSource: worst?.source ?? '(none)',
+            over: (worst?.totalTokens ?? 0) > opts.budget,
+        };
+    }
+    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)}`);
+    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),
+        }));
+        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),
+        };
+        const line = (name, tools, tokens, share) => `  ${name.padEnd(w.name)}  ${tools.padStart(w.tools)}  ${tokens.padStart(w.tokens)}  ${share.padStart(6)}`;
+        lines.push(line('server', 'tools', 'tokens', 'share'));
+        for (const r of rows)
+            lines.push(line(r.name, r.tools, r.tokens, r.share));
+        lines.push(`  ${'─'.repeat(w.name + w.tools + w.tokens + 14)}`);
+        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.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 (report.problems.length) {
+        lines.push('');
+        lines.push('problems');
+        for (const p of report.problems)
+            lines.push(`  ${p}`);
+    }
+    if (report.budget) {
+        lines.push('');
+        lines.push(report.budget.over
+            ? `BUDGET FAIL: ${n(report.budget.worstTotal)} > ${n(report.budget.limit)} (${report.budget.worstSource})`
+            : `budget ok: ${n(report.budget.worstTotal)} ≤ ${n(report.budget.limit)}`);
+    }
+    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);
+}

package/dist/audit/config.d.ts

@@ -0,0 +1,53 @@
+export interface ConfiguredServer {
+    name: string;
+    /** Which client's config this came from ('claude-desktop', 'cursor', ...). */
+    client: string;
+    /** Absolute path of the config file. */
+    source: string;
+    transport: 'stdio' | 'remote';
+    /** Display form of the launch command (argv joined) — stdio only. */
+    command?: string;
+    /** Exact argv, so paths containing spaces survive round-tripping. */
+    argv?: string[];
+    envVarNames: string[];
+    /** Values, needed to spawn the server. NEVER serialize this. */
+    env?: Record<string, string>;
+    /** Remote endpoint — recorded so the report can say why it was skipped. */
+    url?: string;
+}
+/**
+ * JSON with comments and trailing commas — VS Code's mcp.json allows both, and
+ * hand-edited Claude/Cursor configs often pick up a trailing comma too. String
+ * literals are tracked so a `//` or `,}` inside a tool description survives.
+ */
+export declare function parseJsonc(text: string): unknown;
+/**
+ * Pull every server out of one parsed config document. `cwd` selects the
+ * project scope in Claude Code's `~/.claude.json`, which keys per-project
+ * servers by absolute directory.
+ */
+export declare function extractServers(doc: unknown, meta: {
+    client: string;
+    source: string;
+    cwd?: string;
+}): ConfiguredServer[];
+export interface ConfigCandidate {
+    client: string;
+    path: string;
+}
+/** Every place a client config is known to live, whether or not it exists. */
+export declare function configCandidates(env: {
+    home: string;
+    cwd: string;
+    platform: NodeJS.Platform;
+    appData?: string;
+}): ConfigCandidate[];
+export interface LoadedConfig {
+    client: string;
+    source: string;
+    servers: ConfiguredServer[];
+    /** Set when the file exists but could not be read/parsed. */
+    error?: string;
+}
+/** Read + parse the candidates that exist. Unreadable files are reported, not thrown. */
+export declare function loadConfigs(candidates: ConfigCandidate[], cwd: string): LoadedConfig[];

package/dist/audit/config.js

@@ -0,0 +1,179 @@
+/**
+ * MCP client config discovery + parsing.
+ *
+ * The leaderboard measures servers one at a time; `audit` measures the set a
+ * person actually has installed. That set lives in a client config file, and
+ * every client spells it slightly differently:
+ *
+ *   Claude Desktop / Claude Code / Cursor / Windsurf   { "mcpServers": { ... } }
+ *   VS Code (.vscode/mcp.json)                         { "servers": { ... } }
+ *   Claude Code (~/.claude.json)                       also { "projects": { "<dir>": { "mcpServers": ... } } }
+ *
+ * Everything here is pure (paths in, servers out) so the discovery rules are
+ * testable without touching a real home directory.
+ *
+ * Env var VALUES are read (a server usually needs its key to start) but are
+ * never written to a report: report builders pick fields explicitly and only
+ * `envVarNames` is ever serialized.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * JSON with comments and trailing commas — VS Code's mcp.json allows both, and
+ * hand-edited Claude/Cursor configs often pick up a trailing comma too. String
+ * literals are tracked so a `//` or `,}` inside a tool description survives.
+ */
+export function parseJsonc(text) {
+    let out = '';
+    let inString = false;
+    let escaped = false;
+    let pendingComma = false;
+    const flush = (next) => {
+        if (!pendingComma)
+            return;
+        // A comma is only trailing if the next real character closes the container.
+        if (next !== '}' && next !== ']')
+            out += ',';
+        pendingComma = false;
+    };
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        const n = text[i + 1];
+        if (inString) {
+            out += c;
+            if (escaped)
+                escaped = false;
+            else if (c === '\\')
+                escaped = true;
+            else if (c === '"')
+                inString = false;
+            continue;
+        }
+        if (c === '/' && n === '/') {
+            while (i < text.length && text[i] !== '\n')
+                i++;
+            continue;
+        }
+        if (c === '/' && n === '*') {
+            i += 2;
+            while (i < text.length && !(text[i] === '*' && text[i + 1] === '/'))
+                i++;
+            i++;
+            continue;
+        }
+        if (c === ',') {
+            pendingComma = true;
+            continue;
+        }
+        if (/\s/.test(c)) {
+            if (!pendingComma)
+                out += c;
+            continue;
+        }
+        flush(c);
+        out += c;
+        if (c === '"')
+            inString = true;
+    }
+    return JSON.parse(out);
+}
+function toServer(name, raw, client, source) {
+    if (raw.disabled === true)
+        return null;
+    const env = {};
+    for (const [k, v] of Object.entries(raw.env ?? {})) {
+        if (typeof v === 'string')
+            env[k] = v;
+    }
+    const envVarNames = Object.keys(env).sort();
+    // Remote entries carry a url (and sometimes type http/sse) instead of a command.
+    if (!raw.command && typeof raw.url === 'string') {
+        return { name, client, source, transport: 'remote', url: raw.url, envVarNames };
+    }
+    if (typeof raw.command !== 'string' || raw.command.trim() === '')
+        return null;
+    const args = Array.isArray(raw.args) ? raw.args.filter((a) => typeof a === 'string') : [];
+    const argv = [raw.command, ...args];
+    return {
+        name,
+        client,
+        source,
+        transport: 'stdio',
+        // Quote only the args that need it, so the printed command stays copy-pasteable.
+        command: argv.map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' '),
+        argv,
+        envVarNames,
+        env: envVarNames.length ? env : undefined,
+    };
+}
+/**
+ * Pull every server out of one parsed config document. `cwd` selects the
+ * project scope in Claude Code's `~/.claude.json`, which keys per-project
+ * servers by absolute directory.
+ */
+export function extractServers(doc, meta) {
+    if (!doc || typeof doc !== 'object')
+        return [];
+    const d = doc;
+    const out = [];
+    const addBlock = (block) => {
+        if (!block || typeof block !== 'object')
+            return;
+        for (const [name, raw] of Object.entries(block)) {
+            if (!raw || typeof raw !== 'object')
+                continue;
+            const s = toServer(name, raw, meta.client, meta.source);
+            if (s)
+                out.push(s);
+        }
+    };
+    addBlock(d.mcpServers);
+    addBlock(d.servers); // VS Code
+    if (meta.cwd && d.projects && typeof d.projects === 'object') {
+        const project = d.projects[meta.cwd];
+        if (project && typeof project === 'object')
+            addBlock(project.mcpServers);
+    }
+    // A name can legitimately appear in both blocks of the same file; keep the first.
+    const seen = new Set();
+    return out.filter((s) => (seen.has(s.name) ? false : (seen.add(s.name), true)));
+}
+/** Every place a client config is known to live, whether or not it exists. */
+export function configCandidates(env) {
+    const { home, cwd, platform } = env;
+    const desktop = platform === 'darwin'
+        ? join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+        : platform === 'win32'
+            ? join(env.appData ?? join(home, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json')
+            : join(home, '.config', 'Claude', 'claude_desktop_config.json');
+    return [
+        { client: 'claude-desktop', path: desktop },
+        { client: 'claude-code', path: join(home, '.claude.json') },
+        { client: 'claude-code', path: join(cwd, '.mcp.json') },
+        { client: 'cursor', path: join(home, '.cursor', 'mcp.json') },
+        { client: 'cursor', path: join(cwd, '.cursor', 'mcp.json') },
+        { client: 'vscode', path: join(cwd, '.vscode', 'mcp.json') },
+        { client: 'windsurf', path: join(home, '.codeium', 'windsurf', 'mcp_config.json') },
+    ];
+}
+/** Read + parse the candidates that exist. Unreadable files are reported, not thrown. */
+export function loadConfigs(candidates, cwd) {
+    const out = [];
+    for (const c of candidates) {
+        if (!existsSync(c.path))
+            continue;
+        try {
+            const doc = parseJsonc(readFileSync(c.path, 'utf8'));
+            const servers = extractServers(doc, { client: c.client, source: c.path, cwd });
+            // A config with no MCP block at all (e.g. a ~/.claude.json holding only
+            // session history) is not worth a line in the report.
+            if (servers.length === 0)
+                continue;
+            out.push({ client: c.client, source: c.path, servers });
+        }
+        catch (e) {
+            out.push({ client: c.client, source: c.path, servers: [], error: e.message });
+        }
+    }
+    return out;
+}

package/dist/audit/run.d.ts

@@ -0,0 +1,19 @@
+import type { Measurement } from '../core/types.js';
+import { type AuditReport } from './audit.js';
+import { type LoadedConfig } from './config.js';
+export interface AuditOptions {
+    /** Explicit config path(s); when empty, every known client location is tried. */
+    configPaths?: string[];
+    cwd?: string;
+    home?: string;
+    timeoutMs?: number;
+    concurrency?: number;
+    docker?: boolean;
+    contextWindow?: number;
+    budget?: number;
+    onProgress?: (name: string, done: number, total: number) => void;
+}
+export declare function discover(opts?: AuditOptions): LoadedConfig[];
+/** Measure every distinct stdio server across the given configs, once each. */
+export declare function measureAll(configs: LoadedConfig[], opts?: AuditOptions): Promise<Map<string, Measurement>>;
+export declare function runAudit(opts?: AuditOptions): Promise<AuditReport>;