tokenslim-mcp

tokenslim-mcp

MCP server exposing the tokenslim context-compression engine to any MCP host (Claude Code, Cursor, …). Stdio transport, built on the official Python mcp SDK (FastMCP).

Tools

| Tool | Args | Returns | | --- | --- | --- | | tokenslim_compress | content: str, content_type?: str | Compressed text, CCR hash, changed, and stats (orig_tokens / new_tokens / saved_tokens / ratio). | | tokenslim_retrieve | hash: str | { found, hash, content } — the original blob, or found: false if unknown to this session. | | tokenslim_stats | — | Cumulative session savings: compressions, orig_tokens, new_tokens, saved_tokens, ratio. |

content_type is an advisory hint echoed back; the core auto-detects the real type (JSON / log / code / diff / search / markdown / text) and picks a compressor.

Install & register

pip install -e .   # pulls the tokenslim core via git

Register as a stdio MCP server. Example (Claude Code mcpServers):

{
  "mcpServers": {
    "tokenslim": { "command": "tokenslim-mcp" }
  }
}

or run directly: tokenslim-mcp / python -m tokenslim_mcp.

How it works

Each tokenslim_compress call wraps the blob as a one-message array, runs it through the core compress() (with min_bytes=0 so single blobs always get compressed), and returns the rewritten text plus token stats. The original is stored under its tokenslim.ccr.content_hash so tokenslim_retrieve can return it verbatim. tokenslim_stats reports the running total.

Development

pip install -e ".[dev]"
ruff check .
python -m pytest -q

Tests call the tool handlers directly and exercise the FastMCP dispatch — no live MCP host or API keys required.

Known gaps

• Retrieval store is in-process. The core ships CCR markers + content_hash

but not yet a retrieve() / persistent store on main, so retrieval is backed by a per-session dict populated by tokenslim_compress. Hashes already use the core's content_hash, so this will switch to the core CCR store once merged (TODO(core-ccr) in engine.py). A hash from a previous process (or another server instance) will report found: false.

• Compression depth is whatever the core provides; this server adds no

algorithms of its own.

License

Apache-2.0