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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
docs: align MCP proxy docs with implemented API (#614)
Andrew Barnes45b07bf754c7
diff --git a/docs/spec/005-integrations.md b/docs/spec/005-integrations.mdindex 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:**```pythonclass 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.pyindex 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 setupsThe key insight: MCP tool outputs are the PERFECT use case for Headroom.They're often large (100s-1000s of items), structured (JSON), and containmostly 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