mcp-context-cost 0.15.0 → 0.16.0

package/README.md

@@ -294,7 +294,7 @@ answers a question no client asks: **what did this server cost last month?**
 [results/regressions.md](results/regressions.md) reports each server's most recent movement —
 dated to when it happened, separated into *shipped more tools* versus *same tools, rewritten*,
 and compared only within one isolation. The ecosystem ratchets upward: of the servers whose
-cost has moved at all, 11 moved up against 6 that moved down. Method:
+cost has moved at all, 13 moved up against 5 that moved down. Method:
 [cost movement](docs/METHODOLOGY.md#cost-movement).
 
 If you publish a server, the same measurement is available as a badge, so your users can see
@@ -400,8 +400,8 @@ repository), then in your README:
 A badge says what your server costs today; it does nothing about the release
 that adds 1,200 tokens to every user's context next month. Across the servers
 measured here most costs hold steady from sweep to sweep, but when a cost does
-move it usually moves up: the [movement report](results/regressions.md) has 11
-servers ratcheting upward against 6 that got cheaper, and none of those
+move it usually moves up: the [movement report](results/regressions.md) has 13
+servers ratcheting upward against 5 that got cheaper, and none of those
 maintainers had a check that would have said so first. `measure` takes the same
 gate flags `audit` does, so your own CI can be that check:
 
@@ -477,7 +477,7 @@ says as a whole is written up, dated, in
 [The State of MCP Context Cost](https://athakur3.github.io/mcp-context-cost/state-of-mcp-context-cost)
 (September 2026). Two
 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
+third of the list on Wednesdays, so every row comes round within three 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)

package/dist/audit/audit.js

@@ -16,7 +16,7 @@ import { METHODOLOGY_VERSION } from '../core/canonical.js';
 import { isCurrent } from '../core/divergence.js';
 import { SUGGEST_DESCRIPTION_PERCENTILE, suggestFor, } from '../core/tool-shape.js';
 import { identify } from '../core/capture-index.js';
-import { evaluateDeferral, PUBLISHED_WIRE_TO_CLIENT_RATIO, SHELL_SOURCE, } from './deferral.js';
+import { evaluateDeferral, BAND_PRECISION, PUBLISHED_WIRE_TO_CLIENT_RATIO, SHELL_SOURCE, } from './deferral.js';
 import { formatDiff, formatGate } from './diff.js';
 export const DEFAULT_CONTEXT_WINDOW = 200_000;
 const TRIM_TOOL_COUNT = 3;
@@ -493,6 +493,40 @@ function sharedMeasurementLines(d, skippedNames, consequence) {
     }
     return lines;
 }
