mcp-context-cost 0.1.0

package/dist/sweep/client.js

@@ -0,0 +1,204 @@
+/**
+ * Minimal MCP stdio client — deliberately NOT the official SDK: schema-parsing
+ * layers can reorder/strip keys, and our canonical bytes are defined as the
+ * tools array exactly as the wire carried it. JSON.parse preserves key order,
+ * so the objects captured here ARE the wire representation.
+ */
+import { spawn } from 'node:child_process';
+const PROTOCOL_VERSION = '2025-06-18';
+export class McpStdioClient {
+    child;
+    buffer = '';
+    nextId = 1;
+    pending = new Map();
+    stderrChunks = [];
+    exited;
+    constructor(command, args, env) {
+        this.child = spawn(command, args, {
+            env: { ...env },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.child.stdout.setEncoding('utf8');
+        this.child.stdout.on('data', (chunk) => this.onData(chunk));
+        this.child.stderr.setEncoding('utf8');
+        this.child.stderr.on('data', (chunk) => {
+            this.stderrChunks.push(chunk);
+            if (this.stderrChunks.length > 200)
+                this.stderrChunks.shift();
+        });
+        // Writing to a dead pipe must not crash the sweep (EPIPE / write-after-end).
+        this.child.stdin.on('error', () => { });
+        this.exited = new Promise((resolve) => {
+            this.child.on('error', (err) => {
+                this.deadReason = `spawn failed: ${err.message}`;
+                for (const p of this.pending.values())
+                    p.reject(new Error(this.deadReason));
+                this.pending.clear();
+                resolve();
+            });
+            this.child.on('exit', (code) => {
+                const tail = this.stderrTail.slice(-600);
+                this.deadReason = `server exited (code ${code})${tail ? `; stderr tail: ${tail}` : ''}`;
+                for (const p of this.pending.values())
+                    p.reject(new Error(this.deadReason));
+                this.pending.clear();
+                resolve();
+            });
+        });
+    }
+    onData(chunk) {
+        this.buffer += chunk;
+        let idx;
+        while ((idx = this.buffer.indexOf('\n')) >= 0) {
+            const line = this.buffer.slice(0, idx).trim();
+            this.buffer = this.buffer.slice(idx + 1);
+            if (!line)
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue; // non-JSON noise on stdout — ignore
+            }
+            if (msg && typeof msg.method === 'string') {
+                // Request or notification FROM the server. Ping is capability-free and
+                // must be answered; anything else gets a method-not-found so the server
+                // is never left hanging on an unanswered request. Server request ids may
+                // collide with ours, so 'method' presence is checked before id dispatch.
+                if (msg.id !== undefined && msg.id !== null) {
+                    if (msg.method === 'ping')
+                        this.send({ jsonrpc: '2.0', id: msg.id, result: {} });
+                    else
+                        this.send({ jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: 'method not found' } });
+                }
+                continue;
+            }
+            if (msg && typeof msg.id === 'number' && this.pending.has(msg.id)) {
+                const p = this.pending.get(msg.id);
+                this.pending.delete(msg.id);
+                if (msg.error)
+                    p.reject(new Error(`server error ${msg.error.code}: ${msg.error.message}`));
+                else
+                    p.resolve(msg.result);
+            }
+        }
+    }
+    send(obj) {
+        this.child.stdin.write(JSON.stringify(obj) + '\n');
+    }
+    deadReason = null;
+    request(method, params, timeoutMs) {
+        if (this.deadReason)
+            return Promise.reject(new Error(this.deadReason));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`timeout after ${timeoutMs}ms waiting for ${method}`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (v) => {
+                    clearTimeout(timer);
+                    resolve(v);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+            this.send({ jsonrpc: '2.0', id, method, params });
+        });
+    }
+    notify(method, params) {
+        this.send(params === undefined ? { jsonrpc: '2.0', method } : { jsonrpc: '2.0', method, params });
+    }
+    get stderrTail() {
+        return this.stderrChunks.join('').slice(-4000);
+    }
+    async close() {
+        this.child.stdin.end();
+        const killed = setTimeout(() => this.child.kill('SIGKILL'), 2000);
+        this.child.kill('SIGTERM');
+        await this.exited;
+        clearTimeout(killed);
+    }
+}
+/**
+ * Launch a stdio MCP server, run initialize + paginated tools/list, capture the
+ * wire-order tools array. Caller owns error handling/status mapping.
+ */
+export async function captureTools(spec, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    const [cmd, ...args] = typeof spec === 'string' ? splitCommand(spec) : [spec.command, ...spec.argv];
+    const client = new McpStdioClient(cmd, args, {
+        PATH: process.env.PATH,
+        HOME: process.env.HOME,
+        ...opts.env,
+    });
+    try {
+        const init = await client.request('initialize', {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: 'mcp-context-cost', version: '0.1.0' },
+        }, timeoutMs);
+        client.notify('notifications/initialized');
+        const tools = [];
+        const seenCursors = new Set();
+        let cursor;
+        let pages = 0;
+        do {
+            if (++pages > 100)
+                throw new Error('tools/list pagination exceeded 100 pages — cursor loop suspected');
+            const res = await client.request('tools/list', cursor ? { cursor } : {}, timeoutMs);
+            if (Array.isArray(res?.tools))
+                tools.push(...res.tools);
+            cursor = typeof res?.nextCursor === 'string' && res.nextCursor.length > 0 ? res.nextCursor : undefined;
+            if (cursor) {
+                if (seenCursors.has(cursor))
+                    throw new Error('tools/list returned a repeated cursor — pagination loop');
+                seenCursors.add(cursor);
+            }
+        } while (cursor);
+        return {
+            serverInfo: init?.serverInfo,
+            protocolVersion: init?.protocolVersion,
+            tools,
+            stderrTail: client.stderrTail,
+        };
+    }
+    finally {
+        await client.close();
+    }
+}
+/** Shell-free command splitting: honors single/double quotes, no expansion. */
+export function splitCommand(line) {
+    const out = [];
+    let cur = '';
+    let quote = null;
+    for (const ch of line) {
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            else
+                cur += ch;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (/\s/.test(ch)) {
+            if (cur) {
+                out.push(cur);
+                cur = '';
+            }
+        }
+        else {
+            cur += ch;
+        }
+    }
+    if (cur)
+        out.push(cur);
+    if (out.length === 0)
+        throw new Error('empty command');
+    return out;
+}

