mcp-context-cost 0.5.0 → 0.6.0

package/README.md

@@ -62,8 +62,8 @@ in those words.
 **Claude Code defers MCP tool definitions by default** (its **tool search**): they are not
 in context at session start, and load when the model reaches for one. Three variables move
 that, and `audit` reads all three — from the shell it runs in *and* from the `env` block of
-Claude Code's own settings files (managed, `.claude/settings.local.json`,
-`.claude/settings.json`, `~/.claude/settings.json`), because a machine that switched
+Claude Code's own settings files (managed, `<cwd>/.claude/settings.local.json`,
+`<cwd>/.claude/settings.json`, `~/.claude/settings.json`), because a machine that switched
 deferral off in a settings file is not a machine running the default:
 
 | setting | what the audit reports |
@@ -146,7 +146,7 @@ INCREASE FAIL:
 ```
 
 > **Version note.** `--baseline` and `--max-increase` shipped in **0.4.0** (published
-> 2026-08-18, and the current `latest`), so the command above gates on
+> 2026-08-18), so the command above gates on
 > `npx -y mcp-context-cost@latest`. Pinning to **0.3.0 or earlier** does not gate, and fails
 > quietly: those builds ignore flags they do not recognise, so the same command produces a
 > plain audit and **exit 0** — a passing CI check on a gate that never ran. 0.4.0 rejects
@@ -180,8 +180,10 @@ INCREASE FAIL:
 Add `--claude` to annotate each server with its Anthropic-request cost from the published
 [Claude divergence](docs/METHODOLOGY.md#claude-divergence) run — an exact number when the
 published capture hash matches what you have installed, `—` (silence, not a stale guess)
-when it doesn't (today the run covers the top 20 measured servers, so most installs will
-show a mix):
+when it doesn't. The run holds 20 rows — the top 20 measured servers by tokens; 19 of them
+still match the capture on disk here, which is why
+[results/leaderboard.md](results/leaderboard.md) prints a claude number for 19 and leaves the
+twentieth blank rather than stale. Most installs will show a mix:
 
 ```
   server               tools  tokens   share   claude
@@ -198,13 +200,14 @@ Flags: `--json` (full report on stdout, progress on stderr), `--budget N`,
 The number `audit` gives you is the same measurement, run across a curated set of public
 servers — which is how you can tell it is a measurement and not this tool's opinion. It also
 shows what you are choosing between: across the 69 servers measured, cost spans **1,700×**,
-from the 32-token `postgres` reference server to github's 54,422. The table below starts at
-markitdown's 64 tokens, an 850× spread; the full range is in
+from the 32-token `postgres` reference server to github's 54,422. The table below is a
+sample of that range; the full range is in
 [results/leaderboard.md](results/leaderboard.md).
 
 | server | context cost | tools |
 |---|---:|---:|
 | github (official) | **54,422 tokens** | 44 |
+| xcodebuildmcp | 26,594 | 24 |
 | brave-search | 25,456 | 8 |
 | notion | 17,500 | 24 |
 | playwright *(4.8M installs/week)* | 4,024 | 24 |
@@ -274,7 +277,7 @@ number is *not*, config policy, failure taxonomy, frozen color bands, known dive
 | `src/cli.ts` | `audit` (measure your own stack), `verify` (re-derive any published number), `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 |
+| `upstream/` | `badge.sh` + composite-action patch + bash tests — the self-serve badge recipe, carried here |
 | `servers.yaml` | 82 curated candidates with live install metrics and provenance |
 | `results/` · `badges/` | measurements, leaderboard, history series, shields endpoint JSONs |
 | `docs/` | methodology, dashboard, and a generated page per measured server |
@@ -302,15 +305,12 @@ than a guess — [docs/adoption.md](docs/adoption.md), regenerated by `npm run a
 which publishes the queries it ran and every file it examined. A zero there means the
 search ran and found none; if it could not run, it says that instead of publishing a zero.
 
-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                        # 403 TS tests incl. golden fixtures + dispute drills
+npm test                        # TS suite incl. golden fixtures + dispute drills
 npx tsc --noEmit                # typecheck
