mcp-context-cost 0.6.0 → 0.8.0

package/README.md

@@ -70,11 +70,12 @@ deferral off in a settings file is not a machine running the default:
 |---|---|
 | nothing set (the default) | every definition deferred, at any size — no threshold applies |
 | `ENABLE_TOOL_SEARCH=true` | same: every definition deferred |
-| `ENABLE_TOOL_SEARCH=false` | deferral off — every request carries the full total |
+| `ENABLE_TOOL_SEARCH=false` | deferral off — every request carries the full total. In a settings `env` block that is the **string** `"false"`; the JSON boolean `false` is the last row, not this one |
 | `ENABLE_TOOL_SEARCH=auto` / `auto:N` | deferred only once definitions reach 10% / N% of the context window |
 | `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` set | tool search off — read first, because `ENABLE_TOOL_SEARCH` cannot override it |
 | `ANTHROPIC_BASE_URL` off `api.anthropic.com` | falls back to loading up front — consulted only while `ENABLE_TOOL_SEARCH` is unset |
 | anything else in `ENABLE_TOOL_SEARCH` | not a documented value, so nothing is claimed from it |
+| any of the three set, in a settings `env` block, to something that is not a string — a JSON boolean, a number, `null` | it is set there and what it is set to is unknown, so no posture is claimed: the report says whether these tokens are deferred cannot be said from it |
 
 On a machine where none of them is set, the same stack reads:
 
