mcp-context-cost 0.3.0 → 0.5.0

package/dist/cli.js

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

package/dist/core/adoption.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Badge adoption — how many projects outside this one actually display the
+ * badge, and on what day someone last looked.
+ *
+ * Every other number this project publishes is about MCP servers. This one is
+ * about the project itself, and it exists because the alternative is a launch
+ * that produces a number nobody can attribute. "Nobody is using the badge" and
+ * "nobody has checked whether anybody is using the badge" are the same sentence
+ * to a reader, and only one of them is a measurement. So the reading published
+ * here is a dated observation with its own working shown: the exact queries
+ * that were run, every file they turned up, and what each of those files was
+ * judged to be. A zero from this instrument means *these queries ran on this
+ * date and found none*, which is a fact. A missing reading says so in those
+ * words and publishes no number at all.
+ *
+ * ## What counts as displaying the badge
+ *
+ * A file, in a repository owned by someone else, carrying a shields.io endpoint
+ * badge that is auditable — and the project publishes two ways to make one, so
+ * the rule counts both. Either the badge's JSON is served from this
+ * repository's `badges/` directory, or the author hosts their own
+ * `badges/<name>.json` — which is what `npm run sweep` produces, and what every
+ * badge snippet this project ships tells a reader to point shields at — and
+ * links the badge back at the measurement here, which the same snippet
+ * requires.
+ *
+ * Counting only the first form would have published a zero about a spelling
+ * nobody was ever told to write: no snippet in README, in the dashboard or in
+ * the staged upstream patch produces a URL inside this repository's `badges/`,
+ * because each of them is addressed to an author measuring their own server.
+ *
+ * What is still outside the rule is a self-hosted badge that links back to
+ * nothing. Nothing in such a file names this project, so no query can nominate
+ * it — and this project's own README says a badge nobody can audit is
+ * decoration. That limit is published on the page rather than papered over; see
+ * `renderAdoptionPage`.
+ *
+ * The link is paired with the image it wraps rather than looked for anywhere in
+ * the file, because a README carrying an unrelated shields badge and, elsewhere,
+ * a sentence naming this project is not a project displaying this badge.
+ *
+ * ## Why the search is a net and not the judgement
+ *
+ * Code search matches text, and the same badge is written two ways: shields
+ * percent-encodes the `url` parameter, so the published snippet carries
+ * `raw.githubusercontent.com%2Fathakur3%2F…`, while a hand-written badge may
+ * carry the plain path. Measured against GitHub code search on 2026-08-20, the
+ * two forms do not find each other: a repository whose README carries only the
+ * encoded form of a raw URL returns 0 for the plain form of that same path,
+ * while the encoded literal returns matches. Neither query alone is the
+ * question being asked.
+ *
+ * So the queries only nominate candidates. What a candidate *is* gets decided
+ * by reading the file — `classifyFile` below, applied to content that has had
+ * its percent-encoding undone, so one rule covers both spellings. Files that
+ * name the project without displaying the badge are kept in the reading as
+ * rejections, because a zero is worth much more next to the list of things that
+ * were examined and turned down.
+ */
+/** Method identifier, versioned independently of the o200k methodology. */
+export declare const ADOPTION_METHOD = "badge-sightings/v1";
+/** Where this project's badge JSON is published — the thing a badge points at. */
+export interface BadgeSource {
+    owner: string;
+    repo: string;
+    branch: string;
+}
+export declare const BADGE_SOURCE: BadgeSource;
+/** A query as published: what was asked, and why it is part of the question. */
+export interface QueryDef {
+    name: string;
+    q: string;
+    why: string;
+}
+/** A query as answered. `hits` is null whenever `state` is not `ok`. */
+export interface QueryResult extends QueryDef {
+    state: 'ok' | 'failed';
+    hits: number | null;
+    /** Set when the query did not answer — a reading with one of these is refused. */
+    error?: string;
+    /** Set when more results existed than were collected. Also refuses the reading. */
+    truncated?: boolean;
+}
+/** `badge`: displays it. `mention`: names the project without displaying it. */
+export type SightingKind = 'badge' | 'mention';
+export interface Sighting {
+    /** `owner/repo` of the third-party repository. */
+    repo: string;
+    path: string;
+    url: string;
+    kind: SightingKind;
+    /** Which query nominated it — so a reader can re-run the one that found it. */
+    foundBy: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+}
+export interface AdoptionRun {
+    method: string;
+    /** UTC day the queries were run (YYYY-MM-DD). */
+    checkedAt: string;
+    source: BadgeSource;
+    queries: QueryResult[];
+    /** Distinct third-party files examined this run, whatever they turned out to be. */
+    candidates: number;
+    /** Every sighting ever recorded, including ones not seen this run. */
+    sightings: Sighting[];
+    /**
+     * Third-party repositories displaying the badge on `checkedAt`, or null when
+     * the queries did not establish it. Never 0 for want of looking.
+     */
+    thirdPartyRepos: number | null;
+    /** Why no number is published. Null exactly when `thirdPartyRepos` is a number. */
+    unresolved: string | null;
+    /**
+     * The most recent reading that did establish a number, carried across runs.
+     * A search that falls over must not publish a count, but it also must not
+     * erase the last one that stood: "unknown today, 3 on the 20th" is a reading,
+     * and "unknown" alone throws away one that was already paid for.
+     */
+    lastResolved: {
+        checkedAt: string;
+        thirdPartyRepos: number;
+    } | null;
+}
+/**
+ * The published query set. Both spellings of the badge URL are asked for
+ * separately (see the header), plus the click-through the badge is supposed to
+ * carry, plus the project's own name as the widest net — anything that names
+ * the project becomes a candidate and is then judged by its contents.
+ */
+export declare function adoptionQueries(src?: BadgeSource): QueryDef[];
+/**
+ * Undo percent-encoding without throwing on the malformed sequences that turn
+ * up in real files. Decoded per-escape rather than over the whole string, so
+ * one bad `%zz` costs that escape and nothing around it.
+ */
+export declare function decodeLoose(text: string): string;
+/**
+ * A shields endpoint badge as it stands in a file: the JSON it renders from,
+ * and the link a reader clicking it would follow. `linkTarget` is null when the
+ * image is not wrapped in a link at all.
+ */
+export interface EndpointBadge {
+    url: string;
+    linkTarget: string | null;
+}
+/**
+ * Every shields endpoint badge in a file, decoded, each paired with its own
+ * link target. Both spellings a README uses are read: markdown
+ * `[![alt](img)](target)`, which is the snippet this project publishes, and an
+ * HTML anchor wrapping an `<img>`.
+ */
+export declare function endpointBadges(text: string): EndpointBadge[];
+/**
+ * Whether a badge's JSON is served from this repository — auditable by
+ * construction, whatever the badge links to. Matched without regard to case:
+ * GitHub owner and repository names are case-insensitive, a badge written
+ * `MCP-Context-Cost` renders exactly the same one, and code search found the
+ * file that way too.
+ */
+export declare function hostedHere(url: string, src?: BadgeSource): boolean;
+/**
+ * Whether a badge's link target leads back to this project — the repository,
+ * the published pages, or a raw file in either. This is exactly what the
+ * published snippet asks an author to do with a badge whose JSON they host
+ * themselves, and it is what makes that badge auditable rather than decoration.
+ */
+export declare function linksBackToProject(target: string, src?: BadgeSource): boolean;
+/**
+ * Whether a file displays this project's badge, in either published form: the
+ * JSON served from here, or self-hosted JSON with the badge linked back at the
+ * measurement here. See the header for why both count and why the link is
+ * paired with the image rather than looked for anywhere in the file.
+ */
+export declare function displaysBadge(text: string, src?: BadgeSource): boolean;
+/**
+ * Every shields endpoint `url` in a file whose JSON is served from this
+ * repository's `badges/` directory, decoded. The first of the two forms above,
+ * on its own.
+ */
+export declare function endpointUrls(text: string, src?: BadgeSource): string[];
+/**
+ * What a candidate file is. `null` when it turns out to be neither — a search
+ * index can be older than the file it points at.
+ *
+ * Case is ignored here for the same reason it is ignored above, and the first
+ * real run is why it is stated rather than assumed: a file discussing
+ * "MCP-context-cost" was found by the search and would have been thrown out by
+ * an exact-case test, which is a rejection that looks identical to a file that
+ * genuinely stopped mentioning the project.
+ */
+export declare function classifyFile(text: string, src?: BadgeSource): SightingKind | null;
+/** `owner/repo` → is that owner someone other than this project's? */
+export declare function isThirdParty(repoFullName: string, src?: BadgeSource): boolean;
+/** A sighting as observed this run, before it is dated against the previous one. */
+export type FreshSighting = Omit<Sighting, 'firstSeenAt' | 'lastSeenAt'>;
+/**
+ * Date this run's sightings against the last one. A file seen before keeps its
+ * `firstSeenAt`; a file no longer found is kept with the date it was last seen
+ * rather than deleted, so a badge that disappears is visible as a badge that
+ * disappeared instead of as one that never existed.
+ */
+export declare function mergeSightings(previous: Sighting[], fresh: FreshSighting[], checkedAt: string): Sighting[];
+/** Repositories displaying the badge as of `checkedAt` — sorted, deduplicated. */
+export declare function badgeRepos(sightings: Sighting[], checkedAt: string): string[];
+/**
+ * Whether this run may publish a number, and if not, why not. A query that did
+ * not answer, or one whose results were cut short, means the set of files that
+ * carry the badge was never established — and a count taken from an incomplete
+ * search is a zero that means "we did not finish", which is the exact confusion
+ * this instrument exists to remove.
+ */
+export declare function resolveCount(queries: QueryResult[], sightings: Sighting[], checkedAt: string, unreadableCandidates?: number): Pick<AdoptionRun, 'thirdPartyRepos' | 'unresolved'>;
+/**
+ * The last completed reading to carry into this run's record: this one if it
+ * completed, otherwise whatever the previous run was carrying.
+ */
+export declare function carryResolved(previous: AdoptionRun | null, current: Pick<AdoptionRun, 'checkedAt' | 'thirdPartyRepos'>): AdoptionRun['lastResolved'];
+/** Parse results/badge-adoption.json; anything malformed yields null, never throws. */
+export declare function parseAdoption(text: string): AdoptionRun | null;
+/**
+ * The page a reader opens. `null` is the state that matters most: no run on
+ * record renders as "nobody has looked", in those words, with no number — which
+ * is the whole distinction this instrument exists to make readable.
+ */
+export declare function renderAdoptionPage(run: AdoptionRun | null, src?: BadgeSource): string;