mcp-context-cost 0.9.0 → 0.11.0

package/README.md

@@ -193,9 +193,43 @@ still match today and silence for the rest. Most installs will show a mix:
   memory                   9   2,378    4.2%       —
 ```
 
+Add `--suggest` to place each of your tools in the measured set's tool-shape distribution
+([method](docs/METHODOLOGY.md#tool-shape)) and get advice only where the data can point at
+something. Only descriptions draw advice — schemas are functional surface; descriptions are
+prose every request carries — and only descriptions at or above the 90th percentile of the
+1,150 measured tools:
+
+```
+  suggest — descriptions at or above the 90th percentile of measured tools
+  (baseline 2026-09-03: 1,150 tools across 81 measured servers):
+    stub · wordy — 345 tokens: description 321 (p92), schema 14
+      rewriting the description toward the measured median (27) would recover ≈294 tokens on every request
+    1 of 2 tools sit inside the distribution — no advice where nothing is measurably unusual.
+```
+
+A config where nothing is out of distribution is told that in those words, and a baseline
+that cannot be fetched is a named problem, never a silently skipped check.
+
+Add `--changed` to ask the other question — *did the servers I already have get heavier?*
+Each installed server is identified against the published capture history by its canonical
+hash, never by its name, because the name in your config is a label you chose and the bytes
+are not:
+
+```
+  changed — published versions of your servers that have moved since
+  (index 2026-09-04, 2 published captures; matched by canonical hash, never by name):
+    notes (published as obsidian) — you have the capture published 2026-08-19 at 1,132 tokens;
+      the current one is 2,062 (+930, 2026-08-26)
+    updating all 1 would add 930 tokens to every request in this client.
+```
+
+A server whose bytes match no published capture — a version never measured here, a fork, a
+pin — is reported as unidentified with nothing claimed about it.
+Method: [capture index](docs/METHODOLOGY.md#capture-index).
+
 Flags: `--json` (full report on stdout, progress on stderr), `--budget N`,
 `--baseline <report.json>`, `--max-increase N`, `--context N` (default 200,000),
-`--timeout ms`, `--concurrency N`, `--docker`, `--claude`.
+`--timeout ms`, `--concurrency N`, `--docker`, `--claude`, `--suggest`, `--changed`.
 
 ## Where the numbers come from
 
@@ -221,6 +255,14 @@ sample of that range; the full range is in
 Each measured server also has a [detail page](https://athakur3.github.io/mcp-context-cost/servers/)
 showing which tools its tokens are in.)*
 
+Because the set is re-measured on a rotation and most entries launch unpinned, the same data
+answers a question no client asks: **what did this server cost last month?**
+[results/regressions.md](results/regressions.md) reports each server's most recent movement —
+dated to when it happened, separated into *shipped more tools* versus *same tools, rewritten*,
+and compared only within one isolation. The ecosystem ratchets upward: of the servers whose
+cost has moved at all, 9 moved up against 1 that moved down. Method:
+[cost movement](docs/METHODOLOGY.md#cost-movement).
+
 If you publish a server, the same measurement is available as a badge, so your users can see
 the cost before they install rather than after:
 
@@ -304,6 +346,58 @@ Then in your README:
 [![context cost](https://img.shields.io/endpoint?url=<raw URL of badges/my-server.json>)](<link target>)
 ```
 