+/**
+ * What the threshold below is a share *of*, said where the threshold is said.
+ *
+ * The setting is a percentage of the context window, so the token figure it
+ * resolves to is only as right as the window this audit assumed. That window is
+ * a property of the model the client runs, which no config file states and this
+ * audit therefore cannot read: it uses 200,000 unless `--context` overrides it.
+ * A model with a larger window puts the threshold proportionally higher, and a
+ * stack that clears a 20,000-token threshold does not clear a 100,000-token one.
+ *
+ * This is stated rather than silently assumed because the error has a direction.
+ * A window assumed too small makes the threshold too small, which pushes the
+ * verdict toward "at or above" — toward telling a reader their tool definitions
+ * are deferred, and therefore not charged, when the client's own larger
+ * threshold would have loaded every one of them up front. Of the two ways to be
+ * wrong here, that is the one that costs somebody tokens they were told they
+ * would not pay, so it does not get to be a footnote.
+ *
+ * Only threshold mode reaches this. The default defers everything at any size,
+ * where no window and no arithmetic enter the answer at all.
+ */
+function thresholdAssumptionLines(d) {
+    const share = d.thresholdShare ?? 0;
+    if (!(share > 0) || d.thresholdTokens === null || d.thresholdTokens === undefined)
+        return [];
+    const window = Math.round(d.thresholdTokens / share);
+    return [
+        `  That token figure assumes a ${n(window)}-token context window, which is a`,
+        '  property of the model in use and not of your config, so this audit cannot',
+        '  read it — pass --context to set it. A model with a larger window has a',
+        '  proportionally larger threshold, and the same stack can fall on either',
+        '  side of it depending on which model the client runs.',
+    ];
+}
 /** Where a threshold is in play, the unknown size is the whole verdict. */
 const SIDE_UNKNOWN = [
     '  either direction — which side of the threshold this stack falls on cannot be',
@@ -608,6 +642,7 @@ function deferralLines(d, skippedNames) {
     lines.push(`  ${d.client} defers tool definitions above a threshold here (${d.mechanism}):`);
     lines.push(`  ${settingPhrase(d)}, so deferral activates once the`);
     lines.push(`  definitions reach ${n(t)} tokens — ${pct(d.thresholdShare ?? 0)} of the context window.`);
+    lines.push(...thresholdAssumptionLines(d));
     lines.push(...postureSourceLines(d));
     const c = d.clientTokens;
     if (!c) {
@@ -662,7 +697,7 @@ function deferralLines(d, skippedNames) {
 /** "0.20×–1.92×", from whichever band the verdict was actually computed against. */
 function ratioBand(d) {
     const r = d.ratio ?? PUBLISHED_WIRE_TO_CLIENT_RATIO;
-    return `${r.low.toFixed(2)}×–${r.high.toFixed(2)}×`;
+    return `${r.low.toFixed(BAND_PRECISION)}×–${r.high.toFixed(BAND_PRECISION)}×`;
 }
 /** Human output. JSON output is the report object itself. */
 export function formatReport(report) {
@@ -861,8 +896,8 @@ export function formatReport(report) {
     }
     lines.push('');
     lines.push('These are wire tokens — what the server puts on the wire, counted with o200k_base. What your model is billed');
-    lines.push(`differs per provider: measured ratios run ${PUBLISHED_WIRE_TO_CLIENT_RATIO.low.toFixed(2)}×–` +
-        `${PUBLISHED_WIRE_TO_CLIENT_RATIO.high.toFixed(2)}× on Anthropic requests. See docs/METHODOLOGY.md §claude-divergence.`);
+    lines.push(`differs per provider: measured ratios run ${PUBLISHED_WIRE_TO_CLIENT_RATIO.low.toFixed(BAND_PRECISION)}×–` +
+        `${PUBLISHED_WIRE_TO_CLIENT_RATIO.high.toFixed(BAND_PRECISION)}× on Anthropic requests. See docs/METHODOLOGY.md §claude-divergence.`);
     return lines.map((l) => l.replace(/\s+$/, '')).join('\n');
 }
 /** Top-level tool list across every config — used by nothing yet, handy for --json consumers. */

package/dist/audit/deferral.d.ts

@@ -286,6 +286,41 @@ export interface WireToClientRatio {
  * level down. The fields are the record; `source` dates them.
  */
 export declare const PUBLISHED_WIRE_TO_CLIENT_RATIO: WireToClientRatio;
+/**
+ * The decimal places the band is published at.
+ *
+ * Not a display choice: it is the precision a snapshot of the band has to stay
+ * accurate to, because two numbers that round the same way decide the same
+ * above/below verdict against a client threshold, and two that do not, do not.
+ * The pages print the band to this many places (`published-stats.ts`) and
+ * `bandSnapshotProblem` judges a snapshot at the same width, so "still right"
+ * means the same thing in both places.
+ */
+export declare const BAND_PRECISION = 2;
+/**
+ * Is a snapshot of the band still an honest description of `derived`? The
+ * problem in words, or `null` when the snapshot may lag but does not mislead.
+ *
+ * Two callers, one rule. The suite asks it of `PUBLISHED_WIRE_TO_CLIENT_RATIO`
+ * against the run committed beside it. The release readiness gate asks it of
+ * the constant the *last release* shipped against the run on trunk — that band
+ * is what an installed package states offline, and nothing except cutting a
+ * release can move it, so a release being due is exactly what a finding there
+ * means.
+ *
+ * Deliberately not an equality check, and the first version of this rule was
+ * one: it demanded agreement and went red on the next bot commit, which had
+ * done nothing but measure a server for the first time. The run grows whenever
+ * a sweep reaches a new server, and the bot that commits it cannot edit a
+ * TypeScript constant. A snapshot is allowed to lag. It is not allowed to be
+ * wrong:
+ *
+ * - the **band** must still be right to the precision it is published at,
+ *   because it decides an above/below verdict against a client threshold;
+ * - the **count** must never exceed the run, because a snapshot claiming more
+ *   servers than were measured is a fabricated number rather than an old one.
+ */
+export declare function bandSnapshotProblem(snapshot: Pick<WireToClientRatio, 'low' | 'high' | 'servers'>, derived: Pick<WireToClientRatio, 'low' | 'high' | 'servers'>): string | null;
 /** Derive the band from a supplied divergence run, falling back to the published one. */
 export declare function wireToClientRatio(run?: DivergenceRun | null): WireToClientRatio;
 /** One measured server, as the deferral arithmetic needs it. */

package/dist/audit/deferral.js

@@ -258,6 +258,51 @@ export const PUBLISHED_WIRE_TO_CLIENT_RATIO = {
     servers: 86,
     source: 'the published claude-opus-5 divergence run',
 };
+/**
+ * The decimal places the band is published at.
+ *
+ * Not a display choice: it is the precision a snapshot of the band has to stay
+ * accurate to, because two numbers that round the same way decide the same
+ * above/below verdict against a client threshold, and two that do not, do not.
+ * The pages print the band to this many places (`published-stats.ts`) and
+ * `bandSnapshotProblem` judges a snapshot at the same width, so "still right"
+ * means the same thing in both places.
+ */
+export const BAND_PRECISION = 2;
+/**
+ * Is a snapshot of the band still an honest description of `derived`? The
+ * problem in words, or `null` when the snapshot may lag but does not mislead.
+ *
+ * Two callers, one rule. The suite asks it of `PUBLISHED_WIRE_TO_CLIENT_RATIO`
+ * against the run committed beside it. The release readiness gate asks it of
+ * the constant the *last release* shipped against the run on trunk — that band
+ * is what an installed package states offline, and nothing except cutting a
+ * release can move it, so a release being due is exactly what a finding there
+ * means.
+ *
+ * Deliberately not an equality check, and the first version of this rule was
+ * one: it demanded agreement and went red on the next bot commit, which had
+ * done nothing but measure a server for the first time. The run grows whenever
+ * a sweep reaches a new server, and the bot that commits it cannot edit a
+ * TypeScript constant. A snapshot is allowed to lag. It is not allowed to be
+ * wrong:
+ *
+ * - the **band** must still be right to the precision it is published at,
+ *   because it decides an above/below verdict against a client threshold;
+ * - the **count** must never exceed the run, because a snapshot claiming more
+ *   servers than were measured is a fabricated number rather than an old one.
+ */
+export function bandSnapshotProblem(snapshot, derived) {
+    const at = (n) => n.toFixed(BAND_PRECISION);
+    if (snapshot.servers > derived.servers) {
+        return `it is measured across ${snapshot.servers} servers where the run holds ${derived.servers}`;
+    }
+    if (at(snapshot.low) !== at(derived.low) || at(snapshot.high) !== at(derived.high)) {
+        return (`it states ${at(snapshot.low)}×–${at(snapshot.high)}× where the run derives ` +
+            `${at(derived.low)}×–${at(derived.high)}×`);
+    }
+    return null;
+}
 /** Derive the band from a supplied divergence run, falling back to the published one. */
 export function wireToClientRatio(run) {
     if (!run)

package/dist/sweep/published-stats.js

@@ -28,7 +28,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { DEFAULT_CONTEXT_WINDOW } from '../audit/audit.js';
-import { wireToClientRatio } from '../audit/deferral.js';
+import { BAND_PRECISION, wireToClientRatio } from '../audit/deferral.js';
 import { fieldSelectionShare, isCurrent } from '../core/divergence.js';
 import { sessionStartLoad } from '../core/session-start.js';
 import { isGood } from './harness-guard.js';
@@ -240,7 +240,11 @@ export const PAGE_CLAIMS = [
         // page-number guard: three numbers written by hand beside the two
         // sentences regen already kept true.
         template: 'measured at {f}×–{f}× across {n} servers)',
-        values: (s) => [s.claude.ratioMin.toFixed(2), s.claude.ratioMax.toFixed(2), fmt(s.claude.ratioServers)],
+        values: (s) => [
+            s.claude.ratioMin.toFixed(BAND_PRECISION),
+            s.claude.ratioMax.toFixed(BAND_PRECISION),
+            fmt(s.claude.ratioServers),
+        ],
     },
     {
         file: 'README.md',
@@ -358,13 +362,21 @@ export const PAGE_CLAIMS = [
         // different sources for one number is the drift this file exists to end, so
         // both pages state the run and the constant is guarded separately.
         template: 'band ({f}×–{f}×\nacross {n} servers)',
-        values: (s) => [s.claude.ratioMin.toFixed(2), s.claude.ratioMax.toFixed(2), fmt(s.claude.ratioServers)],
+        values: (s) => [
+            s.claude.ratioMin.toFixed(BAND_PRECISION),
+            s.claude.ratioMax.toFixed(BAND_PRECISION),
+            fmt(s.claude.ratioServers),
+        ],
     },
     {
         file: 'docs/METHODOLOGY.md',
         id: 'divergence:ratio-range',
         template: 'it ranged from {f}× to {f}× across the {n} servers in the run,',
-        values: (s) => [s.claude.ratioMin.toFixed(2), s.claude.ratioMax.toFixed(2), fmt(s.claude.ratioServers)],
+        values: (s) => [
+            s.claude.ratioMin.toFixed(BAND_PRECISION),
+            s.claude.ratioMax.toFixed(BAND_PRECISION),
+            fmt(s.claude.ratioServers),
+        ],
     },
     {
         file: 'docs/METHODOLOGY.md',

package/dist/sweep/shard.d.ts

@@ -4,7 +4,7 @@
  * `history.csv` only grows for servers that get measured again, and the only
  * scheduled measurement this project runs is the weekly self-badge job — one
  * server, `memory`. Every other row's trend line therefore stops at whatever
- * date a maintenance run last swept by hand. Re-measuring all 82 on a schedule
+ * date a maintenance run last swept by hand. Re-measuring every one of them on a schedule
  * is not the fix: a cold runner pays a full image pull and package install per
  * server with no cache volume to carry over, so the whole set does not fit in
  * one job's budget comfortably or cheaply.

package/dist/sweep/shard.js

@@ -4,7 +4,7 @@
  * `history.csv` only grows for servers that get measured again, and the only
  * scheduled measurement this project runs is the weekly self-badge job — one
  * server, `memory`. Every other row's trend line therefore stops at whatever
- * date a maintenance run last swept by hand. Re-measuring all 82 on a schedule
+ * date a maintenance run last swept by hand. Re-measuring every one of them on a schedule
  * is not the fix: a cold runner pays a full image pull and package install per
  * server with no cache volume to carry over, so the whole set does not fit in
  * one job's budget comfortably or cheaply.

package/package.json

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