context-xray 0.1.0

package/dist/report/terminal.js

@@ -0,0 +1,105 @@
+const useColor = !process.env['NO_COLOR'] && (process.env['FORCE_COLOR'] === '1' || process.stdout.isTTY === true);
+const c = {
+    reset: useColor ? '\x1b[0m' : '',
+    dim: useColor ? '\x1b[2m' : '',
+    bold: useColor ? '\x1b[1m' : '',
+    red: useColor ? '\x1b[31m' : '',
+    green: useColor ? '\x1b[32m' : '',
+    yellow: useColor ? '\x1b[33m' : '',
+    cyan: useColor ? '\x1b[36m' : '',
+    gray: useColor ? '\x1b[90m' : '',
+};
+const CONTEXT_WINDOW = 200_000;
+const fmt = (n) => n.toLocaleString('en-US');
+/** Visible width, so ANSI codes do not break the column maths. */
+function width(s) {
+    return s.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+function pad(s, to) {
+    const w = width(s);
+    return w >= to ? s : s + ' '.repeat(to - w);
+}
+function padLeft(s, to) {
+    const w = width(s);
+    return w >= to ? s : ' '.repeat(to - w) + s;
+}
+function bar(fraction, widthChars = 18) {
+    const filled = Math.round(Math.max(0, Math.min(1, fraction)) * widthChars);
+    return '#'.repeat(filled) + '.'.repeat(widthChars - filled);
+}
+/** "Claude Desktop, Cursor" -- host names only, config paths live in detail. */
+function hostsOf(w) {
+    const hosts = new Set(w.spec.sources.map((s) => s.split(' (')[0] ?? s));
+    return [...hosts].join(', ');
+}
+function tokensLabel(w) {
+    return `${w.method === 'counted' ? '' : '~'}${fmt(w.taxTokens)}`;
+}
+export function renderTerminal(report, top = 3) {
+    const lines = [];
+    const measured = report.servers.filter((s) => s.ok);
+    const broken = report.servers.filter((s) => !s.ok);
+    const ranked = [...measured].sort((a, b) => b.taxTokens - a.taxTokens);
+    const total = report.totalTaxTokens;
+    const approx = report.method === 'counted' ? '' : '~';
+    lines.push('');
+    lines.push(`  ${c.bold}context-xray${c.reset}  your MCP servers add ${c.bold}${approx}${fmt(total)} tokens${c.reset} to every request`);
+    const cfgs = report.configsSearched.length;
+    lines.push(`  ${c.gray}${cfgs} config${cfgs === 1 ? '' : 's'} searched, ${report.servers.length} server${report.servers.length === 1 ? '' : 's'} found, ${measured.length} measured${broken.length ? `, ${broken.length} failed` : ''}${c.reset}`);
+    lines.push('');
+    if (ranked.length > 0) {
+        lines.push(`  ${c.gray}${pad('rank', 6)}${pad('server', 22)}${pad('host', 18)}${padLeft('tools', 6)}${padLeft('tokens', 10)}${padLeft('share', 7)}${c.reset}`);
+        ranked.forEach((w, i) => {
+            const share = total > 0 ? w.taxTokens / total : 0;
+            const name = w.spec.name.length > 20 ? w.spec.name.slice(0, 19) + '…' : w.spec.name;
+            lines.push(`  ${pad(`#${i + 1}`, 6)}${pad(`${c.bold}${name}${c.reset}`, 22 + (c.bold.length + c.reset.length))}${pad(`${c.gray}${hostsOf(w).slice(0, 16)}${c.reset}`, 18 + (c.gray.length + c.reset.length))}${padLeft(String(w.toolCount), 6)}${padLeft(tokensLabel(w), 10)}${padLeft(`${Math.round(share * 100)}%`, 7)}  ${c.cyan}${bar(share)}${c.reset}`);
+        });
+        lines.push('');
+    }
+    // Per-server detail: the heaviest tools are where the trimming happens.
+    for (const w of ranked) {
+        if (w.tools.length === 0)
+            continue;
+        const info = w.serverInfo?.name ? `${w.serverInfo.name}${w.serverInfo.version ? ` v${w.serverInfo.version}` : ''}` : '';
+        lines.push(`  ${c.bold}${w.spec.name}${c.reset}  ${c.gray}${info}${info ? '  ' : ''}${w.toolCount} tools${w.instructionTokens ? `, instructions ${approx}${fmt(w.instructionTokens)} tok` : ''}${w.connectMs !== undefined ? `, connected in ${w.connectMs}ms` : ''}${c.reset}`);
+        for (const t of w.tools.slice(0, top)) {
+            lines.push(`    ${padLeft(fmt(t.tokens), 8)} tok  ${pad(t.name.slice(0, 40), 42)}${c.gray}desc ${fmt(t.descriptionTokens)}, schema ${fmt(t.schemaTokens)}${c.reset}`);
+        }
+        if (w.tools.length > top) {
+            const rest = w.tools.slice(top).reduce((s, t) => s + t.tokens, 0);
+            lines.push(`    ${padLeft(fmt(rest), 8)} tok  ${c.gray}… ${w.tools.length - top} more tools${c.reset}`);
+        }
+        lines.push('');
+    }
+    for (const w of broken) {
+        lines.push(`  ${c.red}failed${c.reset}  ${c.bold}${w.spec.name}${c.reset}  ${c.gray}${w.error}${c.reset}`);
+    }
+    if (broken.length)
+        lines.push('');
+    // The verdict block: window share and money.
+    const windowShare = total / CONTEXT_WINDOW;
+    const monthlyTokens = total * report.options.requestsPerDay * 30;
+    const monthlyUsd = (monthlyTokens / 1_000_000) * report.options.pricePerMTok;
+    lines.push(`  ${c.gray}${'-'.repeat(72)}${c.reset}`);
+    lines.push(`  ${c.bold}${approx}${fmt(total)} tokens${c.reset} on every request = ${c.bold}${(windowShare * 100).toFixed(1)}%${c.reset} of a ${fmt(CONTEXT_WINDOW)} context window, before you type a word`);
+    lines.push(`  ${c.gray}at ${fmt(report.options.requestsPerDay)} requests/day and $${report.options.pricePerMTok.toFixed(2)}/MTok input: ${c.reset}${c.bold}${approx}$${monthlyUsd.toFixed(monthlyUsd >= 100 ? 0 : 2)}/month${c.reset}${c.gray} of uncached input spend${c.reset}`);
+    if (report.method !== 'counted') {
+        lines.push(`  ${c.gray}estimated without a tokenizer; set ANTHROPIC_API_KEY and pass --precise for exact counts${c.reset}`);
+    }
+    // Advice only when there is something to act on.
+    const advice = [];
+    if (windowShare > 0.1 && ranked.length > 1) {
+        advice.push(`over 10% of the window goes to tool definitions -- disable the servers you are not using today (${ranked[0].spec.name} alone is ${Math.round(((ranked[0].taxTokens) / total) * 100)}%)`);
+    }
+    const fatTool = ranked.flatMap((w) => w.tools.map((t) => ({ server: w.spec.name, t }))).find((x) => x.t.tokens > 600);
+    if (fatTool) {
+        advice.push(`${fatTool.server}'s "${fatTool.t.name}" costs ${fmt(fatTool.t.tokens)} tokens by itself -- a tool description is a prompt you pay for on every request`);
+    }
+    if (advice.length > 0) {
+        lines.push('');
+        for (const a of advice)
+            lines.push(`  ${c.yellow}!${c.reset} ${a}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/types.d.ts

@@ -0,0 +1,88 @@
+export interface ToolDef {
+    name: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+    outputSchema?: JsonSchema;
+    annotations?: Record<string, unknown>;
+    title?: string;
+}
+export interface JsonSchema {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema | JsonSchema[];
+    enum?: unknown[];
+    const?: unknown;
+    description?: string;
+    additionalProperties?: boolean | JsonSchema;
+    [k: string]: unknown;
+}
+/** One MCP server as found in a host config file (or given on the CLI). */
+export interface ServerSpec {
+    name: string;
+    kind: 'stdio' | 'http';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    /** Which config files declared this server (a server can appear in several). */
+    sources: string[];
+    /** Set when the entry cannot be launched (e.g. it needs interactive input). */
+    unlaunchable?: string;
+}
+/** The token weight of a single tool definition, as the host serialises it. */
+export interface ToolWeight {
+    name: string;
+    /** Whole definition: name + description + inputSchema. */
+    tokens: number;
+    descriptionTokens: number;
+    schemaTokens: number;
+}
+export interface ServerWeight {
+    spec: ServerSpec;
+    ok: boolean;
+    /** Why the measurement failed, when it did. */
+    error?: string;
+    connectMs?: number;
+    serverInfo?: {
+        name?: string;
+        version?: string;
+    } | null;
+    protocolVersion?: string | null;
+    tools: ToolWeight[];
+    toolCount: number;
+    resourceCount: number;
+    promptCount: number;
+    /** Sum of all tool-definition tokens: the per-request tax this server charges. */
+    toolTokens: number;
+    /** Tokens in the server's `instructions` string, which hosts also inject. */
+    instructionTokens: number;
+    /** toolTokens + instructionTokens. */
+    taxTokens: number;
+    /** 'estimate' (chars-based) or 'counted' (Anthropic count_tokens). */
+    method: 'estimate' | 'counted';
+}
+export interface XrayOptions {
+    timeoutMs: number;
+    /** Use the Anthropic count_tokens API when a key is available. */
+    precise: boolean;
+    apiKey?: string;
+    /** Assumed requests per day for the cost projection. */
+    requestsPerDay: number;
+    /** $ per million input tokens for the cost projection. */
+    pricePerMTok: number;
+    /** How many tools to show per server in the report. */
+    top: number;
+    concurrency: number;
+}
+export interface XrayReport {
+    servers: ServerWeight[];
+    /** Sum of taxTokens across servers that measured OK. */
+    totalTaxTokens: number;
+    method: 'estimate' | 'counted' | 'mixed';
+    options: Pick<XrayOptions, 'requestsPerDay' | 'pricePerMTok'>;
+    configsSearched: string[];
+    durationMs: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/weigh.d.ts

@@ -0,0 +1,5 @@
+import type { ServerSpec, ServerWeight, XrayOptions } from './types.js';
+/** Connect to one server and measure what it adds to every request. */
+export declare function weighServer(spec: ServerSpec, options: XrayOptions): Promise<ServerWeight>;
+/** Weigh every server with bounded concurrency, preserving input order. */
+export declare function weighAll(specs: ServerSpec[], options: XrayOptions): Promise<ServerWeight[]>;

package/dist/weigh.js

@@ -0,0 +1,126 @@
+import { McpClient, StdioTransport, HttpTransport } from './client/index.js';
+import { estimateTokens, countToolTokens, wireFormat } from './estimate.js';
+function buildTransport(spec) {
+    if (spec.kind === 'http') {
+        return new HttpTransport({ url: spec.url, headers: spec.headers });
+    }
+    return new StdioTransport({
+        command: spec.command,
+        args: spec.args ?? [],
+        env: spec.env,
+        cwd: spec.cwd,
+    });
+}
+function weighTool(tool) {
+    const whole = JSON.stringify(wireFormat(tool));
+    const description = tool.description ?? '';
+    const schema = JSON.stringify(tool.inputSchema ?? {});
+    return {
+        name: tool.name ?? '(unnamed)',
+        tokens: estimateTokens(whole),
+        descriptionTokens: estimateTokens(description),
+        schemaTokens: estimateTokens(schema),
+    };
+}
+const failed = (spec, error) => ({
+    spec,
+    ok: false,
+    error,
+    tools: [],
+    toolCount: 0,
+    resourceCount: 0,
+    promptCount: 0,
+    toolTokens: 0,
+    instructionTokens: 0,
+    taxTokens: 0,
+    method: 'estimate',
+});
+/** Connect to one server and measure what it adds to every request. */
+export async function weighServer(spec, options) {
+    if (spec.unlaunchable)
+        return failed(spec, `not launched: ${spec.unlaunchable}`);
+    const transport = buildTransport(spec);
+    const client = new McpClient(transport, options.timeoutMs);
+    try {
+        await client.start();
+    }
+    catch (e) {
+        return failed(spec, e.message);
+    }
+    let handshake;
+    const t0 = Date.now();
+    try {
+        handshake = await client.initialize();
+    }
+    catch (e) {
+        await client.close();
+        const stderrTail = transport.stderr.slice(-3).join(' | ');
+        return failed(spec, `${e.message}${stderrTail ? ` -- stderr: ${stderrTail}` : ''}`);
+    }
+    const connectMs = Date.now() - t0;
+    if (handshake.raw.error) {
+        await client.close();
+        return failed(spec, `initialize failed: ${handshake.raw.error.code} ${handshake.raw.error.message}`);
+    }
+    client.notifyInitialized();
+    const { tools } = await client.listTools().catch(() => ({ tools: [] }));
+    const resources = await client.listAll('resources/list', 'resources').then((r) => r.items).catch(() => []);
+    const prompts = await client.listAll('prompts/list', 'prompts').then((r) => r.items).catch(() => []);
+    const instructions = typeof handshake.raw.result?.['instructions'] === 'string'
+        ? handshake.raw.result['instructions']
+        : '';
+    const toolWeights = tools.map(weighTool).sort((a, b) => b.tokens - a.tokens);
+    let toolTokens = toolWeights.reduce((sum, t) => sum + t.tokens, 0);
+    let method = 'estimate';
+    // Ground truth when asked for and possible. The per-tool split stays an
+    // estimate (the API prices the whole array), but the headline number -- the
+    // per-request tax -- becomes exact, scaled through the individual tools so
+    // the split still adds up.
+    if (options.precise && options.apiKey && tools.length > 0) {
+        try {
+            const counted = await countToolTokens(options.apiKey, tools);
+            if (counted > 0 && toolTokens > 0) {
+                const scale = counted / toolTokens;
+                for (const t of toolWeights)
+                    t.tokens = Math.round(t.tokens * scale);
+                toolTokens = counted;
+                method = 'counted';
+            }
+        }
+        catch {
+            // The estimate still stands; precision is an upgrade, not a requirement.
+        }
+    }
+    const instructionTokens = estimateTokens(instructions);
+    await client.close();
+    return {
+        spec,
+        ok: true,
+        connectMs,
+        serverInfo: handshake.serverInfo,
+        protocolVersion: handshake.protocolVersion,
+        tools: toolWeights,
+        toolCount: tools.length,
+        resourceCount: resources.length,
+        promptCount: prompts.length,
+        toolTokens,
+        instructionTokens,
+        taxTokens: toolTokens + instructionTokens,
+        method,
+    };
+}
+/** Weigh every server with bounded concurrency, preserving input order. */
+export async function weighAll(specs, options) {
+    const results = new Array(specs.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(options.concurrency, specs.length)) }, async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= specs.length)
+                return;
+            results[i] = await weighServer(specs[i], options);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "context-xray",
+  "version": "0.1.0",
+  "description": "See what your MCP servers cost you. Measures the context-window tokens every configured MCP server injects into each request - before you type a word - across Claude Desktop, Claude Code, Cursor and VS Code. Zero dependencies.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "context-window",
+    "token-usage",
+    "token-cost",
+    "tokens",
+    "context",
+    "claude",
+    "claude-code",
+    "cursor",
+    "llm",
+    "ai-agents",
+    "cost",
+    "audit",
+    "cli",
+    "anthropic"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "context-xray": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Beeeeen/context-xray.git"
+  },
+  "homepage": "https://github.com/Beeeeen/context-xray#readme",
+  "bugs": {
+    "url": "https://github.com/Beeeeen/context-xray/issues"
+  },
+  "author": "Ben Yang <ben@yangjiawei.com>"
+}