promptbudget-mcp

@mukundakatta/promptbudget-mcp

用于按令牌预算处理文本的 MCP 服务。包含三个工具：count、truncate、chunk。适用于 LLM 准备上下文、调整聊天历史，或通过提示词输入较长的源文档时。

工具

工具	功能
count_tokens(text, max_tokens?, chars_per_token?)	预检。返回 tokens。指定 max_tokens 后，还会返回 fits 和 overflow_tokens。
truncate_to_token_budget(text, max_tokens, strategy?, ...)	裁剪文本，使其符合预算。提供 4 种策略：head、tail、head_tail、smart_cut。
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" }

###“将这份 50k-token 文档导入我的 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 crate promptbudget 使用纯 Rust 实现了相同逻辑，适合希望将算法链接到非 MCP 环境中的场景。

更新日志

• 0.2.0（2026-05-10）— 新增 count_tokens（预检）和 chunk_to_budget（拆分并重叠）。README 新增工作流示例和分词器比值表。
• 0.1.1（2026-05-09）— 新增 mcpName 字段，以兼容 MCP Registry。
• 0.1.0（2026-05-09）— 首次发布，包含 truncate_to_token_budget。

许可证

MIT OR Apache-2.0。