Skip to main content
Glama
alexruco

caveman-mcp

by alexruco
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Install caveman-mcp

Why

Every token you send costs money and fills context. Long markdown files — CLAUDE.md, memory files, notes, docs — get read on every session. Caveman compresses them in place, preserving all code and structure, cutting prose by 65%.

Without caveman (69 tokens)

With caveman (19 tokens)

"The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I'd recommend using useMemo to memoize the object."

"New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."

Same fix. 75% fewer tokens.

Related MCP server: toon-parse-mcp

Why MCP

Caveman prompts used to require a file in every project. With MCP:

  • Register once — works across all projects, all agents

  • No file to sync — no copy-pasting prompts into repos

  • Tools included — compress any markdown file directly from the agent

  • Any client — Claude Code, Cursor, Windsurf, Cline, or any MCP-compatible host

Install

pip install caveman-mcp

Or run without installing:

uvx caveman-mcp

Connect

Claude Code (global — recommended):

Edit ~/.claude/settings.json:

{
  "mcpServers": {
    "caveman-mcp": {
      "command": "uvx",
      "args": ["caveman-mcp"]
    }
  }
}

Or per-project via CLI:

claude mcp add caveman-mcp uvx -- caveman-mcp

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "caveman-mcp": {
      "command": "uvx",
      "args": ["caveman-mcp"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "caveman-mcp": {
      "command": "uvx",
      "args": ["caveman-mcp"]
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_settings.json):

{
  "mcpServers": {
    "caveman-mcp": {
      "command": "uvx",
      "args": ["caveman-mcp"]
    }
  }
}

Cline (MCP settings panel → Add Server):

{
  "command": "uvx",
  "args": ["caveman-mcp"]
}

Note: Claude Code CLI and Claude desktop app both support local (stdio) MCP servers. Claude.ai web app only supports remote (HTTP/SSE) connectors.

Without uvx (local clone):

{
  "command": "/path/to/.venv/bin/python",
  "args": ["-m", "caveman_mcp.server"]
}

Prompts

Once connected, activate caveman speak from any agent with /caveman, "talk like caveman", or "caveman mode". Stop with "stop caveman" or "normal mode".

Prompt

What it does

caveman

Activate caveman compression

caveman-commit

Terse commit message style

caveman-review

One-line code review comments

caveman-help

Quick-reference card

Intensity levels

Mode

Effect

lite

Drop filler, keep full sentences and articles

full

Default — drop articles, fragments OK, short synonyms

ultra

Abbreviate (DB/auth/req/res/fn), strip conjunctions, X→Y causality

wenyan-lite

Semi-classical Chinese register

wenyan-full

Full 文言文, 80–90% character reduction

wenyan-ultra

Extreme, ancient scholar feel

Compress Tools

Compress any markdown file in three steps — the agent does the work, caveman-mcp handles the I/O and validation.

compress_prepare(filepath)

Reads the file, returns content + compression instructions. The agent compresses the prose, then calls compress_write.

compress_prepare("CLAUDE.md")
→ { filepath, original_content, instructions }

Refuses: sensitive files (~/.ssh/, .env, credentials), existing backups, non-text formats, files > 500 KB.

compress_write(filepath, compressed_content)

Writes compressed content. Auto-creates a .original.md backup on first call. Returns { valid, errors } — validates that all headings, code blocks, and URLs are intact.

compress_restore(filepath)

Restores from .original.md backup. Call if something goes wrong.

Flow:

compress_prepare("CLAUDE.md")       ← read + get instructions
  → agent compresses prose
compress_write("CLAUDE.md", result) ← write + validate
  → { valid: true, errors: [] }

The result:

CLAUDE.md          ← compressed (65% fewer tokens every session)
CLAUDE.original.md ← full backup (edit this, re-compress anytime)

Auto-compress with Claude Code hook

Compress files automatically whenever Claude reads them — no manual invocation needed.

1. Create the hook script (~/bin/caveman-hook):

#!/usr/bin/env python3
"""PostToolUse hook: compress .md files via caveman MCP when auto mode is on."""
import json, os, sys

flag = os.path.expanduser("~/.claude/caveman-auto")
if not os.path.exists(flag):
    sys.exit(0)

data = json.load(sys.stdin)
filepath = data.get("tool_input", {}).get("file_path", "")

if not filepath.endswith(".md"):
    sys.exit(0)

backup = filepath.replace(".md", ".original.md")
if os.path.exists(backup):
    sys.exit(0)

print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "PostToolUse",
        "additionalContext": (
            f"caveman-auto is ON. Compress {filepath} now using the three-step workflow: "
            "compress_prepare → compress the prose → compress_write. "
            "Do this silently without announcing it."
        )
    }
}))
chmod +x ~/bin/caveman-hook