+### Defend the number, don't just display it
+
+A badge says what your server costs today; it does nothing about the release
+that adds 1,200 tokens to every user's context next month. Across the servers
+measured here, that release is the norm rather than the exception — the
+[movement report](results/regressions.md) has nine servers ratcheting upward
+against one that got cheaper, and none of those maintainers had a check that
+would have said so first. `measure` takes the same gate flags `audit` does, so
+your own CI can be that check:
+
+```bash
+# on your default branch, once — commit the result
+npx -y mcp-context-cost measure --name my-server --command "node dist/index.js"
+cp results/my-server/measurement.json .context-cost/baseline.json
+
+# on every pull request
+npx -y mcp-context-cost measure --name my-server --command "node dist/index.js" \
+  --baseline .context-cost/baseline.json --max-increase 500
+```
+
+```
+diff vs baseline .context-cost/baseline.json
+  my-server: 61 → 182  +121 tokens  (2 → 3 tools)
+    added:   bulk_export (43)
+    grew:    search 30 → 108 (+78)
+
+INCREASE FAIL: +121 tokens, over the 100 allowed — this change adds that to every request of every install.
+```
+
+Both sides are single measurements carrying per-tool counts, so an established
+change is attributed exactly: which tools arrived, which grew, and by how much.
+And `--max-increase` fails on more than the number — a server that stops
+starting on the branch makes the total go *down*, and reporting that as an
+improvement is the one mistake a gate like this must not make, so a change that
+could not be established fails too.
+
+As a GitHub Action, that whole workflow is five lines
+([full example](examples/server-author-ci.yml)):
+
+```yaml
+- uses: athakur3/mcp-context-cost@v1
+  with:
+    name: my-server
+    command: node dist/index.js
+    baseline: .context-cost/baseline.json
+    max-increase: 500
+```
+
+It exposes `tokens`, `tools`, `status`, `measurement` and `badge` as outputs —
+available whether the gate passed or not — so a later step can comment the
+number on the pull request or publish the badge.
+
 Point the link at the measurement behind the number — for servers in this sweep that is
 `https://athakur3.github.io/mcp-context-cost/servers/<name>.html`; otherwise the
 methodology page. A badge nobody can audit is decoration.
@@ -329,7 +423,10 @@ color bands are frozen against the observed distribution of the first full sweep
 
 ## Status
 
