mcpcost 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ondřej Úlehla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# mcpcost
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/mcpcost)](https://www.npmjs.com/package/mcpcost) [![CI](https://github.com/ondraulehla/mcpcost/actions/workflows/ci.yml/badge.svg)](https://github.com/ondraulehla/mcpcost/actions/workflows/ci.yml) [![license](https://img.shields.io/npm/l/mcpcost)](LICENSE)
+
+**`top` for your MCP servers: how many tokens do their tool definitions cost before the first prompt?**
+
+mcpcost is the CLI of [mcpcost](https://github.com/ondraulehla/mcpcost), the board that probes every remote server in the official MCP registry. The board tells you about servers out there. mcpcost tells you about yours.
+
+Every MCP server you configure hands your agent its tool definitions at the start of each session. Those definitions are tokens, and you pay for them in every turn. This command starts each configured server, lists its tools and tells you what they cost.
+
+```
+$ npx mcpcost --config .mcp.json --tools 3
+
+mcpcost 0.2.0 · tool definitions your agent loads before the first prompt
+  .mcp.json
+
+  server      source     result               tools  tokens  of 200k
+  ──────────  ─────────  ───────────────────  ─────  ──────  ───────
+  filesystem  .mcp.json  alive                   14   1 650    0.8 %
+  everything  .mcp.json  alive                   13   1 075    0.5 %
+  deepwiki    .mcp.json  alive                    3     239    0.1 %
+  github      .mcp.json  needs auth (Bearer)
+  apify       .mcp.json  needs auth (Bearer)
+  ──────────  ─────────  ───────────────────  ─────  ──────  ───────
+  total                  3 of 5 measured         30   2 964    1.5 %
+
+  github: Streamable HTTP error: Error POSTing to endpoint: bad request: missing required Authorization header
+  apify: Streamable HTTP error: Error POSTing to endpoint: {"error":"invalid_token", ...
+
+  filesystem: most expensive tools
+        185  read_text_file
+        162  edit_file
+        148  search_files
+```
+
+That run measured this `.mcp.json`: the filesystem and everything reference servers over stdio, DeepWiki, the GitHub MCP and Apify over HTTP. Servers that need auth are reachable but not measured until you put the header in the config.
+
+It reads the config files of Claude Code (`.mcp.json`, `~/.claude.json`), Claude Desktop, Cursor, VS Code, Windsurf and Gemini CLI. Remote servers are probed over Streamable HTTP or SSE with the headers from your config. Local servers are started over stdio with the command, args and env from your config, the same way your client starts them.
+
+## Options
+
+```
+mcpcost [options]                 measure every server in the configs it can find
+mcpcost --config <file>           measure one config file (repeatable)
+mcpcost --url <url>               measure one remote server (repeatable)
+mcpcost --stdio "<command args>"  measure one local server (repeatable)
+
+--window <tokens>    context window for the percentages (default 200000)
+--budget <tokens>    exit with code 1 when the total is above this
+--tools <n>          list the n most expensive tools of each server
+--claude             exact counts from the Anthropic count_tokens endpoint (free, needs ANTHROPIC_API_KEY)
+--model <id>         model for --claude (default claude-opus-5-5)
+--timeout <ms>       per server (default 15000)
+--no-stdio           do not start local servers, only measure remote ones
+--json               machine-readable output
+```
+
+`--budget` makes it a CI check: commit your `.mcp.json`, run `npx mcpcost --budget 30000` in the pipeline, and a pull request that adds a 40 000-token server fails.
+
+## As an MCP server
+
+```json
+{ "mcpServers": { "mcpcost": { "command": "npx", "args": ["-y", "mcpcost", "mcp"] } } }
+```
+
+`mcpcost mcp` serves the same measurements over stdio, so an agent can check a server before it is added to a config. Four tools: `measure_server` (a remote URL or a local command, probed now), `measure_config` (every server in a config file), `lookup_server` and `search_servers` (the public board, which probes the whole registry daily). With `ANTHROPIC_API_KEY` in the environment the counts are exact. The repository's `Dockerfile` builds the same server for containers.
+
+## How tokens are counted
+
+Two ways.
+
+**Exact, with `--claude`.** mcpcost asks the Anthropic `count_tokens` endpoint. It sends one request with the server's tools and one request without them. The difference is what the tools cost, as the model sees them. The endpoint is free and calls no model. It needs `ANTHROPIC_API_KEY` in the environment. You get two numbers: the tools as published, and the tools as Claude Code names them (`mcp__<server>__<tool>`, where `<server>` is the key in your config). The default model is `claude-opus-5-5`. `--budget` then applies to the exact total.
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-… npx mcpcost --claude
+```
+
+**Estimate, by default.** Each tool is serialised as compact JSON with `name`, `description` and `input_schema`, and counted with the `o200k_base` tokenizer. No key is needed. The exact Claude count is about 1.9 times this estimate at the median, because Claude renders schemas in its own format and tokenises prose in its own way. The estimate is the same for every server, so servers stay comparable.
+
+The [public board](https://mcpcost.ulehla.dev) shows both numbers for every remote server in the official registry.
+
+## Library
+
+```ts
+import { probeRemote, probeStdio, discoverConfigs } from 'mcpcost';
+
+const r = await probeRemote(
+  { url: 'https://mcp.deepwiki.com/mcp', type: 'streamable-http' },
+  { claude: { apiKey: process.env.ANTHROPIC_API_KEY!, serverName: 'deepwiki' } } // optional
+);
+r.status;                   // 'ok' | 'auth' | 'payment' | 'not_found' | 'timeout' | ...
+r.toolsTokens;              // 239, the o200k_base estimate
+r.claude?.tokens;           // 438, exact for claude-opus-5-5
+r.claude?.tokensClaudeCode; // 462, with the mcp__deepwiki__ prefix
+r.tools;                    // [{ name, tokens, bytes, descriptionChars }, ...]
+```
+
+## Licence
+
+MIT

package/dist/claude.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Exact token counts from the Anthropic count_tokens endpoint. The endpoint is
+ * free and has its own rate limit. Nothing here calls a model.
+ *
+ * Method: count a request that holds one tiny marker tool plus the server's
+ * tools, and subtract the count of the same request with only the marker tool.
+ * Both requests carry the tool-use system prompt, so it cancels out. What is
+ * left is exactly what the server's tool definitions add, as this model
+ * renders and tokenizes them. No constants from the docs are needed.
+ *
+ * This file has no Node dependencies, so the Worker can import it too.
+ */
+import type { ToolLike } from './payload.js';
+export declare const CLAUDE_MODEL = "claude-opus-5-5";
+export declare const COUNT_TOKENS_URL = "https://api.anthropic.com/v1/messages/count_tokens";
+export interface ClaudeCountOptions {
+    apiKey: string;
+    /** Model id. Default claude-opus-5-5. */
+    model?: string;
+    /** Prefix for every tool name, for example `mcp__github__` as Claude Code sends them. */
+    prefix?: string;
+    fetch?: typeof fetch;
+    /** Retries on 429 and 5xx. Default 5. */
+    retries?: number;
+    /** Timeout for one request. Default 30 s. */
+    timeoutMs?: number;
+    /** Shared rate limiter from createLimiter, for many servers in one process. */
+    limiter?: Limiter;
+}
+export interface Limiter {
+    /** Resolves when the next request may start. */
+    wait(): Promise<void>;
+}
+/**
+ * Lets at most `rpm` requests start in any sliding minute. Organisations have a
+ * count_tokens limit of their own (100 a minute on a small one), and a 429
+ * costs more time than waiting for a slot.
+ */
+export declare function createLimiter(rpm: number): Limiter;
+export interface ClaudeCount {
+    model: string;
+    /** Tokens the tool definitions add to a request. */
+    tokens: number;
+}
+/** The answer when Claude refuses to count, for example on a schema it does not accept. */
+export declare class ClaudeCountError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** The tool list as the Messages API takes it. Names are made safe and unique, because the API refuses duplicates. */
+export declare function toApiTools(tools: ToolLike[], prefix?: string): Array<{
+    name: string;
+    description: string;
+    input_schema: unknown;
+}>;
+/** Exact tokens these tool definitions add to a request for this model. */
+export declare function countClaudeTokens(tools: ToolLike[], options: ClaudeCountOptions): Promise<ClaudeCount>;
+/** Claude Code names a tool mcp__<server>__<tool>. The server part is the key in the config. */
+export declare function claudeCodePrefix(serverName: string): string;
+/** Exact counts for a server: as published, and as Claude Code sends them. */
+export declare function countForServer(tools: ToolLike[], serverName: string, options: ClaudeCountOptions): Promise<{
+    model: string;
+    tokens: number;
+    tokensClaudeCode: number;
+}>;

package/dist/claude.js

@@ -0,0 +1,118 @@
+export const CLAUDE_MODEL = 'claude-opus-5-5';
+export const COUNT_TOKENS_URL = 'https://api.anthropic.com/v1/messages/count_tokens';
+/**
+ * Lets at most `rpm` requests start in any sliding minute. Organisations have a
+ * count_tokens limit of their own (100 a minute on a small one), and a 429
+ * costs more time than waiting for a slot.
+ */
+export function createLimiter(rpm) {
+    const starts = [];
+    let chain = Promise.resolve();
+    return {
+        wait() {
+            chain = chain.then(async () => {
+                for (;;) {
+                    const now = Date.now();
+                    while (starts.length && now - starts[0] >= 60_000)
+                        starts.shift();
+                    if (starts.length < rpm)
+                        break;
+                    await new Promise((r) => setTimeout(r, starts[0] + 60_000 - now + 20));
+                }
+                starts.push(Date.now());
+            });
+            return chain;
+        }
+    };
+}
+/** The answer when Claude refuses to count, for example on a schema it does not accept. */
+export class ClaudeCountError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'ClaudeCountError';
+    }
+}
+const MARKER = { name: 'mcp_pulse_marker', description: '', input_schema: { type: 'object', properties: {} } };
+const MESSAGES = [{ role: 'user', content: 'hi' }];
+const safeName = (name) => name.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 128) || 'tool';
+/** The tool list as the Messages API takes it. Names are made safe and unique, because the API refuses duplicates. */
+export function toApiTools(tools, prefix = '') {
+    const seen = new Map();
+    return tools.map((t) => {
+        let name = safeName(prefix + t.name);
+        const n = seen.get(name) ?? 0;
+        seen.set(name, n + 1);
+        if (n)
+            name = `${name.slice(0, 124)}_${n + 1}`;
+        return {
+            name,
+            description: t.description ?? '',
+            input_schema: t.inputSchema ?? { type: 'object', properties: {} }
+        };
+    });
+}
+async function countRequest(body, options) {
+    const doFetch = options.fetch ?? fetch;
+    const retries = options.retries ?? 5;
+    for (let attempt = 0;; attempt++) {
+        if (options.limiter)
+            await options.limiter.wait();
+        let res;
+        try {
+            res = await doFetch(COUNT_TOKENS_URL, {
+                method: 'POST',
+                headers: { 'x-api-key': options.apiKey, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(options.timeoutMs ?? 30_000)
+            });
+        }
+        catch (e) {
+            if (attempt < retries) {
+                await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                continue;
+            }
+            throw new ClaudeCountError(e instanceof Error ? e.message : String(e), 0);
+        }
+        if ((res.status === 429 || res.status >= 500) && attempt < retries) {
+            const wait = Number(res.headers.get('retry-after')) * 1000 || 1500 * 2 ** attempt;
+            await new Promise((r) => setTimeout(r, Math.min(wait, 30_000)));
+            continue;
+        }
+        const json = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new ClaudeCountError((json.error?.message ?? `HTTP ${res.status}`).slice(0, 300), res.status);
+        return json.input_tokens ?? 0;
+    }
+}
+const baselines = new Map();
+/** Tokens of the message plus the marker tool, once per model and process. */
+function baseline(model, options) {
+    let p = baselines.get(model);
+    if (!p) {
+        p = countRequest({ model, messages: MESSAGES, tools: [MARKER] }, options);
+        p.catch(() => baselines.delete(model));
+        baselines.set(model, p);
+    }
+    return p;
+}
+/** Exact tokens these tool definitions add to a request for this model. */
+export async function countClaudeTokens(tools, options) {
+    const model = options.model ?? CLAUDE_MODEL;
+    if (!tools.length)
+        return { model, tokens: 0 };
+    const base = await baseline(model, options);
+    const withTools = await countRequest({ model, messages: MESSAGES, tools: [MARKER, ...toApiTools(tools, options.prefix)] }, options);
+    return { model, tokens: Math.max(0, withTools - base) };
+}
+/** Claude Code names a tool mcp__<server>__<tool>. The server part is the key in the config. */
+export function claudeCodePrefix(serverName) {
+    const slug = (serverName.split('/').pop() ?? serverName).replace(/[^a-zA-Z0-9_-]/g, '_');
+    return `mcp__${slug}__`;
+}
+/** Exact counts for a server: as published, and as Claude Code sends them. */
+export async function countForServer(tools, serverName, options) {
+    const [plain, cc] = await Promise.all([countClaudeTokens(tools, options), countClaudeTokens(tools, { ...options, prefix: claudeCodePrefix(serverName) })]);
+    return { model: plain.model, tokens: plain.tokens, tokensClaudeCode: cc.tokens };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { homedir } from 'node:os';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { discoverConfigs, readConfigFile } from './configs.js';
+import { probeRemote, VERSION } from './probe.js';
+import { probeStdio } from './stdio.js';
+import { TOKENIZER } from './tokens.js';
+const HELP = `mcpcost ${VERSION}: how many tokens do your MCP servers cost before the first prompt?
+
+Usage
+  mcpcost [options]                 measure every server in the configs it can find
+  mcpcost mcp                       serve the same measurements as an MCP server over stdio
+  mcpcost --config <file>           measure one config file (repeatable)
+  mcpcost --url <url>               measure one remote server (repeatable)
+  mcpcost --stdio "<command args>"  measure one local server (repeatable)
+
+Options
+  --window <tokens>    context window for the percentages (default 200000)
+  --budget <tokens>    exit with code 1 when the total is above this
+  --tools <n>          list the n most expensive tools of each server (default 0)
+  --claude             exact counts from the Anthropic count_tokens endpoint (free, needs ANTHROPIC_API_KEY)
+  --model <id>         model for --claude (default claude-opus-5-5)
+  --timeout <ms>       per server (default 15000)
+  --no-stdio           do not start local servers, only measure remote ones
+  --json               machine-readable output
+  --help, --version
+
+Config files it looks for: .mcp.json, ~/.claude.json, Claude Desktop, Cursor, VS Code, Windsurf, Gemini CLI.
+Without --claude, tokens are an estimate: ${TOKENIZER} over name, description and input schema of each tool.
+With --claude, the exact count for the model is shown too, as published and with the Claude Code mcp__<server>__ prefix.
+The same probe runs the public board at https://mcpcost.ulehla.dev`;
+export async function main(argv) {
+    if (argv[0] === 'mcp') {
+        const { serveStdio } = await import('./mcp.js');
+        await serveStdio();
+        return new Promise(() => undefined);
+    }
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            config: { type: 'string', multiple: true },
+            url: { type: 'string', multiple: true },
+            stdio: { type: 'string', multiple: true },
+            window: { type: 'string', default: '200000' },
+            budget: { type: 'string' },
+            tools: { type: 'string', default: '0' },
+            timeout: { type: 'string', default: '15000' },
+            'no-stdio': { type: 'boolean', default: false },
+            claude: { type: 'boolean', default: false },
+            model: { type: 'string' },
+            json: { type: 'boolean', default: false },
+            help: { type: 'boolean', default: false },
+            version: { type: 'boolean', default: false }
+        },
+        allowPositionals: true
+    });
+    if (values.help) {
+        console.log(HELP);
+        return 0;
+    }
+    if (values.version) {
+        console.log(VERSION);
+        return 0;
+    }
+    const window = Number(values.window) || 200_000;
+    const timeoutMs = Number(values.timeout) || 15_000;
+    const topTools = Number(values.tools) || 0;
+    const budget = values.budget ? Number(values.budget) : undefined;
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (values.claude && !apiKey) {
+        console.error('--claude needs ANTHROPIC_API_KEY in the environment. Only the free count_tokens endpoint is called.');
+        return 2;
+    }
+    const claudeFor = (serverName) => (values.claude && apiKey ? { apiKey, model: values.model, serverName } : undefined);
+    const servers = [];
+    const sources = [];
+    if (values.config?.length) {
+        for (const file of values.config) {
+            const cfg = await readConfigFile(file, 'config');
+            if (!cfg) {
+                console.error(`cannot read ${file}`);
+                return 2;
+            }
+            servers.push(...cfg.servers);
+            sources.push(file);
+        }
+    }
+    for (const url of values.url ?? []) {
+        servers.push({ name: url, source: 'command line', kind: 'remote', url, type: /\/sse\/?$/.test(url) ? 'sse' : 'streamable-http' });
+    }
+    for (const line of values.stdio ?? []) {
+        const [command, ...args] = line.trim().split(/\s+/);
+        servers.push({ name: line, source: 'command line', kind: 'stdio', command, args });
+    }
+    if (!values.config?.length && !values.url?.length && !values.stdio?.length) {
+        const found = await discoverConfigs();
+        for (const cfg of found) {
+            servers.push(...cfg.servers);
+            sources.push(`${cfg.path} (${cfg.client}, ${cfg.servers.length})`);
+        }
+        if (!found.length) {
+            console.error('No MCP config found. Pass --config, --url or --stdio. See --help.');
+            return 2;
+        }
+    }
+    const rows = [];
+    const running = [];
+    for (const s of servers) {
+        const row = { name: s.name, source: s.source, kind: s.kind, target: s.kind === 'remote' ? s.url : [s.command, ...(s.args ?? [])].join(' ') };
+        rows.push(row);
+        if (s.disabled) {
+            row.skipped = 'disabled in config';
+            continue;
+        }
+        if (s.kind === 'stdio' && values['no-stdio']) {
+            row.skipped = 'local server, --no-stdio';
+            continue;
+        }
+        const job = s.kind === 'remote'
+            ? probeRemote({ url: s.url, type: s.type ?? 'streamable-http' }, { timeoutMs, headers: s.headers, claude: claudeFor(s.name) })
+            : probeStdio({ command: s.command, args: s.args, env: s.env, cwd: s.cwd }, { timeoutMs, claude: claudeFor(s.name) });
+        running.push(job.then((r) => void (row.result = r)));
+    }
+    await Promise.all(running);
+    const measured = rows.filter((r) => r.result?.status === 'ok');
+    const exact = values.claude;
+    /** The number a row is ranked and budgeted by: the exact Claude count with --claude, else the estimate. */
+    const cost = (r) => (exact ? r.result?.claude?.tokens : r.result?.toolsTokens);
+    const total = measured.reduce((a, r) => a + (cost(r) ?? 0), 0);
+    const totalEstimate = measured.reduce((a, r) => a + (r.result?.toolsTokens ?? 0), 0);
+    const totalTools = measured.reduce((a, r) => a + (r.result?.toolCount ?? 0), 0);
+    const model = measured.find((r) => r.result?.claude?.model)?.result?.claude?.model ?? values.model ?? 'claude-opus-5-5';
+    rows.sort((a, b) => (cost(b) ?? -1) - (cost(a) ?? -1));
+    if (values.json) {
+        console.log(JSON.stringify({
+            version: VERSION,
+            tokenizer: TOKENIZER,
+            exact: exact ? { endpoint: 'count_tokens', model } : null,
+            window,
+            sources,
+            total: { servers: measured.length, tools: totalTools, tokens: total, tokensEstimate: totalEstimate, shareOfWindow: total / window },
+            servers: rows.map((r) => ({
+                name: r.name,
+                source: r.source,
+                kind: r.kind,
+                target: r.target,
+                skipped: r.skipped,
+                status: r.result?.status,
+                error: r.result?.error,
+                toolCount: r.result?.toolCount,
+                toolsTokens: r.result?.toolsTokens,
+                claudeTokens: r.result?.claude?.tokens,
+                claudeTokensClaudeCode: r.result?.claude?.tokensClaudeCode,
+                claudeError: r.result?.claude?.error,
+                shareOfWindow: cost(r) != null ? cost(r) / window : undefined,
+                initializeMs: r.result?.latencyMs.initialize,
+                toolsListMs: r.result?.latencyMs.toolsList,
+                protocolVersion: r.result?.protocolVersion,
+                tools: topTools > 0 ? r.result?.tools?.slice().sort((a, b) => b.tokens - a.tokens).slice(0, topTools) : undefined
+            }))
+        }, null, 2));
+    }
+    else {
+        console.log(render(rows, { window, total, totalTools, topTools, sources, exact, model, cost }));
+    }
+    if (budget !== undefined && total > budget) {
+        console.error(`\nOver budget: ${fmt(total)} tokens, the budget is ${fmt(budget)}.`);
+        return 1;
+    }
+    return 0;
+}
+function fmt(n) {
+    if (n === undefined || n === null)
+        return '';
+    return n.toLocaleString('en-US').replace(/,/g, ' ');
+}
+function pct(n, window) {
+    const p = (n / window) * 100;
+    return p < 0.1 && n > 0 ? '<0.1 %' : `${p.toFixed(1)} %`;
+}
+function shortSource(source) {
+    return source.replace(homedir(), '~').replace(/ \(project .*\)$/, ' (project)');
+}
+function statusText(r) {
+    if (r.skipped)
+        return `skipped: ${r.skipped}`;
+    const s = r.result?.status;
+    if (!s)
+        return '';
+    if (s === 'ok')
+        return 'alive';
+    if (s === 'auth')
+        return `needs auth${r.result?.authScheme ? ` (${r.result.authScheme})` : ''}`;
+    if (s === 'payment')
+        return 'payment required';
+    if (s === 'newer_protocol')
+        return 'newer protocol than this SDK';
+    if (s === 'not_found')
+        return r.kind === 'stdio' ? 'command not found' : 'not found';
+    return s.replace('_', ' ');
+}
+function render(rows, o) {
+    const lines = [];
+    lines.push(`mcpcost ${VERSION} · tool definitions your agent loads before the first prompt`);
+    if (o.sources.length)
+        lines.push(o.sources.map((s) => `  ${shortSource(s)}`).join('\n'));
+    lines.push('');
+    if (!rows.length) {
+        lines.push('  No servers in these configs.');
+        return lines.join('\n');
+    }
+    const table = [
+        o.exact
+            ? ['server', 'source', 'result', 'tools', 'claude', 'claude code', 'o200k', `of ${Math.round(o.window / 1000)}k`]
+            : ['server', 'source', 'result', 'tools', 'tokens', `of ${Math.round(o.window / 1000)}k`]
+    ];
+    for (const r of rows) {
+        const ok = r.result?.status === 'ok';
+        const c = r.result?.claude;
+        table.push([
+            r.name.length > 28 ? r.name.slice(0, 27) + '…' : r.name,
+            shortSource(r.source).replace(/^.*\//, ''),
+            statusText(r),
+            ok ? fmt(r.result?.toolCount) : '',
+            ...(o.exact ? [ok ? (c?.tokens != null ? fmt(c.tokens) : c?.error ? 'refused' : '') : '', ok ? fmt(c?.tokensClaudeCode) : ''] : []),
+            ok ? fmt(r.result?.toolsTokens) : '',
+            ok && o.cost(r) != null ? pct(o.cost(r), o.window) : ''
+        ]);
+    }
+    const totalEstimate = rows.reduce((a, r) => a + (r.result?.status === 'ok' ? (r.result.toolsTokens ?? 0) : 0), 0);
+    const totalCc = rows.reduce((a, r) => a + (r.result?.claude?.tokensClaudeCode ?? 0), 0);
+    table.push([
+        'total', '', `${rows.filter((r) => r.result?.status === 'ok').length} of ${rows.length} measured`, fmt(o.totalTools),
+        ...(o.exact ? [fmt(o.total), fmt(totalCc)] : []),
+        fmt(totalEstimate), pct(o.total, o.window)
+    ]);
+    const widths = table[0].map((_, i) => Math.max(...table.map((row) => row[i].length)));
+    const right = new Set(table[0].map((_, i) => i).filter((i) => i >= 3));
+    const line = (row) => '  ' + row.map((cell, i) => (right.has(i) ? cell.padStart(widths[i]) : cell.padEnd(widths[i]))).join('  ').trimEnd();
+    lines.push(line(table[0]));
+    lines.push('  ' + widths.map((w) => '─'.repeat(w)).join('  '));
+    for (const row of table.slice(1, -1))
+        lines.push(line(row));
+    lines.push('  ' + widths.map((w) => '─'.repeat(w)).join('  '));
+    lines.push(line(table[table.length - 1]));
+    const failed = rows.filter((r) => r.result && r.result.status !== 'ok' && r.result.error);
+    if (failed.length) {
+        lines.push('');
+        for (const r of failed)
+            lines.push(`  ${r.name}: ${r.result.error.split('\n')[0].slice(0, 160)}`);
+    }
+    if (o.topTools > 0) {
+        for (const r of rows) {
+            if (!r.result?.tools?.length)
+                continue;
+            lines.push('', `  ${r.name}: most expensive tools`);
+            for (const t of [...r.result.tools].sort((a, b) => b.tokens - a.tokens).slice(0, o.topTools)) {
+                lines.push(`    ${fmt(t.tokens).padStart(7)}  ${t.name}`);
+            }
+        }
+    }
+    if (o.exact) {
+        lines.push('', `  claude: exact count from the Anthropic count_tokens endpoint for ${o.model}. claude code: the same with the mcp__<server>__ prefix on each tool name.`);
+        lines.push(`  o200k: the estimate without a key, ${TOKENIZER} over name, description and input schema. "refused": the endpoint did not accept the schema.`);
+        const refused = rows.filter((r) => r.result?.claude?.error);
+        for (const r of refused)
+            lines.push(`  ${r.name}: ${r.result.claude.error.slice(0, 160)}`);
+    }
+    else {
+        lines.push('', `  Estimated with ${TOKENIZER} over name, description and input schema of each tool. Claude counts about 1.9 times this. Add --claude for the exact count.`);
+    }
+    return lines.join('\n');
+}
+function invokedDirectly() {
+    if (!process.argv[1])
+        return false;
+    try {
+        // The bin is a symlink in node_modules/.bin, so compare real paths.
+        return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(2);
+    });
+}

