mattbeen/headroom-mcp repository overview

services:
  proxy:
    build: .
    image: headroom-mcp:latest
    command: ["headroom", "proxy", "--host", "0.0.0.0", "--port", "8787"]
    ports:
      - "8787:8787"
    volumes:
      - ~/headroom/volume:/root/.headroom
    environment:
      HEADROOM_HOST: 0.0.0.0
      HEADROOM_PORT: 8787
    restart: unless-stopped

  headroom-mcp:
    build: .
    image: headroom-mcp:latest
    command: ["headroom", "mcp", "serve", "--proxy-url", "http://proxy:8787"]
    volumes:
      - ~/headroom/volume:/root/.headroom
    depends_on:
      - proxy
    stdin_open: true
    profiles:
      - stdio

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "headroom": {
      "type": "local",
      "command": [
        "docker",
        "run",
        "-i",
        "--rm",
        "-v",
        "C:/home/headroom/volume:/root/.headroom",
        "headroom-mcp:latest",
        "headroom",
        "mcp",
        "serve",
        "--proxy-url",
        "http://host.docker.internal:8787"
      ],
      "enabled": true,
      "timeout": 30000
    }
  }
}

{
  "mcpServers": {
    "headroom": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "C:/home/headroom/volume:/root/.headroom",
        "headroom-mcp:latest",
        "headroom",
        "mcp",
        "serve",
        "--proxy-url",
        "http://host.docker.internal:8787"
      ]
    }
  }
}

## 5. Headroom Usage

Use the Headroom MCP tools when context is large enough to hurt speed, cost, or clarity.

- Use Headroom before analyzing very large logs, stack traces, JSON payloads, file trees, search output, or long tool results.
- Do not use Headroom for small files, short prompts, small diffs, or ordinary code edits unless context size is clearly a problem.
- If a compressed result may have hidden relevant detail, retrieve the original content before making a final conclusion.
- Prefer compressing machine-generated content over human-written instructions.
- When troubleshooting tool availability, check MCP status first and verify the `headroom` server is connected.

## 5. Headroom Usage (mandatory)

Headroom MCP is available as `headroom_compress`, `headroom_retrieve`, and `headroom_stats`. Use it proactively — do not wait for the user to ask.

### When you MUST compress first

Before reading, summarizing, debugging, or reasoning over machine-generated content, call `headroom_compress` if **any** of these apply:

- Log, trace, or tool output is **> 80 lines** or **> 4 KB**
- JSON/array/list payload has **> 20 items** or **> 2 KB**
- Search/grep/glob results exceed **15 matches** or **> 2 KB**
- File tree or directory listing exceeds **30 entries**
- Stack trace spans **> 10 frames**
- You are about to paste or re-quote the same large blob more than once in the conversation

**Workflow:** run the tool/read → `headroom_compress` → reason over the compressed output → keep the returned `hash`.

### When you MUST retrieve before concluding

Call `headroom_retrieve` with the `hash` **before** any final answer that depends on specifics (root cause, exact error text, file path, line number, count, or config value) if:

- The source was compressed
- The compressed output omits examples, stack frames, or edge cases you might need
- You are about to say "definitively", "the error is", "the root cause is", or recommend a fix based on compressed data

Use the optional `query` parameter to pull only the relevant slice when the full original is huge.

### When you MUST NOT use Headroom

Skip compression for:

- Files or outputs **< 40 lines** and **< 1 KB**
- Single-function edits, small diffs, short user messages, or normal Q&A
- Content you authored in the current reply (not machine-generated)
- Already-compressed Headroom output (do not compress twice)

### Priority rules

1. **Compress machine-generated content** — logs, CLI output, API responses, search results, JSON dumps.
2. **Never compress** user instructions, AGENTS.md, or task requirements.
3. **Prefer compress → analyze → retrieve** over loading huge raw blobs into context.
4. At the start of a large-context task, call `headroom_stats` once if you need to confirm the server is connected.

### If Headroom is unavailable

If `headroom` MCP tools fail: say so explicitly, fall back to smaller targeted reads (offset/limit, grep, head/tail), and do not silently pretend compression happened.