package/dist/sweep/dashboard.d.ts

@@ -0,0 +1 @@
+export declare function generateDashboard(root?: string): string;

package/dist/sweep/dashboard.js

@@ -0,0 +1,242 @@
+/**
+ * Self-contained HTML dashboard generated from results/ + servers.yaml.
+ *   npx tsx src/sweep/dashboard.ts [--out docs/dashboard.html]
+ * Regenerate after every sweep; the file doubles as the published artifact.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parse } from 'yaml';
+import { bandColor } 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 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 };
+    });
+    const measured = rows
+        .filter((r) => r.m && (r.m.status === 'measured' || r.m.status === 'dynamic') && r.m.totalTokens !== null)
+        .sort((a, b) => (b.m.totalTokens ?? 0) - (a.m.totalTokens ?? 0));
+    const pending = rows.filter((r) => !r.m && !r.entry.remote);
+    const failed = rows.filter((r) => (r.m && !measured.includes(r)) || r.entry.remote);
+    const totals = measured.map((r) => r.m.totalTokens);
+    const median = totals.length ? totals.slice().sort((a, b) => a - b)[Math.floor(totals.length / 2)] : 0;
+    const max = totals.length ? Math.max(...totals) : 1;
+    const fmt = (n) => n.toLocaleString('en-US');
+    const now = new Date().toISOString().slice(0, 16).replace('T', ' ') + ' UTC';
+    const barRows = measured
+        .map((r, i) => {
+        const m = r.m;
+        const t = m.totalTokens;
+        const band = bandColor(t);
+        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/, '')) : ''}">
+  <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>`;
+    })
+        .join('\n');
+    const failRows = failed
+        .map((r) => {
+        const status = r.entry.remote ? 'remote-auth-wall' : (r.m?.status ?? 'not-run');
+        const note = r.entry.remote ? 'OAuth-gated remote server; listed, not measured' : (r.m?.notes ?? '');
+        return `<tr><td>${esc(r.entry.name)}</td><td><span class="chip">${esc(status)}</span></td><td class="note">${esc(note).slice(0, 160)}</td></tr>`;
+    })
+        .join('\n');
+    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>`;
+    })
+        .join('\n');
+    const specimens = [measured[measured.length - 1], measured[0]]
+        .filter(Boolean)
+        .map((r) => {
+        const t = r.m.totalTokens;
+        const band = bandColor(t);
+        return `<div class="specimen"><span class="badge"><span class="badge-l">context cost</span><span class="badge-r badge-${band}">${fmt(t)} tokens</span></span><code>badges/${esc(r.entry.name)}.json</code></div>`;
+    })
+        .join('\n');
+    return `<title>mcp-context-cost</title>
+<style>
+  :root {
+    --bg: #F7F8F7; --surface: #FFFFFF; --ink: #17211D; --muted: #5C6B64;
+    --line: #DCE2DF; --accent: #14635A; --accent-soft: rgba(20, 99, 90, 0.09);
+    --track: #ECF0EE;
+    --b-brightgreen: #2E7D4F; --b-green: #4F8A2E; --b-yellow: #A87A12;
+    --b-orange: #BA5A1E; --b-red: #A63B2C;
+    --badge-l: #555555; --badge-ink: #FFFFFF;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) {
+      --bg: #151A18; --surface: #1C2321; --ink: #E4EAE7; --muted: #90A199;
+      --line: #2C3531; --accent: #58B3A4; --accent-soft: rgba(88, 179, 164, 0.12);
+      --track: #232B28;
+      --b-brightgreen: #6FC08D; --b-green: #8CBE62; --b-yellow: #D3A748;
+      --b-orange: #DB8A57; --b-red: #D97F6C;
+    }
+  }
+  :root[data-theme="dark"] {
+    --bg: #151A18; --surface: #1C2321; --ink: #E4EAE7; --muted: #90A199;
+    --line: #2C3531; --accent: #58B3A4; --accent-soft: rgba(88, 179, 164, 0.12);
+    --track: #232B28;
+    --b-brightgreen: #6FC08D; --b-green: #8CBE62; --b-yellow: #D3A748;
+    --b-orange: #DB8A57; --b-red: #D97F6C;
+  }
+  * { box-sizing: border-box; }
+  body {
+    background: var(--bg); color: var(--ink); margin: 0; padding: 0 20px 80px;
+    font-family: "Avenir Next", "Helvetica Neue", system-ui, sans-serif;
+    font-size: 15px; line-height: 1.55;
+  }
+  .wrap { max-width: 880px; margin: 0 auto; }
+  header { padding: 48px 0 10px; }
+  .eyebrow { font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size: 11px; letter-spacing: 0.13em; text-transform: uppercase; color: var(--accent); margin: 0 0 10px; }
+  h1 { font-family: "Futura", "Avenir Next", "Century Gothic", sans-serif; font-weight: 700; font-size: clamp(1.9rem, 5vw, 2.6rem); margin: 0 0 10px; letter-spacing: -0.01em; }
+  .sub { color: var(--muted); max-width: 62ch; margin: 0 0 8px; }
+  h2 { font-family: "Futura", "Avenir Next", sans-serif; font-size: 1.15rem; font-weight: 600; margin: 44px 0 4px; }
+  .h2sub { color: var(--muted); font-size: 0.88rem; margin: 0 0 16px; }
+  a { color: var(--accent); }
+
+  .stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 10px; margin: 22px 0 6px; }
+  .stat { background: var(--surface); border: 1px solid var(--line); border-radius: 6px; padding: 12px 14px 10px; }
+  .stat .n { font-family: ui-monospace, "SF Mono", Menlo, monospace; font-variant-numeric: tabular-nums; font-size: 1.45rem; font-weight: 600; display: block; }
+  .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:hover, .row:focus-visible { background: var(--accent-soft); }
+  .rank { font-family: ui-monospace, Menlo, monospace; font-size: 11px; color: var(--muted); text-align: right; font-variant-numeric: tabular-nums; }
+  .name { font-size: 0.86rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .track { background: var(--track); border-radius: 3px; height: 12px; overflow: hidden; }
+  .bar { display: block; height: 100%; background: var(--accent); border-radius: 3px 3px 3px 3px; min-width: 3px; }
+  .val { font-family: ui-monospace, Menlo, monospace; font-variant-numeric: tabular-nums; font-size: 0.82rem; display: flex; align-items: center; gap: 6px; }
+  .dot { width: 8px; height: 8px; border-radius: 50%; display: inline-block; box-shadow: 0 0 0 2px var(--surface); }
+  .dot-brightgreen { background: var(--b-brightgreen); } .dot-green { background: var(--b-green); }
+  .dot-yellow { background: var(--b-yellow); } .dot-orange { background: var(--b-orange); } .dot-red { background: var(--b-red); }
+  .bandname { color: var(--muted); font-size: 0.72rem; min-width: 62px; }
+
+  .legend { display: flex; flex-wrap: wrap; gap: 14px; margin: 10px 2px 0; font-size: 0.78rem; color: var(--muted); }
+  .legend span { display: inline-flex; align-items: center; gap: 5px; }
+
+  #tip { position: fixed; pointer-events: none; background: var(--ink); color: var(--bg); font-size: 0.78rem; padding: 6px 9px; border-radius: 5px; max-width: 340px; display: none; z-index: 10; line-height: 1.4; }
+
+  table { border-collapse: collapse; width: 100%; background: var(--surface); border: 1px solid var(--line); border-radius: 8px; overflow: hidden; font-size: 0.85rem; }
+  th { text-align: left; font-size: 11px; letter-spacing: 0.07em; text-transform: uppercase; color: var(--muted); font-weight: 600; }
+  th, td { padding: 7px 12px; border-bottom: 1px solid var(--line); }
+  tr:last-child td { border-bottom: none; }
+  td.num { font-family: ui-monospace, Menlo, monospace; font-variant-numeric: tabular-nums; text-align: right; }
+  td.note { color: var(--muted); font-size: 0.8rem; }
+  .chip { font-family: ui-monospace, Menlo, monospace; font-size: 11px; background: var(--accent-soft); color: var(--accent); border-radius: 999px; padding: 2px 9px; white-space: nowrap; }
+  .tablewrap { overflow-x: auto; }
+
+  .specimen { display: flex; align-items: center; gap: 14px; margin: 8px 0; }
+  .badge { display: inline-flex; font-family: "Helvetica Neue", Arial, sans-serif; font-size: 11px; border-radius: 3px; overflow: hidden; line-height: 1; }
+  .badge span { padding: 4px 7px; }
+  .badge-l { background: var(--badge-l); color: var(--badge-ink); }
+  .badge-r { color: var(--badge-ink); }
+  .badge-brightgreen { background: #4c1; } .badge-green { background: #97ca00; color: #333; }
+  .badge-yellow { background: #dfb317; color: #333; } .badge-orange { background: #fe7d37; } .badge-red { background: #e05d44; }
+  code { font-family: ui-monospace, Menlo, monospace; font-size: 0.8rem; color: var(--muted); }
+  pre { background: var(--surface); border: 1px solid var(--line); border-radius: 6px; padding: 12px 14px; overflow-x: auto; font-size: 0.8rem; }
+  details summary { cursor: pointer; color: var(--muted); font-size: 0.85rem; }
+  footer { margin-top: 48px; border-top: 1px solid var(--line); padding-top: 16px; color: var(--muted); font-size: 0.8rem; font-family: ui-monospace, Menlo, monospace; }
+  @media (prefers-reduced-motion: no-preference) { .bar { transition: width 0.4s ease; } }
+</style>
+<div class="wrap">
+  <header>
+    <p class="eyebrow">methodology v1.0 · o200k_base · generated ${now}</p>
+    <h1>mcp-context-cost</h1>
+    <p class="sub">What popular MCP servers cost in context tokens before the agent does any work — measured from raw <code>tools/list</code> captures, every number re-derivable from its published measurement file.</p>
+  </header>
+
+  <div class="stats">
+    <div class="stat"><span class="n">${measured.length}<span style="font-size:0.9rem;color:var(--muted)">/${rows.length}</span></span><span class="l">servers measured</span></div>
+    <div class="stat"><span class="n">${fmt(median)}</span><span class="l">median tokens</span></div>
+    <div class="stat"><span class="n">${fmt(max === 1 ? 0 : max)}</span><span class="l">priciest (${esc(measured[0]?.entry.name ?? '—')})</span></div>
+    <div class="stat"><span class="n">${pending.length}</span><span class="l">pending sweep</span></div>
+  </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>
+  <div class="board">
+${barRows || '<p class="h2sub">Sweep in progress — first results land shortly.</p>'}
+  </div>
+  <div class="legend">
+    <span><span class="dot dot-brightgreen"></span>lean &lt;1K</span>
+    <span><span class="dot dot-green"></span>light 1–5K</span>
+    <span><span class="dot dot-yellow"></span>moderate 5–15K</span>
+    <span><span class="dot dot-orange"></span>heavy 15–30K</span>
+    <span><span class="dot dot-red"></span>very heavy ≥30K</span>
+  </div>
+
+  <h2>Not measured — and why</h2>
+  <p class="h2sub">Every candidate appears; failures are findings, not omissions.</p>
+  <div class="tablewrap"><table>
+    <thead><tr><th>server</th><th>status</th><th>note</th></tr></thead>
+    <tbody>${failRows || '<tr><td colspan="3" class="note">none yet</td></tr>'}</tbody>
+  </table></div>
+
+  <h2>The badge</h2>
+  <p class="h2sub">A shields.io endpoint badge backed by a reproducible measurement — merge one line into a README.</p>
+  ${specimens || '<p class="h2sub">Specimens render once the sweep lands.</p>'}
+  <pre>[![context cost](https://img.shields.io/endpoint?url=&lt;raw badges/&lt;server&gt;.json URL&gt;)](&lt;methodology URL&gt;)</pre>
+
+  <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>
+    <tbody>${tableRows}</tbody>
+  </table></div>
+  </details>
+
+  <footer>
+    Reproduce any number: <code>mcp-context-cost verify results/&lt;server&gt;/measurement.json</code> — re-derives tokens + SHA-256 from the raw capture.
+    Bands are provisional until frozen against the full-sweep distribution.
+  </footer>
+</div>
+<div id="tip" role="status"></div>
+<script>
+  (function () {
+    var tip = document.getElementById('tip');
+    document.querySelectorAll('.row[data-tip]').forEach(function (row) {
+      function show() { tip.textContent = row.getAttribute('data-tip'); tip.style.display = 'block'; }
+      function hide() { tip.style.display = 'none'; }
+      row.addEventListener('mouseenter', show);
+      row.addEventListener('focus', show);
+      row.addEventListener('mouseleave', hide);
+      row.addEventListener('blur', hide);
+      row.addEventListener('mousemove', function (e) {
+        var x = Math.min(e.clientX + 14, window.innerWidth - tip.offsetWidth - 8);
+        tip.style.left = x + 'px';
+        tip.style.top = Math.min(e.clientY + 14, window.innerHeight - tip.offsetHeight - 8) + 'px';
+      });
+      row.addEventListener('focus', function () {
+        var r = row.getBoundingClientRect();
+        tip.style.left = r.left + 'px';
+        tip.style.top = r.bottom + 6 + 'px';
+      });
+    });
+  })();
+</script>
+`;
+}
+const isMain = process.argv[1]?.endsWith('dashboard.ts') || process.argv[1]?.endsWith('dashboard.js');
+if (isMain) {
+    const i = process.argv.indexOf('--out');
+    const out = i >= 0 ? process.argv[i + 1] : 'docs/dashboard.html';
+    const html = generateDashboard();
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, html);
+    console.log(`wrote ${out} (${(html.length / 1024).toFixed(0)}KB)`);
+}

package/dist/sweep/docker.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Docker isolation for sweep measurements: clean filesystem, no ambient
+ * credentials, non-interactive, resource-capped. Network stays enabled because
+ * npx/uvx launches fetch the package at startup — the isolation claim is
+ * "credential-free clean environment", not an airgap, and each measurement
+ * records the isolation actually used.
+ */
+export interface DockerOptions {
+    /** Base image; default node:22-slim (use a uv image for python servers). */
+    image?: string;
+    /** Extra env var NAMES to pass through with dummy values. */
+    dummyEnv?: string[];
+    /** Container name, so a timed-out container can be force-removed. */
+    containerName?: string;
+}
+export declare const DEFAULT_NODE_IMAGE = "public.ecr.aws/docker/library/node:22-slim";
+export declare const DEFAULT_PYTHON_IMAGE = "ghcr.io/astral-sh/uv:python3.12-bookworm-slim";
+export interface IsolationRecord {
+    docker: boolean;
+    image?: string;
+    network?: string;
+    note?: string;
+}
+/**
+ * Wrap a launch command line in `docker run`. The inner command is passed to
+ * `sh -lc` inside the container; quoting is preserved by argv (no host shell).
+ */
+export declare function dockerize(commandLine: string, opts?: DockerOptions): {
+    command: string;
+    argv: string[];
+    isolation: IsolationRecord;
+};

