mcp-context-cost 0.3.0 → 0.4.0

package/dist/audit/diff.js

@@ -0,0 +1,318 @@
+/** Parse and shape-check a stored report. A baseline that cannot be read is never "no change". */
+export function parseBaselineReport(text) {
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch (e) {
+        return { report: null, problem: `baseline is not JSON: ${e.message}` };
+    }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+        return { report: null, problem: 'baseline is not an audit report object' };
+    }
+    const r = doc;
+    if (!Array.isArray(r.configs)) {
+        return { report: null, problem: "baseline has no 'configs' array — is it the output of `audit --json`?" };
+    }
+    if (typeof r.methodologyVersion !== 'string' || typeof r.encoding !== 'string') {
+        return { report: null, problem: 'baseline is missing methodologyVersion/encoding — is it the output of `audit --json`?' };
+    }
+    for (const c of r.configs) {
+        if (!c || typeof c !== 'object' || typeof c.source !== 'string') {
+            return { report: null, problem: 'baseline has a config entry without a source path' };
+        }
+    }
+    return { report: doc };
+}
+function statesOf(cfg) {
+    const out = new Map();
+    for (const s of cfg.servers ?? [])
+        out.set(s.name, { present: true, tokens: typeof s.tokens === 'number' ? s.tokens : null });
+    // A skipped server IS in the config; it just has no number. Keeping it distinct
+    // from absent is the whole reason `removed` and `unmeasured-now` are separate kinds.
+    for (const s of cfg.skipped ?? [])
+        if (!out.has(s.name))
+            out.set(s.name, { present: true, tokens: null });
+    return out;
+}
+export function diffConfig(before, after, matchedBy) {
+    const afterShare = after.contextShare;
+    if (!before) {
+        return {
+            client: after.client,
+            source: after.source,
+            matchedBy: 'unmatched',
+            beforeTotal: null,
+            afterTotal: after.totalTokens,
+            delta: null,
+            beforeShare: null,
+            afterShare,
+            exact: false,
+            understatedBy: 0,
+            overstatedBy: 0,
+            servers: [],
+        };
+    }
+    const b = statesOf(before);
+    const a = statesOf(after);
+    const servers = [];
+    let understatedBy = 0;
+    let overstatedBy = 0;
+    let exact = true;
+    for (const name of new Set([...b.keys(), ...a.keys()])) {
+        const bs = b.get(name);
+        const as = a.get(name);
+        if (bs && !as) {
+            servers.push(bs.tokens === null
+                ? { name, kind: 'removed', before: null, after: null, delta: null, note: 'was in the config but never measured — removing it changed no measured cost' }
+                : { name, kind: 'removed', before: bs.tokens, after: null, delta: -bs.tokens });
+            continue;
+        }
+        if (!bs && as) {
+            servers.push(as.tokens === null
+                ? { name, kind: 'added', before: null, after: null, delta: null, note: 'added but not measurable — its cost is unknown, not zero' }
+                : { name, kind: 'added', before: null, after: as.tokens, delta: as.tokens });
+            continue;
+        }
+        if (!bs || !as)
+            continue;
+        if (bs.tokens !== null && as.tokens !== null) {
+            const delta = as.tokens - bs.tokens;
+            servers.push({ name, kind: delta === 0 ? 'unchanged' : 'changed', before: bs.tokens, after: as.tokens, delta });
+        }
+        else if (bs.tokens !== null && as.tokens === null) {
+            exact = false;
+            understatedBy += bs.tokens;
+            servers.push({
+                name,
+                kind: 'unmeasured-now',
+                before: bs.tokens,
+                after: null,
+                delta: null,
+                note: `measured ${bs.tokens.toLocaleString('en-US')} in the baseline and could not be measured now — its cost is missing from the total, not gone from your config`,
+            });
+        }
+        else if (bs.tokens === null && as.tokens !== null) {
+            exact = false;
+            overstatedBy += as.tokens;
+            servers.push({
+                name,
+                kind: 'unmeasured-before',
+                before: null,
+                after: as.tokens,
+                delta: null,
+                note: `could not be measured in the baseline and measures ${as.tokens.toLocaleString('en-US')} now — this cost is newly visible, not necessarily new`,
+            });
+        }
+        else {
+            servers.push({
+                name,
+                kind: 'unmeasured-both',
+                before: null,
+                after: null,
+                delta: null,
+                note: 'not measurable in either run — contributes 0 to both totals and hides an unknown cost',
+            });
+        }
+    }
+    // Biggest movers first; ties and non-deltas fall to the bottom in name order.
+    servers.sort((x, y) => Math.abs(y.delta ?? 0) - Math.abs(x.delta ?? 0) || x.name.localeCompare(y.name));
+    return {
+        client: after.client,
+        source: after.source,
+        matchedBy,
+        beforeTotal: before.totalTokens,
+        afterTotal: after.totalTokens,
+        delta: after.totalTokens - before.totalTokens,
+        beforeShare: before.contextShare ?? null,
+        afterShare,
+        exact,
+        understatedBy,
+        overstatedBy,
+        servers,
+    };
+}
+/**
+ * Pair current configs with baseline configs.
+ *
+ * Exact source path first. Then one deliberate fallback: if each side has
+ * exactly one config, they are the same config seen from two machines — the CI
+ * case, where a baseline recorded at /Users/… meets a checkout at /home/runner/….
+ * Anything looser would pair two unrelated clients and call the difference a
+ * change, so everything else stays unmatched and says so.
+ */
+export function pairConfigs(before, after) {
+    const unusedBefore = new Map(before.map((c) => [c.source, c]));
+    const pairs = [];
+    for (const cur of after) {
+        const hit = unusedBefore.get(cur.source);
+        if (hit) {
+            unusedBefore.delete(cur.source);
+            pairs.push({ before: hit, after: cur, matchedBy: 'source' });
+        }
+        else {
+            pairs.push({ before: null, after: cur, matchedBy: 'unmatched' });
+        }
+    }
+    if (before.length === 1 && after.length === 1 && pairs[0].before === null) {
+        pairs[0] = { before: before[0], after: after[0], matchedBy: 'sole-config' };
+        unusedBefore.delete(before[0].source);
+    }
+    return { pairs, dropped: [...unusedBefore.values()] };
+}
+export function buildDiff(baseline, current) {
+    const warnings = [];
+    let comparable = true;
+    if (baseline.methodologyVersion !== current.methodologyVersion) {
+        comparable = false;
+        warnings.push(`methodology changed (${baseline.methodologyVersion} → ${current.methodologyVersion}) — token counts from the two runs are not the same measurement`);
+    }
+    if (baseline.encoding !== current.encoding) {
+        comparable = false;
+        warnings.push(`encoding changed (${baseline.encoding} → ${current.encoding}) — the counts are in different units`);
+    }
+    if (baseline.contextWindow !== current.contextWindow) {
+        // Shares move, token counts do not. Worth saying, not worth invalidating.
+        warnings.push(`context window changed (${baseline.contextWindow.toLocaleString('en-US')} → ${current.contextWindow.toLocaleString('en-US')}) — shares are not comparable, token counts still are`);
+    }
+    const { pairs, dropped } = pairConfigs(baseline.configs, current.configs);
+    const configs = pairs.map((p) => diffConfig(p.before, p.after, p.matchedBy));
+    for (const c of configs) {
+        if (c.matchedBy === 'unmatched') {
+            warnings.push(`${c.source}: no matching config in the baseline — its ${c.afterTotal.toLocaleString('en-US')} tokens are shown as a total, not a change`);
+        }
+        if (c.matchedBy === 'sole-config' && c.source !== baseline.configs[0]?.source) {
+            warnings.push(`paired ${c.source} with the baseline's ${baseline.configs[0]?.source} — one config on each side, different paths`);
+        }
+    }
+    for (const d of dropped) {
+        warnings.push(`${d.source}: in the baseline (${d.totalTokens.toLocaleString('en-US')} tokens) and not found now — a config that disappeared is not a config that got cheaper`);
+    }
+    const increases = configs.filter((c) => typeof c.delta === 'number' && c.delta > 0);
+    increases.sort((a, b) => b.delta - a.delta);
+    return {
+        baselineGeneratedAt: baseline.generatedAt,
+        baselineMethodologyVersion: baseline.methodologyVersion,
+        comparable,
+        droppedConfigs: dropped.map((d) => ({ client: d.client, source: d.source, totalTokens: d.totalTokens })),
+        warnings,
+        configs,
+        worstIncrease: increases.length ? { source: increases[0].source, delta: increases[0].delta } : null,
+    };
+}
+const n = (x) => x.toLocaleString('en-US');
+const signed = (x) => `${x >= 0 ? '+' : '−'}${n(Math.abs(x))}`;
+const pct = (x) => `${(x * 100).toFixed(1)}%`;
+/** `--config <path>` records the client as 'explicit', which is a parser detail, not a name. */
+const clientLabel = (client) => (client === 'explicit' || !client ? 'this client' : client);
+export function formatDiff(diff, contextWindow) {
+    const lines = [];
+    lines.push('');
+    lines.push(`diff vs baseline measured ${diff.baselineGeneratedAt} (methodology ${diff.baselineMethodologyVersion})`);
+    for (const c of diff.configs) {
+        lines.push('');
+        if (c.matchedBy === 'unmatched' || c.delta === null || c.beforeTotal === null) {
+            lines.push(`  ${c.source}  ${n(c.afterTotal)} tokens — no baseline for this config, so nothing to compare`);
+            continue;
+        }
+        const rows = c.servers.filter((s) => s.kind !== 'unchanged');
+        lines.push(`  ${c.source}`);
+        lines.push(`    ${n(c.beforeTotal)}  →  ${n(c.afterTotal)}   ${signed(c.delta)}`);
+        if (rows.length) {
+            lines.push('');
+            const w = Math.max(...rows.map((r) => r.name.length), 6);
+            for (const r of rows) {
+                const from = r.before === null ? '—' : n(r.before);
+                const to = r.after === null ? '—' : n(r.after);
+                const d = r.delta === null ? '' : `  ${signed(r.delta)}`;
+                lines.push(`    ${r.kind.padEnd(17)} ${r.name.padEnd(w)}  ${from.padStart(9)} → ${to.padStart(9)}${d}`);
+            }
+        }
+        const unchanged = c.servers.length - rows.length;
+        if (unchanged)
+            lines.push(`    (${unchanged} server${unchanged === 1 ? '' : 's'} unchanged)`);
+        lines.push('');
+        if (!c.exact) {
+            // The headline sentence is where a skimmer stops, so it must not assert a change
+            // this run could not establish. A server that died takes its tokens out of the
+            // total exactly like a server you uninstalled — printing "removes 2,378 tokens"
+            // and correcting it two lines down is the flattering reading getting read.
+            lines.push(`    Not a clean comparison: a server changed measured-ness between the two runs.`);
+            lines.push(`    The measured total moved ${signed(c.delta)}, but that is not what your config did.`);
+            lines.push('');
+            for (const r of c.servers) {
+                if (r.kind === 'unmeasured-now' || r.kind === 'unmeasured-before')
+                    lines.push(`      ${r.name}: ${r.note}`);
+            }
+            if (c.understatedBy)
+                lines.push(`      → true cost is at least ${n(c.understatedBy)} higher than the ${n(c.afterTotal)} measured now.`);
+            if (c.overstatedBy)
+                lines.push(`      → up to ${n(c.overstatedBy)} of that movement was already being paid, just unmeasured.`);
+        }
+        else if (c.delta === 0) {
+            lines.push(`    No change: this config costs the same ${n(c.afterTotal)} tokens per request as the baseline.`);
+        }
+        else if (c.delta > 0) {
+            lines.push(`    This change adds ${n(c.delta)} tokens to every request in ${clientLabel(c.client)} — ` +
+                `${pct(c.beforeShare ?? 0)} → ${pct(c.afterShare)} of a ${n(contextWindow)}-token context window.`);
+        }
+        else {
+            lines.push(`    This change removes ${n(Math.abs(c.delta))} tokens from every request in ${clientLabel(c.client)} — ` +
+                `${pct(c.beforeShare ?? 0)} → ${pct(c.afterShare)} of a ${n(contextWindow)}-token context window.`);
+        }
+        const blind = c.servers.filter((r) => r.kind === 'unmeasured-both' || ((r.kind === 'added' || r.kind === 'removed') && r.delta === null));
+        if (blind.length) {
+            lines.push('');
+            for (const r of blind)
+                lines.push(`    ${r.name}: ${r.note}`);
+        }
+    }
+    if (diff.warnings.length) {
+        lines.push('');
+        lines.push('  diff warnings');
+        for (const w of diff.warnings)
+            lines.push(`    ${w}`);
+    }
+    if (!diff.comparable) {
+        lines.push('');
+        lines.push('  The two runs are not the same measurement, so the numbers above are not a change.');
+        lines.push('  Re-record the baseline with this version: mcp-context-cost audit --json > baseline.json');
+    }
+    return lines.join('\n');
+}
+/**
+ * `--max-increase N` — the CI gate. Fails on an increase over the limit, and
+ * equally on any reason the increase could not be established.
+ *
+ * That second half is the point. A gate that passes when a server failed to
+ * start, or when the baseline covered a config this run never found, is a green
+ * check on a question nobody asked. Everything this portfolio has learned says
+ * unchecked must not read as clean, so an inexact diff fails and names why.
+ */
+export function evaluateIncreaseGate(diff, limit) {
+    const reasons = [];
+    if (!diff.comparable)
+        reasons.push('the baseline is not the same measurement as this run — nothing was compared');
+    for (const c of diff.configs) {
+        if (c.matchedBy === 'unmatched') {
+            reasons.push(`${c.source}: no baseline to check its ${n(c.afterTotal)} tokens against`);
+        }
+        else if (!c.exact) {
+            reasons.push(`${c.source}: a server changed measured-ness, so the change could not be established exactly`);
+        }
+    }
+    for (const d of diff.droppedConfigs) {
+        reasons.push(`${d.source}: covered by the baseline and not found in this run`);
+    }
+    const increase = diff.worstIncrease?.delta ?? (diff.configs.some((c) => typeof c.delta === 'number') ? 0 : null);
+    if (reasons.length === 0 && increase !== null && increase > limit) {
+        reasons.push(`${diff.worstIncrease.source}: +${n(increase)} tokens per request, over the ${n(limit)} allowed`);
+    }
+    return { limit, pass: reasons.length === 0, increase, reasons };
+}
+export function formatGate(gate) {
+    if (gate.pass) {
+        return `increase ok: ${gate.increase === null ? 'no change to measure' : `${signed(gate.increase)} tokens`} ≤ ${n(gate.limit)} allowed`;
+    }
+    return ['INCREASE FAIL:', ...gate.reasons.map((r) => `  ${r}`)].join('\n');
+}

package/dist/audit/run.d.ts

@@ -1,6 +1,9 @@
 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[];
@@ -11,8 +14,17 @@ export interface AuditOptions {
     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>>;

package/dist/audit/run.js

@@ -6,8 +6,24 @@
  */
 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();
@@ -52,8 +68,19 @@ export async function measureAll(configs, opts = {}) {
 export async function runAudit(opts = {}) {
     const configs = discover(opts);
     const measured = await measureAll(configs, opts);
-    return buildReport(configs, measured, {
+    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,16 +2,26 @@
 /**
  * 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 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/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) {
@@ -30,8 +40,68 @@ 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 === '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;
@@ -49,7 +119,44 @@ if (cmd === 'audit') {
         }
         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({
@@ -59,6 +166,8 @@ if (cmd === 'audit') {
         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`),
     });
@@ -71,10 +180,16 @@ if (cmd === 'audit') {
                 `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 ? 1 : 0);
+    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;
@@ -121,21 +236,36 @@ else 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
@@ -149,10 +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]  measure the servers in your own MCP config');
+    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('  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;