mcp-context-cost 0.2.0 → 0.3.0

package/README.md

@@ -3,7 +3,8 @@
 [![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.**
+**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
@@ -29,6 +30,53 @@ 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`,
@@ -71,7 +119,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 |
+| `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 +152,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                        # 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)

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>;

package/dist/audit/run.js

@@ -0,0 +1,59 @@
+/**
+ * Audit orchestration: discover configs, measure each distinct server once,
+ * hand the results to `buildReport`.
+ *
+ * Kept apart from audit.ts so the arithmetic stays spawn-free and testable.
+ */
+import { homedir } from 'node:os';
+import { measureServer } from '../sweep/run.js';
+import { buildReport, serverKey } from './audit.js';
+import { configCandidates, loadConfigs } from './config.js';
+export function discover(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? homedir();
+    const candidates = opts.configPaths && opts.configPaths.length
+        ? opts.configPaths.map((path) => ({ client: 'explicit', path }))
+        : configCandidates({ home, cwd, platform: process.platform, appData: process.env.APPDATA });
+    return loadConfigs(candidates, cwd);
+}
+/** Measure every distinct stdio server across the given configs, once each. */
+export async function measureAll(configs, opts = {}) {
+    const unique = new Map();
+    for (const cfg of configs) {
+        for (const s of cfg.servers) {
+            if (s.transport !== 'stdio')
+                continue;
+            // Two clients pointing at the same argv are one measurement, not two.
+            if (!unique.has(serverKey(s)))
+                unique.set(serverKey(s), s);
+        }
+    }
+    const queue = [...unique.entries()];
+    const total = queue.length;
+    const measured = new Map();
+    let done = 0;
+    const worker = async () => {
+        for (let next = queue.shift(); next; next = queue.shift()) {
+            const [key, s] = next;
+            const m = await measureServer(s.name, s.command ?? '', {
+                argv: s.argv,
+                env: s.env,
+                timeoutMs: opts.timeoutMs ?? 60_000,
+                docker: opts.docker,
+                persist: false,
+            });
+            measured.set(key, m);
+            opts.onProgress?.(s.name, ++done, total);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(opts.concurrency ?? 3, total || 1)) }, worker));
+    return measured;
+}
+export async function runAudit(opts = {}) {
+    const configs = discover(opts);
+    const measured = await measureAll(configs, opts);
+    return buildReport(configs, measured, {
+        contextWindow: opts.contextWindow,
+        budget: opts.budget,
+    });
+}

package/dist/cli.js

@@ -2,12 +2,14 @@
 /**
  * mcp-context-cost CLI — the dispute drill as a command.
  *
+ *   mcp-context-cost audit [--budget N] [--json]      measure the servers in your own
+ *                                                MCP config; exit 1 if over budget
  *   mcp-context-cost verify <measurement.json> [--json]   re-derive the number from the
  *                                                published capture; exit 1 on mismatch
  *   mcp-context-cost verify --remote <url> [--json]   same, fetched from a measurement URL
  *   mcp-context-cost measure --name x --command "npx -y ..."   one-off measurement
  *
- * Exit codes: 0 ok, 1 verification/measurement failed, 2 usage error.
+ * Exit codes: 0 ok, 1 verification/measurement/budget failed, 2 usage error.
  */
 import { readFileSync } from 'node:fs';
 import { canonicalString, countTokens, sha256Hex } from './core/canonical.js';
@@ -29,7 +31,50 @@ export function verifyMeasurement(m) {
     return { ok: problems.length === 0, rederivedTokens: tokens, rederivedSha: sha, problems };
 }
 const [, , cmd, ...rest] = process.argv;
