mcp-context-cost 0.2.0 → 0.4.0

package/dist/audit/run.d.ts

@@ -0,0 +1,31 @@
+import type { Measurement } from '../core/types.js';
+import { type DivergenceRun } from '../core/divergence.js';
+import { type AuditReport } from './audit.js';
+import { type LoadedConfig } from './config.js';
+/** Where the published `tools-delta/v1` run lives when `--claude` doesn't override it. */
+export declare const DEFAULT_DIVERGENCE_URL = "https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/divergence.json";
+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;
+    /** Join each measured server against the published Claude divergence run. */
+    claude?: boolean;
+    /** Override the divergence.json source — mainly for tests and self-hosted mirrors. */
+    divergenceUrl?: string;
+    onProgress?: (name: string, done: number, total: number) => void;
+}
+/** Fetch and parse the published divergence run. Never throws: a failure is a report problem, not a crash. */
+export declare function fetchDivergence(url: string): Promise<{
+    run: DivergenceRun | null;
+    problem?: string;
+}>;
+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,86 @@
+/**
+ * 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 { parseDivergence } from '../core/divergence.js';
+import { buildReport, serverKey } from './audit.js';
+import { configCandidates, loadConfigs } from './config.js';
+/** Where the published `tools-delta/v1` run lives when `--claude` doesn't override it. */
+export const DEFAULT_DIVERGENCE_URL = 'https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/divergence.json';
+/** Fetch and parse the published divergence run. Never throws: a failure is a report problem, not a crash. */
+export async function fetchDivergence(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+        if (!res.ok)
+            return { run: null, problem: `claude divergence: HTTP ${res.status} fetching ${url}` };
+        const run = parseDivergence(await res.text());
+        return run ? { run } : { run: null, problem: `claude divergence: malformed data at ${url}` };
+    }
+    catch (e) {
+        return { run: null, problem: `claude divergence: failed to fetch ${url}: ${e.message}` };
+    }
+}
+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);
+    let divergence = null;
+    let divergenceProblem;
+    if (opts.claude) {
+        const fetched = await fetchDivergence(opts.divergenceUrl ?? DEFAULT_DIVERGENCE_URL);
+        divergence = fetched.run;
+        divergenceProblem = fetched.problem;
+    }
+    const report = buildReport(configs, measured, {
+        contextWindow: opts.contextWindow,
+        budget: opts.budget,
+        divergence,
+    });
+    if (divergenceProblem)
+        report.problems.push(divergenceProblem);
+    return report;
+}

package/dist/cli.d.ts

@@ -6,3 +6,24 @@ export declare function verifyMeasurement(m: Measurement): {
     rederivedSha: string | null;
     problems: string[];
 };
+/** Derives a servers.yaml-style slug from a remote URL's hostname, e.g. mcp.deepwiki.com -> deepwiki. */
+export declare function slugFromUrl(url: string): string;
+/** Installed version, for error messages that need to say which one you are running. */
+export declare function cliVersion(): string;
+/**
+ * Reject flags this build does not know.
+ *
+ * An older CLI used to ignore an unrecognised flag and carry on. That is the exact failure
+ * this project exists to catch, in our own tool: `audit --baseline base.json
+ * --max-increase 2000` on a build without those flags ran a plain audit and **exited 0** —
+ * a green CI check on a gate that never ran. The README documents flags before they are
+ * published, so the version skew is not hypothetical; it is the normal case for anyone
+ * running `npx -y mcp-context-cost`.
+ *
+ * So an unknown flag is a usage error, and the message names the running version, because
+ * the likeliest cause is that the reader's command is newer than their install.
+ */
+export declare function unknownFlags(argv: string[], spec: {
+    value: string[];
+    boolean: string[];
+}): string[];

package/dist/cli.js

