Caveman
Agent toolingMCP server

MCP server

caveman-mcp is a stdio JSON-RPC adapter that exposes the compression engine to any MCP host as three tools. It links the engine in-process, so MCP calls run the same compressors as the CLI.

The adapter owns MCP framing only. Compression, recovery, stats, and inferred ratios come from the engine. The server opens no network connection.

The three tools

A host that loads caveman-mcp sees three tools (exact, case-sensitive names):

text
caveman_compress(input: string)
caveman_retrieve(recovery_handle: string)
caveman_stats()
  • caveman_compress(input) — runs the engine over a string and returns the compressed text, an inferred ratio, and a recovery_handle. Incompressible or malformed input is returned unchanged with ratio: 0 and recovery_handle: null.
  • caveman_retrieve(recovery_handle) — returns the byte-exact original for a handle from this session. Nothing is dropped permanently; a compressed result can always be expanded back.
  • caveman_stats() — session totals: tokens before and after, the aggregate ratio, basis: "inferred", and scope: "session".

S4lossy · recoverable Compression is lossy but recoverable. Every drop the engine makes is stored under a content-addressed handle and is reachable through caveman_retrieve.

Configure your host

The adapter speaks MCP over stdio, so any host that launches a command and talks to it on stdin/stdout can use it. Point the host at your built binary:

json
{
  "mcpServers": {
    "caveman": {
      "command": "/absolute/path/to/caveman-mcp"
    }
  }
}

The npx name is not live yet

You may see a {"command": "npx", "args": ["-y", "caveman-mcp"]} form in the source. That published name is reserved, not live — npx caveman-mcp does not resolve to this project yet. Until it does, run your own build: set CAVEMAN_MCP_BIN to its path, or point the host's command/args straight at the binary as shown above.

Build it

terminal
go build -o caveman-mcp ./public/mcp/cmd/caveman-mcp

That produces one binary. The host execs it, the binary opens an in-memory CCR store scoped to that session, and serves tools on stdin/stdout. When the session ends, handles from that in-memory store go away.

How it stays honest

The adapter is built to fail in the safe direction in every case.

Fail open on input, fail closed on protocol

Fail open — if the engine errors or the input is malformed, caveman_compress returns the input byte-identical with ratio: 0. A compression problem never becomes a protocol error or a lost payload.

Fail closed — an unknown tool name or an unknown recovery_handle returns isError: true with a cave_snake_code, never a fabricated payload. An unknown JSON-RPC method returns -32601 (method not found).

Two more invariants hold by construction:

  • Zero-egress. The adapter imports no net, net/http, or os/exec. A source-parsing test fails the build if any of them appear. The tools cannot phone home because the code that would is not linked.
  • inferred-only. The string verified never appears in a result. caveman_stats always reports basis: "inferred". The open tools estimate; they do not certify.

Scope

Version one is stdio-only and handles string payloads — the engine detects the content type for you, so you pass raw text and it routes JSON, logs, code, diffs, and search results to the right compressor. There is no HTTP transport yet.

Compression engine

The compressors these tools run, and the CCR store behind retrieve.

BSL
Cavemem

The same MCP framing, applied to durable agent memory.

BSL