package/dist/configs.d.ts

@@ -0,0 +1,41 @@
+import type { RemoteTransport } from './types.js';
+/** One server as a client config describes it. */
+export interface ConfiguredServer {
+    name: string;
+    /** Where it came from: file path, plus the scope inside the file when there is one. */
+    source: string;
+    kind: 'remote' | 'stdio';
+    url?: string;
+    type?: RemoteTransport;
+    headers?: Record<string, string>;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    disabled?: boolean;
+}
+export interface ConfigFile {
+    path: string;
+    /** The client that owns the file. */
+    client: string;
+    servers: ConfiguredServer[];
+}
+export interface DiscoverOptions {
+    cwd?: string;
+    home?: string;
+    platform?: NodeJS.Platform;
+    env?: Record<string, string | undefined>;
+}
+/** Expands ${VAR} and ${VAR:-default} the way Claude Code does in .mcp.json. */
+export declare function expand(value: string, env: Record<string, string | undefined>): string;
+/** Normalises one `{ name: {...} }` map of servers. Accepts the shapes Claude, Cursor, Windsurf and VS Code write. */
+export declare function normalizeServers(map: Record<string, unknown> | undefined, source: string, env?: Record<string, string | undefined>): ConfiguredServer[];
+/** Parses one config file of a known client. Returns null when the file is missing or not JSON. */
+export declare function readConfigFile(file: string, client: string, options?: DiscoverOptions): Promise<ConfigFile | null>;
+/** The places the common clients keep their MCP config. */
+export declare function knownConfigPaths(options?: DiscoverOptions): Array<{
+    path: string;
+    client: string;
+}>;
+/** Reads every known config file that exists. */
+export declare function discoverConfigs(options?: DiscoverOptions): Promise<ConfigFile[]>;