compresh-mcp 0.1.0__tar.gz

compresh_mcp-0.1.0/LICENSE

@@ -0,0 +1,34 @@
+Business Source License 1.1
+
+License text Copyright (c) 2026 Compresh Ltd.
+
+Parameters
+
+Licensor:               Compresh Ltd
+Licensed Work:          compresh-mcp (this distribution)
+Additional Use Grant:   You may use the Licensed Work in non-production
+                        environments. Production use requires a valid
+                        Compresh subscription — see https://compre.sh/pricing
+Change Date:            2030-05-16
+Change License:         MIT License
+
+For information about alternative licensing arrangements, contact
+hello@compre.sh.
+
+---
+
+Notice
+
+The Business Source License (this document, or the "License") is not an
+Open Source license. However, the Licensed Work will eventually be made
+available under an Open Source License, as stated in this License.
+
+Full BSL 1.1 text: https://mariadb.com/bsl11/
+
+---
+
+Patent notice
+
+Q-protective ranking + Protection Zone are covered by TR-TPMK patent
+application 2026/007305 (Compresh Ltd, May 2026). A valid Compresh
+subscription includes implementation license for the covered claims.

compresh_mcp-0.1.0/NOTICES.md

@@ -0,0 +1,38 @@
+# Third-Party Notices
+
+This package, `compresh-mcp` (BUSL-1.1), bundles third-party code.
+
+---
+
+## tulbase (MIT)
+
+The `compresh_mcp.tulbase` subpackage is a vendored copy of
+[tulbase](https://github.com/compresh/tulbase), a depth-aware context
+compression library for LLM proxies.
+
+- **License**: MIT
+- **Copyright**: © 2026 Compresh Ltd
+- **Upstream**: https://github.com/compresh/tulbase
+- **Vendored version**: 0.2.0
+- **License text**: see `src/compresh_mcp/tulbase/LICENSE`
+
+The vendored copy is the canonical reference implementation. The standalone
+`tulbase` PyPI package (when published) will contain identical code. Vendoring
+exists to keep `compresh-mcp` self-contained on PyPI without forcing a
+separate dependency.
+
+If you only need the MIT open-core compression layer (turn-box, protection zone,
+compose, retrieval) without the Compresh paid-tier TUL 1.0 classifiers, prefer
+installing the standalone package once it ships:
+
+```bash
+pip install tulbase
+```
+
+---
+
+## Acknowledgements
+
+- [Model Context Protocol](https://modelcontextprotocol.io/) — Anthropic
+- [sentence-transformers](https://www.sbert.net/) — UKPLab (MIT)
+- [DuckDB](https://duckdb.org/) — DuckDB Foundation (MIT)

compresh_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: compresh-mcp
+Version: 0.1.0
+Summary: MCP server for Compresh — production-grade context compression with Q-protective ranking, epistemic markers, and depth-aware adaptation
+Author-email: Compresh Ltd <hello@compre.sh>
+License: BUSL-1.1
+Project-URL: Homepage, https://compre.sh
+Project-URL: Documentation, https://compre.sh/docs
+Project-URL: Issues, https://github.com/compresh/compresh-mcp/issues
+Keywords: mcp,model-context-protocol,llm,agent,context-compression,compresh,q-protective,epistemic,tulving
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICES.md
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: duckdb>=0.10.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: scikit-learn>=1.3.0
+Provides-Extra: tokenizer
+Requires-Dist: tiktoken>=0.5.0; extra == "tokenizer"
+Provides-Extra: summarizer
+Requires-Dist: sumy>=0.11.0; extra == "summarizer"
+Requires-Dist: nltk>=3.8.0; extra == "summarizer"
+Provides-Extra: injection
+Requires-Dist: torch>=2.0.0; extra == "injection"
+Requires-Dist: transformers>=4.30.0; extra == "injection"
+Provides-Extra: proxy
+Requires-Dist: fastapi>=0.100.0; extra == "proxy"
+Requires-Dist: uvicorn>=0.23.0; extra == "proxy"
+Provides-Extra: verify
+Requires-Dist: tiktoken>=0.7.0; extra == "verify"
+Requires-Dist: transformers>=4.40.0; extra == "verify"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# compresh-mcp
+
+**MCP server for Compresh** — production-grade context compression for LLM agent conversations.
+
+> Compresh adds Q-protective ranking, epistemic marker classification, and
+> depth-aware adaptation on top of the open-source [`tulbase`](https://github.com/compresh/tulbase)
+> compression core. This is the **paid tier** distribution.
+
+## 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
+
+See [https://compre.sh/pricing](https://compre.sh/pricing). Three tiers:
+
+- **Tier-A** (integrated MCP/OAuth metadata, e.g. Cowork, Claude Code, Cursor):
+  saving-share **%25** on actual model cost
+- **Tier-B** (family-level provider declaration):
+  saving-share **%25** on the family's cheapest model price
+- **Tier-C** (anonymous / local LLM / free models):
+  flat **$0.20 per 1M saved input tokens**
+
+Every new user: **$30 free credit** (90-day expiry), **$10 minimum budget**
+(charged $7.5 after standard %25 discount).
+
+## Installation
+
+```bash
+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](https://compre.sh/signup)
+automatically.
+
+## MCP client configuration
+
+### Claude Code (`~/.claude/mcp.json`)
+
+```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](./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
+
+This repo is **private** during dogfood phase (May 2026). Public release
+scheduled for Q3 2026 alongside the Compresh dashboard MVP.

compresh_mcp-0.1.0/README.md

@@ -0,0 +1,105 @@
+# compresh-mcp
+
+**MCP server for Compresh** — production-grade context compression for LLM agent conversations.
+
+> Compresh adds Q-protective ranking, epistemic marker classification, and
+> depth-aware adaptation on top of the open-source [`tulbase`](https://github.com/compresh/tulbase)
+> compression core. This is the **paid tier** distribution.
+
+## 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
+
+See [https://compre.sh/pricing](https://compre.sh/pricing). Three tiers:
+
+- **Tier-A** (integrated MCP/OAuth metadata, e.g. Cowork, Claude Code, Cursor):
+  saving-share **%25** on actual model cost
+- **Tier-B** (family-level provider declaration):
+  saving-share **%25** on the family's cheapest model price
+- **Tier-C** (anonymous / local LLM / free models):
+  flat **$0.20 per 1M saved input tokens**
+
+Every new user: **$30 free credit** (90-day expiry), **$10 minimum budget**
+(charged $7.5 after standard %25 discount).
+
+## Installation
+
+```bash
+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](https://compre.sh/signup)
+automatically.
+
+## MCP client configuration
+
+### Claude Code (`~/.claude/mcp.json`)
+
+```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](./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
+
+This repo is **private** during dogfood phase (May 2026). Public release
+scheduled for Q3 2026 alongside the Compresh dashboard MVP.

compresh_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,99 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "compresh-mcp"
+version = "0.1.0"
+description = "MCP server for Compresh — production-grade context compression with Q-protective ranking, epistemic markers, and depth-aware adaptation"
+readme = "README.md"
+license = { text = "BUSL-1.1" }
+authors = [
+    { name = "Compresh Ltd", email = "hello@compre.sh" },
+]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "llm",
+    "agent",
+    "context-compression",
+    "compresh",
+    "q-protective",
+    "epistemic",
+    "tulving",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "mcp >= 1.0.0",
+    "duckdb >= 0.10.0",
+    "httpx >= 0.24.0",
+    "sentence-transformers >= 2.2.0",
+    "scikit-learn >= 1.3.0",
+]
+
+[project.optional-dependencies]
+# tulbase tokenizer (cost counter)
+tokenizer = [
+    "tiktoken >= 0.5.0",
+]
+# tulbase summarizer (LexRank — recommended for production)
+summarizer = [
+    "sumy >= 0.11.0",
+    "nltk >= 3.8.0",
+]
+# tulbase injection detector (heavy ML deps)
+injection = [
+    "torch >= 2.0.0",
+    "transformers >= 4.30.0",
+]
+# tulbase FastAPI proxy mode (not needed for MCP stdio usage)
+proxy = [
+    "fastapi >= 0.100.0",
+    "uvicorn >= 0.23.0",
+]
+verify = [
+    "tiktoken >= 0.7.0",
+    "transformers >= 4.40.0",
+]
+dev = [
+    "pytest >= 8.0",
+    "pytest-asyncio >= 0.23",
+    "ruff >= 0.4",
+    "mypy >= 1.10",
+]
+
+[project.urls]
+Homepage = "https://compre.sh"
+Documentation = "https://compre.sh/docs"
+Issues = "https://github.com/compresh/compresh-mcp/issues"
+
+[project.scripts]
+compresh-mcp = "compresh_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+compresh_mcp = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "C4", "SIM", "RUF"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

compresh_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

compresh_mcp-0.1.0/src/compresh_mcp/__init__.py

@@ -0,0 +1,26 @@
+"""compresh-mcp — MCP server for Compresh paid tier.
+
+Bundles the open-source tulbase compression core (MIT, vendored as
+``compresh_mcp.tulbase``) and adds the proprietary TUL 1.0 layer:
+
+    - Q-protective sentence ranking (Q1-Q4 categorization)
+    - Epistemic marker classification (VR/HR/CR/UC)
+    - Semantic store (cross-turn Q3 dedup)
+    - Auth + saving telemetry to Compresh dashboard
+
+The vendored tulbase code is the canonical reference (MIT, © Compresh Ltd 2026,
+see ``tulbase/LICENSE``). For the standalone tulbase distribution, see
+https://github.com/compresh/tulbase.
+
+For pricing and account management, see https://compre.sh.
+"""
+
+from . import tulbase
+
+__version__ = "0.1.0"
+__author__ = "Compresh Ltd"
+__license__ = "BUSL-1.1"
+
+from .server import main as run_server
+
+__all__ = ["__version__", "run_server", "tulbase"]

compresh_mcp-0.1.0/src/compresh_mcp/auth.py

@@ -0,0 +1,176 @@
+"""Compresh API key validation + usage telemetry.
+
+The MCP server validates the user's COMPRESH_API_KEY against the
+Compresh production API at startup, then reports per-session savings
+back so the dashboard reflects local usage.
+
+The Compresh API base URL is configurable via COMPRESH_API_BASE
+(default: https://api.compre.sh) — useful for staging/dev environments.
+
+Validation flow:
+
+    1. Read COMPRESH_API_KEY from environment.
+    2. If missing/empty -> raise NoApiKey (caller triggers onboarding flow).
+    3. POST to /v1/auth/verify with Bearer token.
+    4. If 200 -> cache validated key + user info for session lifetime.
+    5. If 401/403 -> raise InvalidApiKey (caller may re-prompt).
+    6. If network failure -> raise AuthNetworkError (caller may proceed
+       in offline mode with a warning).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+import httpx
+
+logger = logging.getLogger("compresh-mcp.auth")
+
+DEFAULT_API_BASE = os.environ.get("COMPRESH_API_BASE", "https://api.compre.sh")
+DEFAULT_TIMEOUT = float(os.environ.get("COMPRESH_AUTH_TIMEOUT", "10"))
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class AuthError(Exception):
+    """Base class for auth failures."""
+
+
+class NoApiKey(AuthError):
+    """COMPRESH_API_KEY environment variable missing or empty."""
+
+
+class InvalidApiKey(AuthError):
+    """API key was rejected by the Compresh server (401/403)."""
+
+
+class AuthNetworkError(AuthError):
+    """Network or unexpected error while contacting Compresh server."""
+
+
+# ---------------------------------------------------------------------------
+# Result dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class AuthResult:
+    """Outcome of a successful key validation."""
+
+    ok: bool
+    api_key: str
+    email: Optional[str] = None
+    tier: Optional[str] = None  # "free" | "pro"
+    free_credit_remaining: Optional[float] = None
+    budget_remaining: Optional[float] = None
+    error: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def get_api_key() -> Optional[str]:
+    """Read COMPRESH_API_KEY from environment, return None if missing/empty."""
+    key = (os.environ.get("COMPRESH_API_KEY") or "").strip()
+    return key or None
+
+
+def verify_api_key(
+    api_key: Optional[str] = None,
+    *,
+    api_base: str = DEFAULT_API_BASE,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> AuthResult:
+    """Validate an API key against the Compresh server.
+
+    Raises:
+        NoApiKey: key is missing/empty.
+        InvalidApiKey: key was rejected (401/403).
+        AuthNetworkError: transport-level failure (caller decides whether
+            to proceed in offline mode).
+    """
+    key = api_key or get_api_key()
+    if not key:
+        raise NoApiKey("COMPRESH_API_KEY environment variable is not set")
+
+    url = f"{api_base.rstrip('/')}/v1/auth/verify"
+    headers = {"Authorization": f"Bearer {key}", "Accept": "application/json"}
+
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            resp = client.get(url, headers=headers)
+    except httpx.HTTPError as e:
+        logger.warning("auth network error: %s", e)
+        raise AuthNetworkError(f"network error: {type(e).__name__}: {e}") from e
+
+    if resp.status_code in (401, 403):
+        logger.info("auth rejected: %d", resp.status_code)
+        raise InvalidApiKey(f"server rejected key (HTTP {resp.status_code})")
+
+    if resp.status_code != 200:
+        logger.warning("auth unexpected status: %d", resp.status_code)
+        raise AuthNetworkError(f"unexpected HTTP {resp.status_code}")
+
+    data = resp.json() if resp.content else {}
+    return AuthResult(
+        ok=True,
+        api_key=key,
+        email=data.get("email"),
+        tier=data.get("tier"),
+        free_credit_remaining=data.get("free_credit_remaining"),
+        budget_remaining=data.get("budget_remaining"),
+    )
+
+
+def report_usage(
+    api_key: str,
+    *,
+    session_id: str,
+    saved_input_tokens: int,
+    saved_chars: int,
+    n_turns: int,
+    n_compressed_entries: int,
+    provider_hint: Optional[str] = None,
+    model_hint: Optional[str] = None,
+    api_base: str = DEFAULT_API_BASE,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> bool:
+    """Send a per-session usage report to Compresh for billing/telemetry.
+
+    Returns True on 2xx, False otherwise. Failures are non-fatal — local
+    compression continues, telemetry catches up at the next successful
+    report.
+    """
+    url = f"{api_base.rstrip('/')}/v1/usage/report"
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+    payload = {
+        "session_id": session_id,
+        "saved_input_tokens": saved_input_tokens,
+        "saved_chars": saved_chars,
+        "n_turns": n_turns,
+        "n_compressed_entries": n_compressed_entries,
+        "provider_hint": provider_hint,
+        "model_hint": model_hint,
+        "source": "compresh-mcp",
+    }
+
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            resp = client.post(url, headers=headers, json=payload)
+        if 200 <= resp.status_code < 300:
+            return True
+        logger.warning("usage report rejected: %d", resp.status_code)
+    except httpx.HTTPError as e:
+        logger.warning("usage report network error: %s", e)
+    return False