-Active. Every row carries the date of its own most recent measurement. Two
+Active. Every row carries the date of its own most recent measurement, and what the data
+says as a whole is written up, dated, in
+[The State of MCP Context Cost](https://athakur3.github.io/mcp-context-cost/state-of-mcp-context-cost)
+(September 2026). Two
 weekly jobs re-measure the set — the `memory` reference server on Mondays, and a rotating
 sixth of the list on Wednesdays, so every row comes round within six weeks. Read each row's
 date as the date it means, and don't take the cadence on trust — the build history is

package/dist/audit/audit.d.ts

@@ -1,4 +1,6 @@
 import { type DivergenceRun } from '../core/divergence.js';
+import { type ToolShapeBaseline, type ToolSuggestion } from '../core/tool-shape.js';
+import { type CaptureIndex, type CaptureVerdict } from '../core/capture-index.js';
 import type { Measurement, MeasurementStatus, ToolMeasurement } from '../core/types.js';
 import type { ConfiguredServer, LoadedConfig } from './config.js';
 import { type DeferralVerdict, type ToolSearchEnv, type ToolSearchSource } from './deferral.js';
@@ -43,6 +45,31 @@ export interface TrimAdvice {
     recoverableTokens: number;
     recoverableShare: number;
 }
+/**
+ * `--suggest`: this config's tools placed in the measured set's tool-shape
+ * distribution. Only descriptions draw advice (schemas are functional surface;
+ * descriptions are prose every request carries), and only descriptions the
+ * baseline puts at or above the threshold percentile — a config where nothing
+ * is measurably unusual gets that said in those words, not advice invented to
+ * have some.
+ */
+export interface ConfigSuggestions {
+    /** Heaviest-recovery first. */
+    outOfDistribution: ToolSuggestion[];
+    checkedTools: number;
+}
+/**
+ * `--changed`: one locally measured server placed against the published capture
+ * history, joined by canonical hash rather than by name. The local label is
+ * carried alongside the published server the bytes identify, because they need
+ * not agree — a config may call the official GitHub server anything at all, and
+ * a name that disagrees with the bytes is information rather than noise.
+ */
+export interface ServerCaptureVerdict {
+    /** The name this config gave the server. */
+    name: string;
+    verdict: CaptureVerdict;
+}
 export interface AuditConfigResult {
     client: string;
     source: string;
@@ -54,6 +81,10 @@ export interface AuditConfigResult {
     skipped: AuditServerResult[];
     heaviestTools: HeaviestTool[];
     trimAdvice: TrimAdvice | null;
+    /** Present only when `--suggest` ran with a usable baseline. */
+    suggestions?: ConfigSuggestions;
+    /** Present only when `--changed` ran with a usable capture index. */
+    captureVerdicts?: ServerCaptureVerdict[];
     /**
      * Whether this client loads the total up front or defers it, and — when the
      * client decides that by a threshold — which side of it this stack is on.
@@ -128,6 +159,17 @@ export interface AuditReport {
         model: string;
         measuredAt: string;
     };
+    /** Which published tool-shape baseline `--suggest` read its percentiles from. */
+    toolShape?: {
+        generatedAt: string;
+        toolCount: number;
+        serverCount: number;
+    };
+    /** Which published capture index `--changed` joined against. */
+    captureIndex?: {
+        generatedAt: string;
+        captureCount: number;
+    };
     /** Present only when a baseline report was supplied (`--baseline`). */
     diff?: AuditDiff;
     /** Present only when `--max-increase` was supplied alongside a baseline. */
@@ -160,6 +202,10 @@ export declare function buildReport(configs: LoadedConfig[], measured: Map<strin
     generatedAt?: string;
     /** Published `tools-delta/v1` run to join against (`--claude`); omit to skip the join. */
     divergence?: DivergenceRun | null;
+    /** Published `tool-shape/v1` baseline (`--suggest`); omit to skip suggestions. */
+    toolShape?: ToolShapeBaseline | null;
+    /** Published `capture-index/v1` (`--changed`); omit to skip the version join. */
+    captureIndex?: CaptureIndex | null;
     /**
      * The audited machine's SHELL tool-search variables. Passed in rather than
      * read here so this stays pure and a report is reproducible from its

package/dist/audit/audit.js

@@ -14,10 +14,22 @@
  */
 import { METHODOLOGY_VERSION } from '../core/canonical.js';
 import { isCurrent } from '../core/divergence.js';
+import { SUGGEST_DESCRIPTION_PERCENTILE, suggestFor, } from '../core/tool-shape.js';
+import { identify } from '../core/capture-index.js';
 import { evaluateDeferral, PUBLISHED_WIRE_TO_CLIENT_RATIO, SHELL_SOURCE, } from './deferral.js';
 import { formatDiff, formatGate } from './diff.js';
 export const DEFAULT_CONTEXT_WINDOW = 200_000;
 const TRIM_TOOL_COUNT = 3;
+function buildSuggestions(pool, baseline) {
+    const outOfDistribution = [];
+    for (const { server, t } of pool) {
+        const s = suggestFor(server, t, baseline);
+        if (s)
+            outOfDistribution.push(s);
+    }
+    outOfDistribution.sort((a, b) => b.approxRecoverableTokens - a.approxRecoverableTokens);
+    return { outOfDistribution, checkedTools: pool.length };
+}
 function buildTrimAdvice(sortedTools, totalTokens) {
     if (totalTokens <= 0 || sortedTools.length < 2)
         return null;
@@ -189,6 +201,7 @@ export function buildReport(configs, measured, opts = {}) {
         const ok = [];
         const skipped = [];
         const tools = [];
+        const shapePool = [];
         // Counted only for servers that put a number into the total: a twin that
         // failed to launch is already a floor, and adds nothing to a sum.
         let sharedHere = 0;
@@ -240,8 +253,11 @@ export function buildReport(configs, measured, opts = {}) {
                 claudeTokens: opts.divergence ? (isCurrent(divRow, m.canonicalSha256 ?? null) ? divRow.claudeDelta : null) : undefined,
                 notes: m.status === 'dynamic' ? m.notes : undefined,
             });
-            for (const t of m.tools)
+            for (const t of m.tools) {
                 tools.push({ server: s.name, tool: t.name, tokens: t.tokens });
+                if (opts.toolShape)
+                    shapePool.push({ server: s.name, t });
+            }
         }
         const totalTokens = ok.reduce((a, s) => a + (s.tokens ?? 0), 0);
         const toolCount = ok.reduce((a, s) => a + (s.toolCount ?? 0), 0);
@@ -264,6 +280,10 @@ export function buildReport(configs, measured, opts = {}) {
             skipped,
             heaviestTools: tools.slice(0, 5),
             trimAdvice: buildTrimAdvice(tools, totalTokens),
+            suggestions: opts.toolShape ? buildSuggestions(shapePool, opts.toolShape) : undefined,
+            captureVerdicts: opts.captureIndex
+                ? ok.map((s) => ({ name: s.name, verdict: identify(s.canonicalSha256, opts.captureIndex) }))
+                : undefined,
         };
         built.push(result);
         shared.set(result, sharedHere);
@@ -282,6 +302,19 @@ export function buildReport(configs, measured, opts = {}) {
     if (opts.divergence) {
         report.claudeDivergence = { model: opts.divergence.model, measuredAt: opts.divergence.measuredAt };
     }
+    if (opts.toolShape) {
+        report.toolShape = {
+            generatedAt: opts.toolShape.generatedAt,
+            toolCount: opts.toolShape.toolCount,
+            serverCount: opts.toolShape.serverCount,
+        };
+    }
+    if (opts.captureIndex) {
+        report.captureIndex = {
+            generatedAt: opts.captureIndex.generatedAt,
+            captureCount: Object.keys(opts.captureIndex.captures).length,
+        };
+    }
     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.
@@ -617,6 +650,68 @@ export function formatReport(report) {
                 `(${names}) would recover ${n(cfg.trimAdvice.recoverableTokens)} tokens ` +
                 `(${pct(cfg.trimAdvice.recoverableShare)} of this config) — if your client supports per-tool filtering.`);
         }
+        if (cfg.captureVerdicts) {
+            const behind = cfg.captureVerdicts.filter((v) => v.verdict.kind === 'behind');
+            const current = cfg.captureVerdicts.filter((v) => v.verdict.kind === 'current');
+            const unknown = cfg.captureVerdicts.length - behind.length - current.length;
+            const idx = report.captureIndex
+                ? `index ${report.captureIndex.generatedAt}, ${n(report.captureIndex.captureCount)} published captures`
+                : 'the published capture index';
+            lines.push('');
+            if (behind.length === 0) {
+                lines.push(`  changed: no server here is running a published capture that has since moved ` +
+                    `(${idx}; matched by canonical hash, never by name).`);
+            }
+            else {
+                const total = behind.reduce((a, v) => a + v.verdict.deltaTokens, 0);
+                lines.push(`  changed — published versions of your servers that have moved since ` +
+                    `(${idx}; matched by canonical hash, never by name):`);
+                for (const { name, verdict: v } of behind) {
+                    // The local label and the published server are printed together: the
+                    // bytes decide which server this is, and a name that disagrees is a
+                    // fact worth seeing rather than one to smooth over.
+                    const alias = name === v.server ? name : `${name} (published as ${v.server})`;
+                    lines.push(`    ${alias} — you have the capture published ${v.yourDate} at ${n(v.yourTokens)} tokens; ` +
+                        `the current one is ${n(v.currentTokens)} (${v.deltaTokens >= 0 ? '+' : '−'}${n(Math.abs(v.deltaTokens))}, ${v.currentDate})`);
+                }
+                lines.push(`    updating all ${behind.length} would ${total >= 0 ? 'add' : 'remove'} ${n(Math.abs(total))} tokens ` +
+                    `${total >= 0 ? 'to' : 'from'} every request in this client.`);
+            }
+            if (unknown > 0) {
+                lines.push(`    ${unknown} server${unknown === 1 ? '' : 's'} could not be identified: the installed bytes match no ` +
+                    `published capture — a version never measured here, or one published before the index began. ` +
+                    `Nothing is claimed about ${unknown === 1 ? 'it' : 'them'}.`);
+            }
+        }
+        if (cfg.suggestions) {
+            const sg = cfg.suggestions;
+            const base = report.toolShape
+                ? `baseline ${report.toolShape.generatedAt}: ${n(report.toolShape.toolCount)} tools across ` +
+                    `${report.toolShape.serverCount} measured servers`
+                : 'published baseline';
+            lines.push('');
+            if (sg.outOfDistribution.length === 0) {
+                lines.push(`  suggest: every description in this config sits inside the measured distribution — ` +
+                    `nothing the data can point at (${sg.checkedTools} tools against ${base}).`);
+            }
+            else {
+                lines.push(`  suggest — descriptions at or above the ${SUGGEST_DESCRIPTION_PERCENTILE}th percentile of ` +
+                    `measured tools (${base}):`);
+                const shown = sg.outOfDistribution.slice(0, 8);
+                for (const s of shown) {
+                    lines.push(`    ${s.server} · ${s.tool} — ${n(s.tokens)} tokens: description ${n(s.descriptionTokens)} ` +
+                        `(p${s.descriptionPercentile}), schema ${n(s.inputSchemaTokens)}`);
+                    lines.push(`      rewriting the description toward the measured median (${n(s.medianDescriptionTokens)}) ` +
+                        `would recover ≈${n(s.approxRecoverableTokens)} tokens on every request`);
+                }
+                if (sg.outOfDistribution.length > shown.length) {
+                    lines.push(`    …and ${sg.outOfDistribution.length - shown.length} more above the threshold.`);
+                }
+                const within = sg.checkedTools - sg.outOfDistribution.length;
+                lines.push(`    ${within} of ${sg.checkedTools} tools sit inside the distribution — ` +
+                    `no advice where nothing is measurably unusual.`);
+            }
+        }
         if (cfg.skipped.length) {
             lines.push('');
             lines.push('  not measured');

package/dist/audit/run.d.ts

@@ -1,10 +1,16 @@
 import type { Measurement } from '../core/types.js';
 import { type DivergenceRun } from '../core/divergence.js';
+import { type ToolShapeBaseline } from '../core/tool-shape.js';
+import { type CaptureIndex } from '../core/capture-index.js';
 import { type AuditReport } from './audit.js';
 import { type ToolSearchEnv, type ToolSearchSource } from './deferral.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";
+/** Where the published `tool-shape/v1` baseline lives when `--suggest` doesn't override it. */
+export declare const DEFAULT_TOOL_SHAPE_URL = "https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/tool-shape.json";
+/** Where the published `capture-index/v1` lives when `--changed` doesn't override it. */
+export declare const DEFAULT_CAPTURE_INDEX_URL = "https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/capture-index.json";
 export interface AuditOptions {
     /** Explicit config path(s); when empty, every known client location is tried. */
     configPaths?: string[];
@@ -19,6 +25,14 @@ export interface AuditOptions {
     claude?: boolean;
     /** Override the divergence.json source — mainly for tests and self-hosted mirrors. */
     divergenceUrl?: string;
+    /** Place this config's tools in the published tool-shape distribution and advise where the data can. */
+    suggest?: boolean;
+    /** Override the tool-shape.json source — mainly for tests and self-hosted mirrors. */
+    toolShapeUrl?: string;
+    /** Identify each server against the published capture history, by hash, and report what has moved. */
+    changed?: boolean;
+    /** Override the capture-index.json source — mainly for tests and self-hosted mirrors. */
+    captureIndexUrl?: string;
     /**
      * The tool-search variables as this process's SHELL has them. Defaults to
      * this process's environment. Overridable so a test can state a machine
@@ -33,6 +47,16 @@ export interface AuditOptions {
     settings?: ToolSearchSource[];
     onProgress?: (name: string, done: number, total: number) => void;
 }
+/** Fetch and parse the published capture index. Never throws: a failure is a report problem, not a crash. */
+export declare function fetchCaptureIndex(url: string): Promise<{
+    index: CaptureIndex | null;
+    problem?: string;
+}>;
+/** Fetch and parse the published tool-shape baseline. Never throws: a failure is a report problem, not a crash. */
+export declare function fetchToolShape(url: string): Promise<{
+    baseline: ToolShapeBaseline | null;
+    problem?: string;
+}>;
 /** 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;

package/dist/audit/run.js

@@ -7,11 +7,43 @@
 import { homedir } from 'node:os';
 import { measureServer } from '../sweep/run.js';
 import { parseDivergence } from '../core/divergence.js';
+import { parseToolShapeBaseline } from '../core/tool-shape.js';
+import { parseCaptureIndex } from '../core/capture-index.js';
 import { buildReport, serverKey } from './audit.js';
 import { toolSearchEnv } from './deferral.js';
 import { configCandidates, loadConfigs, loadSettingsSources, settingsCandidates, } 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';
+/** Where the published `tool-shape/v1` baseline lives when `--suggest` doesn't override it. */
+export const DEFAULT_TOOL_SHAPE_URL = 'https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/tool-shape.json';
+/** Where the published `capture-index/v1` lives when `--changed` doesn't override it. */
+export const DEFAULT_CAPTURE_INDEX_URL = 'https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/capture-index.json';
+/** Fetch and parse the published capture index. Never throws: a failure is a report problem, not a crash. */
+export async function fetchCaptureIndex(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+        if (!res.ok)
+            return { index: null, problem: `capture index: HTTP ${res.status} fetching ${url}` };
+        const index = parseCaptureIndex(await res.text());
+        return index ? { index } : { index: null, problem: `capture index: malformed data at ${url}` };
+    }
+    catch (e) {
+        return { index: null, problem: `capture index: failed to fetch ${url}: ${e.message}` };
+    }
+}
+/** Fetch and parse the published tool-shape baseline. Never throws: a failure is a report problem, not a crash. */
+export async function fetchToolShape(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+        if (!res.ok)
+            return { baseline: null, problem: `tool shape: HTTP ${res.status} fetching ${url}` };
+        const baseline = parseToolShapeBaseline(await res.text());
+        return baseline ? { baseline } : { baseline: null, problem: `tool shape: malformed data at ${url}` };
+    }
+    catch (e) {
+        return { baseline: null, problem: `tool shape: failed to fetch ${url}: ${e.message}` };
+    }
+}
 /** Fetch and parse the published divergence run. Never throws: a failure is a report problem, not a crash. */
 export async function fetchDivergence(url) {
     try {
@@ -89,14 +121,34 @@ export async function runAudit(opts = {}) {
         divergence = fetched.run;
         divergenceProblem = fetched.problem;
     }
+    let toolShape = null;
+    let toolShapeProblem;
+    if (opts.suggest) {
+        const fetched = await fetchToolShape(opts.toolShapeUrl ?? DEFAULT_TOOL_SHAPE_URL);
+        toolShape = fetched.baseline;
+        toolShapeProblem = fetched.problem;
+    }
+    let captureIndex = null;
+    let captureIndexProblem;
+    if (opts.changed) {
+        const fetched = await fetchCaptureIndex(opts.captureIndexUrl ?? DEFAULT_CAPTURE_INDEX_URL);
+        captureIndex = fetched.index;
+        captureIndexProblem = fetched.problem;
+    }
     const report = buildReport(configs, measured, {
         contextWindow: opts.contextWindow,
         budget: opts.budget,
         divergence,
+        toolShape,
+        captureIndex,
         env: opts.env ?? toolSearchEnv(process.env),
         settings: opts.settings ?? discoverSettings(opts),
     });
     if (divergenceProblem)
         report.problems.push(divergenceProblem);
+    if (toolShapeProblem)
+        report.problems.push(toolShapeProblem);
+    if (captureIndexProblem)
+        report.problems.push(captureIndexProblem);
     return report;
 }

package/dist/cli.js

@@ -99,8 +99,19 @@ function rejectUnknownFlags(cmd, argv, spec) {
 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'],
+        value: [
+            'config',
+            'budget',
+            'baseline',
+            'max-increase',
+            'context',
+            'timeout',
+            'concurrency',
+            'divergence-url',
+            'tool-shape-url',
+            'capture-index-url',
+        ],
+        boolean: ['json', 'docker', 'claude', 'suggest', 'changed'],
     });
     const argOf = (name) => {
         const i = rest.indexOf(`--${name}`);
@@ -171,6 +182,10 @@ if (cmd === 'audit') {
             docker: rest.includes('--docker'),
             claude: rest.includes('--claude'),
             divergenceUrl: argOf('divergence-url'),
+            suggest: rest.includes('--suggest'),
+            toolShapeUrl: argOf('tool-shape-url'),
+            changed: rest.includes('--changed'),
+            captureIndexUrl: argOf('capture-index-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`),
         });
@@ -280,7 +295,7 @@ else if (cmd === 'verify') {
 }
 else if (cmd === 'measure') {
     rejectUnknownFlags('measure', rest, {
-        value: ['name', 'command', 'remote', 'timeout', 'docker-image'],
+        value: ['name', 'command', 'remote', 'timeout', 'docker-image', 'baseline', 'max-increase', 'budget'],
         boolean: ['docker'],
     });
     const argOf = (name) => {
@@ -303,6 +318,45 @@ else if (cmd === 'measure') {
         console.error('usage: mcp-context-cost measure --name <slug> --command "npx -y <server>" [--timeout ms] [--docker]');
         process.exit(2);
     }
+    const { diffServer, evaluateServerGate, formatServerDiff, parseBaselineMeasurement, } = await import('./core/server-diff.js');
+    // Gate limits are read before anything is measured: an unusable number is a
+    // usage error, and finding that out after a two-minute container launch is
+    // the wrong time to find it out.
+    const numericFlag = (flag) => {
+        const raw = argOf(flag);
+        if (raw === undefined)
+            return undefined;
+        const v = Number(raw);
+        if (!Number.isFinite(v) || v < 0) {
+            console.error(`--${flag} must be a non-negative number, got '${raw}'`);
+            process.exit(2);
+        }
+        return v;
+    };
+    const maxIncrease = numericFlag('max-increase');
+    const budget = numericFlag('budget');
+    const baselinePath = argOf('baseline');
+    if (maxIncrease !== undefined && !baselinePath) {
+        console.error('--max-increase needs --baseline <measurement.json> to compare against');
+        process.exit(2);
+    }
+    let baseline = null;
+    if (baselinePath) {
+        let raw;
+        try {
+            raw = readFileSync(baselinePath, 'utf8');
+        }
+        catch (e) {
+            console.error(`cannot read baseline ${baselinePath}: ${e.message}`);
+            process.exit(2);
+        }
+        const parsed = parseBaselineMeasurement(raw);
+        if (!parsed.measurement) {
+            console.error(`${baselinePath}: ${parsed.problem}`);
+            process.exit(2);
+        }
+        baseline = parsed.measurement;
+    }
     const { measureServer } = await import('./sweep/run.js');
     const m = await measureServer(name, remoteUrl ? `npx -y mcp-remote ${remoteUrl}` : command, {
         timeoutMs: Number(argOf('timeout') ?? 60_000),
@@ -314,6 +368,20 @@ else if (cmd === 'measure') {
     console.log(ok
         ? `${name}: ${m.totalTokens} tokens across ${m.toolCount} tools (${m.status}) — results/${name}/measurement.json, badges/${name}.json`
         : `${name}: ${m.status} — ${m.notes ?? ''}`);
+    if (baseline || budget !== undefined || maxIncrease !== undefined) {
+        const diff = diffServer(name, baseline, m);
+        if (baseline) {
+            console.log('');
+            console.log(`diff vs baseline ${baselinePath}`);
+            console.log(formatServerDiff(diff));
+        }
+        const gate = evaluateServerGate(diff, { budget, maxIncrease });
+        if (!gate.pass) {
+            console.log('');
+            console.error(gate.failure);
+            process.exit(1);
+        }
+    }
     process.exit(ok ? 0 : 1);
 }
 else if (cmd !== undefined && cmd !== '--help' && cmd !== '-h') {
@@ -331,5 +399,8 @@ else {
     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('        [--baseline <measurement.json>] [--max-increase N] [--budget N]');
+    console.log('                                              gate your own server in CI: fail the');
+    console.log('                                              build when a change adds too much');
     console.log('exit codes: 0 ok, 1 verification/measurement/budget failed, 2 usage error');
 }

package/dist/core/capture-index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Which published version is this, by its bytes?
+ *
+ * `audit --changed` answers "did the servers in my config get heavier?" — and
+ * the whole question turns on joining a machine's installed server to the
+ * published history. Matching by *name* would be a lie waiting to happen: a
+ * config's keys are arbitrary local labels, so a server a user calls `github`
+ * may be a fork, a pin, or something else entirely, and reporting the official
+ * server's movement against it would be a confident false statement.
+ *
+ * So the join is byte identity — the same discipline the Claude column already
+ * uses to decide whether it may print. `results/capture-index.json` maps the
+ * `canonicalSha256` of every capture the project has ever published to the
+ * server and date it belongs to. A local measurement either *is* one of those
+ * captures, exactly, or it is not in the published history at all, and there is
+ * no third state to be fuzzy about.
+ *
+ * The index is derivable from the per-server tool vectors, which is why it can
+ * only see as far back as those vectors go: a version published before the
+ * vectors existed is not in the index and reads as unknown, not as absent from
+ * history. Versioned independently, like every published artifact.
+ */
+/** Method identifier, versioned independently of METHODOLOGY_VERSION. */
+export declare const CAPTURE_INDEX_METHOD = "capture-index/v1";
+export interface IndexedCapture {
+    server: string;
+    /** The day this capture was first measured. */
+    date: string;
+    totalTokens: number;
+    toolCount: number;
+}
+export interface CaptureIndex {
+    method: string;
+    /** UTC day the index was derived (YYYY-MM-DD). */
+    generatedAt: string;
+    /** canonicalSha256 → the capture it identifies. */
+    captures: Record<string, IndexedCapture>;
+    /** server → the newest published capture's hash. */
+    current: Record<string, string>;
+}
+export declare function parseCaptureIndex(text: string): CaptureIndex | null;
+/**
+ * What the index can say about one locally measured server.
+ *
+ * `unknown` is the honest and common outcome: users install versions this
+ * project has never measured, and versions published before the capture index
+ * existed are not in it either. It is reported, not hidden — an absence of a
+ * record about that version, not a statement that nothing changed.
+ */
+export type CaptureVerdict = {
+    kind: 'behind';
+    /** The published server this capture belongs to — established by bytes, not by name. */
+    server: string;
+    yourDate: string;
+    yourTokens: number;
+    currentDate: string;
+    currentTokens: number;
+    /** What moving to the current published version would add to every request. */
+    deltaTokens: number;
+} | {
+    kind: 'current';
+    server: string;
+    date: string;
+    tokens: number;
+} | {
+    kind: 'unknown';
+};
+/**
+ * Identify a local capture against the published index.
+ *
+ * A hash that matches the server's newest published capture is `current`; one
+ * that matches an older capture is `behind`, carrying the exact delta to
+ * current. Anything else — including a version newer than anything published —
+ * is `unknown`, because the index cannot describe what it has never measured.
+ */
+export declare function identify(canonicalSha256: string | null | undefined, index: CaptureIndex): CaptureVerdict;