mcp-context-cost 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,8 @@
 # mcp-context-cost
 
+[![npm](https://img.shields.io/npm/v/mcp-context-cost)](https://www.npmjs.com/package/mcp-context-cost)
+[![CI](https://github.com/athakur3/mcp-context-cost/actions/workflows/ci.yml/badge.svg)](https://github.com/athakur3/mcp-context-cost/actions/workflows/ci.yml)
+
 **Reproducible context-cost badges for MCP servers.**
 
 Every MCP server you wire into an agent injects its tool schemas into the model's context
@@ -16,7 +19,9 @@ popular servers:
 | markitdown | 64 | 1 |
 
 *(57 of 82 popular servers measured, 2026-08-16 sweep — full table in
-[results/leaderboard.md](results/leaderboard.md); every failure is listed with its reason.)*
+[results/leaderboard.md](results/leaderboard.md); every failure is listed with its reason.
+Each measured server also has a [detail page](https://athakur3.github.io/mcp-context-cost/servers/)
+showing which tools its tokens are in.)*
 
 This project makes that cost **legible and disputable**:
 
@@ -24,6 +29,21 @@ This project makes that cost **legible and disputable**:
 [context cost | 12,430 tokens]   ← shields.io badge, linked to the methodology
 ```
 
+## What it costs on Claude
+
+The badge counts every byte a server returns. An Anthropic request carries only `name`,
+`description`, and `input_schema` — and counts them with a denser tokenizer. Both effects are
+now measured against a pinned model and published beside the badge, and they do not cancel:
+
+| server | badge (o200k) | Claude (`claude-opus-5`) | |
+|---|---:|---:|---|
+| github | 54,422 | **18,406** | 81% of the capture is `annotations`/`outputSchema` metadata Claude never sees |
+| notion | 17,500 | **33,560** | almost no metadata to drop, so the tokenizer difference dominates |
+
+So the heaviest server on the badge is not the heaviest server on Claude. Per-server
+breakdowns are on each [detail page](https://athakur3.github.io/mcp-context-cost/servers/);
+the method is [Claude divergence](docs/METHODOLOGY.md#claude-divergence).
+
 ## Why trust the number?
 
 Every badge is backed by a `measurement.json` containing the raw `tools/list` capture, the
@@ -31,10 +51,17 @@ SHA-256 of its canonical bytes, the pinned tokenizer (`o200k_base`), and the exa
 command. Disputes reduce to a byte-level diff:
 
 ```bash
-npx tsx src/cli.ts verify results/github/measurement.json
+npx -y mcp-context-cost verify results/github/measurement.json
 # OK github-mcp-server: 54422 tokens (o200k_base, methodology 1.0) — capture, hash, and count all agree
+
+# or point it at a published measurement.json directly, no clone required
+npx -y mcp-context-cost verify --remote https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/github/measurement.json
 ```
 
+Add `--json` for scripting (`{ ok, serverName, rederivedTokens, rederivedSha, problems, badge }`
+on stdout, `badge` omitted on failure). Exit codes: `0` ok, `1` verification/measurement
+failed, `2` usage error.
+
 Full definition: [docs/METHODOLOGY.md](docs/METHODOLOGY.md) — what is counted, what the
 number is *not*, config policy, failure taxonomy, frozen color bands, known divergences.
 
@@ -46,9 +73,11 @@ number is *not*, config policy, failure taxonomy, frozen color bands, known dive
 | `src/sweep/` | raw-wire MCP stdio client + Dockerized batch sweep + leaderboard/dashboard generators |
 | `src/cli.ts` | `verify` (re-derive any published number) and `measure` |
 | `spec/fixtures/` | golden vectors shared by the TypeScript and bash implementations |
+| `tools/` | the one script that calls a network API (Claude divergence); kept out of the package so the library stays offline |
 | `upstream/` | staged contribution to [sd2k/mcp-tokens-action](https://github.com/sd2k/mcp-tokens-action): `badge.sh` + action patch + tests |
 | `servers.yaml` | 82 curated candidates with live install metrics and provenance |
-| `results/` · `badges/` | measurements, leaderboard, shields endpoint JSONs |
+| `results/` · `badges/` | measurements, leaderboard, history series, shields endpoint JSONs |
+| `docs/` | methodology, dashboard, and a generated page per measured server |
 
 ## Measure your own server
 
@@ -61,16 +90,20 @@ cat badges/my-server.json   # strict shields.io endpoint JSON
 Then in your README:
 
 ```markdown
-[![context cost](https://img.shields.io/endpoint?url=<raw URL of badges/my-server.json>)](<methodology URL>)
+[![context cost](https://img.shields.io/endpoint?url=<raw URL of badges/my-server.json>)](<link target>)
 ```
 
+Point the link at the measurement behind the number — for servers in this sweep that is
+`https://athakur3.github.io/mcp-context-cost/servers/<name>.html`; otherwise the
+methodology page. A badge nobody can audit is decoration.
+
 Or self-serve from CI via the (staged) mcp-tokens-action badge inputs — see
 [upstream/action-patch.md](upstream/action-patch.md).
 
 ## Development
 
 ```bash
-npm test                        # 24 TS tests incl. golden fixtures + dispute drills
+npm test                        # 53 TS tests incl. golden fixtures + dispute drills
 npx tsc --noEmit                # typecheck
 ./upstream/tests/badge-test.sh  # 21 bash tests — byte-identical to the TS reference
 npm run sweep:all -- --docker   # full curated sweep (Docker isolation)
@@ -83,8 +116,9 @@ color bands are frozen against the observed distribution of the first full sweep
 
 ## Status
 
-Pre-launch. Measurement pipeline, leaderboard, methodology, and upstream contribution are
-complete; the badge-adoption campaign and launch posts are drafted in `campaign/` awaiting
-go-ahead. Build log: [PROGRESS.md](PROGRESS.md).
+Active. The leaderboard refreshes weekly; badge PRs are open across the ecosystem and
+[sd2k/mcp-tokens-action#5](https://github.com/sd2k/mcp-tokens-action/pull/5) proposes the
+self-serve badge path upstream. See [ROADMAP.md](ROADMAP.md) for what's next —
+contributions welcome, especially new `servers.yaml` entries.
 
 MIT © 2026

package/dist/cli.js

@@ -2,9 +2,12 @@
 /**
  * mcp-context-cost CLI — the dispute drill as a command.
  *
- *   mcp-context-cost verify <measurement.json>   re-derive the number from the
+ *   mcp-context-cost verify <measurement.json> [--json]   re-derive the number from the
  *                                                published capture; exit 1 on mismatch
+ *   mcp-context-cost verify --remote <url> [--json]   same, fetched from a measurement URL
  *   mcp-context-cost measure --name x --command "npx -y ..."   one-off measurement
+ *
+ * Exit codes: 0 ok, 1 verification/measurement failed, 2 usage error.
  */
 import { readFileSync } from 'node:fs';
 import { canonicalString, countTokens, sha256Hex } from './core/canonical.js';
@@ -27,13 +30,41 @@ export function verifyMeasurement(m) {
 }
 const [, , cmd, ...rest] = process.argv;
 if (cmd === 'verify') {
-    const path = rest.find((a) => !a.startsWith('--'));
-    if (!path) {
-        console.error('usage: mcp-context-cost verify <measurement.json>');
+    const json = rest.includes('--json');
+    const remoteIdx = rest.indexOf('--remote');
+    const remoteUrl = remoteIdx >= 0 ? rest[remoteIdx + 1] : undefined;
+    const path = rest.find((a) => !a.startsWith('--') && a !== remoteUrl);
+    if (!remoteUrl && !path) {
+        console.error('usage: mcp-context-cost verify <measurement.json> [--json]');
+        console.error('       mcp-context-cost verify --remote <url> [--json]');
         process.exit(2);
     }
-    const m = JSON.parse(readFileSync(path, 'utf8'));
+    let raw;
+    if (remoteUrl) {
+        try {
+            const res = await fetch(remoteUrl, { signal: AbortSignal.timeout(15_000) });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            raw = await res.text();
+        }
+        catch (e) {
+            const problem = `failed to fetch ${remoteUrl}: ${e.message}`;
+            if (json)
+                console.log(JSON.stringify({ ok: false, rederivedTokens: null, rederivedSha: null, problems: [problem] }));
+            else
+                console.error(problem);
+            process.exit(1);
+        }
+    }
+    else {
+        raw = readFileSync(path, 'utf8');
+    }
+    const m = JSON.parse(raw);
     const r = verifyMeasurement(m);
+    if (json) {
+        console.log(JSON.stringify({ serverName: m.serverName, ...r, badge: r.ok ? toBadge(m) : undefined }));
+        process.exit(r.ok ? 0 : 1);
+    }
     if (r.ok) {
         console.log(`OK ${m.serverName}: ${r.rederivedTokens} tokens (${m.encoding}, methodology ${m.methodologyVersion}) — capture, hash, and count all agree`);
         console.log(`badge: ${JSON.stringify(toBadge(m))}`);
@@ -73,6 +104,8 @@ else if (cmd !== undefined && cmd !== '--help' && cmd !== '-h') {
 }
 else {
     console.log('mcp-context-cost — reproducible context-cost measurement for MCP servers');
-    console.log('  verify <measurement.json>    re-derive tokens+sha from the published capture');
+    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');
 }

package/dist/core/bands.d.ts

@@ -5,3 +5,8 @@
  */
 export declare function bandColor(totalTokens: number): string;
 export declare const UNKNOWN_COLOR = "lightgrey";
+/** Human-readable name + range for each band, shared by every generated view. */
+export declare const BAND_META: Record<string, {
+    label: string;
+    range: string;
+}>;

package/dist/core/bands.js

@@ -15,3 +15,11 @@ export function bandColor(totalTokens) {
     return 'red';
 }
 export const UNKNOWN_COLOR = 'lightgrey';
+/** Human-readable name + range for each band, shared by every generated view. */
+export const BAND_META = {
+    brightgreen: { label: 'lean', range: '< 1K' },
+    green: { label: 'light', range: '1–5K' },
+    yellow: { label: 'moderate', range: '5–15K' },
+    orange: { label: 'heavy', range: '15–30K' },
+    red: { label: 'very heavy', range: '≥ 30K' },
+};

package/dist/core/canonical.js

@@ -44,7 +44,9 @@ export function measureTools(tools, meta) {
         toolCount: tools.length,
         tools: perTool,
         canonicalSha256: sha256Hex(canonical),
-        rawToolsCapture: tools,
+        // Snapshot from the canonical string, not the live `tools` reference — the whole
+        // point of a capture is that it can't change out from under its own hash later.
+        rawToolsCapture: JSON.parse(canonical),
         measuredAt: meta.measuredAt ?? new Date().toISOString(),
         serverName: meta.serverName,
         serverVersion: meta.serverVersion,

package/dist/core/divergence.d.ts

@@ -0,0 +1,71 @@
+/** Method identifier, versioned independently of the o200k methodology. */
+export declare const DIVERGENCE_METHOD = "tools-delta/v1";
+/** The three fields an Anthropic tool definition carries — nothing else. */
+export declare const ANTHROPIC_TOOL_FIELDS: readonly ['name', 'description', 'input_schema'];
+export interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: unknown;
+}
+export interface DivergenceRow {
+    /** o200k count of the full canonical capture — the published headline. */
+    o200kFull: number;
+    /** o200k count of the name/description/input_schema projection. */
+    o200kMapped: number;
+    /**
+     * Claude tokens the projection adds to a request: count_tokens(with tools)
+     * minus count_tokens(same request, no tools). Includes the one-time tool
+     * framework overhead, because attaching any server pays it once.
+     */
+    claudeDelta: number;
+    toolCount: number;
+    /**
+     * canonicalSha256 of the measurement this row was computed from. A re-sweep
+     * changes the hash, which marks the row stale instead of silently mismatched.
+     */
+    capturedSha256: string;
+    /** Set when count_tokens rejected the projection; no numbers are published. */
+    error?: string;
+}
+export interface DivergenceRun {
+    method: string;
+    /** Exact model id the counts are pinned to — Anthropic's tokenizer drifts. */
+    model: string;
+    /** UTC day the counts were taken (YYYY-MM-DD). */
+    measuredAt: string;
+    /** count_tokens for the probe request with no tools at all. */
+    baselineTokens: number;
+    /**
+     * A single minimal tool. Its delta is an upper bound on the fixed framework
+     * overhead included in every `claudeDelta` (the probe tool itself costs > 0,
+     * so the true overhead is strictly less).
+     */
+    probeDelta: number;
+    servers: Record<string, DivergenceRow>;
+}
+/**
+ * Project a `tools/list` capture onto the Anthropic tool shape. Tools without a
+ * usable name are dropped rather than renamed — a fabricated name would change
+ * the token count being compared.
+ */
+export declare function toAnthropicTools(raw: unknown[]): AnthropicTool[];
+/** o200k count of the projection — the same tokenizer as the headline number. */
+export declare function mappedTokens(raw: unknown[]): number;
+/**
+ * Share of the headline number that is MCP-only metadata (cause 1 above).
+ * Returns null when there is nothing to divide by.
+ */
+export declare function fieldSelectionShare(row: DivergenceRow): number | null;
+/**
+ * Claude tokens per o200k token of the headline — the ratio a reader wants when
+ * asking "does the badge over- or under-state what this costs me?".
+ */
+export declare function claudeRatio(row: DivergenceRow): number | null;
+/**
+ * A row is only reportable if it carries numbers and was computed from the
+ * capture currently on disk. Stale rows are hidden rather than shown with a
+ * caveat: a wrong number next to a fresh badge is worse than no number.
+ */
+export declare function isCurrent(row: DivergenceRow | undefined, canonicalSha256: string | null): row is DivergenceRow;
+/** Parse results/divergence.json; anything malformed yields null, never throws. */
+export declare function parseDivergence(text: string): DivergenceRun | null;

package/dist/core/divergence.js

@@ -0,0 +1,103 @@
+/**
+ * Claude divergence — the gap between the published o200k index and what a
+ * server's tools actually cost in an Anthropic request.
+ *
+ * The gap has two independent causes, and reporting them as one number hides
+ * the larger of the two:
+ *
+ * 1. **Field selection.** An Anthropic tool definition carries exactly `name`,
+ *    `description`, and `input_schema`. A `tools/list` result may additionally
+ *    carry `title`, `annotations`, `outputSchema`, `execution`, `icons` — real
+ *    bytes the server ships, counted by the canonical form, but never present
+ *    in the `tools` array a client sends to the API. For some servers this is
+ *    the majority of the payload.
+ * 2. **Tokenizer and framing.** o200k_base vs Anthropic's tokenizer, plus the
+ *    fixed framework overhead the API adds once when any tool is present.
+ *
+ * So the divergence is published as a decomposition: the headline o200k count,
+ * the o200k count of the projection (isolating cause 1), and Claude's own count
+ * of that same projection (isolating cause 2).
+ */
+import { countTokens } from './canonical.js';
+/** Method identifier, versioned independently of the o200k methodology. */
+export const DIVERGENCE_METHOD = 'tools-delta/v1';
+/** The three fields an Anthropic tool definition carries — nothing else. */
+export const ANTHROPIC_TOOL_FIELDS = ['name', 'description', 'input_schema'];
+/**
+ * Project a `tools/list` capture onto the Anthropic tool shape. Tools without a
+ * usable name are dropped rather than renamed — a fabricated name would change
+ * the token count being compared.
+ */
+export function toAnthropicTools(raw) {
+    const out = [];
+    for (const t of raw) {
+        const tool = (t ?? {});
+        if (typeof tool.name !== 'string' || tool.name === '')
+            continue;
+        out.push({
+            name: tool.name,
+            description: typeof tool.description === 'string' ? tool.description : '',
+            // An absent schema is sent as the empty object schema, which is what the
+            // API requires; every tool in the current sweep supplies one.
+            input_schema: tool.inputSchema ?? { type: 'object', properties: {} },
+        });
+    }
+    return out;
+}
+/** o200k count of the projection — the same tokenizer as the headline number. */
+export function mappedTokens(raw) {
+    return countTokens(JSON.stringify(toAnthropicTools(raw)));
+}
+/**
+ * Share of the headline number that is MCP-only metadata (cause 1 above).
+ * Returns null when there is nothing to divide by.
+ */
+export function fieldSelectionShare(row) {
+    if (row.o200kFull <= 0)
+        return null;
+    return (row.o200kFull - row.o200kMapped) / row.o200kFull;
+}
+/**
+ * Claude tokens per o200k token of the headline — the ratio a reader wants when
+ * asking "does the badge over- or under-state what this costs me?".
+ */
+export function claudeRatio(row) {
+    if (row.o200kFull <= 0 || typeof row.claudeDelta !== 'number')
+        return null;
+    return row.claudeDelta / row.o200kFull;
+}
+/**
+ * A row is only reportable if it carries numbers and was computed from the
+ * capture currently on disk. Stale rows are hidden rather than shown with a
+ * caveat: a wrong number next to a fresh badge is worse than no number.
+ */
+export function isCurrent(row, canonicalSha256) {
+    if (!row || row.error)
+        return false;
+    if (typeof row.claudeDelta !== 'number')
+        return false;
+    return !!canonicalSha256 && row.capturedSha256 === canonicalSha256;
+}
+/** Parse results/divergence.json; anything malformed yields null, never throws. */
+export function parseDivergence(text) {
+    let run;
+    try {
+        run = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const r = run;
+    if (!r || typeof r.model !== 'string' || typeof r.measuredAt !== 'string')
+        return null;
+    if (!r.servers || typeof r.servers !== 'object')
+        return null;
+    return {
+        method: typeof r.method === 'string' ? r.method : DIVERGENCE_METHOD,
+        model: r.model,
+        measuredAt: r.measuredAt,
+        baselineTokens: typeof r.baselineTokens === 'number' ? r.baselineTokens : 0,
+        probeDelta: typeof r.probeDelta === 'number' ? r.probeDelta : 0,
+        servers: r.servers,
+    };
+}

package/dist/core/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types.js';
 export * from './canonical.js';
+export * from './divergence.js';
 export * from './bands.js';
 export * from './badge.js';
 export * from './snippet.js';

package/dist/core/index.js

@@ -1,5 +1,6 @@
 export * from './types.js';
 export * from './canonical.js';
+export * from './divergence.js';
 export * from './bands.js';
 export * from './badge.js';
 export * from './snippet.js';

package/dist/sweep/dashboard.js

@@ -6,17 +6,15 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { parse } from 'yaml';
-import { bandColor } from '../core/bands.js';
+import { bandColor, BAND_META } from '../core/bands.js';
 const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-const BAND_META = {
-    brightgreen: { label: 'lean', range: '< 1K' },
-    green: { label: 'light', range: '1–5K' },
-    yellow: { label: 'moderate', range: '5–15K' },
-    orange: { label: 'heavy', range: '15–30K' },
-    red: { label: 'very heavy', range: '≥ 30K' },
-};
 export function generateDashboard(root = process.cwd()) {
     const doc = parse(readFileSync(join(root, 'servers.yaml'), 'utf8'));
+    const divergencePath = join(root, 'results', 'divergence.json');
+    const divergence = existsSync(divergencePath)
+        ? JSON.parse(readFileSync(divergencePath, 'utf8'))
+        : {};
+    const dSrv = divergence.servers ?? {};
     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,12 +37,15 @@ export function generateDashboard(root = process.cwd()) {
         const meta = BAND_META[band];
         const largest = [...m.tools].sort((a, b) => b.tokens - a.tokens)[0];
         const pct = Math.max(1.2, (t / max) * 100);
-        return `<div class="row" tabindex="0" data-tip="${esc(m.toolCount)} tools · largest: ${esc(largest?.name)} (${fmt(largest?.tokens ?? 0)} tok) · ${esc(r.entry.category)} · ${esc(m.status)}${m.serverVersion ? ' · v' + esc(String(m.serverVersion).replace(/^v/, '')) : ''}">
+        const div = dSrv[r.entry.name];
+        const claudeTip = div ? ` · in a Claude request: ${fmt(div.claudeDelta)} tok` : '';
+        // 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/, '')) : ''}">
   <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="val"><span class="dot dot-${band}" aria-hidden="true"></span>${fmt(t)}<span class="bandname">${meta.label}</span></span>
-</div>`;
+</a>`;
     })
         .join('\n');
     const failRows = failed
@@ -57,7 +58,8 @@ export function generateDashboard(root = process.cwd()) {
     const tableRows = measured
         .map((r, i) => {
         const m = r.m;
-        return `<tr><td>${i + 1}</td><td>${esc(r.entry.name)}</td><td class="num">${fmt(m.totalTokens)}</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 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>`;
     })
         .join('\n');
     const specimens = [measured[measured.length - 1], measured[0]]
@@ -115,8 +117,9 @@ 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; }
+  .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: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; }
@@ -169,7 +172,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. Hover or focus a row for detail.</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). Hover a row for both 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>
@@ -195,7 +198,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</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></tr></thead>
     <tbody>${tableRows}</tbody>
   </table></div>
   </details>

package/dist/sweep/history.d.ts

@@ -0,0 +1,30 @@
+import type { Measurement } from '../core/types.js';
+export interface HistoryRow {
+    /** UTC calendar day of the measurement (YYYY-MM-DD). */
+    date: string;
+    server: string;
+    tokens: number;
+    toolCount: number;
+    /** 'measured' or 'dynamic' — dynamic means the tool set moved between captures. */
+    status: string;
+}
+export declare const HISTORY_HEADER = "date,server,tokens,toolCount,status";
+/** Parse history.csv text; malformed or non-numeric rows are dropped, not thrown. */
+export declare function parseHistory(text: string): HistoryRow[];
+export declare function formatHistory(rows: HistoryRow[]): string;
+/** Upsert one row by (date, server) — the newest write for a day wins. */
+export declare function upsert(rows: HistoryRow[], row: HistoryRow): HistoryRow[];
+/**
+ * A measurement contributes a row only if it produced a number: failures and
+ * auth walls are recorded in the leaderboard's "not measured" section, and
+ * writing them here as zeros would fabricate a drop to zero in the series.
+ */
+export declare function rowFor(server: string, m: Measurement): HistoryRow | null;
+/**
+ * Fold every results/<server>/measurement.json into results/history.csv.
+ * Idempotent: running twice over the same results is a no-op.
+ */
+export declare function appendHistory(root?: string): {
+    rows: number;
+    added: number;
+};

package/dist/sweep/history.js

@@ -0,0 +1,120 @@
+/**
+ * results/history.csv — the time series behind the leaderboard snapshot.
+ *
+ * One row per (date, server): a server's tokens on the day it was measured.
+ * Every sweep upserts by (date, server), so re-running a sweep on the same day
+ * corrects that day's row instead of appending a duplicate. Rows for earlier
+ * dates are never rewritten — history is append-only in practice.
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const HISTORY_HEADER = 'date,server,tokens,toolCount,status';
+function csvCell(s) {
+    const v = String(s ?? '');
+    return /[",\n]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
+}
+/** Split one CSV line, honouring double-quoted fields. */
+function splitCsvLine(line) {
+    const out = [];
+    let cur = '';
+    let quoted = false;
+    for (let i = 0; i < line.length; i++) {
+        const c = line[i];
+        if (quoted) {
+            if (c === '"' && line[i + 1] === '"') {
+                cur += '"';
+                i++;
+            }
+            else if (c === '"')
+                quoted = false;
+            else
+                cur += c;
+        }
+        else if (c === '"')
+            quoted = true;
+        else if (c === ',') {
+            out.push(cur);
+            cur = '';
+        }
+        else
+            cur += c;
+    }
+    out.push(cur);
+    return out;
+}
+/** Parse history.csv text; malformed or non-numeric rows are dropped, not thrown. */
+export function parseHistory(text) {
+    const rows = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim() || line.startsWith('date,'))
+            continue;
+        const [date, server, tokens, toolCount, status] = splitCsvLine(line);
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(date ?? '') || !server)
+            continue;
+        if (!/^\d+$/.test(tokens ?? '') || !/^\d+$/.test(toolCount ?? ''))
+            continue;
+        rows.push({ date, server, tokens: Number(tokens), toolCount: Number(toolCount), status: status ?? '' });
+    }
+    return rows;
+}
+export function formatHistory(rows) {
+    const sorted = [...rows].sort((a, b) => a.date.localeCompare(b.date) || a.server.localeCompare(b.server));
+    const lines = sorted.map((r) => [csvCell(r.date), csvCell(r.server), r.tokens, r.toolCount, csvCell(r.status)].join(','));
+    return [HISTORY_HEADER, ...lines].join('\n') + '\n';
+}
+/** Upsert one row by (date, server) — the newest write for a day wins. */
+export function upsert(rows, row) {
+    const i = rows.findIndex((r) => r.date === row.date && r.server === row.server);
+    if (i < 0)
+        return [...rows, row];
+    const next = [...rows];
+    next[i] = row;
+    return next;
+}
+/**
+ * A measurement contributes a row only if it produced a number: failures and
+ * auth walls are recorded in the leaderboard's "not measured" section, and
+ * writing them here as zeros would fabricate a drop to zero in the series.
+ */
+export function rowFor(server, m) {
+    if (m.status !== 'measured' && m.status !== 'dynamic')
+        return null;
+    if (typeof m.totalTokens !== 'number' || typeof m.toolCount !== 'number')
+        return null;
+    const date = String(m.measuredAt ?? '').slice(0, 10);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date))
+        return null;
+    return { date, server, tokens: m.totalTokens, toolCount: m.toolCount, status: m.status };
+}
+/**
+ * Fold every results/<server>/measurement.json into results/history.csv.
+ * Idempotent: running twice over the same results is a no-op.
+ */
+export function appendHistory(root = process.cwd()) {
+    const resultsDir = join(root, 'results');
+    const path = join(resultsDir, 'history.csv');
+    const existing = existsSync(path) ? parseHistory(readFileSync(path, 'utf8')) : [];
+    let rows = existing;
+    if (!existsSync(resultsDir))
+        return { rows: 0, added: 0 };
+    for (const server of readdirSync(resultsDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .sort()) {
+        const file = join(resultsDir, server, 'measurement.json');
+        if (!existsSync(file))
+            continue;
+        let m;
+        try {
+            m = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            continue; // a half-written measurement should not abort the whole fold
+        }
+        const row = rowFor(server, m);
+        if (row)
+            rows = upsert(rows, row);
+    }
+    writeFileSync(path, formatHistory(rows));
+    return { rows: rows.length, added: rows.length - existing.length };
+}

package/dist/sweep/regen.js

@@ -1,7 +1,14 @@
-/** Regenerate leaderboard + dashboard from existing results/: npx tsx src/sweep/regen.ts */
+/** Regenerate leaderboard + history + server pages from results/: npx tsx src/sweep/regen.ts */
 import { readFileSync } from 'node:fs';
 import { parse } from 'yaml';
 import { writeLeaderboard, percentiles } from './report.js';
+import { appendHistory } from './history.js';
+import { writeServerPages } from './server-pages.js';
 const doc = parse(readFileSync('servers.yaml', 'utf8'));
 writeLeaderboard(doc.servers);
+// History first: the server pages read history.csv for their over-time table.
+const h = appendHistory();
+const p = writeServerPages(doc.servers);
 console.log('leaderboard:', JSON.stringify(percentiles(doc.servers)));
+console.log(`history: ${h.rows} rows (${h.added >= 0 ? '+' : ''}${h.added})`);
+console.log(`server pages: ${p.pages}`);

package/dist/sweep/report.d.ts

@@ -1,3 +1,4 @@
+import { type DivergenceRun } from '../core/divergence.js';
 export interface ServerEntry {
     name: string;
     command: string;
@@ -11,6 +12,10 @@ export interface ServerEntry {
     dockerImage?: string;
     timeoutSeconds?: number;
 }
+/** Neutralize markdown/table syntax in third-party strings (tool names, notes). */
+export declare function mdCell(s: unknown): string;
+/** results/divergence.json if a divergence run has been recorded, else null. */
+export declare function loadDivergence(root?: string): DivergenceRun | null;
 export declare function writeLeaderboard(entries: ServerEntry[], root?: string): void;
 /** Percentile helper for freezing color bands against the observed distribution. */
 export declare function percentiles(entries: ServerEntry[], root?: string): Record<string, number>;

package/dist/sweep/report.js

@@ -4,8 +4,9 @@
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { isCurrent, parseDivergence } from '../core/divergence.js';
 /** Neutralize markdown/table syntax in third-party strings (tool names, notes). */
-function mdCell(s) {
+export function mdCell(s) {
     return String(s ?? '')
         .replace(/[|`[\]<>]/g, (c) => `\\${c}`)
         .replace(/\r?\n/g, ' ')
@@ -21,8 +22,21 @@ function loadRows(entries, root = process.cwd()) {
         return { entry, m: existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null };
     });
 }
+/** results/divergence.json if a divergence run has been recorded, else null. */
+export function loadDivergence(root = process.cwd()) {
+    const p = join(root, 'results', 'divergence.json');
+    return existsSync(p) ? parseDivergence(readFileSync(p, 'utf8')) : null;
+}
 export function writeLeaderboard(entries, root = process.cwd()) {
     const rows = loadRows(entries, root);
+    const div = loadDivergence(root);
+    /** Claude tokens for a row, or null when not measured / stale / errored. */
+    const claude = (r) => {
+        if (!div || !r.m)
+            return null;
+        const d = div.servers[r.entry.name];
+        return isCurrent(d, r.m.canonicalSha256) ? d.claudeDelta : null;
+    };
     const measured = rows
         .filter((r) => r.m && (r.m.status === 'measured' || r.m.status === 'dynamic'))
         .sort((a, b) => (b.m.totalTokens ?? 0) - (a.m.totalTokens ?? 0));
@@ -31,14 +45,28 @@ export function writeLeaderboard(entries, root = process.cwd()) {
     md.push('# MCP server context-cost leaderboard');
     md.push('');
     md.push(`Tokens = o200k_base count of the canonical \`tools/list\` bytes ([methodology v1.0](../docs/METHODOLOGY.md)). ` +
-        `Measured ${measured.length}/${rows.length} candidates; every candidate is listed — failures are findings, not omissions.`);
+        `Measured ${measured.length}/${rows.length} candidates; every candidate is listed — failures are findings, not omissions. ` +
+        `Server names link to their per-tool breakdown.`);
     md.push('');
-    md.push('| # | server | tokens | tools | largest tool | status | category |');
-    md.push('|---:|---|---:|---:|---|---|---|');
+    if (div) {
+        const n = measured.filter((r) => claude(r) !== null).length;
+        md.push(`The **claude** column is the same tools measured through Anthropic's \`count_tokens\` on ` +
+            `\`${mdCell(div.model)}\` (${mdCell(div.measuredAt)}, method \`${mdCell(div.method)}\`): the tokens the server's ` +
+            `tools add to a request, measured for the top ${n}. It is not a rescaling of the o200k column — ` +
+            `two effects pull in opposite directions, and the [per-server pages](../docs/servers/) break both out. ` +
+            `See [Claude divergence](../docs/METHODOLOGY.md#claude-divergence).`);
+        md.push('');
+    }
+    md.push(`| # | server | tokens |${div ? ' claude |' : ''} tools | largest tool | status | category |`);
+    md.push(`|---:|---|---:|${div ? '---:|' : ''}---:|---|---|---|`);
     measured.forEach((r, i) => {
         const m = r.m;
         const largest = [...m.tools].sort((a, b) => b.tokens - a.tokens)[0];
-        md.push(`| ${i + 1} | ${mdCell(r.entry.name)} | ${m.totalTokens.toLocaleString('en-US')} | ${m.toolCount} | ` +
+        const link = `[${mdCell(r.entry.name)}](../docs/servers/${encodeURIComponent(r.entry.name)}.md)`;
+        const c = claude(r);
+        md.push(`| ${i + 1} | ${link} | ${m.totalTokens.toLocaleString('en-US')} |` +
+            (div ? ` ${c === null ? '—' : c.toLocaleString('en-US')} |` : '') +
+            ` ${m.toolCount} | ` +
             `${largest ? `${mdCell(largest.name)} (${largest.tokens.toLocaleString('en-US')})` : '—'} | ${m.status} | ${mdCell(r.entry.category)} |`);
     });
     md.push('');
@@ -54,9 +82,12 @@ export function writeLeaderboard(entries, root = process.cwd()) {
         md.push('');
     }
     writeFileSync(join(root, 'results', 'leaderboard.md'), md.join('\n') + '\n');
-    const csv = ['name,tokens,toolCount,status,category,metric,metricSource'];
+    // Columns are append-only: consumers key off the header, so adding the Claude
+    // pair at the end leaves every existing parser working.
+    const csv = ['name,tokens,toolCount,status,category,metric,metricSource,claudeTokens,claudeModel'];
     for (const r of rows) {
         const m = r.m;
+        const c = claude(r);
         csv.push([
             csvCell(r.entry.name),
             m?.totalTokens ?? '',
@@ -65,6 +96,8 @@ export function writeLeaderboard(entries, root = process.cwd()) {
             csvCell(r.entry.category),
             r.entry.metric ?? '',
             csvCell(r.entry.metricSource),
+            c ?? '',
+            c === null ? '' : csvCell(div.model),
         ].join(','));
     }
     writeFileSync(join(root, 'results', 'leaderboard.csv'), csv.join('\n') + '\n');

package/dist/sweep/run.js

@@ -87,6 +87,10 @@ if (isMain) {
         docker: process.argv.includes('--docker'),
         dockerImage: arg('docker-image'),
     });
+    // CLI path only — measureServer itself stays history-free so concurrent
+    // sweep-all workers never race on the same file.
+    const { appendHistory } = await import('./history.js');
+    appendHistory();
     console.log(m.status === 'measured' || m.status === 'dynamic'
         ? `${name}: ${m.totalTokens} tokens across ${m.toolCount} tools (${m.status})`
         : `${name}: ${m.status} — ${m.notes ?? ''}`);

package/dist/sweep/server-pages.d.ts

@@ -0,0 +1,17 @@
+import type { Measurement } from '../core/types.js';
+import { type ServerEntry } from './report.js';
+import { type HistoryRow } from './history.js';
+import { type DivergenceRun } from '../core/divergence.js';
+/** One server's page. `history` is that server's rows, oldest first. */
+export declare function renderServerPage(entry: ServerEntry, m: Measurement, history?: HistoryRow[], divergence?: DivergenceRun | null): string;
+/** The index that lists every candidate — measured ones link to their page. */
+export declare function renderServerIndex(rows: {
+    entry: ServerEntry;
+    m: Measurement | null;
+}[]): string;
+/** Write docs/servers/*.md for every measured server, plus the index. */
+export declare function writeServerPages(entries: ServerEntry[], root?: string): {
+    pages: number;
+};
+/** Public URL of a server's page — used by the leaderboard and the badge snippet. */
+export declare function serverPageUrl(name: string): string;

package/dist/sweep/server-pages.js

@@ -0,0 +1,228 @@
+/**
+ * Per-server detail pages: docs/servers/<name>.md plus an index.
+ *
+ * These are the badge's click-through target. A badge says "12,430 tokens";
+ * the page behind it says which tools those tokens are in, what launched the
+ * server, the hash of the bytes counted, and the one command that re-derives
+ * the number. Generated from results/ only — no network, no timestamps beyond
+ * the measurement's own, so regenerating without a new sweep is a no-op diff.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { bandColor, BAND_META } from '../core/bands.js';
+import { loadDivergence, mdCell } from './report.js';
+import { parseHistory } from './history.js';
+import { claudeRatio, fieldSelectionShare, isCurrent } from '../core/divergence.js';
+/**
+ * Pages are served from GitHub Pages (docs/), but results/ and badges/ are not
+ * published there — links into them must be absolute repo URLs.
+ */
+const REPO_URL = 'https://github.com/athakur3/mcp-context-cost';
+const BLOB = `${REPO_URL}/blob/main`;
+const PAGES_URL = 'https://athakur3.github.io/mcp-context-cost';
+/** Longest per-tool table we print inline; the rest live in the raw capture. */
+const MAX_TOOL_ROWS = 30;
+const fmt = (n) => n.toLocaleString('en-US');
+/** True when a measurement produced a number we can stand behind. */
+function isMeasured(m) {
+    return !!m && (m.status === 'measured' || m.status === 'dynamic') && typeof m.totalTokens === 'number';
+}
+function isolationText(m) {
+    const iso = m.isolation;
+    if (!iso)
+        return 'not recorded';
+    if (!iso.docker)
+        return 'host process (no container)';
+    return ['docker', iso.image, iso.network ? `network ${iso.network}` : '', iso.note]
+        .filter(Boolean)
+        .join(' · ');
+}
+/**
+ * The Claude divergence section: the headline, the projection onto the three
+ * fields an Anthropic tool definition carries, and Claude's own count of that
+ * projection. Printed only when a current divergence row exists for this server.
+ */
+function divergenceSection(row, run) {
+    const share = fieldSelectionShare(row);
+    const ratio = claudeRatio(row);
+    const md = [];
+    md.push('## What this costs on Claude');
+    md.push('');
+    md.push(`Measured ${mdCell(run.measuredAt)} against \`${mdCell(run.model)}\` via Anthropic's \`count_tokens\` ` +
+        `(method \`${mdCell(run.method)}\`).`);
+    md.push('');
+    md.push('| | tokens | |');
+    md.push('|---|---:|---|');
+    md.push(`| o200k, full capture | ${fmt(row.o200kFull)} | the badge number — every byte \`tools/list\` returned |`);
+    md.push(`| o200k, Anthropic fields only | ${fmt(row.o200kMapped)} | ` +
+        `${share === null ? '—' : `${(share * 100).toFixed(1)}% of the capture is MCP-only metadata`} |`);
+    md.push(`| **Claude, same fields** | **${fmt(row.claudeDelta)}** | ` +
+        `${ratio === null ? '—' : `${ratio.toFixed(2)}× the badge number`} |`);
+    md.push('');
+    md.push(`An Anthropic tool definition carries \`name\`, \`description\`, and \`input_schema\` and nothing else, so ` +
+        `\`title\`, \`annotations\`, \`outputSchema\`, \`execution\`, and \`icons\` are dropped before the request — ` +
+        `that is the second row. The third row is the same tools counted by Anthropic, which is larger than the ` +
+        `second because Anthropic's tokenizer is denser on this content than o200k_base *and* the API adds its own ` +
+        `framing (at most ${fmt(run.probeDelta)} tokens of it fixed, measured against a single minimal tool). ` +
+        `The two effects run in opposite directions, which is why the Claude number is not a fixed multiple of the badge.`);
+    md.push('');
+    return md;
+}
+/** One server's page. `history` is that server's rows, oldest first. */
+export function renderServerPage(entry, m, history = [], divergence = null) {
+    const total = m.totalTokens;
+    const band = BAND_META[bandColor(total)];
+    const tools = [...m.tools].sort((a, b) => b.tokens - a.tokens);
+    const shown = tools.slice(0, MAX_TOOL_ROWS);
+    const pct = (n) => (total > 0 ? `${((n / total) * 100).toFixed(1)}%` : '—');
+    const md = [];
+    md.push(`# ${mdCell(entry.name)} — context cost`);
+    md.push('');
+    md.push(`**${fmt(total)} tokens** across ${m.toolCount} tools — *${band.label}* (${band.range}). ` +
+        `Measured ${String(m.measuredAt).slice(0, 10)} under [methodology v${mdCell(m.methodologyVersion)}](../METHODOLOGY.html).`);
+    md.push('');
+    md.push('| | |');
+    md.push('|---|---|');
+    md.push(`| server (self-reported) | ${mdCell(m.serverName)}${m.serverVersion ? ` v${mdCell(String(m.serverVersion).replace(/^v/, ''))}` : ''} |`);
+    md.push(`| status | ${mdCell(m.status)} |`);
+    md.push(`| tokenizer | ${mdCell(m.provider)} / ${mdCell(m.encoding)} |`);
+    md.push(`| launch command | \`${mdCell(m.launchCommand ?? entry.command)}\` |`);
+    md.push(`| isolation | ${mdCell(isolationText(m))} |`);
+    md.push(`| env vars supplied | ${m.envVarNames?.length ? m.envVarNames.map(mdCell).join(', ') : 'none'} |`);
+    md.push(`| canonical SHA-256 | \`${mdCell(m.canonicalSha256)}\` |`);
+    if (entry.category)
+        md.push(`| category | ${mdCell(entry.category)} |`);
+    if (entry.repo)
+        md.push(`| source | ${mdCell(entry.repo)} |`);
+    md.push('');
+    if (m.status === 'dynamic') {
+        md.push('> This server\'s `tools/list` differed between two consecutive captures, so the number ' +
+            'is the first capture and moves between sweeps. Treat it as a range, not a constant.');
+        md.push('');
+    }
+    md.push('## Where the tokens are');
+    md.push('');
+    md.push('| tool | tokens | share | description | schema |');
+    md.push('|---|---:|---:|---:|---:|');
+    for (const t of shown) {
+        md.push(`| ${mdCell(t.name)} | ${fmt(t.tokens)} | ${pct(t.tokens)} | ${fmt(t.descriptionTokens)} | ${fmt(t.inputSchemaTokens)} |`);
+    }
+    md.push('');
+    if (tools.length > shown.length) {
+        const rest = tools.slice(shown.length).reduce((s, t) => s + t.tokens, 0);
+        md.push(`*${tools.length - shown.length} smaller tools omitted (${fmt(rest)} tokens combined) — ` +
+            `all of them are in the [raw capture](${BLOB}/results/${encodeURIComponent(entry.name)}/measurement.json).*`);
+        md.push('');
+    }
+    md.push('Each tool is tokenized on its own, so the parts do not sum exactly to the whole: the ' +
+        'array adds its own brackets and commas, and the tokenizer merges tokens across object ' +
+        'boundaries. The badge number is always the count of the whole array, never a sum of parts.');
+    md.push('');
+    const divRow = divergence?.servers[entry.name];
+    if (divergence && isCurrent(divRow, m.canonicalSha256)) {
+        md.push(...divergenceSection(divRow, divergence));
+    }
+    if (history.length > 1) {
+        md.push('## Over time');
+        md.push('');
+        md.push('| date | tokens | tools | change |');
+        md.push('|---|---:|---:|---:|');
+        history.forEach((h, i) => {
+            const prev = history[i - 1];
+            const delta = prev ? h.tokens - prev.tokens : null;
+            const change = delta === null ? '—' : delta === 0 ? 'no change' : `${delta > 0 ? '+' : ''}${fmt(delta)}`;
+            md.push(`| ${mdCell(h.date)} | ${fmt(h.tokens)} | ${h.toolCount} | ${change} |`);
+        });
+        md.push('');
+        md.push(`Full series: [results/history.csv](${BLOB}/results/history.csv).`);
+        md.push('');
+    }
+    md.push('## Re-derive it');
+    md.push('');
+    md.push('```bash');
+    md.push(`npx -y mcp-context-cost verify results/${entry.name}/measurement.json`);
+    md.push('```');
+    md.push('');
+    md.push(`That re-tokenizes the [published capture](${BLOB}/results/${encodeURIComponent(entry.name)}/measurement.json) ` +
+        `and checks the count and the hash. If it disagrees with the badge, the badge is wrong — ` +
+        `[open an issue](${REPO_URL}/issues) and it gets corrected.`);
+    md.push('');
+    md.push(`[Badge JSON](${BLOB}/badges/${encodeURIComponent(entry.name)}.json) · ` +
+        `[All servers](index.html) · [Leaderboard](${BLOB}/results/leaderboard.md) · ` +
+        `[Methodology](../METHODOLOGY.html)`);
+    md.push('');
+    return md.join('\n');
+}
+/** The index that lists every candidate — measured ones link to their page. */
+export function renderServerIndex(rows) {
+    const measured = rows.filter((r) => isMeasured(r.m)).sort((a, b) => b.m.totalTokens - a.m.totalTokens);
+    const rest = rows.filter((r) => !isMeasured(r.m));
+    const md = [];
+    md.push('# Server pages');
+    md.push('');
+    md.push(`One page per measured server: the per-tool breakdown behind the badge, the exact launch ` +
+        `command, and the command that re-derives the number. ${measured.length} of ${rows.length} ` +
+        `candidates measured.`);
+    md.push('');
+    md.push('| # | server | tokens | tools | band |');
+    md.push('|---:|---|---:|---:|---|');
+    measured.forEach((r, i) => {
+        const t = r.m.totalTokens;
+        md.push(`| ${i + 1} | [${mdCell(r.entry.name)}](${encodeURIComponent(r.entry.name)}.html) | ${fmt(t)} | ` +
+            `${r.m.toolCount} | ${BAND_META[bandColor(t)].label} |`);
+    });
+    md.push('');
+    if (rest.length > 0) {
+        md.push('## Not measured');
+        md.push('');
+        md.push('No page: there is no number to show. The reason is recorded per candidate.');
+        md.push('');
+        md.push('| server | status |');
+        md.push('|---|---|');
+        for (const r of rest) {
+            const status = r.entry.remote ? 'remote-auth-wall' : (r.m?.status ?? 'not-yet-run');
+            md.push(`| ${mdCell(r.entry.name)} | ${mdCell(status)} |`);
+        }
+        md.push('');
+    }
+    md.push(`[Leaderboard](${BLOB}/results/leaderboard.md) · [Methodology](../METHODOLOGY.html) · [Dashboard](../dashboard.html)`);
+    md.push('');
+    return md.join('\n');
+}
+/** Write docs/servers/*.md for every measured server, plus the index. */
+export function writeServerPages(entries, root = process.cwd()) {
+    const outDir = join(root, 'docs', 'servers');
+    mkdirSync(outDir, { recursive: true });
+    const historyPath = join(root, 'results', 'history.csv');
+    const history = existsSync(historyPath) ? parseHistory(readFileSync(historyPath, 'utf8')) : [];
+    const divergence = loadDivergence(root);
+    const rows = entries.map((entry) => {
+        const p = join(root, 'results', entry.name, 'measurement.json');
+        let m = null;
+        if (existsSync(p)) {
+            try {
+                m = JSON.parse(readFileSync(p, 'utf8'));
+            }
+            catch {
+                m = null; // a half-written measurement should not abort the whole run
+            }
+        }
+        return { entry, m };
+    });
+    let pages = 0;
+    for (const { entry, m } of rows) {
+        if (!isMeasured(m))
+            continue;
+        const series = history
+            .filter((h) => h.server === entry.name)
+            .sort((a, b) => a.date.localeCompare(b.date));
+        writeFileSync(join(outDir, `${entry.name}.md`), renderServerPage(entry, m, series, divergence));
+        pages++;
+    }
+    writeFileSync(join(outDir, 'index.md'), renderServerIndex(rows));
+    return { pages };
+}
+/** Public URL of a server's page — used by the leaderboard and the badge snippet. */
+export function serverPageUrl(name) {
+    return `${PAGES_URL}/servers/${encodeURIComponent(name)}.html`;
+}

package/dist/sweep/sweep-all.js

@@ -8,6 +8,7 @@ import { readFileSync } from 'node:fs';
 import { parse } from 'yaml';
 import { measureServer } from './run.js';
 import { writeLeaderboard } from './report.js';
+import { appendHistory } from './history.js';
 function arg(name) {
     const i = process.argv.indexOf(`--${name}`);
     return i >= 0 ? process.argv[i + 1] : undefined;
@@ -45,6 +46,8 @@ async function worker() {
     }
 }
 await Promise.all(Array.from({ length: Math.max(1, concurrency) }, () => worker()));
+// Serial, after every worker has finished: history.csv is a read-modify-write.
 writeLeaderboard(doc.servers);
+const h = appendHistory();
 const measured = Object.values(summary).filter((s) => s.includes('tokens')).length;
-console.log(`done: ${measured}/${entries.length} measured; leaderboard regenerated`);
+console.log(`done: ${measured}/${entries.length} measured; leaderboard + history (${h.rows} rows) regenerated`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-context-cost",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Reproducible context-cost badges for MCP servers — measure what a server's tool schemas cost before the agent does any work",
   "type": "module",
   "license": "MIT",
@@ -29,9 +29,11 @@
   ],
   "scripts": {
     "build": "tsc",
+    "prepublishOnly": "npm run build && npm test && npm run typecheck",
     "test": "vitest run",
     "test:badge": "./upstream/tests/badge-test.sh",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tools.json",
+    "divergence": "tsx tools/measure-divergence.ts",
     "sweep": "tsx src/sweep/run.ts",
     "sweep:all": "tsx src/sweep/sweep-all.ts",
     "verify": "tsx src/cli.ts verify"
@@ -44,6 +46,7 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.117.1",
     "@types/node": "^26.2.0",
     "tsx": "^4.23.12",
     "typescript": "^7.0.2",