Repository navigation
Expand file tree
/
Copy pathmcp.py
More file actions
441 lines (375 loc) · 14.2 KB
/
Copy pathmcp.py
File metadata and controls
441 lines (375 loc) · 14.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
"""MCP (Model Context Protocol) CLI commands for Claude Code integration.
Provides commands to configure and run the Headroom MCP server, enabling
Claude Code subscription users to use CCR (Compress-Cache-Retrieve) without
needing API key access.
"""
import json
from pathlib import Path
from typing import Any
import click
from .main import main
# Default paths
CLAUDE_CONFIG_DIR = Path.home() / ".claude"
MCP_CONFIG_PATH = CLAUDE_CONFIG_DIR / "mcp.json"
# Servers registered via `claude mcp add` (user scope) live in ~/.claude.json,
# NOT in ~/.claude/mcp.json. Status must check both to avoid a false negative.
CLAUDE_JSON_PATH = Path.home() / ".claude.json"
DEFAULT_PROXY_URL = "http://127.0.0.1:8787"
DEFAULT_HTTP_HOST = "127.0.0.1"
DEFAULT_HTTP_PORT = 8788
DEFAULT_HTTP_PATH = "/mcp"
def get_headroom_command() -> list[str]:
"""Get the command to run headroom MCP server.
Returns the CLI invocation used by Claude Code config.
"""
return ["headroom", "mcp", "serve"]
def load_mcp_config() -> dict[str, Any]:
"""Load existing MCP config or return empty structure."""
if MCP_CONFIG_PATH.exists():
try:
with open(MCP_CONFIG_PATH, encoding="utf-8") as f:
result: dict[str, Any] = json.load(f)
return result
except (json.JSONDecodeError, OSError):
return {"mcpServers": {}}
return {"mcpServers": {}}
def save_mcp_config(config: dict) -> None:
"""Save MCP config, creating directory if needed."""
CLAUDE_CONFIG_DIR.mkdir(parents=True, exist_ok=True)
with open(MCP_CONFIG_PATH, "w", encoding="utf-8") as f:
json.dump(config, f, indent=2)
f.write("\n") # Trailing newline
def find_headroom_registration() -> tuple[Path, dict[str, Any]] | None:
"""Locate an existing 'headroom' MCP server registration.
Claude Code stores servers registered with `claude mcp add` (user scope) in
~/.claude.json under "mcpServers". Headroom's own `mcp install` fallback
writes ~/.claude/mcp.json, and a project may define ./.mcp.json. Check all of
them so `status` reflects reality instead of only looking at mcp.json.
Returns (config_path, server_config) for the first match, else None.
"""
for path in (CLAUDE_JSON_PATH, MCP_CONFIG_PATH, Path.cwd() / ".mcp.json"):
if not path.exists():
continue
try:
with open(path) as f:
data = json.load(f)
except (json.JSONDecodeError, OSError):
continue
servers = data.get("mcpServers", {})
if isinstance(servers, dict) and "headroom" in servers:
return path, servers["headroom"]
return None
@main.group()
def mcp() -> None:
"""MCP server for Claude Code integration.
\b
The MCP server exposes headroom_retrieve as a tool that Claude Code
can use to retrieve compressed content. This enables CCR (Compress-
Cache-Retrieve) for subscription users who don't have API access.
\b
Quick Start:
headroom mcp install # Configure Claude Code
headroom proxy # Start the proxy (in another terminal)
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude
\b
The MCP server provides on-demand tools (compress, retrieve, stats).
For automatic compression of ALL traffic, also set ANTHROPIC_BASE_URL
to route through the proxy.
\b
How it works:
1. ANTHROPIC_BASE_URL routes all requests through the proxy
2. The proxy compresses large tool outputs (file listings, search results)
3. Claude sees compressed summaries with hash markers
4. When Claude needs full details, it calls headroom_retrieve
5. The MCP server fetches original content from the proxy
\b
Note on tool naming: MCP clients display tools as
`mcp__<server>__<tool>`. Our server is named "headroom" and our
tools are named headroom_retrieve / headroom_compress / etc., so
Claude Code shows them as `mcp__headroom__headroom_retrieve`. The
"headroom" doubling is normal MCP namespacing — not a bug. The
proxy's compression markers (and any docs/prompts) reference the
bare tool name `headroom_retrieve`.
"""
pass
@mcp.command("install")
@click.option(
"--proxy-url",
default=DEFAULT_PROXY_URL,
help=f"Headroom proxy URL (default: {DEFAULT_PROXY_URL})",
)
@click.option(
"--agent",
"agents",
multiple=True,
help="Restrict installation to specific agents (default: every detected agent).",
)
@click.option(
"--force",
is_flag=True,
help="Overwrite existing headroom config in case of mismatch.",
)
def mcp_install(proxy_url: str, agents: tuple[str, ...], force: bool) -> None:
"""Install the Headroom MCP server into every detected coding agent.
\b
By default this installs into every agent that has a registrar and is
detected on this system (Claude Code today; Cursor / Codex / Continue /
others added in subsequent releases). Pass ``--agent NAME`` one or more
times to restrict the installation.
\b
Examples:
headroom mcp install # every detected agent
headroom mcp install --agent claude # Claude Code only
headroom mcp install --proxy-url http://localhost:9000
"""
try:
import mcp # noqa: F401
except ImportError:
click.echo("Error: MCP SDK not installed.", err=True)
click.echo("Install with: pip install 'headroom-ai[mcp]'", err=True)
raise SystemExit(1) from None
from headroom.mcp_registry import any_succeeded, format_results, install_everywhere
results = install_everywhere(
proxy_url=proxy_url,
agents=list(agents) if agents else None,
force=force,
)
if not results:
click.echo("No agents matched the requested filter.")
raise SystemExit(1)
click.echo("Installing Headroom MCP server...")
for line in format_results(
results,
verbose=True,
overwrite_hint=f"headroom mcp install --proxy-url {proxy_url} --force",
):
click.echo(line)
if not any_succeeded(results):
raise SystemExit(1)
click.echo(
f"\nNext steps:\n"
f" 1. Start the Headroom proxy (if not running): headroom proxy\n"
f" 2. Start your agent (e.g.) ANTHROPIC_BASE_URL={proxy_url} claude\n"
f" 3. Restart any agent that was already running so it picks up the new MCP server.\n"
)
@mcp.command("uninstall")
def mcp_uninstall() -> None:
"""Remove Headroom MCP server from detected agent configs.
\b
Removes headroom from every agent registrar known to Headroom. Other MCP
servers are preserved.
"""
from headroom.mcp_registry import get_all_registrars
removed = False
for registrar in get_all_registrars():
if not registrar.detect():
continue
removed_names: list[str] = []
for server_name in ("headroom", "codebase-memory-mcp"):
if registrar.unregister_server(server_name):
removed_names.append(server_name)
if removed_names:
click.echo(
f"✓ {registrar.display_name}: removed {', '.join(removed_names)} MCP server(s)"
)
removed = True
if not removed:
click.echo("Headroom MCP is not configured. Nothing to uninstall.")
@mcp.command("reconcile")
@click.option("--adopt", is_flag=True, help="Replace only the Serena entry with Headroom's spec.")
def mcp_reconcile(adopt: bool) -> None:
"""Inspect or explicitly reconcile a user-managed Serena MCP entry."""
from headroom.mcp_registry import (
CLAUDE_SERENA_CONTEXT,
ClaudeConfigMutationError,
ClaudeRegistrar,
RegisterStatus,
build_serena_spec,
)
from headroom.mcp_registry.ledger import (
LedgerMutationError,
record_install,
validate_ledger_for_mutation,
)
registrar = ClaudeRegistrar()
if not registrar.detect():
raise click.ClickException("claude is not detected")
recommended = build_serena_spec(CLAUDE_SERENA_CONTEXT)
observed = registrar.get_server("serena")
if adopt:
try:
registrar.validate_configs_for_mutation()
validate_ledger_for_mutation()
except (ClaudeConfigMutationError, LedgerMutationError) as exc:
raise click.ClickException(str(exc)) from exc
if adopt:
result = registrar.register_server(recommended, force=True)
if result.status not in (RegisterStatus.REGISTERED, RegisterStatus.ALREADY):
raise click.ClickException(result.detail or "could not adopt Serena configuration")
record_install("claude", recommended)
click.echo(
"Adopted Headroom's Serena configuration for Claude; unrelated config preserved."
)
return
click.echo("Serena reconciliation for Claude")
click.echo(f" observed: {'absent' if observed is None else 'present'}")
click.echo(f" recommendation: {recommended.command} {' '.join(recommended.args)}")
if observed is not None and observed != recommended:
click.echo(" action: use --adopt to replace it")
@mcp.command("status")
def mcp_status() -> None:
"""Check Headroom MCP configuration status.
\b
Shows whether headroom is configured in Claude Code and if
the proxy is reachable.
"""
click.echo("Headroom MCP Status")
click.echo("=" * 40)
# Check MCP SDK
try:
import mcp # noqa: F401
click.echo("MCP SDK: ✓ Installed")
except ImportError:
click.echo("MCP SDK: ✗ Not installed")
click.echo(" pip install 'headroom-ai[mcp]'")
from headroom.mcp_registry import get_all_registrars
proxy_url = DEFAULT_PROXY_URL
any_configured = False
click.echo("Agent Config:")
for registrar in get_all_registrars():
if not registrar.detect():
click.echo(f" {registrar.display_name}: ✗ Not detected")
continue
spec = registrar.get_server("headroom")
if spec is None:
click.echo(f" {registrar.display_name}: ✗ Not configured")
continue
any_configured = True
proxy_url = spec.env.get("HEADROOM_PROXY_URL", proxy_url)
click.echo(f" {registrar.display_name}: ✓ Configured")
if not any_configured:
click.echo(" Run: headroom mcp install")
click.echo(f"Proxy URL: {proxy_url}")
# Check proxy connectivity
try:
import httpx
try:
response = httpx.get(f"{proxy_url}/health", timeout=2.0)
if response.status_code == 200:
click.echo(f"Proxy Status: ✓ Running at {proxy_url}")
else:
click.echo(f"Proxy Status: ✗ Unhealthy (status {response.status_code})")
except httpx.ConnectError:
click.echo("Proxy Status: ✗ Not running")
click.echo(" Run: headroom proxy")
except httpx.TimeoutException:
click.echo("Proxy Status: ✗ Timeout")
except httpx.HTTPError as e:
# Catch the rest (InvalidURL, UnsupportedProtocol, ProtocolError, …)
# so a malformed configured HEADROOM_PROXY_URL can't crash `status`.
click.echo(f"Proxy Status: ✗ Unreachable ({proxy_url}: {e})")
except ImportError:
click.echo("Proxy Status: ? (httpx not installed)")
@mcp.command("serve")
@click.option(
"--proxy-url",
default=None,
envvar="HEADROOM_PROXY_URL",
help=f"Headroom proxy URL (default: {DEFAULT_PROXY_URL})",
)
@click.option(
"--transport",
type=click.Choice(["stdio", "http"], case_sensitive=False),
default="stdio",
show_default=True,
help="Transport to use for headroom mcp serve",
)
@click.option(
"--host",
default=DEFAULT_HTTP_HOST,
show_default=True,
help="HTTP bind host",
)
@click.option(
"--port",
default=DEFAULT_HTTP_PORT,
show_default=True,
type=int,
help="HTTP bind port",
)
@click.option(
"--path",
default=DEFAULT_HTTP_PATH,
show_default=True,
help="HTTP endpoint path",
)
@click.option(
"--direct",
is_flag=True,
help="(Deprecated, ignored) Direct CompressionStore access is no longer supported",
)
@click.option(
"--debug",
is_flag=True,
help="Enable debug logging",
)
def mcp_serve(
proxy_url: str | None,
transport: str,
host: str,
port: int,
path: str,
direct: bool,
debug: bool,
) -> None:
"""Start the MCP server (called by Claude Code).
\b
This command is typically invoked by Claude Code via the MCP config,
not run directly. It starts the MCP server with stdio by default or
Streamable HTTP when requested.
\b
For manual testing:
headroom mcp serve --debug
headroom mcp serve --transport http --host 127.0.0.1 --port 8788 --path /mcp
"""
import asyncio
import logging
# Check for MCP SDK
try:
from headroom.ccr.mcp_server import create_ccr_mcp_server
except ImportError as e:
click.echo(f"Error: MCP dependencies not installed: {e}", err=True)
click.echo("Install with: pip install 'headroom-ai[mcp]'", err=True)
raise SystemExit(1) from None
if debug:
logging.basicConfig(
level=logging.DEBUG,
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
)
else:
# Minimal logging for MCP (stdout is used for protocol)
logging.basicConfig(
level=logging.WARNING,
format="%(levelname)s: %(message)s",
)
transport = transport.lower()
# Use default if not specified
effective_proxy_url = proxy_url or DEFAULT_PROXY_URL
if direct:
click.echo(
"Warning: --direct is deprecated and ignored; MCP retrieval uses the proxy URL.",
err=True,
)
server = create_ccr_mcp_server(proxy_url=effective_proxy_url)
async def run() -> None:
try:
if transport == "http":
await server.run_streamable_http(host=host, port=port, path=path, debug=debug)
else:
await server.run_stdio()
finally:
await server.cleanup()
try:
asyncio.run(run())
except KeyboardInterrupt:
pass # Clean exit on Ctrl+C