mcp-context-cost 0.4.0 → 0.6.0

package/dist/audit/deferral.js

@@ -0,0 +1,403 @@
+/** Share of the context window at which deferral activates under `auto`. */
+export const TOOL_SEARCH_AUTO_SHARE = 0.1;
+/** The variables that decide whether this machine's Claude Code defers. */
+export const TOOL_SEARCH_VARS = [
+    'ENABLE_TOOL_SEARCH',
+    'CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS',
+    'ANTHROPIC_BASE_URL',
+];
+/** Pick the three variables that matter out of a process environment. */
+export function toolSearchEnv(env) {
+    return {
+        ENABLE_TOOL_SEARCH: env.ENABLE_TOOL_SEARCH,
+        CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS,
+        ANTHROPIC_BASE_URL: env.ANTHROPIC_BASE_URL,
+    };
+}
+/** What `source` says for the process environment, which has no path. */
+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. */
+const FIRST_PARTY_API_HOST = 'api.anthropic.com';
+/** What is printed for a base URL we could not parse — a marker, not the value. */
+const UNREADABLE_BASE_URL = '(unreadable URL)';
+/**
+ * The hostname of a base URL, or null if it does not parse.
+ *
+ * The hostname is the whole of what the mode decision needs, and it is also the
+ * whole of what may leave this function: the rest of the value can carry a
+ * credential. A value that does not parse is not first-party, which is the
+ * reading that says tokens are paid — never the one that says they are free.
+ */
+function baseUrlHost(raw) {
+    try {
+        return new URL(raw).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the tool-search setting out of ONE environment. Values are matched
+ * exactly as documented: an unrecognized value produces `setting-unrecognized`
+ * rather than a guess, because guessing here would print a definite verdict
+ * about tokens the reader may or may not be paying.
+ *
+ * `source` is left null here: this function is given one environment and has no
+ * way to say which of the machine's places it came from. `resolveToolSearchSources`,
+ * which does, fills it in.
+ */
+export function resolveToolSearch(env) {
+    const betas = env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS?.trim();
+    // Read first: documented as not overridable by ENABLE_TOOL_SEARCH.
+    if (betas) {
+        return {
+            mode: 'loads-upfront',
+            thresholdShare: null,
+            variable: 'CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS',
+            value: betas,
+            source: null,
+            readFromMachine: true,
+        };
+    }
+    const raw = env.ENABLE_TOOL_SEARCH?.trim();
+    const set = (mode, thresholdShare) => ({
+        mode,
+        thresholdShare,
+        variable: 'ENABLE_TOOL_SEARCH',
+        value: raw ?? null,
+        source: null,
+        readFromMachine: true,
+    });
+    if (raw === undefined || raw === '') {
+        const base = env.ANTHROPIC_BASE_URL?.trim();
+        if (base) {
+            const host = baseUrlHost(base);
+            if (host !== FIRST_PARTY_API_HOST) {
+                return {
+                    mode: 'loads-upfront',
+                    thresholdShare: null,
+                    variable: 'ANTHROPIC_BASE_URL',
+                    // The hostname alone. `base` itself is never carried out of here.
+                    value: host ?? UNREADABLE_BASE_URL,
+                    source: null,
+                    readFromMachine: true,
+                };
+            }
+        }
+        return {
+            mode: 'defers-all',
+            thresholdShare: null,
+            variable: 'ENABLE_TOOL_SEARCH',
+            value: null,
+            source: null,
+            readFromMachine: false,
+        };
+    }
+    if (raw === 'true')
+        return set('defers-all', null);
+    if (raw === 'false')
+        return set('loads-upfront', null);
+    if (raw === 'auto')
+        return set('threshold', TOOL_SEARCH_AUTO_SHARE);
+    const custom = /^auto:(\d{1,3})$/.exec(raw);
+    if (custom) {
+        const pct = Number(custom[1]);
+        if (pct >= 0 && pct <= 100)
+            return set('threshold', pct / 100);
+    }
+    return set('setting-unrecognized', null);
+}
+/**
+ * Read the posture from every place the audited machine can set it.
+ *
+ * Claude Code takes these variables from the shell it was started in AND from
+ * the `env` block of its own settings files, so an audit that reads only the
+ * shell answers the machine's question with someone else's environment. The
+ * case that made this necessary: `~/.claude/settings.json` sets
+ * `ENABLE_TOOL_SEARCH: "false"`, the shell running the audit sets nothing, and
+ * every request on that machine pays for every tool definition while the report
+ * calls it the documented default and says the tokens are not loaded at all.
+ *
+ * Among the settings files the order is Claude Code's documented precedence —
+ * enterprise managed policy, then project-local, then project, then user
+ * (Claude Code settings documentation, §"Settings files", read 2026-08-20) — so
+ * the first of them that sets a variable is the one that would win.
+ *
+ * Between the settings files and the shell there is NO order on record here, so
+ * 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. 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.
+ */
+export function resolveToolSearchSources(sources) {
+    const unresolved = (reason, variable) => ({
+        mode: 'setting-unresolved',
+        thresholdShare: null,
+        variable,
+        value: null,
+        source: null,
+        readFromMachine: false,
+        unresolved: reason,
+    });
+    if (sources.some((s) => s.state === 'unreadable'))
+        return unresolved('source-unreadable', null);
+    const settings = sources.filter((s) => s.scope !== 'shell');
+    const shell = sources.find((s) => s.scope === 'shell');
+    /** 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.find((s) => holds(s, name));
+        const shellValue = (shell?.vars[name] ?? '').trim();
+        // 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 { value: (winner.vars[name] ?? '').trim(), source: winner.source };
+        if (shellValue && shell)
+            return { value: shellValue, source: shell.source };
+        return null;
+    };
+    // Consulted in the same order `resolveToolSearch` consults them, so a
+    // disagreement over a variable that would not have decided anything —
+    // ANTHROPIC_BASE_URL behind an explicit ENABLE_TOOL_SEARCH — does not refuse
+    // an answer the machine actually gives.
+    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 }),
+            source: betas.source,
+        };
+    }
+    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 };
+}
+/**
+ * The band as published in this repository's own `results/divergence.json`
+ * (claude-opus-5, 2026-08-19, 20 servers). Used when no divergence run was
+ * supplied; `--claude` recomputes it from the run it fetched.
+ */
+export const PUBLISHED_WIRE_TO_CLIENT_RATIO = {
+    low: 0.2,
+    high: 1.92,
+    servers: 20,
+    source: 'the published claude-opus-5 divergence run',
+};
+/** Derive the band from a supplied divergence run, falling back to the published one. */
+export function wireToClientRatio(run) {
+    if (!run)
+        return PUBLISHED_WIRE_TO_CLIENT_RATIO;
+    let low = Infinity;
+    let high = -Infinity;
+    let servers = 0;
+    for (const row of Object.values(run.servers)) {
+        if (!row || row.error || typeof row.claudeDelta !== 'number' || !(row.o200kFull > 0))
+            continue;
+        const ratio = row.claudeDelta / row.o200kFull;
+        low = Math.min(low, ratio);
+        high = Math.max(high, ratio);
+        servers++;
+    }
+    if (servers === 0)
+        return PUBLISHED_WIRE_TO_CLIENT_RATIO;
+    return { low, high, servers, source: `the ${run.measuredAt} ${run.model} divergence run` };
+}
+/** Clients this tool discovers that have no default deferral on record. */
+const NO_DEFERRAL_ON_RECORD = new Set(['claude-desktop', 'cursor', 'vscode', 'windsurf']);
+/**
+ * Where deferral does not apply even when the machine's setting says it should.
+ * None of these can be read from the config or the environment, so they are
+ * printed as conditions for the reader to check rather than folded into the
+ * verdict.
+ */
+const EXCEPTIONS = [
+    'a Microsoft Foundry deployment hosted on Azure, which rejects tool search server-side',
+    "Google Cloud's Agent Platform on a model earlier than the Claude 4.5 generation",
+    'a model without support for tool_reference blocks (before Sonnet 4.5 / Haiku 4.5 / Opus 4.5)',
+    'a server pinned with "alwaysLoad": true, whose tools load at session start regardless',
+];
+function estimate(servers, ratio) {
+    let low = 0;
+    let high = 0;
+    let exact = 0;
+    let estimated = 0;
+    for (const s of servers) {
+        if (typeof s.claudeTokens === 'number') {
+            // A published Anthropic count for this exact capture. It carries the tool
+            // framework overhead the API charges once per request rather than once
+            // per server, so a multi-server sum leans high by at most that overhead —
+            // far inside the band the converted servers already contribute.
+            low += s.claudeTokens;
+            high += s.claudeTokens;
+            exact++;
+        }
+        else {
+            low += s.tokens * ratio.low;
+            high += s.tokens * ratio.high;
+            estimated++;
+        }
+    }
+    return { low: Math.round(low), high: Math.round(high), exact, estimated };
+}
+/**
+ * Read one session's deferral position. Pure arithmetic over a built scope — no
+ * config file is re-read and no server is launched. The environment is passed
+ * in rather than read here, so the answer is reproducible from its inputs.
+ */
+export function evaluateDeferral(scope, opts) {
+    const wireTokens = scope.servers.reduce((a, s) => a + s.tokens, 0);
+    const isFloor = scope.skippedCount > 0;
+    const sharedMeasurements = scope.sharedMeasurements;
+    // Every field a verdict carries, at its "nothing to say" value. Each mode
+    // below overrides only what it can actually answer.
+    const base = {
+        client: scope.client,
+        sources: scope.sources,
+        wireTokens,
+        isFloor,
+        // Carried by every mode, not just the one that returns early on it below.
+        // That early return withholds `clientTokens` and `crosses`, which only
+        // threshold mode ever computes; the other modes derive nothing from the
+        // total and so have nothing to withhold. What they do all do is PRINT it,
+        // so the caveat belongs in every branch of the report — see
+        // `sharedMeasurementLines` in audit.ts, which every mode calls.
+        sharedMeasurements,
+        mechanism: null,
+        setting: null,
+        thresholdShare: null,
+        thresholdTokens: null,
+        clientTokens: null,
+        ratio: null,
+        distanceTokens: null,
+        crosses: null,
+        exceptions: [],
+    };
+    if (scope.client !== 'claude-code') {
+        return {
+            ...base,
+            mode: NO_DEFERRAL_ON_RECORD.has(scope.client) ? 'no-deferral-on-record' : 'client-unknown',
+        };
+    }
+    // The shell is one place among several, not the machine. Everything Claude
+    // Code would read is resolved together, and a disagreement between them is
+    // refused rather than decided by whichever this happened to open.
+    const sources = [
+        { scope: 'shell', source: SHELL_SOURCE, state: 'read', vars: opts.env ?? {} },
+        ...(opts.settings ?? []),
+    ];
+    const resolved = resolveToolSearchSources(sources);
+    const setting = {
+        variable: resolved.variable,
+        value: resolved.value,
+        source: resolved.source,
+        readFromMachine: resolved.readFromMachine,
+        sources: sources.map(toolSearchSourceRecord),
+        ...(resolved.unresolved ? { unresolved: resolved.unresolved } : {}),
+    };
+    if (resolved.mode !== 'threshold') {
+        return {
+            ...base,
+            mode: resolved.mode,
+            mechanism: 'tool search',
+            setting,
+            // Nothing is deferred in the other two modes, so the conditions under
+            // which deferral fails to apply are not worth printing there.
+            exceptions: resolved.mode === 'defers-all' ? EXCEPTIONS : [],
+        };
+    }
+    const thresholdShare = resolved.thresholdShare ?? TOOL_SEARCH_AUTO_SHARE;
+    const thresholdTokens = Math.round(opts.contextWindow * thresholdShare);
+    if (sharedMeasurements > 0) {
+        // There is a threshold, and no total to hold against it. A shared
+        // measurement is not a floor: a twin can serve more tools than the one that
+        // was launched or fewer, so the sum can be wrong in either direction and
+        // neither side can be ruled out. The same machine has already been seen to
+        // report 13,834 wire tokens or 392 for one stack depending on which twin
+        // the cache happened to hold, and to print a confident — opposite — side
+        // each time. This is the rule `evaluateIncreaseGate` states and `crosses`
+        // already follows: an answer that could not be established fails rather
+        // than resolves. The threshold itself is still reported, because where the
+        // line sits is known even when this stack's distance from it is not.
+        return {
+            ...base,
+            mode: 'threshold',
+            mechanism: 'tool search',
+            setting,
+            thresholdShare,
+            thresholdTokens,
+            exceptions: EXCEPTIONS,
+        };
+    }
+    const ratio = wireToClientRatio(opts.divergence);
+    const clientTokens = estimate(scope.servers, ratio);
+    // At-or-above, on the documented "defers all of them once the definitions
+    // reach 10%". A range that is entirely over is over even if it is a floor:
+    // more unmeasured tokens cannot take it back under.
+    const crosses = clientTokens.low >= thresholdTokens
+        ? true
+        : isFloor || clientTokens.high >= thresholdTokens
+            ? null
+            : false;
+    return {
+        ...base,
+        mode: 'threshold',
+        mechanism: 'tool search',
+        setting,
+        thresholdShare,
+        thresholdTokens,
+        clientTokens,
+        ratio,
+        distanceTokens: { low: clientTokens.low - thresholdTokens, high: clientTokens.high - thresholdTokens },
+        crosses,
+        exceptions: EXCEPTIONS,
+    };
+}

package/dist/audit/run.d.ts

@@ -1,6 +1,7 @@
 import type { Measurement } from '../core/types.js';
 import { type DivergenceRun } from '../core/divergence.js';
 import { type AuditReport } from './audit.js';
+import { type ToolSearchEnv, type ToolSearchSource } from './deferral.js';
 import { type LoadedConfig } from './config.js';
 /** Where the published `tools-delta/v1` run lives when `--claude` doesn't override it. */
 export declare const DEFAULT_DIVERGENCE_URL = "https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/divergence.json";
@@ -18,6 +19,18 @@ export interface AuditOptions {
     claude?: boolean;
     /** Override the divergence.json source — mainly for tests and self-hosted mirrors. */
     divergenceUrl?: string;
+    /**
+     * The tool-search variables as this process's SHELL has them. Defaults to
+     * this process's environment. Overridable so a test can state a machine
+     * rather than inherit the one it runs on.
+     */
+    env?: ToolSearchEnv;
+    /**
+     * The same variables as Claude Code's own settings files set them — the other
+     * half of the answer, and the half a shell cannot show. Defaults to reading
+     * those files off the machine being audited (`discoverSettings`).
+     */
+    settings?: ToolSearchSource[];
     onProgress?: (name: string, done: number, total: number) => void;
 }
 /** Fetch and parse the published divergence run. Never throws: a failure is a report problem, not a crash. */
@@ -26,6 +39,15 @@ export declare function fetchDivergence(url: string): Promise<{
     problem?: string;
 }>;
 export declare function discover(opts?: AuditOptions): LoadedConfig[];
+/**
+ * Read every settings file Claude Code would take its deferral setting from.
+ *
+ * A sibling of `discover` above and deliberately separate from it: that one
+ * finds which servers exist, this one finds how the client treats them. The
+ * setting does not live in a client config, and reading only the shell that
+ * launched this audit answers for the wrong machine.
+ */
+export declare function discoverSettings(opts?: AuditOptions): ToolSearchSource[];
 /** Measure every distinct stdio server across the given configs, once each. */
 export declare function measureAll(configs: LoadedConfig[], opts?: AuditOptions): Promise<Map<string, Measurement>>;
 export declare function runAudit(opts?: AuditOptions): Promise<AuditReport>;

package/dist/audit/run.js

@@ -8,7 +8,8 @@ import { homedir } from 'node:os';
 import { measureServer } from '../sweep/run.js';
 import { parseDivergence } from '../core/divergence.js';
 import { buildReport, serverKey } from './audit.js';
-import { configCandidates, loadConfigs } from './config.js';
+import { toolSearchEnv } from './deferral.js';
+import { configCandidates, loadConfigs, loadSettingsSources, settingsCandidates, } from './config.js';
 /** Where the published `tools-delta/v1` run lives when `--claude` doesn't override it. */
 export const DEFAULT_DIVERGENCE_URL = 'https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/divergence.json';
 /** Fetch and parse the published divergence run. Never throws: a failure is a report problem, not a crash. */
@@ -32,6 +33,19 @@ export function discover(opts = {}) {
         : configCandidates({ home, cwd, platform: process.platform, appData: process.env.APPDATA });
     return loadConfigs(candidates, cwd);
 }
+/**
+ * Read every settings file Claude Code would take its deferral setting from.
+ *
+ * A sibling of `discover` above and deliberately separate from it: that one
+ * finds which servers exist, this one finds how the client treats them. The
+ * setting does not live in a client config, and reading only the shell that
+ * launched this audit answers for the wrong machine.
+ */
+export function discoverSettings(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? homedir();
+    return loadSettingsSources(settingsCandidates({ home, cwd, platform: process.platform, programData: process.env.ProgramData }));
+}
 /** Measure every distinct stdio server across the given configs, once each. */
 export async function measureAll(configs, opts = {}) {
     const unique = new Map();
@@ -79,6 +93,8 @@ export async function runAudit(opts = {}) {
         contextWindow: opts.contextWindow,
         budget: opts.budget,
         divergence,
+        env: opts.env ?? toolSearchEnv(process.env),
+        settings: opts.settings ?? discoverSettings(opts),
     });
     if (divergenceProblem)
         report.problems.push(divergenceProblem);

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>`);