@@ -105,11 +106,13 @@ costs **more** than loading the definitions would.
 Three things the report will not do: it will not convert between units silently (in
 threshold mode the stack is compared as a range, because the audit counts wire bytes and the
 threshold is counted in what the client sends to the API — measured at 0.20×–1.92× across 20
-servers); it will not pick a winner when two places on the machine set the same variable to
-different values, or when a settings file exists and cannot be read; and it will not pass an
-absence of a record off as a measurement. The first two print as unanswered questions. The
-third prints as an answer that names itself: for the four discovered clients with no default
-on record — `claude-desktop`, `cursor`, `vscode`, `windsurf` — the tokens are counted as
+servers); it will not claim a posture the machine did not state readably, which is four
+refusals and not one — when two places set the same variable to different values, when a
+settings file exists and cannot be read, when the place that would decide sets the variable
+to something that is not a string, and when `ENABLE_TOOL_SEARCH` holds a value Claude Code
+does not document; and it will not pass an absence of a record off as a measurement. The
+first two print as unanswered questions. The third prints as an answer that names
+itself: for the four discovered clients with no default on record — `claude-desktop`, `cursor`, `vscode`, `windsurf` — the tokens are counted as
 loaded up front, and the report says so in those words, "an absence of a record about the
 client, not a measurement of it".
 Full model, sources and dates: [METHODOLOGY §who pays the number](docs/METHODOLOGY.md#who-pays).

package/dist/audit/audit.d.ts

@@ -101,14 +101,19 @@ export interface AuditReport {
     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.
+     * Client configs that were read and parsed and have nothing to total. They
+     * get no report line, but they are the record that a client is installed
+     * here, which is not the same machine as one with no client at all.
+     *
+     * `allDisabled`, when present, is why there is nothing to total: the file
+     * declares those servers and every one of them is switched off. A config
+     * without it declares no servers at all. The two are different facts about a
+     * file this opened, so they are not published as one.
      */
     emptyConfigs: {
         client: string;
         source: string;
+        allDisabled?: string[];
     }[];
     budget?: {
         limit: number;

package/dist/audit/audit.js

@@ -177,10 +177,13 @@ 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.
+        // Parsed, and nothing to total. Not a problem and not a report line: it is
+        // recorded as itself, so a reader is told what this machine actually has —
+        // including, where that is the case, that what it has is servers turned off.
         if (cfg.declaresNothing || cfg.servers.length === 0) {
-            emptyConfigs.push({ client: cfg.client, source: cfg.source });
+            emptyConfigs.push(cfg.allDisabled?.length
+                ? { client: cfg.client, source: cfg.source, allDisabled: cfg.allDisabled }
+                : { client: cfg.client, source: cfg.source });
             continue;
         }
         const ok = [];

package/dist/audit/config.d.ts

@@ -32,6 +32,23 @@ export declare function extractServers(doc: unknown, meta: {
     source: string;
     cwd?: string;
 }): ConfiguredServer[];
+/**
+ * What one config document declares, servers and switched-off entries both.
+ *
+ * `extractServers` above answers "what is there to measure", which is the
+ * question almost every caller has. This answers the wider one, because a file
+ * that declares three servers and switches all three off has nothing to measure
+ * and is still not a file that declares nothing — and the only place that
+ * difference is still visible is here, before the off ones are dropped.
+ */
+export declare function extractDeclaration(doc: unknown, meta: {
+    client: string;
+    source: string;
+    cwd?: string;
+}): {
+    servers: ConfiguredServer[];
+    disabled: string[];
+};
 export interface ConfigCandidate {
     client: string;
     path: string;
@@ -57,6 +74,14 @@ export interface LoadedConfig {
      * first.
      */
     declaresNothing?: true;
+    /**
+     * Set instead of `declaresNothing` when the file was read and parsed cleanly,
+     * declares servers, and every one of them is switched off — the names, in the
+     * file's own words. There is nothing to total either way, but a person who
+     * turned their servers off is not a person who declared none, and telling
+     * them the file declares nothing is a false statement about a file this read.
+     */
+    allDisabled?: string[];
 }
 /** 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

@@ -113,16 +113,34 @@ function toServer(name, raw, client, source) {
  * servers by absolute directory.
  */
 export function extractServers(doc, meta) {
+    return extractDeclaration(doc, meta).servers;
+}
+/**
+ * What one config document declares, servers and switched-off entries both.
+ *
+ * `extractServers` above answers "what is there to measure", which is the
+ * question almost every caller has. This answers the wider one, because a file
+ * that declares three servers and switches all three off has nothing to measure
+ * and is still not a file that declares nothing — and the only place that
+ * difference is still visible is here, before the off ones are dropped.
+ */
+export function extractDeclaration(doc, meta) {
     if (!doc || typeof doc !== 'object')
-        return [];
+        return { servers: [], disabled: [] };
     const d = doc;
     const out = [];
+    const off = [];
     const addBlock = (block) => {
         if (!block || typeof block !== 'object')
             return;
         for (const [name, raw] of Object.entries(block)) {
             if (!raw || typeof raw !== 'object')
                 continue;
+            // Recorded before `toServer` drops it, which is the only difference this
+            // can still see: an entry it returns null for because the person turned
+            // it off, rather than because it is malformed or absent.
+            if (raw.disabled === true)
+                off.push(name);
             const s = toServer(name, raw, meta.client, meta.source);
             if (s)
                 out.push(s);
@@ -137,7 +155,11 @@ export function extractServers(doc, meta) {
     }
     // A name can legitimately appear in both blocks of the same file; keep the first.
     const seen = new Set();
-    return out.filter((s) => (seen.has(s.name) ? false : (seen.add(s.name), true)));
+    const servers = out.filter((s) => (seen.has(s.name) ? false : (seen.add(s.name), true)));
+    // A name that is off in one block and live in another is a live server, not a
+    // switched-off one, so it is not reported as both.
+    const disabled = [...new Set(off.filter((n) => !seen.has(n)))].sort();
+    return { servers, disabled };
 }
 /** Every place a client config is known to live, whether or not it exists. */
 export function configCandidates(env) {
@@ -165,12 +187,19 @@ export function loadConfigs(candidates, cwd) {
             continue;
         try {
             const doc = parseJsonc(readFileSync(c.path, 'utf8'));
-            const servers = extractServers(doc, { client: c.client, source: c.path, cwd });
+            const { servers, disabled } = extractDeclaration(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 — 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) {
+                // ...and one whose every declared server is switched off is carried as
+                // that, not as one declaring nothing: the second is a claim about the
+                // file that the file itself contradicts.
+                if (disabled.length) {
+                    out.push({ client: c.client, source: c.path, servers: [], allDisabled: disabled });
+                    continue;
+                }
                 out.push({ client: c.client, source: c.path, servers: [], declaresNothing: true });
                 continue;
             }

package/dist/cli.js

@@ -176,9 +176,26 @@ if (cmd === 'audit') {
         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.
+        // A machine whose client config was found, opened and parsed, and has
+        // nothing to total, is told that — being told no client was found anywhere
+        // would send a reader looking for an install they already have. Which of
+        // the two reasons it is gets said, because "declares nothing" is a false
+        // statement about a file that declares servers and switches them off.
+        else if (empty.some((c) => c.allDisabled?.length))
+            console.error(`${empty.length === 1 ? 'an MCP client config was found' : `${empty.length} MCP client configs were found`}, ` +
+                `and ${empty.length === 1 ? 'it has no server' : 'none of them has a server'} to measure:\n` +
+                empty
+                    .map((c) => {
+                    const off = c.allDisabled ?? [];
+                    if (!off.length)
+                        return `  ${c.client}: ${c.source} — declares no servers at all`;
+                    return (`  ${c.client}: ${c.source} — declares ${off.length} server${off.length === 1 ? '' : 's'}, ` +
+                        `and ${off.length === 1 ? 'it is' : 'every one of them is'} switched off: ${off.join(', ')}`);
+                })
+                    .join('\n') +
+                `${where}\n` +
+                `${empty.length === 1 ? 'It was' : 'They were'} read and parsed; a switched-off server is not started, so it costs nothing to measure.\n` +
+                `Switch one back on, declare one, or point at a different config: mcp-context-cost audit --config <path/to/mcp.json>`);
         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` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-context-cost",
-  "version": "0.6.0",
+  "version": "0.8.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",