Budgetary: estimate token spend

@budgetary/mcp

あらゆる MCP 対応ホスト（Claude Code、Cursor、GitHub Copilot、Codex など）に、コーディングタスクを実行する前の事前確率的なトークン消費額の見積もりと、実際のコストをベストエフォートで測定する、捏造のない方法を提供する単一のModel Context Protocolサーバーです。予測は確率、測定は件数です。特定のタスクを予測する確かな根拠がない場合は、推測せずその旨を伝えます。一度構築すれば、どこにでも追加できます。以前計画されていたホストごとの拡張機能に代わるものです。

サーバーが公開するモデルから呼び出し可能なツールは、estimate の1つだけです。ホスト型の Budgetary API（https://api.budgetary.tools）と通信します。

インストール — ホストごとに1つのコマンド

キーを BUDGETARY_API_KEY として渡し、BUDGETARY_HOST でホストを指定すると、台帳の項目で見積もり元を区別できます。インストールの確認プロンプトで起動が停止しないよう、npx には必ず -y を付けてください。

Claude Code

claude mcp add budgetary \
  --env BUDGETARY_API_KEY=bg_test_... \
  --env BUDGETARY_HOST=claude-code \
  -- npx -y @budgetary/mcp

実際の使用量を自動送信するには、このコマンドだけでなくプラグインが必要です。 claude mcp add で接続されるのはestimate ツールだけです。実際の使用量をセッション終了時に送信するフックは、同梱のClaude Code プラグイン（マニフェスト経由）で接続されます。そのため、claude mcp add だけでは見積もりを取得できますが、実際の使用量はほかのホストと同様に手動で記録します。自動化するにはプラグインをインストールするか、フックを自分で追加してください（下記参照）。

確認するために、これを先に読む必要はありません。npx @budgetary/mcp doctor を実行すると、このマシンで自動送信のセッション終了処理がこれまでに実行されたかどうかが報告され、未設定の場合は追加すべき正確なフックが表示されます。上記のコマンドのように BUDGETARY_HOST=claude-code を指定してインストールすると、サーバーは最初の見積もり時に一度だけその旨を伝えます。いずれも Claude Code の設定を書き換えることはありません。このパッケージ内のコードが設定を読み取ったり編集したりすることはありません。

プラグインを使わずにフックを接続するには、~/.claude/settings.json に次の内容を自分で追加してください。

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @budgetary/mcp on-session-end",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

キーをコマンドに埋め込むのではなく、~/.budgetary/config.json に記述してください（API キーの設定を参照）。そうすれば、プロセス一覧にキーが表示されません。

フックが機能することは、実際の使用によって確認できます。次のセッションが終了すると、npx @budgetary/mcp doctor の Last auto: にその実行結果が表示されます。それまでは doctor に自動送信が記録されていないと表示されますが、これは想定どおりであり、編集に失敗したことを示すものではありません。このパッケージ内のコードは Claude Code の設定を読み取らないため、それより前にフックの動作を確認することはできません。

Cursor — .cursor/mcp.json（プロジェクト）または ~/.cursor/mcp.json（グローバル）

{
  "mcpServers": {
    "budgetary": {
      "command": "npx",
      "args": ["-y", "@budgetary/mcp"],
      "env": {
        "BUDGETARY_API_KEY": "bg_test_...",
        "BUDGETARY_HOST": "cursor"
      }
    }
  }
}

GitHub Copilot（VS Code） — .vscode/mcp.json

VS Code では mcpServers ではなく servers キーを使用し、inputs を使ってシークレットの入力を促すことができます。

{
  "inputs": [
    { "id": "budgetary-key", "type": "promptString", "description": "Budgetary API key", "password": true }
  ],
  "servers": {
    "budgetary": {
      "command": "npx",
      "args": ["-y", "@budgetary/mcp"],
      "env": {
        "BUDGETARY_API_KEY": "${input:budgetary-key}",
        "BUDGETARY_HOST": "copilot"
      }
    }
  }
}

Codex

codex mcp add budgetary \
  --env BUDGETARY_API_KEY=bg_test_... \
  --env BUDGETARY_HOST=codex \
  -- npx -y @budgetary/mcp

…または ~/.codex/config.toml に記述します。

[mcp_servers.budgetary]
command = "npx"
args = ["-y", "@budgetary/mcp"]

[mcp_servers.budgetary.env]
BUDGETARY_API_KEY = "bg_test_..."
BUDGETARY_HOST = "codex"

MCP レジストリから（ワンクリック）