@@ -2,14 +2,26 @@
 /**
  * mcp-context-cost CLI — the dispute drill as a command.
  *
+ *   mcp-context-cost audit [--budget N] [--claude] [--json]   measure the servers in your
+ *                                                own MCP config; exit 1 if over budget.
+ *   mcp-context-cost audit --baseline <report.json> [--max-increase N]   diff against a
+ *                                                stored earlier report; exit 1 if this
+ *                                                config change adds more than N tokens
+ *                                                to every request (or if it can't tell).
+ *                                                --claude adds each server's Anthropic-
+ *                                                request cost where the published capture
+ *                                                hash matches what's installed.
  *   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
+ *   mcp-context-cost measure --remote <url> [--name x]   same, via the mcp-remote bridge
+ *                                                (name defaults to the URL's hostname)
  *
- * 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 { createRequire } from 'node:module';
 import { canonicalString, countTokens, sha256Hex } from './core/canonical.js';
 import { toBadge } from './core/badge.js';
 export function verifyMeasurement(m) {
@@ -28,8 +40,156 @@ export function verifyMeasurement(m) {
         problems.push(`toolCount mismatch: capture has ${m.rawToolsCapture.length}, stored ${m.toolCount}`);
     return { ok: problems.length === 0, rederivedTokens: tokens, rederivedSha: sha, problems };
 }
+/** Derives a servers.yaml-style slug from a remote URL's hostname, e.g. mcp.deepwiki.com -> deepwiki. */
+export function slugFromUrl(url) {
+    const host = new URL(url).hostname.replace(/^(www|mcp)\./, '');
+    return host.replace(/[^a-z0-9]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'remote';
+}
+/** Installed version, for error messages that need to say which one you are running. */
+export function cliVersion() {
+    try {
+        return createRequire(import.meta.url)('../package.json').version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Reject flags this build does not know.
+ *
+ * An older CLI used to ignore an unrecognised flag and carry on. That is the exact failure
+ * this project exists to catch, in our own tool: `audit --baseline base.json
+ * --max-increase 2000` on a build without those flags ran a plain audit and **exited 0** —
+ * a green CI check on a gate that never ran. The README documents flags before they are
+ * published, so the version skew is not hypothetical; it is the normal case for anyone
+ * running `npx -y mcp-context-cost`.
+ *
+ * So an unknown flag is a usage error, and the message names the running version, because
+ * the likeliest cause is that the reader's command is newer than their install.
+ */
+export function unknownFlags(argv, spec) {
+    const known = new Set([...spec.value, ...spec.boolean]);
+    const unknown = [];
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (!tok.startsWith('--'))
+            continue;
+        const name = tok.slice(2).split('=')[0];
+        if (!known.has(name)) {
+            unknown.push(tok.split('=')[0]);
+            continue;
+        }
+        // Skip a value-taking flag's value, so `--command "--weird"` is not read as a flag.
+        if (spec.value.includes(name) && !tok.includes('='))
+            i++;
+    }
+    return unknown;
+}
+function rejectUnknownFlags(cmd, argv, spec) {
+    const bad = unknownFlags(argv, spec);
+    if (!bad.length)
+        return;
+    const all = [...spec.value, ...spec.boolean].sort().map((f) => `--${f}`).join(' ');
+    console.error(`unknown flag for \`${cmd}\`: ${bad.join(', ')}`);
+    console.error(`this is mcp-context-cost ${cliVersion()} — if you copied the command from the README,`);
+    console.error(`your install may be older than the docs. Try: npx -y mcp-context-cost@latest ${cmd} ...`);
+    console.error(`known flags for ${cmd}: ${all}`);
+    process.exit(2);
+}
 const [, , cmd, ...rest] = process.argv;
-if (cmd === 'verify') {
+if (cmd === 'audit') {
+    rejectUnknownFlags('audit', rest, {
+        value: ['config', 'budget', 'baseline', 'max-increase', 'context', 'timeout', 'concurrency', 'divergence-url'],
+        boolean: ['json', 'docker', 'claude'],
+    });
+    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 nonNegative = (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 zero or a positive number, got '${raw}'`);
+            process.exit(2);
+        }
+        return v;
+    };
+    const budget = numeric('budget');
+    const baselinePath = argOf('baseline');
+    const maxIncrease = nonNegative('max-increase');
+    if (maxIncrease !== undefined && !baselinePath) {
+        console.error('--max-increase needs a --baseline to measure the increase against');
+        process.exit(2);
+    }
+    const { buildDiff, evaluateIncreaseGate, parseBaselineReport } = await import('./audit/diff.js');
+    // Read and shape-check the baseline BEFORE measuring anything: a typo in the path
+    // should cost a second, not a full server sweep that is then thrown away.
+    let baseline;
+    if (baselinePath) {
+        let raw;
+        try {
+            raw = readFileSync(baselinePath, 'utf8');
+        }
+        catch (e) {
+            console.error(`cannot read baseline ${baselinePath}: ${e.message}`);
+            process.exit(2);
+        }
+        const parsed = parseBaselineReport(raw);
+        if (!parsed.report) {
+            console.error(`${baselinePath}: ${parsed.problem}`);
+            process.exit(2);
+        }
+        baseline = parsed.report;
+    }
+    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'),
+        claude: rest.includes('--claude'),
+        divergenceUrl: argOf('divergence-url'),
+        // 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);
+    }
+    if (baseline) {
+        report.diff = buildDiff(baseline, report);
+        if (maxIncrease !== undefined)
+            report.increaseGate = evaluateIncreaseGate(report.diff, maxIncrease);
+    }
+    console.log(json ? JSON.stringify(report) : formatReport(report));
+    process.exit(report.budget?.over || report.increaseGate?.pass === false ? 1 : 0);
+}
+else if (cmd === 'verify') {
+    rejectUnknownFlags('verify', rest, { value: ['remote'], boolean: ['json'] });
     const json = rest.includes('--json');
     const remoteIdx = rest.indexOf('--remote');
     const remoteUrl = remoteIdx >= 0 ? rest[remoteIdx + 1] : undefined;
@@ -76,21 +236,36 @@ if (cmd === 'verify') {
     process.exit(1);
 }
 else if (cmd === 'measure') {
+    rejectUnknownFlags('measure', rest, {
+        value: ['name', 'command', 'remote', 'timeout', 'docker-image'],
+        boolean: ['docker'],
+    });
     const argOf = (name) => {
         const i = rest.indexOf(`--${name}`);
         return i >= 0 ? rest[i + 1] : undefined;
     };
-    const name = argOf('name');
     const command = argOf('command');
-    if (!name || !command) {
+    const remoteUrl = argOf('remote');
+    if (remoteUrl && !/^https?:\/\//i.test(remoteUrl)) {
+        console.error(`--remote must be an http(s) URL, got '${remoteUrl}'`);
+        process.exit(2);
+    }
+    if (!command && !remoteUrl) {
+        console.error('usage: mcp-context-cost measure --name <slug> --command "npx -y <server>" [--timeout ms] [--docker]');
+        console.error('       mcp-context-cost measure --remote <url> [--name <slug>] [--timeout ms] [--docker]');
+        process.exit(2);
+    }
+    const name = argOf('name') ?? (remoteUrl ? slugFromUrl(remoteUrl) : undefined);
+    if (!name) {
         console.error('usage: mcp-context-cost measure --name <slug> --command "npx -y <server>" [--timeout ms] [--docker]');
         process.exit(2);
     }
     const { measureServer } = await import('./sweep/run.js');
-    const m = await measureServer(name, command, {
+    const m = await measureServer(name, remoteUrl ? `npx -y mcp-remote ${remoteUrl}` : command, {
         timeoutMs: Number(argOf('timeout') ?? 60_000),
         docker: rest.includes('--docker'),
         dockerImage: argOf('docker-image'),
+        argv: remoteUrl ? ['npx', '-y', 'mcp-remote', remoteUrl] : undefined,
     });
     const ok = m.status === 'measured' || m.status === 'dynamic';
     console.log(ok
@@ -104,8 +279,14 @@ 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] [--claude]  measure the servers in your own MCP config');
+    console.log('        [--json] [--context N] [--timeout ms] [--concurrency N] [--docker]');
+    console.log('        [--baseline <report.json>] [--max-increase N]   diff against an earlier');
+    console.log('                                              audit --json report; --max-increase');
+    console.log('                                              fails when a change adds too much');
     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('  measure --remote <url> [--name x]      measure a remote server via mcp-remote');
+    console.log('exit codes: 0 ok, 1 verification/measurement/budget failed, 2 usage error');
 }

package/dist/sweep/dashboard.d.ts

@@ -1 +1,9 @@
+/**
+ * A 12-point-max inline trend line, oldest to newest. Muted stroke (this is
+ * texture, not a headline number) with the current value picked out as an
+ * accent dot, per the sparkline spec: de-emphasis hue for the line, accent
+ * for "now". Flat series still draw a level line rather than faking a zero
+ * baseline. Returns '' when there's nothing to trend (0-1 points).
+ */
+export declare function renderSparkline(tokens: number[]): string;
 export declare function generateDashboard(root?: string): string;

package/dist/sweep/dashboard.js

@@ -7,6 +7,38 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { parse } from 'yaml';
 import { bandColor, BAND_META } from '../core/bands.js';
+import { parseHistory } from './history.js';
+/** Longest series a sparkline plots — a stat-tile trend, not a full chart. */
+const SPARK_MAX_POINTS = 12;
+/**
+ * A 12-point-max inline trend line, oldest to newest. Muted stroke (this is
+ * texture, not a headline number) with the current value picked out as an
+ * accent dot, per the sparkline spec: de-emphasis hue for the line, accent
+ * for "now". Flat series still draw a level line rather than faking a zero
+ * baseline. Returns '' when there's nothing to trend (0-1 points).
+ */
+export function renderSparkline(tokens) {
+    const points = tokens.slice(-SPARK_MAX_POINTS);
+    if (points.length < 2)
+        return '';
+    const w = 56;
+    const h = 18;
+    const pad = 3;
+    const min = Math.min(...points);
+    const max = Math.max(...points);
+    const range = max - min;
+    const stepX = (w - pad * 2) / (points.length - 1);
+    const coords = points.map((v, i) => {
+        const x = pad + i * stepX;
+        const y = range === 0 ? h / 2 : pad + (h - pad * 2) * (1 - (v - min) / range);
+        return `${x.toFixed(1)},${y.toFixed(1)}`;
+    });
+    const [lastX, lastY] = coords[coords.length - 1].split(',');
+    return `<svg class="spark" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}" aria-hidden="true" focusable="false">
+    <polyline points="${coords.join(' ')}" fill="none" stroke="var(--muted)" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/>
+    <circle cx="${lastX}" cy="${lastY}" r="2.2" fill="var(--accent)" stroke="var(--surface)" stroke-width="1"/>
+  </svg>`;
+}
 const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 export function generateDashboard(root = process.cwd()) {
     const doc = parse(readFileSync(join(root, 'servers.yaml'), 'utf8'));
@@ -15,6 +47,12 @@ export function generateDashboard(root = process.cwd()) {
         ? JSON.parse(readFileSync(divergencePath, 'utf8'))
         : {};
     const dSrv = divergence.servers ?? {};
+    const historyPath = join(root, 'results', 'history.csv');
+    const history = existsSync(historyPath) ? parseHistory(readFileSync(historyPath, 'utf8')) : [];
+    const seriesFor = (name) => history
+        .filter((h) => h.server === name)
+        .sort((a, b) => a.date.localeCompare(b.date))
+        .map((h) => h.tokens);
     const rows = doc.servers.map((entry) => {
         const p = join(root, 'results', entry.name, 'measurement.json');
         return { entry, m: existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null };
@@ -39,11 +77,15 @@ export function generateDashboard(root = process.cwd()) {
         const pct = Math.max(1.2, (t / max) * 100);
         const div = dSrv[r.entry.name];
         const claudeTip = div ? ` · in a Claude request: ${fmt(div.claudeDelta)} tok` : '';
+        const series = seriesFor(r.entry.name);
+        const spark = renderSparkline(series);
+        const trendTip = series.length > 1 ? ` · ${series.length}-sweep trend: ${series[0].toLocaleString('en-US')} → ${series[series.length - 1].toLocaleString('en-US')}` : '';
         // The whole row is the link to the server's detail page (docs/servers/).
-        return `<a class="row" href="servers/${encodeURIComponent(r.entry.name)}.html" data-tip="${esc(m.toolCount)} tools · largest: ${esc(largest?.name)} (${fmt(largest?.tokens ?? 0)} tok)${claudeTip} · ${esc(r.entry.category)} · ${esc(m.status)}${m.serverVersion ? ' · v' + esc(String(m.serverVersion).replace(/^v/, '')) : ''}">
+        return `<a class="row" href="servers/${encodeURIComponent(r.entry.name)}.html" data-tip="${esc(m.toolCount)} tools · largest: ${esc(largest?.name)} (${fmt(largest?.tokens ?? 0)} tok)${claudeTip}${trendTip} · ${esc(r.entry.category)} · ${esc(m.status)}${m.serverVersion ? ' · v' + esc(String(m.serverVersion).replace(/^v/, '')) : ''}">
   <span class="rank">${i + 1}</span>
   <span class="name">${esc(r.entry.name)}</span>
   <span class="track"><span class="bar" style="width:${pct.toFixed(1)}%"></span></span>
+  <span class="spark-cell">${spark}</span>
   <span class="val"><span class="dot dot-${band}" aria-hidden="true"></span>${fmt(t)}<span class="bandname">${meta.label}</span></span>
 </a>`;
     })
@@ -59,7 +101,11 @@ export function generateDashboard(root = process.cwd()) {
         .map((r, i) => {
         const m = r.m;
         const div = dSrv[r.entry.name];
-        return `<tr><td>${i + 1}</td><td>${esc(r.entry.name)}</td><td class="num">${fmt(m.totalTokens)}</td><td class="num">${div ? fmt(div.claudeDelta) : '—'}</td><td class="num">${esc(m.toolCount)}</td><td>${esc(BAND_META[bandColor(m.totalTokens)].label)}</td><td>${esc(r.entry.category)}</td></tr>`;
+        const series = seriesFor(r.entry.name);
+        const trend = series.length > 1
+            ? `${series[series.length - 1] - series[0] >= 0 ? '+' : ''}${fmt(series[series.length - 1] - series[0])} / ${series.length}d`
+            : '—';
+        return `<tr><td>${i + 1}</td><td>${esc(r.entry.name)}</td><td class="num">${fmt(m.totalTokens)}</td><td class="num">${div ? fmt(div.claudeDelta) : '—'}</td><td class="num">${esc(m.toolCount)}</td><td>${esc(BAND_META[bandColor(m.totalTokens)].label)}</td><td>${esc(r.entry.category)}</td><td class="num">${trend}</td></tr>`;
     })
         .join('\n');
     const specimens = [measured[measured.length - 1], measured[0]]
@@ -117,13 +163,15 @@ export function generateDashboard(root = process.cwd()) {
   .stat .l { font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: var(--muted); }
 
   .board { background: var(--surface); border: 1px solid var(--line); border-radius: 8px; padding: 14px 16px; }
-  .row { display: grid; grid-template-columns: 2ch minmax(120px, 190px) 1fr max-content; gap: 10px; align-items: center; padding: 3px 4px; border-radius: 4px; outline: none; color: inherit; text-decoration: none; }
+  .row { display: grid; grid-template-columns: 2ch minmax(120px, 190px) 1fr 56px max-content; gap: 10px; align-items: center; padding: 3px 4px; border-radius: 4px; outline: none; color: inherit; text-decoration: none; }
   .row:hover, .row:focus-visible { background: var(--accent-soft); }
   .row:hover .name, .row:focus-visible .name { text-decoration: underline; }
   .rank { font-family: ui-monospace, Menlo, monospace; font-size: 11px; color: var(--muted); text-align: right; font-variant-numeric: tabular-nums; }
   .name { font-size: 0.86rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
   .track { background: var(--track); border-radius: 3px; height: 12px; overflow: hidden; }
   .bar { display: block; height: 100%; background: var(--accent); border-radius: 3px 3px 3px 3px; min-width: 3px; }
+  .spark-cell { display: flex; align-items: center; justify-content: center; height: 18px; }
+  .spark-cell:empty { visibility: hidden; }
   .val { font-family: ui-monospace, Menlo, monospace; font-variant-numeric: tabular-nums; font-size: 0.82rem; display: flex; align-items: center; gap: 6px; }
   .dot { width: 8px; height: 8px; border-radius: 50%; display: inline-block; box-shadow: 0 0 0 2px var(--surface); }
   .dot-brightgreen { background: var(--b-brightgreen); } .dot-green { background: var(--b-green); }
@@ -172,7 +220,7 @@ export function generateDashboard(root = process.cwd()) {
   </div>
 
   <h2>Leaderboard</h2>
-  <p class="h2sub">Tokens = o200k_base count of the canonical <code>tools/list</code> bytes — the wire payload. What a <em>Claude request</em> actually carries can differ sharply (github: 54,422 on the wire, ${dSrv['github'] ? fmt(dSrv['github'].claudeDelta) : '…'} in a request — 80% of its schema bytes are fields no Anthropic request sends). Hover a row for both numbers; <a href="METHODOLOGY.html#claude-divergence">method</a>.</p>
+  <p class="h2sub">Tokens = o200k_base count of the canonical <code>tools/list</code> bytes — the wire payload. What a <em>Claude request</em> actually carries can differ sharply (github: 54,422 on the wire, ${dSrv['github'] ? fmt(dSrv['github'].claudeDelta) : '…'} in a request — 80% of its schema bytes are fields no Anthropic request sends). The trend line plots tokens across every sweep date on record (oldest→newest, dot = current); servers with one sweep so far show no line yet. Hover a row for exact numbers; <a href="METHODOLOGY.html#claude-divergence">method</a>.</p>
   <div class="board">
 ${barRows || '<p class="h2sub">Sweep in progress — first results land shortly.</p>'}
   </div>
@@ -198,7 +246,7 @@ ${barRows || '<p class="h2sub">Sweep in progress — first results land shortly.
 
   <details><summary>Full data table</summary>
   <div class="tablewrap" style="margin-top:10px"><table>
-    <thead><tr><th>#</th><th>server</th><th>tokens (o200k)</th><th>claude req</th><th>tools</th><th>band</th><th>category</th></tr></thead>
+    <thead><tr><th>#</th><th>server</th><th>tokens (o200k)</th><th>claude req</th><th>tools</th><th>band</th><th>category</th><th>trend</th></tr></thead>
     <tbody>${tableRows}</tbody>
   </table></div>
   </details>

package/dist/sweep/docker.d.ts

@@ -12,6 +12,14 @@ export interface DockerOptions {
     dummyEnv?: string[];
     /** Container name, so a timed-out container can be force-removed. */
     containerName?: string;
+    /**
+     * Install `git` inside the container before launch. The slim base images
+     * carry no VCS, so `uvx --from git+...` installs fail with "Git executable
+     * not found" — this only prefixes the containerized invocation, never the
+     * recorded `launchCommand`, so the published command stays what a user with
+     * git already on PATH would actually run.
+     */
+    needsGit?: boolean;
 }
 export declare const DEFAULT_NODE_IMAGE = "public.ecr.aws/docker/library/node:22-slim";
 export declare const DEFAULT_PYTHON_IMAGE = "ghcr.io/astral-sh/uv:python3.12-bookworm-slim";

package/dist/sweep/docker.js

@@ -35,7 +35,10 @@ export function dockerize(commandLine, opts = {}) {
     for (const name of opts.dummyEnv ?? []) {
         argv.push('-e', `${name}=dummy`);
     }
-    argv.push(image, 'sh', '-lc', commandLine);
+    const gitPrefix = opts.needsGit
+        ? 'command -v git >/dev/null 2>&1 || (apt-get update -qq && apt-get install -y -qq --no-install-recommends git >/dev/null 2>&1); '
+        : '';
+    argv.push(image, 'sh', '-lc', gitPrefix + commandLine);
     return {
         command: 'docker',
         argv,
@@ -43,7 +46,9 @@ export function dockerize(commandLine, opts = {}) {
             docker: true,
             image,
             network: 'bridge',
-            note: 'network enabled for package fetch; clean FS, no host credentials',
+            note: opts.needsGit
+                ? 'network enabled for package fetch; clean FS, no host credentials, git installed'
+                : 'network enabled for package fetch; clean FS, no host credentials',
         },
     };
 }

package/dist/sweep/report.d.ts

@@ -11,6 +11,8 @@ export interface ServerEntry {
     remote?: boolean;
     dockerImage?: string;
     timeoutSeconds?: number;
+    /** Launch needs the `git` binary (e.g. `uvx --from git+...`) — absent from the slim isolation images. */
+    needsGit?: boolean;
 }
 /** Neutralize markdown/table syntax in third-party strings (tool names, notes). */
 export declare function mdCell(s: unknown): string;

package/dist/sweep/run.d.ts

@@ -7,5 +7,18 @@ export interface MeasureOptions {
     dockerImage?: string;
     /** env var NAMES to provide as dummy values (docker mode). */
     dummyEnv?: string[];
+    /** Install `git` in the container before launch (docker mode) — see docker.ts. */
+    needsGit?: boolean;
+    /**
+     * 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 ')) {
@@ -28,7 +32,12 @@ export async function measureServer(name, command, opts = {}) {
     }
     else if (opts.docker) {
         containerName = `mcp-ctx-${name}-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
-        const d = dockerize(command, { image: opts.dockerImage, dummyEnv: opts.dummyEnv, containerName });
+        const d = dockerize(command, {
+            image: opts.dockerImage,
+            dummyEnv: opts.dummyEnv,
+            containerName,
+            needsGit: opts.needsGit,
+        });
         spec = { command: d.command, argv: d.argv };
         isolation = d.isolation;
     }
@@ -67,6 +76,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 +85,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/dist/sweep/sweep-all.js

@@ -36,6 +36,7 @@ async function worker() {
             docker,
             dockerImage: e.dockerImage,
             dummyEnv: e.env ?? [],
+            needsGit: e.needsGit,
         });
         const secs = ((Date.now() - started) / 1000).toFixed(0);
         summary[e.name] =