What Is the caveman-shrink MCP Server and How Does It Work?

The caveman-shrink MCP server is a stdio proxy middleware that compresses prose fields in Model Context Protocol responses to reduce token consumption while preserving code snippets, URLs, and semantic meaning.

The caveman-shrink MCP server solves token budget constraints in MCP ecosystems by acting as an intelligent compression layer. Developed as part of the JuliusBrussee/caveman repository, this tool wraps any upstream MCP server to shrink descriptive text in tool catalogs before the data reaches your model.

How caveman-shrink Works

The server operates as a transparent proxy between your MCP client and upstream servers. It intercepts JSON-RPC responses containing tool definitions, compresses specified text fields, and forwards the optimized payload to the client.

The stdio Proxy Architecture

When you launch caveman-shrink, it spawns the upstream MCP server as a child process using Node’s child_process.spawn with stdio options defined in src/mcp-servers/caveman-shrink/spawn-options.js. The proxy maintains bidirectional communication:

• Client-to-server: All incoming requests pass through unchanged to the upstream server
• Server-to-client: Responses undergo line-buffered JSON parsing and transformation via the transformResponse function

This architecture ensures that tool execution requests (tools/call) and their responses remain untouched, eliminating any risk of breaking downstream parsing logic.

Field Compression Logic

The core compression happens in src/mcp-servers/caveman-shrink/index.js within the transformResponse function (lines 73-98). For each MCP list response—whether tools/list, prompts/list, resources/list, or resourceTemplates—the proxy:

1. Identifies configured fields (default: description)
2. Passes field values through the compress function imported from src/mcp-servers/caveman-shrink/compress.js
3. Replaces the original text only if the compression yields a shorter string
4. Optionally logs byte deltas when debug mode is enabled

The compression algorithm specifically preserves code snippets, file paths, URLs, and identifiers using the same boundary detection logic found in the parent caveman skill, ensuring semantic content remains intact while removing redundant verbosity.

Installing and Configuring caveman-shrink

You can install the proxy globally or run it directly via npx without installation.

Installation Methods

Install via npm:

npm install -g caveman-shrink

Or run directly:

npx caveman-shrink <upstream-cmd> [args...]

The top-level caveman installer also supports automatic registration. When using bin/install.js with the --with-mcp-shrink flag, the installer adds the proxy to your Claude configuration and includes the caveman-shrink package in the installation results:

caveman install --with-mcp-shrink="npx @modelcontextprotocol/server-filesystem /my/project"

Environment Configuration

Control compression behavior through environment variables:

• CAVEMAN_SHRINK_FIELDS: Comma-separated list of field names to compress (default: description)
• CAVEMAN_SHRINK_DEBUG: Set to 1 to log per-field compression deltas to stderr

These settings are documented in src/mcp-servers/caveman-shrink/README.md (lines 45-50).

Usage Examples

Basic Proxy Usage

Wrap any MCP server command to immediately reduce token usage:

caveman-shrink npx @modelcontextprotocol/server-filesystem /path/to/dir

Claude Code Integration

Configure the proxy in your Claude Code settings (~/.claude.json):

{
  "mcpServers": {
    "fs-shrunk": {
      "command": "npx",
      "args": [
        "caveman-shrink",
        "npx",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/dir"
      ]
    }
  }
}

This configuration example appears in the README at src/mcp-servers/caveman-shrink/README.md (lines 22-30).

Debug Logging

Enable verbose output to verify compression effectiveness:

CAVEMAN_SHRINK_DEBUG=1 caveman-shrink npx @modelcontextprotocol/server-filesystem /my/project

When enabled, the proxy prints lines such as:

[caveman-shrink] tools.myTool.description: 214→147 bytes

This logging occurs in the debug branch of index.js (lines 91-96), showing the exact byte reduction for each transformed field.

Summary

• caveman-shrink acts as a stdio proxy that compresses MCP response fields to save tokens
• The transformResponse function in src/mcp-servers/caveman-shrink/index.js handles the compression loop for tools, prompts, and resources
• Code snippets, URLs, and file paths remain untouched while prose gets optimized
• Configure target fields via CAVEMAN_SHRINK_FIELDS and monitor compression via CAVEMAN_SHRINK_DEBUG
• Installation options include global npm install, npx execution, or the caveman installer with --with-mcp-shrink

Frequently Asked Questions

Does caveman-shrink modify tool execution responses?

No. The proxy only transforms list responses (tools/list, prompts/list, resources/list) and passes through tools/call requests and responses unchanged. This ensures that tool execution remains unaffected by the compression layer.

Which fields does caveman-shrink compress by default?

By default, the proxy compresses only the description field. You can customize this by setting the CAVEMAN_SHRINK_FIELDS environment variable to a comma-separated list of field names you want to target.

Can I use caveman-shrink with any MCP server?

Yes. The proxy wraps any MCP server that communicates via stdio, regardless of the underlying implementation. As long as the upstream server speaks the Model Context Protocol, caveman-shrink can sit between it and any MCP-compliant client.

How does caveman-shrink preserve code while compressing text?

The compression algorithm in src/mcp-servers/caveman-shrink/compress.js recognizes boundaries for code blocks, URLs, file paths, and identifiers. It applies compression only to natural language prose, ensuring that technical references remain intact and parseable by downstream tools.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}