このサーバーは、MCP レジストリ（https://registry.modelcontextprotocol.io）に io.github.thriftell/budgetary として登録されています。登録内容には上記の npm パッケージのみが記載されています。レジストリからインストールするホストでは、登録内容で宣言された項目の入力を求められます。必須の BUDGETARY_API_KEY と、任意の BUDGETARY_HOST です。

BUDGETARY_HOST も設定してください。 見積もり元のホストを示すための値であり、明示的に設定した値は、サーバーが独自に検出する値より常に優先されます。空欄の場合もホストは mcp として記録されますが、未送信の実行に関する一度限りの通知は、この変数に依存しなくなりました。MCP ハンドシェイクにはホスト名自体が含まれるため、BUDGETARY_HOST を設定しなかった Claude Code のインストールでも、完了した実行がここから送信されていない場合は、その旨が一度通知されます。クライアントが読み込む登録内容が古く、該当する項目がない場合は、上記の各セクションと同じように、ホスト独自の MCP 設定でそのサーバーの項目に追加してください。

リモートエンドポイント（手動設定専用）

Streamable-HTTP エンドポイント https://api.budgetary.tools/mcp が用意されています。レジストリの掲載では、現在このエンドポイントを案内していません。掲載エントリーには URL 以外の情報を含められないためです。API キーは tools/call に必要ですが、そのためのフィールドがなく、エンドポイントを選ぶ時点で以下の情報を伝える場所もありません。手動で設定するか、使用しないでください。

推定専用です。 このエンドポイントにはローカルプロセスがありません。保留ストアも、セッション終了時のフックも、読み取り可能なトランスクリプトもないため、実行に実際にかかった費用を測定できません。また、カウント値を受け取るツールも意図的に用意していません。測定ではなく、値を教えてもらう必要があるためです。このエンドポイントで行った推定が、どのような経路であっても、実測値によって確定されることはありません。実行を計測したい場合は、上記の npm パッケージをインストールしてください。

認証には Authorization: Bearer bg_… を使用します。これがなくても initialize と tools/list は応答しますが、tools/call は authentication_failed を返します。ホストが古い掲載情報をキャッシュしている場合は、リモートエンドポイントがインストールオプションとして表示されることがあります。掲載の取り下げが適用されるのは、現在のエントリーのみです。

API キーの設定

サーバーは、次の順序でキーを取得します。

1. サーバーの環境変数に設定された BUDGETARY_API_KEY（上記のホスト設定で設定します）。
2. ~/.budgetary/config.json → { "api_key": "bg_...", "base_url"? }。

どちらも設定されていない場合、estimate ツールはエラーの代わりに、キーの設定を促す簡潔なガイダンスを返します。例外をスローすることも、ホストをクラッシュさせることもありません。

mkdir -p ~/.budgetary
# Write the key with an EDITOR so it never lands in your shell history:
"${EDITOR:-nano}" ~/.budgetary/config.json   # add: { "api_key": "bg_test_..." }
chmod 600 ~/.budgetary/config.json            # owner-only

シェルの履歴にシークレットが記録される echo '{...}' > config.json よりもエディターの使用をおすすめします。また、ファイルが全ユーザーから読み取り可能にならないよう、chmod 600 を設定してください。

キーのプレフィックスで環境がわかります。

• bg_test_ — 無料のテスト階層です。開発用としてすぐに使用できます。
• bg_live_ — 本番環境です。ライブキーには有効なプランが必要です。有効なプランがない場合、API は 403 を返し、ツールは "Your Budgetary key isn't on an active plan." と表示します。（これは、キー自体が拒否されたことを意味する 401 とは異なります。）

API キーがツールの結果、pending.json、ログのいずれかに表示されることはありません。

オプション：作業中の言語をタグ付けする

各推定に作業中の言語を任意でタグ付けすると、推定履歴を言語別にまとめられます。サーバーの環境に設定します。

--env BUDGETARY_LANGUAGE=TypeScript

または、~/.budgetary/config.json に language フィールドを追加します（両方が設定されている場合は環境変数が優先されます）。

{ "api_key": "bg_test_...", "language": "TypeScript" }

これは TypeScript、Python、Go などの自由形式の表示名で、サーバー側で整形されます。正確な表記にする必要はありません。BUDGETARY_HOST と同様に、環境内で宣言する無害なタグです。言語モデルが設定することはなく、タスクの説明から推測されることもありません。estimate ツールに language 引数がないのは意図的です。何も設定しない場合、推定は言語情報なしで記録されます。言語の設定は必須ではなく、推定自体が変わることもありません。