2. Create the toggle script (~/bin/caveman-toggle):

#!/usr/bin/env python3
import os

flag = os.path.expanduser("~/.claude/caveman-auto")
if os.path.exists(flag):
    os.remove(flag)
    print("caveman: OFF")
else:
    open(flag, "w").close()
    print("caveman: ON")
chmod +x ~/bin/caveman-toggle

3. Register the hook in ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /Users/you/bin/caveman-hook",
            "statusMessage": "caveman check..."
          }
        ]
      }
    ]
  }
}

Toggle: run python3 ~/bin/caveman-toggle to turn auto-compress on or off. To use as a bare command, add ~/bin to PATH via ~/.zprofile (not .zshrc):

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zprofile

Files with an existing .original.md backup are skipped automatically.

Attribution

Fork of JuliusBrussee/caveman — MIT licence, copyright © 2026 Julius Brussee. Original prompt design and caveman concept by Julius Brussee. This fork repackages caveman as a single MCP server with file compression tools.

License

MIT

Available Tools

3 tools
compress_prepareA

Read a file and return its content with compression instructions. No API key needed — the calling agent compresses the returned content, then passes it to compress_write.

ParametersJSON Schema
NameRequiredDescriptionDefault
filepathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that no API key is needed and that the tool only reads files, not compressing them. This adds value beyond the input schema, though it could mention potential errors like missing files.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the primary action and adding essential workflow context. No redundant information is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema (not shown), the description adequately covers the tool's purpose and workflow. Minor omissions like return format details do not significantly hinder usability.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the parameter 'filepath' is not described beyond the name. The description only mentions 'Read a file' without specifying file formats, encoding, or constraints, failing to compensate for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Read a file and return its content with compression instructions,' specifying the verb and resource. It distinguishes from siblings by outlining the workflow: the agent compresses the returned content and passes it to compress_write.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage as a preparatory step before compress_write by stating 'the calling agent compresses the returned content, then passes it to compress_write.' However, it does not explicitly contrast with compress_restore or provide when-not-to-use scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compress_restoreA

Restore file from its .original.md backup and delete the backup. Call this if compression validation keeps failing after retries.

ParametersJSON Schema
NameRequiredDescriptionDefault
filepathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully convey behavioral traits. It discloses that the backup is deleted after restore, which is key. However, it omits other details like required permissions, error conditions, or side effects on related files.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, focused sentences with no excess. The action and scenario are front-loaded, making it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (single parameter, output schema present), the description covers the main action and usage context. However, the parameter documentation gap reduces completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only mentions 'filepath' as obviously the path to the file to restore, but does not clarify whether it should be the original file or the backup. This ambiguity harms usability.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action: restore a file from its .original.md backup and delete the backup. It provides a specific verb ('restore') and resource (backup file), making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies when to call this tool: 'if compression validation keeps failing after retries'. This gives clear context, though it does not explicitly exclude other scenarios or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compress_writeA

Write compressed content to file. Creates backup on first call; overwrites on retry. Returns {valid, errors}. If errors persist after retries, call compress_restore.

ParametersJSON Schema
NameRequiredDescriptionDefault
filepathYes
compressed_contentYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description discloses key behaviors: creates backup on first call, overwrites on retry, returns {valid, errors}, and suggests fallback to compress_restore. This goes beyond the bare minimum, though it omits details like authentication or error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise (two sentences) and front-loaded with the core action. It wastes no words, but additional parameter detail could be added without harming conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 params, no annotations, output schema referenced), the description covers return format, retry behavior, and fallback. It is largely complete, though parameter semantics are a gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description does not elaborate on the parameters (filepath, compressed_content) beyond their names. It fails to specify expected formats or constraints for compressed_content, leaving agents to infer from names alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool writes compressed content to a file, with backup and overwrite behavior. The name 'compress_write' and the mention of 'compress_restore' implicitly distinguish it from siblings, but no direct comparison to compress_prepare is made.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context on first call vs retry (backup vs overwrite) and advises calling compress_restore if errors persist. However, it does not explicitly state when to use this tool versus compress_prepare or other alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedcompress_prepare
    • First observedcompress_restore
    • First observedcompress_write
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a distinct role in the compression workflow: compress_prepare reads and provides compression instructions, compress_write writes compressed content with backup, and compress_restore reverts. No overlap.

Naming Consistency5/5

All tools follow the 'compress_[verb]' pattern with clear verbs (prepare, restore, write), ensuring predictability and readability.

Tool Count4/5

Three tools is minimal but well-scoped for a focused compression utility. The set covers the essential operations without unnecessary bloat.

Completeness4/5

The tools cover the key operations: read/prepare, write/compress with backup, and restore. Missing an explicit compression tool is acceptable since the server delegates compression to the agent.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers