@mukundakatta/promptbudget-mcp

MCP server for token-budget-aware text handling. Three tools: count, truncate, chunk. Use when an LLM is preparing context, fitting chat history, or feeding long source documents through a prompt.

Tools

| Tool | What it does | |---|---| | count_tokens(text, max_tokens?, chars_per_token?) | Pre-flight check. Returns tokens. With max_tokens, also returns fits + overflow_tokens. | | truncate_to_token_budget(text, max_tokens, strategy?, ...) | Trim text to fit. 4 strategies: head, tail, head_tail, smart_cut. | | chunk_to_budget(text, max_tokens, overlap_tokens?, ...) | Split long text into multiple under-budget chunks, with optional overlap. |

Strategies for truncate

| Strategy | Drops | Good for | |---|---|---| | head | Tail | Long source docs you want to summarize from the top | | tail (default) | Head | Chat history where latest matters most | | head_tail | Middle | Instructions + latest turn both matter | | smart_cut | Middle, with visible marker | Same as head_tail but model knows truncation happened |

Real workflows

"Does this fit in my prompt?"

// 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 }

If fits: true, send as-is. If fits: false, decide between truncate_to_token_budget (lose info) or chunk_to_budget (multiple LLM calls).

"Make this fit, keep the latest"

{
  "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" }

"Ingest this 50k-token doc into my 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
}

The overlap_tokens value lets sentences at chunk boundaries still have surrounding context in the next chunk — important for RAG retrieval quality.

Token counting accuracy

The default chars_per_token = 4 is the OpenAI rule of thumb. It's accurate within ~10–15% for English. For accurate accounting against a specific model, plug in your real tokenizer's chars-per-token ratio:

| Tokenizer | Chars/token (English) | |---|---| | cl100k_base (GPT-4, GPT-3.5) | ~4 | | o200k_base (GPT-4o) | ~4.5 | | Claude tokenizer | ~3.5 | | Llama 3 | ~3.8 |

For non-English text, divide further (Chinese is ~1 char/token, code is ~3 chars/token).

Install — Claude Desktop

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

Same shape for Cursor / Cline / Windsurf / Zed.

Run directly (no MCP client)

npx -y @mukundakatta/promptbudget-mcp

The server speaks MCP over stdio. Pair with mcptools or your client of choice. If nothing prints to the terminal, that is correct: stdio servers wait silently for an MCP client to connect.

Sibling library

The Rust crate promptbudget implements the same logic in pure Rust, in case you'd rather link the algorithm into a non-MCP context.

Changelog

• 0.2.0 (2026-05-10) — added count_tokens (pre-flight check) and chunk_to_budget (split-with-overlap). README expanded with workflow examples + tokenizer ratio table.
• 0.1.1 (2026-05-09) — added mcpName field for MCP Registry compatibility.
• 0.1.0 (2026-05-09) — initial release with truncate_to_token_budget.

License

MIT OR Apache-2.0.