通常の stdio MCP サーバーが認識できるのはホストから送信されるメッセージだけで、どのファイルを開いているかはわかりません。そのため、この宣言された値（ホスト／セッションごとに 1 つ）が、サーバーの頼れる情報になります。言語情報を一切公開しないホストでは、推定は言語情報なしで記録されます。

オプション：BUDGETARY_SOURCE — 一連の実行に付けるオペレーター用ラベル

通常のユーザーはここで何も設定する必要はなく、設定しなくても何も変わりません。 これは、ベンチマーク、負荷テスト、スクリプトによる評価などの自動化ハーネスからこのクライアントを操作し、実行にラベルを付けて後から実際の実行と区別したいオペレーター向けのものです。

その一連の実行のために起動するプロセスの環境で設定してください。そうすれば、その環境変数の有効期間は一連の実行に限られます。

BUDGETARY_SOURCE=my-harness-run <the command your harness runs>

これを MCP ホストの設定に入れないでください。 BUDGETARY_HOST や BUDGETARY_LANGUAGE とは異なり、このラベルは claude mcp add --env、~/.claude.json、.mcp.json に設定しないでください。これらの設定はマシン全体に適用され、永続します。一連の実行のために設定したラベルが気付かれないまま残り、その後、そのマシンで行われるすべての通常のセッションにラベルが付いてしまいます。記録の見た目は何も変わらないため、判別もできません。この変数は、意図的に ~/.budgetary/config.json からも読み込まれません。この3つのうち、config.json によるフォールバックがあるのは BUDGETARY_LANGUAGE だけです。実行を表すラベルが、その実行後も残るべきではありません。

実績の送信には、このラベルが付与されます。デフォルトは mcp_client です。これは不透明な文字列です。クライアントはこの文字列に意味を付与せず、形式（A–Z a–z 0–9 . _ - の最大64文字）のみを検証します。不正な形式の場合は無視してデフォルトにフォールバックし、送信を失敗させることはありません。（ラベルが拒否されたことを標準エラー出力で確認するには、BUDGETARY_DEBUG=1 を指定して実行してください。それ以外の場合、誤記は通知されません。）

このラベルには、意図的に備わっていない点が2つあります。

• データの扱い方は変わりません。 これは設定ではなくラベルです。設定しても（または設定しなくても）、権限が付与されたり、機能が有効になったり、記録される内容やその利用方法が変わったりすることはありません。
• タスクごとのフィールドではなく、モデルが設定することもありません。 BUDGETARY_HOST や BUDGETARY_LANGUAGE と同様、環境変数で宣言します。estimate ツールに source 引数がないのは意図的です。

ラベルは見積もりの作成時に一度だけ決定され、その見積もりの保留中エントリーに保存されます。そのため、後で別のセッションから異なる環境で送信を再試行することになっても、実際に行われた実行のラベルが報告されます。

実績 — 可能な場合は自動で、それ以外は手動で。捏造はしません

事前見積もりは一連の処理の半分にすぎません。キャリブレーションには、実行後の実際のトークン数が必要です。記録方法は、ホストが提供する情報によって異なります。

• Claude Code（プラグインあり）— 自動。 このホストは実際のセッショントランスクリプトを書き込みます。プラグインのセッション終了フックが、実際の tokens_in + tokens_out（キャッシュ読み取りトークンは除外）を読み取って送信します。さらに、短い動作トレースも送信します。トレースには、実行で使用されたツール（Read、Edit、Bash など）、各ツールのおおよそのトークン数、各ステップについての生の測定値2つが含まれます。測定値は、実行したコマンド（一般的なプログラム名（pytest や go test など）と、残りの内容を対象にしたソルト付きの不可逆なダイジェストからなる、秘匿化済みの記述子。生のパス、引数、コマンドは含まれません）と、成功したかどうかです。トレースはトランスクリプトから測定され、モデルから提供されることはありません。確実に読み取れないフィールドは省略されますが、合計値は送信されます。人間による操作は不要です。

• Claude Code（プラグインなしで claude mcp add を使用）— トランスクリプトから手動で送信。 プラグインがなければセッション終了フックがないため、自動送信は行われません。ただし、Claude Code はどちらの場合も同じ実際のトランスクリプトを書き込むため、カウントを入力する必要はありません。セッションの終了後、測定された合計値（および同じ動作トレース）を次のように送信してください。

  npx @budgetary/mcp on-session-end --transcript ~/.claude/projects/<project>/<session-id>.jsonl
  

  推定を行ったディレクトリから実行し、完了したセッションを指定してください。書き込み中のトランスクリプトは未完了です。また、推定に対する最初の報告が採用されます。実行結果を申告するには --success または --failed を追加してください。どちらも指定しない場合、実行結果は未報告のままです（下記参照）。さらによい方法は、上記のフックを設定し、手動での作業をなくすことです。

