RELATED 01
Token Optimizer MCP
Local stdio server that caches, diffs and compresses what a coding agent reads to cut context use
576GitHub stars
5.5k/wknpm downloads
71popularity score
caveman-shrink
Proxy that wraps another MCP server and shortens its descriptions to save context tokens
By Julius Brussee (individual) JavaScript Local · stdio Developer toolsAI and ML
66 popularity score ★ 118k ↓ 3.0k/wk
Connect your client
Local (npm)
Add in one click
Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.
Or add it by command or config
Claude CodeTerminal
claude mcp add caveman-shrink -- npx -y caveman-shrink '<UPSTREAM_COMMAND>' '<UPSTREAM_ARGS>'Claude Desktopclaude_desktop_config.json
{
"mcpServers": {
"caveman-shrink": {
"command": "npx",
"args": [
"-y",
"caveman-shrink",
"<UPSTREAM_COMMAND>",
"<UPSTREAM_ARGS>"
]
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"caveman-shrink": {
"command": "npx",
"args": [
"-y",
"caveman-shrink",
"<UPSTREAM_COMMAND>",
"<UPSTREAM_ARGS>"
]
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"caveman-shrink": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"caveman-shrink",
"<UPSTREAM_COMMAND>",
"<UPSTREAM_ARGS>"
]
}
}
}Codex~/.codex/config.toml
[mcp_servers.caveman-shrink]
command = "npx"
args = ["-y", "caveman-shrink", "<UPSTREAM_COMMAND>", "<UPSTREAM_ARGS>"]Gemini CLITerminal
gemini mcp add --scope user caveman-shrink npx -- -y caveman-shrink '<UPSTREAM_COMMAND>' '<UPSTREAM_ARGS>'Settings 2
CAVEMAN_SHRINK_FIELDS |
Optional: Comma-separated field names to compress in list responses and nested input schemas. |
|---|---|
CAVEMAN_SHRINK_DEBUG |
Optional: Set to 1 to log each field's size before and after compression to stderr. |
What it does
caveman-shrink is a stdio proxy you put in front of another MCP server. Your client starts caveman-shrink, and it starts the upstream server as a child process from the command and arguments you pass it. Messages from the client go to the upstream untouched. On the way back, any response carrying a tools, prompts, resources or resourceTemplates list has its description text rewritten with the caveman rules, which drop articles, filler, hedging and pleasantries but keep code, URLs, paths and identifiers as written.
The point is a tool catalogue that costs the model fewer tokens to read while the tools behave the same. The proxy has no tools of its own, so the assistant sees the upstream's tools with shorter text. Results of tools/call pass through unchanged, and lines that are not valid JSON are forwarded as they are.
In index.js the rewrite also walks each tool's inputSchema, so parameter descriptions are shortened too, which the README does not mention. CAVEMAN_SHRINK_FIELDS widens the set of field names that get compressed (description by default), and CAVEMAN_SHRINK_DEBUG=1 prints the byte savings for each field to stderr.
It lives in the caveman repository, a larger set of agent skills and tools for cutting token use. Its own README marks it pre-1.0 and warns that the compression rules and the field set may change.
What it needs
| Runtime | Node.js |
|---|---|
| Runs on | macOS, Windows, Linux |
| Also |
|
It does nothing alone. Pass the upstream server's launch command and its arguments after caveman-shrink, for example npx caveman-shrink npx @modelcontextprotocol/server-filesystem /path/to/dir. Started with no arguments it prints a usage line and exits with code 2.
Limits
- Early release Pre-1.0: its README says the compression rules and the set of fields may change.
- Not covered Only list responses are rewritten. Requests and tools/call results pass through as sent.
- Limit On SIGTERM, SIGINT or SIGHUP it signals the upstream and sends SIGKILL after 2 seconds (shutdown.js), but only to the direct child, so a launcher like npx can leave the real server running.
- Platform On Windows it refuses an upstream .cmd or .bat shim that does not point at a Node script (spawn-options.js).
- Limit It splits messages on newlines, so an upstream that frames messages another way is passed through without compression.
Who it suits
Worth trying if you run MCP servers with long tool catalogues and want the model to spend fewer tokens reading them, without changing what the tools return. It runs locally, needs no account and only edits description text, so the risk is mostly that a shortened description reads less clearly to the model. Since it is pre-1.0 and its rules may change, check the output with CAVEMAN_SHRINK_DEBUG=1 before relying on it. If your upstream is a server you control, trimming its descriptions at the source does the same job without a second process.