compresh-mcp

MCP server for Compresh — production-grade context compression for LLM agent conversations.

Compresh adds query-aware retrieval (TUL 2.0) on top of the open-source tulbase compression core. Instead of summarizing older turns, it retrieves the turns relevant to the current question — lossless and role-tagged — from the full conversation history. This is the paid tier distribution.

Architecture (0.3.0+)

• Local: bundled tulbase (MIT, vendored as compresh_mcp.tulbase) runs on every turn for fast compression + cold-storage support (fetch_compressed / list_compressed MCP tools).
• Server: the TUL 2.0 paid layer (query-aware retrieval over full history, role-preserving render) runs on Compresh infrastructure via the /v1/tul2 endpoint, gated by your Compresh API key + tier.
• Degraded mode: if /v1/tul2 is unreachable, compresh-mcp transparently falls back to the local tulbase result so compression never blocks.

The paid endpoint was the legacy /v1/tul1 through 0.2.x; 0.3.0 calls the canonical /v1/tul2 (the TUL 1.0 Q-matrix layer was retired in the 15 Jun 2026 retrieval pivot). The server keeps /v1/tul1 as a deprecated alias, so older clients keep working. Previously (0.1.0, yanked), paid classifiers shipped inside the client package and leaked paid features locally — install 0.3.0 or later. See CHANGELOG.md.

What's the difference vs tulbase-mcp?

Feature	tulbase-mcp (free, open-source)	compresh-mcp (paid)
Base LexRank summarization	✅	✅
Modality elision (code, terminal, JSON, stack traces)	✅	✅
Cold storage + fetch_compressed	✅	✅
Protection Zone (Claim 1e)	✅	✅
Q-protective sentence ranking (Q1–Q4 categorization)	❌	✅
Epistemic markers (VR/HR/CR/UC)	❌	✅
Semantic store (cross-turn Q3 dedup)	❌	✅
Saving telemetry to Compresh dashboard	❌	✅
Multi-device sync (planned)	❌	✅

In Compresh's bench (Compresh-bench v1, 600-turn multi-model), Q-protective ranking adds 5–12 percentage points of equivalence preservation vs base LexRank at the same token savings — Pareto improvement.

Pricing

Plan	Period	Saving-share
Starter (free + budget loaded)	pay-as-you-go	30%
Pro Quarterly ($18)	3 mo	20%
Pro Semi-Annual ($33)	6 mo	16%
Pro Annual ($60)	1 yr	12%
Anonymous / free / local LLM	—	0% (free, tulbase only)

Every new user: $30 free credit (90-day expiry), $10 minimum top-up (charged $7.50 with a permanent 25% discount on top-ups).

Saving-share is the cut Compresh takes on the savings measured against the user's chosen model. The base value comes from the actual model price (when known) or the provider family's cheapest model; anonymous / free-model usage falls back to a flat $0.20 / 1M saved input tokens.

See compre.sh/pricing for the canonical pricing page.

Installation

pip install compresh-mcp

On first run, you'll be prompted for your Compresh API key. If you don't have an account, your browser opens to compre.sh/signup automatically.

MCP client configuration

Claude Code (~/.claude/mcp.json)

{
  "mcpServers": {
    "compresh": {
      "command": "compresh-mcp",
      "env": {
        "COMPRESH_API_KEY": "sk-comp_...",
        "COMPRESH_API_BASE": "https://api.compre.sh"
      }
    }
  }
}

Cursor (~/.cursor/mcp.json)

Same structure as Claude Code.

Cowork

Cowork → Settings → Tools → MCP servers → Add:

• Command: compresh-mcp
• Environment: COMPRESH_API_KEY=sk-comp_...

Tools exposed

Same four tools as tulbase-mcp, with enhanced behavior:

• compress — Q-protective compression by default (protection_mode="balanced")
• fetch_compressed, list_compressed, stats — same interface

Plus paid-tier extras:

• usage — current cycle budget, free credit balance, savings metrics

License

Business Source License 1.1 — see LICENSE. Production use permitted with valid Compresh API key. License automatically converts to MIT after 4 years (Year 2030).

Patents

Q-protective sentence ranking + Protection Zone are covered by TR-TPMK patent application 2026/007305 (Compresh Ltd, May 2026). A valid Compresh subscription grants implementation license.

Status

v0.1.0 — first public release, May 2026. Active development. APIs may change before v1.0. Issues and pull requests welcome.

Links

• compre.sh — product site
• Documentation — full reference
• GitHub — source
• Issues — bug reports
• tulbase (open core, MIT) — standalone