package/dist/sweep/docker.js

@@ -0,0 +1,49 @@
+// ECR Public / ghcr mirrors — Docker Hub pulls hang on some networks (observed
+// on this machine 2026-08-16: hub pulls stall indefinitely while ECR works).
+export const DEFAULT_NODE_IMAGE = 'public.ecr.aws/docker/library/node:22-slim';
+export const DEFAULT_PYTHON_IMAGE = 'ghcr.io/astral-sh/uv:python3.12-bookworm-slim';
+/**
+ * Wrap a launch command line in `docker run`. The inner command is passed to
+ * `sh -lc` inside the container; quoting is preserved by argv (no host shell).
+ */
+export function dockerize(commandLine, opts = {}) {
+    const image = opts.image ?? (commandLine.trimStart().startsWith('uvx') ? DEFAULT_PYTHON_IMAGE : DEFAULT_NODE_IMAGE);
+    const argv = [
+        'run',
+        '--rm',
+        '-i',
+        ...(opts.containerName ? ['--name', opts.containerName] : []),
+        '--pull=missing',
+        '--memory=1g',
+        '--pids-limit=512',
+        '--security-opt',
+        'no-new-privileges',
+        '-e',
+        'HOME=/tmp',
+        '-w',
+        '/tmp',
+        // Shared package caches across containers — packages only, no credentials.
+        '-v',
+        'mcp-ctx-npm-cache:/tmp/.npm-cache',
+        '-e',
+        'npm_config_cache=/tmp/.npm-cache',
+        '-v',
+        'mcp-ctx-uv-cache:/tmp/.uv-cache',
+        '-e',
+        'UV_CACHE_DIR=/tmp/.uv-cache',
+    ];
+    for (const name of opts.dummyEnv ?? []) {
+        argv.push('-e', `${name}=dummy`);
+    }
+    argv.push(image, 'sh', '-lc', commandLine);
+    return {
+        command: 'docker',
+        argv,
+        isolation: {
+            docker: true,
+            image,
+            network: 'bridge',
+            note: 'network enabled for package fetch; clean FS, no host credentials',
+        },
+    };
+}

