# caveman-shrink MCP Middleware: A Complete Guide to Compressing MCP Server Responses

> Learn how caveman-shrink MCP middleware compresses Model Context Protocol server responses. Reduce token usage by compressing prose while preserving code and URLs. A complete guide.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-07-06

---

**caveman-shrink is a stdio proxy middleware that intercepts Model Context Protocol (MCP) server responses and compresses prose fields like `description` to reduce token usage while preserving code fragments, URLs, and identifiers.**

The `caveman-shrink` middleware is a lightweight Node.js utility from the JuliusBrussee/caveman repository that acts as a transparent proxy between MCP clients and upstream servers. It processes JSON-RPC traffic in real-time, applying intelligent text compression to reduce the token footprint of tool catalogs and resource listings without stripping syntactically meaningful content.

## What caveman-shrink MCP Middleware Does

`caveman-shrink` functions as a **stdio proxy** that transparently sits between an MCP client (such as Claude Code) and an upstream MCP server. Its primary purpose is to **compress prose fields**—by default the `description` field—in JSON-RPC responses returned by the upstream server.

The compression algorithm follows the same token-saving rules as the `caveman-compress` skill: it preserves **code fragments**, **URLs**, **file paths**, **identifiers**, and other structured tokens while removing filler words, articles, and hedging language. This ensures that language models receive the essential semantic content without wasting tokens on verbose formatting.

## How caveman-shrink Works: Architecture and Implementation

Understanding the internal architecture of `caveman-shrink` helps explain its efficiency and reliability.

### Process Spawning and Management

The middleware entry point is [`src/mcp-servers/caveman-shrink/index.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/index.js), which executes as a Node.js script (`#!/usr/bin/env node`). It parses command-line arguments and spawns the upstream MCP server using `child_process.spawn` with platform-specific options imported from [`spawn-options.js`](https://github.com/JuliusBrussee/caveman/blob/main/spawn-options.js) (lines 45-52). Errors and exit codes from the upstream process propagate directly back to the caller, ensuring reliable error handling.

### Line-Buffered JSON-RPC Processing

MCP transports JSON objects one per line. The `makeLineBuffer` function (lines 60-70 in [`index.js`](https://github.com/JuliusBrussee/caveman/blob/main/index.js)) accumulates incoming data chunks until it encounters a newline, then parses each complete line as JSON. This approach ensures that partial TCP packets or stdio buffers never corrupt the JSON-RPC message stream.

### Response Transformation Logic

The `transformResponse` function (lines 73-100) inspects the `result` object of upstream responses and searches for arrays named `tools`, `prompts`, `resources`, or `resourceTemplates`. For each object within these arrays, it compresses fields specified in the `CAVEMAN_SHRINK_FIELDS` environment variable (default: `description`).

The actual compression logic resides in [`src/mcp-servers/caveman-shrink/compress.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/compress.js), specifically the `compress` and `compressDescriptionsInPlace` functions. If any top-level fields are compressed, the helper skips `compressDescriptionsInPlace` to avoid double-processing nested schemas (lines 104-106).

### Traffic Direction Handling

Client-to-upstream traffic passes through unchanged—version 1 does not modify request bodies. Only upstream-to-client responses undergo transformation, and only for the specific response types listed above.

## Installing caveman-shrink

You can install the middleware globally or run it on-demand without installation.

Install globally using npm:

```bash
npm install -g caveman-shrink

```

Or use `npx` to run without installing:

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

```

## Configuring caveman-shrink in Claude Code

To use `caveman-shrink` with Claude Code or any MCP-compatible client, add a new entry under `mcpServers` in your configuration. The middleware wraps the real upstream command as arguments:

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

```

When Claude Code loads this configuration, it starts `caveman-shrink`, which in turn spawns the `@modelcontextprotocol/server-filesystem` server. Every `tools/list`, `prompts/list`, `resources/list`, or `resourceTemplates/list` response has its `description` fields compressed before reaching the model.

## Customizing Compression Behavior

Configure which fields get compressed and enable debugging output using environment variables.

### Targeting Specific Fields

Set `CAVEMAN_SHRINK_FIELDS` to a comma-separated list of field names:

```bash
CAVEMAN_SHRINK_FIELDS=description,summary \
npx caveman-shrink npx @modelcontextprotocol/server-filesystem /my/project

```

This compresses both `description` and `summary` fields in the MCP responses.

### Debugging Compression Metrics

Enable debug mode to see per-field size deltas:

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

```

When `CAVEMAN_SHRINK_DEBUG=1` is set, the middleware writes compression statistics to `stderr`, showing exactly how many bytes or tokens were saved per field.

## Summary

- **caveman-shrink** is a stdio proxy middleware from the JuliusBrussee/caveman repository that compresses MCP server responses to reduce token usage.
- It processes JSON-RPC line-by-line using `makeLineBuffer` and transforms responses via `transformResponse` in [`src/mcp-servers/caveman-shrink/index.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/index.js).
- By default, it compresses the `description` field in `tools`, `prompts`, `resources`, and `resourceTemplates` arrays while preserving code tokens and identifiers.
- Configure custom fields using the `CAVEMAN_SHRINK_FIELDS` environment variable and enable debugging with `CAVEMAN_SHRINK_DEBUG=1`.
- Install via `npm install -g caveman-shrink` or run directly with `npx caveman-shrink <command>`.

## Frequently Asked Questions

### What is the difference between caveman-shrink and caveman-compress?

While both tools reduce token usage, `caveman-compress` is a skill that operates on text directly within prompts, whereas `caveman-shrink` is a middleware that intercepts and modifies MCP server responses transparently. The shrink middleware applies the same compression rules as the compress skill but works at the protocol level between the client and server.

### Does caveman-shrink modify MCP request bodies or only responses?

`caveman-shrink` only modifies upstream-to-client responses, specifically those containing `tools`, `prompts`, `resources`, or `resourceTemplates` lists. Client-to-upstream traffic passes through unchanged according to the source code in [`src/mcp-servers/caveman-shrink/index.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/index.js) (lines 23-26).

### Can I compress fields other than description?

Yes. Set the `CAVEMAN_SHRINK_FIELDS` environment variable to a comma-separated list of field names. For example, `CAVEMAN_SHRINK_FIELDS=description,summary` compresses both description and summary fields in the JSON-RPC responses.

### How do I troubleshoot if caveman-shrink is not compressing responses?

Enable debug mode by setting `CAVEMAN_SHRINK_DEBUG=1` before running the command. This outputs per-field size deltas to `stderr`, allowing you to verify that compression is occurring and measure the token savings. Check that your upstream server actually returns the fields specified in `CAVEMAN_SHRINK_FIELDS`.