-if (cmd === 'verify') {
+if (cmd === 'audit') {
+    const argOf = (name) => {
+        const i = rest.indexOf(`--${name}`);
+        return i >= 0 ? rest[i + 1] : undefined;
+    };
+    const all = (name) => rest.flatMap((a, i) => (a === `--${name}` && rest[i + 1] ? [rest[i + 1]] : []));
+    const json = rest.includes('--json');
+    const numeric = (name) => {
+        const raw = argOf(name);
+        if (raw === undefined)
+            return undefined;
+        const v = Number(raw);
+        if (!Number.isFinite(v) || v <= 0) {
+            console.error(`--${name} must be a positive number, got '${raw}'`);
+            process.exit(2);
+        }
+        return v;
+    };
+    const budget = numeric('budget');
+    const { runAudit } = await import('./audit/run.js');
+    const { formatReport } = await import('./audit/audit.js');
+    const report = await runAudit({
+        configPaths: all('config'),
+        budget,
+        contextWindow: numeric('context'),
+        timeoutMs: numeric('timeout'),
+        concurrency: numeric('concurrency'),
+        docker: rest.includes('--docker'),
+        // Progress goes to stderr so `--json` stdout stays a single parseable object.
+        onProgress: json ? undefined : (name, done, total) => process.stderr.write(`  [${done}/${total}] ${name}\n`),
+    });
+    if (report.configs.length === 0) {
+        const where = report.problems.length ? `\n${report.problems.map((p) => `  ${p}`).join('\n')}` : '';
+        if (json)
+            console.log(JSON.stringify(report));
+        else
+            console.error(`no MCP config found. Looked in the standard Claude Desktop / Claude Code / Cursor / VS Code / Windsurf locations.${where}\n` +
+                `Point at one explicitly: mcp-context-cost audit --config <path/to/mcp.json>`);
+        process.exit(1);
+    }
+    console.log(json ? JSON.stringify(report) : formatReport(report));
+    process.exit(report.budget?.over ? 1 : 0);
+}
+else if (cmd === 'verify') {
     const json = rest.includes('--json');
     const remoteIdx = rest.indexOf('--remote');
     const remoteUrl = remoteIdx >= 0 ? rest[remoteIdx + 1] : undefined;
@@ -104,8 +149,10 @@ else if (cmd !== undefined && cmd !== '--help' && cmd !== '-h') {
 }
 else {
     console.log('mcp-context-cost — reproducible context-cost measurement for MCP servers');
+    console.log('  audit [--config <path>] [--budget N]  measure the servers in your own MCP config');
+    console.log('        [--json] [--context N] [--timeout ms] [--concurrency N] [--docker]');
     console.log('  verify <measurement.json> [--json]    re-derive tokens+sha from the published capture');
     console.log('  verify --remote <url> [--json]        same, fetched from a measurement URL');
     console.log('  measure --name x --command "npx -y <server>"   run a one-off measurement');
-    console.log('exit codes: 0 ok, 1 verification/measurement failed, 2 usage error');
+    console.log('exit codes: 0 ok, 1 verification/measurement/budget failed, 2 usage error');
 }

package/dist/sweep/run.d.ts

@@ -7,5 +7,16 @@ export interface MeasureOptions {
     dockerImage?: string;
     /** env var NAMES to provide as dummy values (docker mode). */
     dummyEnv?: string[];
+    /**
+     * Exact argv, when the caller already has it (client configs store command and
+     * args separately). Avoids re-splitting a joined string on spaces, which would
+     * break any path containing one. Host path only — docker still wraps `command`.
+     */
+    argv?: string[];
+    /**
+     * Write results/<name>/measurement.json + badges/<name>.json (default true).
+     * `audit` runs in the user's own directory and must not litter it.
+     */
+    persist?: boolean;
 }
 export declare function measureServer(name: string, command: string, opts?: MeasureOptions): Promise<Measurement>;

package/dist/sweep/run.js

@@ -5,7 +5,8 @@
  * Runs tools/list capture TWICE; differing tool sets -> status "dynamic".
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { captureTools } from './client.js';
 import { dockerize } from './docker.js';
 import { measureTools, failedMeasurement, canonicalString } from '../core/canonical.js';
@@ -15,11 +16,14 @@ function arg(name) {
     return i >= 0 ? process.argv[i + 1] : undefined;
 }
 export async function measureServer(name, command, opts = {}) {
-    if (!/^[a-z0-9][a-z0-9._-]*$/i.test(name) || name.includes('..')) {
+    const persist = opts.persist !== false;
+    // The name becomes a directory when persisting; that's the only reason it's
+    // constrained, so in-memory callers may use whatever the config called it.
+    if (persist && (!/^[a-z0-9][a-z0-9._-]*$/i.test(name) || name.includes('..'))) {
         throw new Error(`invalid server name '${name}' — letters/digits/dot/dash/underscore only`);
     }
     const root = opts.root ?? process.cwd();
-    let spec = command;
+    let spec = opts.argv && opts.argv.length ? { command: opts.argv[0], argv: opts.argv.slice(1) } : command;
     let isolation = { docker: false };
     let containerName;
     if (opts.docker && command.trimStart().startsWith('docker ')) {
@@ -67,6 +71,8 @@ export async function measureServer(name, command, opts = {}) {
             spawn('docker', ['rm', '-f', containerName], { stdio: 'ignore' }).on('error', () => { });
         }
     }
+    if (!persist)
+        return m;
     const resultDir = join(root, 'results', name);
     mkdirSync(resultDir, { recursive: true });
     writeFileSync(join(resultDir, 'measurement.json'), JSON.stringify(m, null, 2) + '\n');
@@ -74,7 +80,10 @@ export async function measureServer(name, command, opts = {}) {
     writeFileSync(join(root, 'badges', `${name}.json`), JSON.stringify(toBadge(m)) + '\n');
     return m;
 }
-const isMain = process.argv[1]?.endsWith('run.ts') || process.argv[1]?.endsWith('run.js');
+// Exact path match, not endsWith('run.ts'): any other file whose name happens to
+// end in "run.ts" (src/audit/run.ts, a scratch dryrun.ts) would otherwise run this
+// block and exit 2 on missing --name.
+const isMain = process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isMain) {
     const name = arg('name');
     const command = arg('command');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-context-cost",
-  "version": "0.2.0",
-  "description": "Reproducible context-cost badges for MCP servers — measure what a server's tool schemas cost before the agent does any work",
+  "version": "0.3.0",
+  "description": "Measure what your MCP servers cost in context tokens — audit your own config, or badge the server you publish",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -15,6 +15,10 @@
     "model-context-protocol",
     "tokens",
     "context-window",
+    "audit",
+    "token-budget",
+    "claude",
+    "cursor",
     "badge",
     "shields",
     "developer-tools"