• Codex — ロールアウトから手動で報告。 Codex にはセッション終了フックがありませんが、ロールアウトのトランスクリプトは書き出されます。セッション終了後、実際のカウントを報告してください。

  npx @budgetary/mcp on-session-end --transcript ~/.codex/sessions/rollout-<ts>-<uuid>.jsonl
  

  推定を行ったディレクトリから実行してください。

  実行結果の申告は任意で、デフォルト値はありません。 --success／--failed は、実行が目標を達成したかどうかを示し、そのまま転送されます。ただし、実際に確認した呼び出し元だけが申告できます。そのため、どちらのフラグも指定しない場合、このフィールドは省略され、サーバーには実行結果が未観測として記録されます。これは3つ目の状態です。実行が失敗したことを意味するわけでも、成功したことを意味するわけでもありません。どちらかを推測しないでください。誤った判定は取り消せません（推定に対する最初の報告だけが保存され、更新用の呼び出しはありません）。一方、実測したトークン数はどちらの場合も報告できます。

  セッションを自ら起動したハーネスは、実行の終了状況を観測しているため、--censoring <category> でその状況も申告できます。値は natural、harness_watchdog、operative_cap、kill_switch のいずれか1つです（API 契約で定められた限定語彙です）。値は完全一致で照合され、そのまま転送されます。それ以外の値は送信内容から省略され、カテゴリに正規化されることも、エラーになることもありません。終了状況を観測していない実行には指定しないでください。フィールドがない場合は「不明」として正確に記録されますが、natural と推測して指定すると、サーバーには検出できない虚偽の申告になります。

• Cursor／Copilot／その他のホスト — 手動で報告。 これらのホストは、完了したエージェント実行のトークン総数をサードパーティのサーバーに渡しません。また、言語モデルもその数を知りません。そのため、時間があるときに自分で記録します。

  npx @budgetary/mcp report-actual
  

  このプロジェクトで直近に行われた、実績値が未報告の推定を表示し、入力／出力トークン数（ホストの使用状況 UI で確認してください。48,000 のように桁区切りされた数値も使えます）、タスクが成功したかどうか、任意の所要時間、そして観測できた場合は実行の終了状況（上限到達、ウォッチドッグによる終了、意図的な中断、自動終了）を入力するよう求めます。最後の質問で Enter キーを押すと、その項目は記録されません。「わからない」も正式な回答です。観測されていない終了状況が値に変換されることはありません。

実績値が未報告の推定をいつでも確認できます（読み取り専用で、サーバーへの呼び出しはありません）。

npx @budgetary/mcp pending

トークン数をモデルが入力することはありません。 モデルが呼び出せるツールは estimate だけです。実績値が報告されるのは、（a）実際のトランスクリプトを読み取るセッション終了フック、または（b）人間が入力する report-actual コマンドからのみです。捏造された実績値はキャリブレーションを損なうため、モデルがカウントを書き込むためのツールは意図的に用意されていません。

記録された実行で得られる情報

実行を記録すると、トークンがどこで使われたかを実測値に基づいて内訳表示します。exploration、generation、testing、retries、otherそれぞれについて、実測合計に占める割合が示されます。また、API による「このようなタスクとして、これは通常の範囲だったか」という回答も表示されます。どちらも API が計算して報告した内容を、受け取ったとおりに出力します。API が何も報告しない場合は、推測で補わず、何も出力しません。この内訳は、その実行自体の件数を測定したものなので正確であり、比較対象は不要です。判定結果が正直に insufficient_data となる場合もあります。これはエラーではなく、その問いに対する正直な回答です。

表示される場所は、実行の送信方法によって異なります。

• report-actual / on-session-end --transcript — 送信確認のすぐ下に、ターミナルで表示されます。
• セッション終了フック — フックの出力はホストによってデバッグログに送られるため、ユーザーには届きません。そのため、サマリーはローカルにバッファーされ、次の estimate の下に表示されます。対象の実行 ID も併記されます。一度だけ表示され、繰り返し表示されることはありません。

ダッシュボード

予測値と実測値のキャリブレーションダッシュボードを使うには、Open VSX から Budgetary（budgetary.budgetary-vscode）をインストールしてください。Cursor やその他の VS Code フォークでも、変更なしで動作します。このサーバーで同じ機能を再実装することはありません。

