mcpcost 0.0.0-stage → 0.3.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.3.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/auth-cli.d.ts

@@ -0,0 +1 @@
+export declare function authCommand(argv: string[]): Promise<number>;

package/dist/auth-cli.js

@@ -0,0 +1,194 @@
+/**
+ * `mcpcost auth`: the consent step for a server that needs auth, once, in the
+ * user's browser. The result lands in the credentials file; every later
+ * measurement of that URL uses it and refreshes the token on its own.
+ */
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { auth } from '@modelcontextprotocol/sdk/client/auth.js';
+import { credentialKey, createProvider, credentialsFor, defaultCredentialsPath, describeEntry, loadCredentials, saveCredentials } from './credentials.js';
+import { probeRemote } from './probe.js';
+const HELP = `mcpcost auth: store credentials for a server that needs auth
+
+Usage
+  mcpcost auth <url>                        OAuth: register, open the browser for the consent, store the tokens
+  mcpcost auth <url> --header "Name: value" store a static header instead (repeatable)
+  mcpcost auth --list                       what the credentials file holds, without the secrets
+  mcpcost auth <url> --remove               forget the entry for this URL
+
+Options
+  --credentials <file>   the credentials file (default ~/.mcpcost/credentials.json, or $MCPCOST_CREDENTIALS)
+  --scope <scope>        scope to ask for in the OAuth flow
+  --no-open              print the authorization URL, do not open the browser
+  --timeout <ms>         how long to wait for the consent (default 300000)
+
+After the consent the server is measured once with the new credentials, so you see that it works.
+The daily board uses the same file through its MCPCOST credentials table; see the README.`;
+function openBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url.replace(/&/g, '^&')]] : ['xdg-open', [url]];
+    try {
+        const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+        child.on('error', () => undefined);
+        child.unref();
+    }
+    catch {
+        // The URL is printed too.
+    }
+}
+/** Waits for one GET /callback?code=…&state=… on a local port. */
+function callbackServer(expectedState, timeoutMs) {
+    return new Promise((resolveServer, rejectServer) => {
+        let resolveCode = () => undefined;
+        let rejectCode = () => undefined;
+        const code = new Promise((res, rej) => {
+            resolveCode = res;
+            rejectCode = rej;
+        });
+        const server = createServer((req, res) => {
+            const u = new URL(req.url ?? '/', 'http://127.0.0.1');
+            if (u.pathname !== '/callback') {
+                res.writeHead(404).end();
+                return;
+            }
+            const error = u.searchParams.get('error');
+            const received = u.searchParams.get('code');
+            const state = u.searchParams.get('state');
+            res.setHeader('content-type', 'text/html; charset=utf-8');
+            if (error || !received) {
+                res.writeHead(400).end(`<p>mcpcost: the authorization failed: ${error ?? 'no code'}. You can close this tab.</p>`);
+                rejectCode(new Error(`authorization failed: ${error ?? 'no code in the callback'} ${u.searchParams.get('error_description') ?? ''}`.trim()));
+                return;
+            }
+            if (expectedState() && state !== expectedState()) {
+                res.writeHead(400).end('<p>mcpcost: the state did not match. You can close this tab.</p>');
+                rejectCode(new Error('the state in the callback did not match'));
+                return;
+            }
+            res.writeHead(200).end('<p>mcpcost: authorized. You can close this tab and go back to the terminal.</p>');
+            resolveCode(received);
+        });
+        const timer = setTimeout(() => rejectCode(new Error(`no callback within ${Math.round(timeoutMs / 1000)} s`)), timeoutMs);
+        timer.unref();
+        server.on('error', rejectServer);
+        server.listen(0, '127.0.0.1', () => {
+            const port = server.address().port;
+            resolveServer({ redirectUrl: `http://127.0.0.1:${port}/callback`, code, close: () => { clearTimeout(timer); server.close(); } });
+        });
+    });
+}
+export async function authCommand(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            header: { type: 'string', multiple: true },
+            credentials: { type: 'string' },
+            list: { type: 'boolean', default: false },
+            remove: { type: 'boolean', default: false },
+            scope: { type: 'string' },
+            'no-open': { type: 'boolean', default: false },
+            timeout: { type: 'string', default: '300000' },
+            help: { type: 'boolean', default: false }
+        },
+        allowPositionals: true
+    });
+    if (values.help) {
+        console.log(HELP);
+        return 0;
+    }
+    const file = values.credentials ?? defaultCredentialsPath();
+    const store = await loadCredentials(file);
+    if (values.list) {
+        const keys = Object.keys(store.servers);
+        if (!keys.length)
+            console.log(`${file}: no credentials stored`);
+        for (const k of keys)
+            console.log(`${k}\n  ${describeEntry(store.servers[k])}`);
+        return 0;
+    }
+    const raw = positionals[0];
+    if (!raw) {
+        console.error(HELP);
+        return 2;
+    }
+    let key;
+    try {
+        key = credentialKey(raw);
+    }
+    catch {
+        console.error(`${raw} is not a URL`);
+        return 2;
+    }
+    if (values.remove) {
+        if (store.servers[key]) {
+            delete store.servers[key];
+            await saveCredentials(store, file);
+            console.log(`${key}: removed from ${file}`);
+        }
+        else
+            console.log(`${key}: nothing stored`);
+        return 0;
+    }
+    if (values.header?.length) {
+        const entry = (store.servers[key] ??= {});
+        entry.headers ??= {};
+        for (const h of values.header) {
+            const i = h.indexOf(':');
+            if (i <= 0) {
+                console.error(`--header wants "Name: value", got ${JSON.stringify(h)}`);
+                return 2;
+            }
+            entry.headers[h.slice(0, i).trim()] = h.slice(i + 1).trim();
+        }
+        await saveCredentials(store, file);
+        console.log(`${key}: ${describeEntry(entry)} stored in ${file}`);
+        return verify(store, key);
+    }
+    // The OAuth flow: discovery, registration, the consent in the browser, the token.
+    const timeoutMs = Number(values.timeout) || 300_000;
+    const cb = await callbackServer(() => provider.lastState, timeoutMs);
+    const provider = createProvider(store, key, {
+        redirectUrl: cb.redirectUrl,
+        scope: values.scope,
+        onRedirect: (url) => {
+            console.log(`\nOpen this URL and allow the access:\n  ${url}\n`);
+            if (!values['no-open'])
+                openBrowser(url.toString());
+            console.log('Waiting for the consent…');
+        }
+    });
+    try {
+        const first = await auth(provider, { serverUrl: key });
+        if (first === 'REDIRECT') {
+            const code = await cb.code;
+            const second = await auth(provider, { serverUrl: key, authorizationCode: code });
+            if (second !== 'AUTHORIZED')
+                throw new Error(`unexpected result ${second}`);
+        }
+        await saveCredentials(store, file);
+        console.log(`${key}: ${describeEntry(store.servers[key])} stored in ${file}`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (provider.changed)
+            await saveCredentials(store, file);
+        console.error(`${key}: the OAuth flow failed: ${message}`);
+        console.error('If the server takes an API key instead, store it with: mcpcost auth <url> --header "Authorization: Bearer …"');
+        return 1;
+    }
+    finally {
+        cb.close();
+    }
+    return verify(store, key);
+}
+/** One measurement with the stored credentials, so the user sees the result. */
+async function verify(store, key) {
+    const creds = credentialsFor(store, key);
+    const type = /\/sse\/?$/.test(new URL(key).pathname) ? 'sse' : 'streamable-http';
+    const r = await probeRemote({ url: key, type }, { timeoutMs: 20_000, headers: creds?.headers, authProvider: creds?.authProvider, includeTools: false });
+    if (r.status === 'ok')
+        console.log(`measured: alive, ${r.toolCount} tools, ${r.toolsTokens?.toLocaleString('en-US')} tokens (o200k estimate)`);
+    else
+        console.log(`measured: ${r.status}${r.httpStatus ? ` (HTTP ${r.httpStatus})` : ''}${r.error ? `: ${r.error.split('\n')[0].slice(0, 160)}` : ''}`);
+    return r.status === 'ok' ? 0 : 1;
+}

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