promptbudget-mcp

@mukundakatta/promptbudget-mcp

トークン予算を考慮したテキスト処理のための MCP サーバーです。ツールは count、truncate、chunk の3つです。LLM がコンテキストを準備したり、チャット履歴を収めたり、長いソース文書をプロンプトに渡したりするときに使用します。

ツール

ツール	機能
count_tokens(text, max_tokens?, chars_per_token?)	事前チェックを行います。tokens を返します。max_tokens を指定すると、fits と overflow_tokens も返します。
truncate_to_token_budget(text, max_tokens, strategy?, ...)	テキストを予算内に収まるよう切り詰めます。戦略は head、tail、head_tail、smart_cut の4つです。
chunk_to_budget(text, max_tokens, overlap_tokens?, ...)	長いテキストを、任意のオーバーラップを含む予算内の複数のチャンクに分割します。

切り詰めの戦略

戦略	削除する部分	適した用途
head	末尾	冒頭から要約したい長いソース文書
tail（デフォルト）	先頭	最新の内容が最も重要なチャット履歴
head_tail	中間	指示と最新のターンの両方が重要な場合
smart_cut	中間（視認できるマーカー付き）	head_tail と同様ですが、モデルが切り詰められたことを認識できます

実際のワークフロー

「これはプロンプトに収まりますか？」

// Tool call from your agent
{
  "name": "count_tokens",
  "arguments": { "text": "<...long text...>", "max_tokens": 4096 }
}
// Returns:
{ "tokens": 5230, "max_tokens": 4096, "fits": false, "overflow_tokens": 1134, "chars_per_token": 4 }

fits: true の場合は、そのまま送信します。fits: false の場合は、truncate_to_token_budget（情報が失われます）と chunk_to_budget（LLM を複数回呼び出します）のどちらを使うか決めます。

「最新の内容を残して、これを収めてください」

{
  "name": "truncate_to_token_budget",
  "arguments": { "text": "<chat history>", "max_tokens": 4096, "strategy": "tail" }
}
// Returns:
{ "truncated": "...", "original_tokens": 5230, "truncated_tokens": 4096, "strategy_used": "tail" }

「この5万トークンの文書を RAG に取り込んでください」

{
  "name": "chunk_to_budget",
  "arguments": { "text": "<long doc>", "max_tokens": 512, "overlap_tokens": 50 }
}
// Returns:
{
  "chunks": ["...", "...", "..."],
  "chunk_count": 110,
  "total_tokens": 50000,
  "chunk_max_tokens": 512,
  "overlap_tokens": 50
}

overlap_tokens の値により、チャンク境界付近の文が次のチャンクでも前後のコンテキストを保てます。これは RAG の検索品質にとって重要です。

トークン数の精度

デフォルトの chars_per_token = 4 は、OpenAI の経験則です。英語では約10～15％以内の精度です。特定のモデルに対して正確に計算するには、実際のトークナイザーの文字数／トークン比を指定してください。

トークナイザー	文字数／トークン（英語）
cl100k_base（GPT-4、GPT-3.5）	約4
o200k_base（GPT-4o）	約4.5
Claude トークナイザー	約3.5
Llama 3	約3.8

英語以外のテキストでは、さらに小さい値を指定してください（中国語は約1文字／トークン、コードは約3文字／トークンです）。

インストール — Claude Desktop

{
  "mcpServers": {
    "promptbudget": {
      "command": "npx",
      "args": ["-y", "@mukundakatta/promptbudget-mcp"]
    }
  }
}

Cursor／Cline／Windsurf／Zed でも同様の形式です。

直接実行（MCP クライアントなし）

npx -y @mukundakatta/promptbudget-mcp

このサーバーは stdio 経由で MCP を使用します。mcptools または任意のクライアントと組み合わせてください。ターミナルに何も表示されなくても問題ありません。stdio サーバーは MCP クライアントが接続するまで何も表示せずに待機します。

関連ライブラリ

Rust クレート promptbudget は同じロジックを純粋な Rust で実装しています。MCP 以外のコンテキストにアルゴリズムを組み込みたい場合に利用できます。

変更履歴

• 0.2.0（2026-05-10） — count_tokens（事前チェック）と chunk_to_budget（オーバーラップ付き分割）を追加しました。ワークフローの例とトークナイザー比の表を README に追加しました。
• 0.1.1（2026-05-09） — MCP Registry との互換性のため、mcpName フィールドを追加しました。
• 0.1.0（2026-05-09） — truncate_to_token_budget を含む初回リリースです。

ライセンス

MIT OR Apache-2.0。