プライバシー

マシンで初めて estimate が正常に実行されると、ここを案内するメモが一度だけ追記され、npx @budgetary/mcp doctor を実行するたびに、その短縮版が繰り返し表示されます。このメモは1 回の呼び出し分遅れて表示され、そのことも明記しています。何かを表示できる時点では、estimate はすでにタスクのテキストを送信済みです。これは開示と参照先の提示であり、何も要求せず、何も制限せず、何の権限も付与しません。このセクションでは、参照先の内容を説明します。

マシンから https://api.budgetary.tools に送信されるのは、次の情報だけです。

• estimate に渡すタスクの説明（一字一句そのまま）。
• モデルが指定した場合は、その対象モデル識別子（例：claude-opus-4-7）。これは estimate ツールの省略可能な model 引数で、指定がない場合は省略されます。
• ホストタグ。BUDGETARY_HOST を設定している場合はその値、そうでない場合は定数 mcp です。呼び出し元の MCP ホストを示すだけで、それ以外の情報は含みません。
• 呼び出しごとのリクエスト ID。再試行した呼び出しが二重にカウントされないよう、estimate ごとに新しいランダムな UUID が生成されます。ユーザー、マシン、タスクに関する情報から導出されることはありません。
• 設定している場合は、宣言した言語タグ（例：TypeScript）。ホスト名と同様の無害なラベルです。BUDGETARY_LANGUAGE または設定の language フィールドで明示的に有効にしない限り、送信されません。
• 実行後のトークン数（tokens_in、tokens_out）と所要時間、結果が実際に確認できた場合に限る success フラグ、さらに宣言されていた場合は実行の終了方法。終了方法は natural、harness_watchdog、operative_cap、kill_switch のいずれかで、それ以外はありません。
• 固定のクライアントラベル。オペレーターが BUDGETARY_SOURCE で上書きしていない限り（上記を参照）、mcp_client です。どのクライアントがレコードを送信したかを示すだけで、それ以外の情報は含みません。固定文字列であり、ユーザー、マシン、タスクのいずれの部分からも導出されません。
• Claude Code では、振る舞いトレース。各ステップについて、ホストツール名（例：Read、Bash）、そのトークン数、対象を示す秘匿化された記述子、成功したかどうかが含まれます。記述子でプログラム名がそのまま公開されるのは、一般的で機微情報を含まないツール（例：pytest、npm run）に限られます。貼り付けられた認証情報や非公開スクリプト名が表示されることはなく、ソルト付きダイジェストのみが記録されます。プログラム名以降（パス、引数、コマンドの残りの部分）は、常にダイジェストに含まれます。ファイルツールの場合は、パスのダイジェストのみが記録されます。カスタムツールや内部ツール（組織の非公開 MCP ツールなど）は、実際の名前ではなく、一般名の mcp:other として報告されます。ファイルの内容、絶対パス、コマンド引数、出力がマシンから送信されることはありません。送信されるのは、許可リストに登録されたプログラム名と不透明なキーだけです。BUDGETARY_TRACE_TARGET=off を設定すると、記述子は完全に除外されます（トレースにはツール名とトークン数のみが残ります）。明示的に 1、true、on、yes のいずれかを指定しない値は、すべてオフとして扱われます。

これ以外の情報は一切送信されません。記述子のダイジェストと、各見積もりに付随する project_id はどちらも、ソルト付きの不可逆ハッシュ（HMAC-SHA256）です。記述子のダイジェストには送信ごとに新しいソルトが使われ、project_id には ~/.budgetary/install-salt に保存されるマシン固有のインストールソルトが使われます。ソルトがマシンの外に出ることはないため、サーバーが受け取るのは、コマンドやパスに逆変換できない安定したキーです。保留中のデータは ~/.budgetary/pending.json に保存され、ファーストパーティの Claude Code クライアントおよび Codex クライアントとバイト単位で共有されます。そのため、一度設定すれば、すべてのホストに適用されます。送信した実行について API が返す測定済みの概要は、estimate で表示されるまで ~/.budgetary/measured.json にローカル保存されます。保存されるのは直近の少数のレコードのみで、1 週間後に削除されます。これはすでに受け取った応答のコピーであり、その中の情報が別の場所に送信されることはありません。

リファレンス

v1 API の仕様（エンドポイント、エラーコード、シナリオラベル）については、docs/api-contract.md を参照してください。

Apache-2.0 ライセンスの下でライセンスされています。