Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

docs: align MCP proxy docs with implemented API (#614)

Andrew Barnes45b07bf754c7
diff --git a/docs/spec/005-integrations.md b/docs/spec/005-integrations.md
index 0763e5e1b..8ba09b538 100644
--- a/docs/spec/005-integrations.md
+++ b/docs/spec/005-integrations.md
@@ -207,46 +207,41 @@ app.add_middleware(
---
-### MCP Server (`headroom/integrations/mcp/server.py`)
+### MCP integration helpers (`headroom/integrations/mcp/server.py`)
-Model Context Protocol server for Claude Desktop integration.
+Helpers for MCP-aware host applications and custom wrappers. This module does
+not currently ship a standalone `HeadroomMCPProxy` server implementation.
**`HeadroomMCPCompressor` class:**
```python
class HeadroomMCPCompressor:
def __init__(
self,
- headroom_url: str = "http://localhost:8787",
- api_key: str | None = None,
+ config: HeadroomConfig | None = None,
+ profiles: list[MCPToolProfile] | None = None,
+ token_counter: Callable[[str], int] | None = None,
) -> None:
- self.headroom_url = headroom_url
- self.api_key = api_key
-
- async def compress(self, messages: list[dict]) -> CompressResult:
- """MCP tool: compress"""
- pass
-
- async def get_savings(self) -> SavingsStats:
- """MCP tool: get_savings"""
- pass
+ ...
- async def get_stats(self) -> Stats:
- """MCP tool: get_stats"""
+ def compress(
+ self,
+ content: str,
+ tool_name: str,
+ tool_args: dict[str, Any] | None = None,
+ user_query: str = "",
+ ) -> MCPCompressionResult:
+ """Compress an MCP tool result."""
pass
```
-**MCP Tools:**
-- `compress` — Compress messages
-- `get_savings` — Get savings statistics
-- `get_stats` — Get compression statistics
-
-**MCP Resources:**
-- `session://headroom/sessions` — List of sessions
-- `savings://headroom/history` — Savings history
+**Companion helpers:**
+- `compress_tool_result(...)` — standalone helper for host applications
+- `HeadroomMCPClientWrapper` — wraps an MCP client and compresses tool results
+- `create_headroom_mcp_proxy(...)` — returns config for a custom wrapper/proxy
-**Configuration:**
+**Ready-to-run MCP tools server:**
```bash
-headroom mcp --port 8766
+headroom mcp serve
```
---
diff --git a/headroom/integrations/mcp/server.py b/headroom/integrations/mcp/server.py
index e002a0001..23fdf3e8f 100644
--- a/headroom/integrations/mcp/server.py
+++ b/headroom/integrations/mcp/server.py
@@ -1,25 +1,27 @@
-"""Headroom MCP Integration: Compress tool outputs from MCP servers.
+"""Headroom MCP integration helpers for compressing tool outputs.
-This module provides multiple ways to integrate Headroom with MCP:
+This module currently provides these MCP integration surfaces:
-1. HeadroomMCPProxy - A proxy server that wraps upstream MCP servers
-2. compress_tool_result() - Standalone function for host applications
-3. HeadroomMCPMiddleware - Transport-level middleware
+1. HeadroomMCPCompressor - core compression logic for MCP tool results
+2. compress_tool_result() - standalone helper for host applications
+3. HeadroomMCPClientWrapper - client wrapper that compresses tool outputs
+4. create_headroom_mcp_proxy() - configuration helper for custom proxy setups
The key insight: MCP tool outputs are the PERFECT use case for Headroom.
They're often large (100s-1000s of items), structured (JSON), and contain
mostly low-relevance data with a few critical items (errors, matches).
-Example - Proxy Server:
+Example - Custom proxy configuration:
```python
- # Configure proxy to wrap your MCP servers
- proxy = HeadroomMCPProxy(
- upstream_servers=["slack", "database", "github"],
+ # Build config for your own MCP proxy/server wrapper
+ proxy_config = create_headroom_mcp_proxy(
+ upstream_servers=[
+ ("slack", slack_server),
+ ("database", db_server),
+ ("github", github_server),
+ ],
config=HeadroomConfig(),
)
-
- # Run as MCP server - clients connect to this instead
- proxy.run()
```
Example - Standalone Function:
@@ -511,17 +513,18 @@ def create_headroom_mcp_proxy(
upstream_servers: list[tuple[str, MCPServer]],
config: HeadroomConfig | None = None,
) -> dict[str, Any]:
- """Create configuration for a Headroom MCP proxy server.
+ """Create configuration for a custom Headroom MCP proxy/server wrapper.
- This returns a configuration dict that can be used to set up
- a proxy server that wraps upstream MCP servers.
+ This returns the compressor and upstream-server mapping needed by an
+ application-defined MCP proxy/server wrapper. Headroom does not yet ship
+ a ready-to-run ``HeadroomMCPProxy`` server implementation.
Args:
upstream_servers: List of (name, server) tuples.
config: Headroom configuration.
Returns:
- Configuration dict for proxy server.
+ Configuration dict for a custom proxy/server wrapper.
Example:
```python