-./upstream/tests/badge-test.sh  # 21 bash tests — byte-identical to the TS reference
+./upstream/tests/badge-test.sh  # bash suite — byte-identical to the TS reference
 npm run sweep:all -- --docker   # full curated sweep (Docker isolation)
 ```
 
@@ -322,11 +322,13 @@ color bands are frozen against the observed distribution of the first full sweep
 ## Status
 
 Active. 46 of the 69 numbers come from the sweep of 2026-08-19 and 23 from 2026-08-18. Two
-weekly jobs re-measure the set — one reference server (`memory`) every Monday, and a rotating
-sixth of the list every Wednesday, so the full set turns over in six weeks — but treat the
-leaderboard as a dated snapshot rather than a live feed. 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.
+weekly jobs re-measure the set — the `memory` reference server on Mondays, and a rotating
+sixth of the list on Wednesdays, so every row comes round within six weeks. Read each row's
+date as the date it means, and don't take the cadence on trust — the build history is
+public, one click each:
+[re-sweep runs](https://github.com/athakur3/mcp-context-cost/actions/workflows/resweep.yml)
+and [self-badge runs](https://github.com/athakur3/mcp-context-cost/actions/workflows/self-badge.yml).
+See [ROADMAP.md](ROADMAP.md) for what's next — contributions welcome, especially new
+`servers.yaml` entries.
 
 MIT © 2026

package/dist/audit/audit.d.ts

@@ -100,6 +100,16 @@ export interface AuditReport {
     generatedAt: string;
     contextWindow: number;
     configs: AuditConfigResult[];
+    /**
+     * Client configs that were read and parsed but declare no servers. They get
+     * no report line — there is nothing to total — but they are the record that a
+     * client is installed here, which is not the same machine as one with no
+     * client at all.
+     */
+    emptyConfigs: {
+        client: string;
+        source: string;
+    }[];
     budget?: {
         limit: number;
         worstTotal: number;

package/dist/audit/audit.js

@@ -166,6 +166,7 @@ function attachDeferral(configs, contextWindow, opts) {
 export function buildReport(configs, measured, opts = {}) {
     const contextWindow = opts.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
     const problems = [];
+    const emptyConfigs = [];
     const built = [];
     // Across every config at once: a twin in one client's file is measured for
     // the other client's entry just the same.
@@ -176,6 +177,12 @@ export function buildReport(configs, measured, opts = {}) {
             problems.push(`${cfg.source}: ${cfg.error}`);
             continue;
         }
+        // Parsed, and declares nothing. Not a problem and not a report line: it is
+        // recorded as itself, so a reader is told what this machine actually has.
+        if (cfg.declaresNothing || cfg.servers.length === 0) {
+            emptyConfigs.push({ client: cfg.client, source: cfg.source });
+            continue;
+        }
         const ok = [];
         const skipped = [];
         const tools = [];
@@ -266,6 +273,7 @@ export function buildReport(configs, measured, opts = {}) {
         generatedAt: opts.generatedAt ?? new Date().toISOString(),
         contextWindow,
         configs: results,
+        emptyConfigs,
         problems,
     };
     if (opts.divergence) {
@@ -338,11 +346,16 @@ function postureSourceLines(d) {
             absent++;
             continue;
         }
+        // A place that sets one of them to something unreadable is neither a place
+        // that sets it nor a place that sets none of them, and printing it as the
+        // second is the silence this report would then argue from.
+        const unreadableVars = r.unreadable?.length
+            ? `sets ${r.unreadable.join(', ')} to a value this cannot read`
+            : '';
         const held = r.state === 'unreadable'
             ? 'could not be read — what it sets is unknown'
-            : r.sets.length
-                ? `sets ${r.sets.join(', ')}`
-                : 'sets none of them';
+            : [r.sets.length ? `sets ${r.sets.join(', ')}` : '', unreadableVars].filter(Boolean).join(', and ') ||
+                'sets none of them';
         // Which place the verdict came out of, said once rather than left to a
         // reader to work out from two lists.
         const decided = d.setting?.source === r.source ? ', which decided this' : '';
@@ -445,6 +458,13 @@ function deferralLines(d, skippedNames) {
             lines.push('  machine reads it from, and which one Claude Code takes is not on record');
             lines.push('  here. Whether these tokens are deferred cannot be said from them.');
         }
+        else if (d.setting?.unresolved === 'value-unreadable') {
+            lines.push(`  ${d.setting.variable} is set by a settings file Claude Code reads, to`);
+            lines.push('  something that is not a value this can read — an env block holds it as a');
+            lines.push('  JSON boolean, a number or null rather than a string. It is set there, and');
+            lines.push('  what it is set to is unknown, so whether these tokens are deferred cannot');
+            lines.push('  be said from it.');
+        }
         else {
             lines.push('  A settings file Claude Code reads exists here and could not be read, so');
             lines.push('  what it sets is unknown — and it can set the variable that decides this.');

package/dist/audit/config.d.ts

@@ -49,6 +49,14 @@ export interface LoadedConfig {
     servers: ConfiguredServer[];
     /** Set when the file exists but could not be read/parsed. */
     error?: string;
+    /**
+     * Set when the file was read and parsed cleanly and declares no servers at
+     * all. Such a config has nothing to total, but "this client declares nothing"
+     * and "no client is installed here" are different facts about a machine and
+     * only one of them is about the client, so the second is not reported as the
+     * first.
+     */
+    declaresNothing?: true;
 }
 /** Read + parse the candidates that exist. Unreadable files are reported, not thrown. */
 export declare function loadConfigs(candidates: ConfigCandidate[], cwd: string): LoadedConfig[];

package/dist/audit/config.js

@@ -167,9 +167,13 @@ export function loadConfigs(candidates, cwd) {
             const doc = parseJsonc(readFileSync(c.path, 'utf8'));
             const servers = extractServers(doc, { client: c.client, source: c.path, cwd });
             // A config with no MCP block at all (e.g. a ~/.claude.json holding only
-            // session history) is not worth a line in the report.
-            if (servers.length === 0)
+            // session history) is not worth a line in the report — it has no total.
+            // It is still worth carrying: it is the evidence that a client is on this
+            // machine, which is what tells an empty client apart from no client.
+            if (servers.length === 0) {
+                out.push({ client: c.client, source: c.path, servers: [], declaresNothing: true });
                 continue;
+            }
             out.push({ client: c.client, source: c.path, servers });
         }
         catch (e) {
@@ -227,14 +231,30 @@ export function loadSettingsSources(candidates) {
                 throw new Error('not a settings object');
             const block = doc.env;
             const vars = {};
+            const unreadable = [];
             if (block && typeof block === 'object' && !Array.isArray(block)) {
                 for (const name of TOOL_SEARCH_VARS) {
+                    if (!(name in block))
+                        continue;
                     const v = block[name];
                     if (typeof v === 'string')
                         vars[name] = v;
+                    // The variable is set in this file, to something that is not a value
+                    // this can read — `"ENABLE_TOOL_SEARCH": false`, the JSON boolean, is
+                    // the one people write. Dropping it here made the file look like a
+                    // file that sets nothing, and the report then stated the documented
+                    // default at a machine whose settings say otherwise.
+                    else
+                        unreadable.push(name);
                 }
             }
-            return { scope: c.scope, source: c.path, state: 'read', vars };
+            return {
+                scope: c.scope,
+                source: c.path,
+                state: 'read',
+                vars,
+                ...(unreadable.length ? { unreadable } : {}),
+            };
         }
         catch {
             return { scope: c.scope, source: c.path, state: 'unreadable', vars: {} };

package/dist/audit/deferral.d.ts

@@ -82,6 +82,17 @@ export interface ToolSearchSource {
     state: 'read' | 'absent' | 'unreadable';
     /** What this place sets, of the three. Values are read here, never reported. */
     vars: ToolSearchEnv;
+    /**
+     * Variables this place sets to something that is not a value this audit can
+     * read — an env block holding a JSON boolean, a number, or null.
+     *
+     * The file parsed and the variable IS set in it; what it is set to is
+     * unknown. That is not the same as unset, and reading it as unset is how a
+     * machine whose `~/.claude/settings.json` held `"ENABLE_TOOL_SEARCH": false`
+     * — the boolean, not the string — was told the documented default stands and
+     * these tokens are never loaded up front.
+     */
+    unreadable?: ToolSearchVar[];
 }
 /**
  * A source as it appears in a report: names of what it sets, never values.
@@ -96,6 +107,12 @@ export interface ToolSearchSourceRecord {
     state: ToolSearchSource['state'];
     /** Variable NAMES set here. A value can be a base URL carrying a credential. */
     sets: ToolSearchVar[];
+    /**
+     * Variable NAMES this place sets to something unreadable, when it does.
+     * Omitted otherwise, so the common source record keeps its shape — a reader
+     * meets this field only where there is an unknown to meet.
+     */
+    unreadable?: ToolSearchVar[];
 }
 /** A source as it is published: what it sets, by name. */
 export declare function toolSearchSourceRecord(s: ToolSearchSource): ToolSearchSourceRecord;
@@ -148,7 +165,7 @@ export interface ToolSearchSetting {
      */
     sources: ToolSearchSourceRecord[];
     /** Set only in `setting-unresolved`: why no mode could be read off them. */
-    unresolved?: 'sources-disagree' | 'source-unreadable';
+    unresolved?: 'sources-disagree' | 'source-unreadable' | 'value-unreadable';
 }
 interface ResolvedToolSearch extends Omit<ToolSearchSetting, 'sources'> {
     mode: Extract<DeferralMode, 'defers-all' | 'threshold' | 'loads-upfront' | 'setting-unrecognized' | 'setting-unresolved'>;
@@ -185,7 +202,10 @@ export declare function resolveToolSearch(env: ToolSearchEnv): ResolvedToolSearc
  * a disagreement is refused rather than resolved: `setting-unresolved` names the
  * variable and every place, and no verdict is given. A place that exists and
  * could not be read is the same refusal for the same reason — what it sets is
- * unknown, and an unknown that could flip the answer is not a default.
+ * unknown, and an unknown that could flip the answer is not a default. So is a
+ * place that parsed and sets the deciding variable to something that is not a
+ * readable value: the variable is set there, and dropping it leaves the report
+ * arguing from a silence that is not silent.
  *
  * Not visible from here at all, and so not claimed: a variable set on Claude
  * Code's own command line.

package/dist/audit/deferral.js

@@ -18,11 +18,13 @@ export function toolSearchEnv(env) {
 export const SHELL_SOURCE = '(shell environment)';
 /** A source as it is published: what it sets, by name. */
 export function toolSearchSourceRecord(s) {
+    const unreadable = TOOL_SEARCH_VARS.filter((n) => (s.unreadable ?? []).includes(n));
     return {
         scope: s.scope,
         source: s.source,
         state: s.state,
         sets: TOOL_SEARCH_VARS.filter((n) => (s.vars[n] ?? '').trim() !== ''),
+        ...(unreadable.length ? { unreadable } : {}),
     };
 }
 /** The one host Claude Code treats as first-party for the tool-search fallback. */
@@ -136,7 +138,10 @@ export function resolveToolSearch(env) {
  * a disagreement is refused rather than resolved: `setting-unresolved` names the
  * variable and every place, and no verdict is given. A place that exists and
  * could not be read is the same refusal for the same reason — what it sets is
- * unknown, and an unknown that could flip the answer is not a default.
+ * unknown, and an unknown that could flip the answer is not a default. So is a
+ * place that parsed and sets the deciding variable to something that is not a
+ * readable value: the variable is set there, and dropping it leaves the report
+ * arguing from a silence that is not silent.
  *
  * Not visible from here at all, and so not claimed: a variable set on Claude
  * Code's own command line.
@@ -155,16 +160,32 @@ export function resolveToolSearchSources(sources) {
         return unresolved('source-unreadable', null);
     const settings = sources.filter((s) => s.scope !== 'shell');
     const shell = sources.find((s) => s.scope === 'shell');
-    /** The value that would win for one variable, or the fact that two places disagree. */
+    /** Whether a place sets this variable at all — readably or not. */
+    const holds = (s, name) => (s.vars[name] ?? '').trim() !== '' || (s.unreadable ?? []).includes(name);
+    /**
+     * The value that would win for one variable, or the fact that it cannot be
+     * had: two places disagree, or the place that would win sets it to something
+     * unreadable.
+     *
+     * Precedence is what makes the unreadable case worth separating from a blanket
+     * refusal. A higher-precedence file setting a value Claude Code documents is
+     * the value in force, and an unreadable one underneath it decides nothing —
+     * the same reasoning that keeps a disagreement over `ANTHROPIC_BASE_URL` from
+     * refusing an answer an explicit `ENABLE_TOOL_SEARCH` already gave.
+     */
     const read = (name) => {
-        const winner = settings
-            .map((s) => ({ value: (s.vars[name] ?? '').trim(), source: s.source }))
-            .find((v) => v.value !== '');
+        const winner = settings.find((s) => holds(s, name));
         const shellValue = (shell?.vars[name] ?? '').trim();
-        if (winner && shellValue && winner.value !== shellValue)
+        // Whichever place would decide holds an unknown: it could be any of the
+        // documented values or none of them, and the ones it could be do not agree.
+        if (winner && (winner.vars[name] ?? '').trim() === '')
+            return 'unreadable';
+        if (shell && holds(shell, name) && shellValue === '')
+            return 'unreadable';
+        if (winner && shellValue && (winner.vars[name] ?? '').trim() !== shellValue)
             return 'conflict';
         if (winner)
-            return winner;
+            return { value: (winner.vars[name] ?? '').trim(), source: winner.source };
         if (shellValue && shell)
             return { value: shellValue, source: shell.source };
         return null;
@@ -176,6 +197,8 @@ export function resolveToolSearchSources(sources) {
     const betas = read('CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS');
     if (betas === 'conflict')
         return unresolved('sources-disagree', 'CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS');
+    if (betas === 'unreadable')
+        return unresolved('value-unreadable', 'CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS');
     if (betas) {
         return {
             ...resolveToolSearch({ CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: betas.value }),
@@ -185,12 +208,16 @@ export function resolveToolSearchSources(sources) {
     const enable = read('ENABLE_TOOL_SEARCH');
     if (enable === 'conflict')
         return unresolved('sources-disagree', 'ENABLE_TOOL_SEARCH');
+    if (enable === 'unreadable')
+        return unresolved('value-unreadable', 'ENABLE_TOOL_SEARCH');
     if (enable) {
         return { ...resolveToolSearch({ ENABLE_TOOL_SEARCH: enable.value }), source: enable.source };
     }
     const base = read('ANTHROPIC_BASE_URL');
     if (base === 'conflict')
         return unresolved('sources-disagree', 'ANTHROPIC_BASE_URL');
+    if (base === 'unreadable')
+        return unresolved('value-unreadable', 'ANTHROPIC_BASE_URL');
     const resolved = resolveToolSearch(base ? { ANTHROPIC_BASE_URL: base.value } : {});
     return { ...resolved, source: resolved.readFromMachine ? (base?.source ?? null) : null };
 }

package/dist/cli.js

@@ -173,8 +173,19 @@ if (cmd === 'audit') {
     });
     if (report.configs.length === 0) {
         const where = report.problems.length ? `\n${report.problems.map((p) => `  ${p}`).join('\n')}` : '';
+        const empty = report.emptyConfigs ?? [];
         if (json)
             console.log(JSON.stringify(report));
+        // A machine whose client config was found, opened and parsed, and simply
+        // declares nothing, is told that — being told no client was found anywhere
+        // would send a reader looking for an install they already have.
+        else if (empty.length)
+            console.error(`${empty.length === 1 ? 'an MCP client config was found' : `${empty.length} MCP client configs were found`}, ` +
+                `and ${empty.length === 1 ? 'it declares' : 'they declare'} no servers:\n` +
+                empty.map((c) => `  ${c.client}: ${c.source}`).join('\n') +
+                `${where}\n` +
+                `${empty.length === 1 ? 'It was' : 'They were'} read and parsed; there is simply nothing declared to measure.\n` +
+                `Declare a server in one of them, or point at a different config: mcp-context-cost audit --config <path/to/mcp.json>`);
         else
             console.error(`no MCP config found. Looked in the standard Claude Desktop / Claude Code / Cursor / VS Code / Windsurf locations.${where}\n` +
                 `Point at one explicitly: mcp-context-cost audit --config <path/to/mcp.json>`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-context-cost",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Measure what your MCP servers cost in context tokens — audit your own config, or badge the server you publish",
   "type": "module",
   "license": "MIT",