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

> Discover the caveman-shrink MCP server, a stdio proxy that compresses prose fields in MCP responses to cut token use while keeping code and URLs intact. Learn how it works!

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: deep-dive
- Published: 2026-07-11

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```bash
npm install -g caveman-shrink

```

Or run directly:

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

```

The top-level caveman installer also supports automatic registration. When using [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```bash
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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

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

```

### Claude Code Integration

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

```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`](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/README.md) (lines 22-30).

### Debug Logging

Enable verbose output to verify compression effectiveness:

```bash
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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.