package/dist/sweep/regen.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sweep/regen.js

@@ -0,0 +1,7 @@
+/** Regenerate leaderboard + dashboard from existing results/: npx tsx src/sweep/regen.ts */
+import { readFileSync } from 'node:fs';
+import { parse } from 'yaml';
+import { writeLeaderboard, percentiles } from './report.js';
+const doc = parse(readFileSync('servers.yaml', 'utf8'));
+writeLeaderboard(doc.servers);
+console.log('leaderboard:', JSON.stringify(percentiles(doc.servers)));

package/dist/sweep/report.d.ts

@@ -0,0 +1,16 @@
+export interface ServerEntry {
+    name: string;
+    command: string;
+    package?: string;
+    env?: string[];
+    metric?: number;
+    metricSource?: string;
+    category?: string;
+    repo?: string;
+    remote?: boolean;
+    dockerImage?: string;
+    timeoutSeconds?: number;
+}
+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

@@ -0,0 +1,81 @@
+/**
+ * Leaderboard generation from results/<name>/measurement.json + servers.yaml
+ * metadata. Every yaml entry appears — failures included, no silent drops.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Neutralize markdown/table syntax in third-party strings (tool names, notes). */
+function mdCell(s) {
+    return String(s ?? '')
+        .replace(/[|`[\]<>]/g, (c) => `\\${c}`)
+        .replace(/\r?\n/g, ' ')
+        .slice(0, 160);
+}
+function csvCell(s) {
+    const v = String(s ?? '');
+    return /[",\n]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
+}
+function loadRows(entries, root = process.cwd()) {
+    return entries.map((entry) => {
+        const p = join(root, 'results', entry.name, 'measurement.json');
+        return { entry, m: existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null };
+    });
+}
+export function writeLeaderboard(entries, root = process.cwd()) {
+    const rows = loadRows(entries, root);
+    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));
+    const unmeasured = rows.filter((r) => !measured.includes(r));
+    const md = [];
+    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.`);
+    md.push('');
+    md.push('| # | server | tokens | tools | largest tool | status | category |');
+    md.push('|---:|---|---:|---:|---|---|---|');
+    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} | ` +
+            `${largest ? `${mdCell(largest.name)} (${largest.tokens.toLocaleString('en-US')})` : '—'} | ${m.status} | ${mdCell(r.entry.category)} |`);
+    });
+    md.push('');
+    if (unmeasured.length > 0) {
+        md.push('## Not measured (and why)');
+        md.push('');
+        md.push('| server | status | note |');
+        md.push('|---|---|---|');
+        for (const r of unmeasured) {
+            const status = r.entry.remote ? 'remote-auth-wall' : (r.m?.status ?? 'not-yet-run');
+            md.push(`| ${mdCell(r.entry.name)} | ${status} | ${mdCell(r.m?.notes)} |`);
+        }
+        md.push('');
+    }
+    writeFileSync(join(root, 'results', 'leaderboard.md'), md.join('\n') + '\n');
+    const csv = ['name,tokens,toolCount,status,category,metric,metricSource'];
+    for (const r of rows) {
+        const m = r.m;
+        csv.push([
+            csvCell(r.entry.name),
+            m?.totalTokens ?? '',
+            m?.toolCount ?? '',
+            r.entry.remote ? 'remote-auth-wall' : (m?.status ?? 'not-yet-run'),
+            csvCell(r.entry.category),
+            r.entry.metric ?? '',
+            csvCell(r.entry.metricSource),
+        ].join(','));
+    }
+    writeFileSync(join(root, 'results', 'leaderboard.csv'), csv.join('\n') + '\n');
+}
+/** Percentile helper for freezing color bands against the observed distribution. */
+export function percentiles(entries, root = process.cwd()) {
+    const totals = loadRows(entries, root)
+        .map((r) => r.m?.totalTokens)
+        .filter((t) => typeof t === 'number')
+        .sort((a, b) => a - b);
+    // Nearest-rank percentile: ceil(p/100 * n) as 1-based rank (unbiased at exact multiples).
+    const at = (p) => totals[Math.min(totals.length - 1, Math.max(0, Math.ceil((p / 100) * totals.length) - 1))] ?? 0;
+    return { p25: at(25), p50: at(50), p75: at(75), p90: at(90), n: totals.length };
+}

package/dist/sweep/run.d.ts

@@ -0,0 +1,11 @@
+import type { Measurement } from '../core/types.js';
+export interface MeasureOptions {
+    timeoutMs?: number;
+    env?: Record<string, string>;
+    root?: string;
+    docker?: boolean;
+    dockerImage?: string;
+    /** env var NAMES to provide as dummy values (docker mode). */
+    dummyEnv?: string[];
+}
+export declare function measureServer(name: string, command: string, opts?: MeasureOptions): Promise<Measurement>;