contextforge-mcp 0.2.0__tar.gz → 0.2.1__tar.gz

contextforge_mcp-0.2.1/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: contextforge-mcp
+Version: 0.2.1
+Summary: MCP orchestrator: codebase-memory-mcp + headroom + Spec Kit
+Project-URL: Repository, https://github.com/capatinore/contextforge-mcp
+Author-email: Camilo Patiño <capatinore@github.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,code-intelligence,compression,context,llm,mcp,spec-kit
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: headroom-ai>=0.9.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# contextforge-mcp
+
+**MCP compression middleware** that connects [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) + [headroom](https://github.com/headroomlabs-ai/headroom) + [Spec Kit](https://github.com/github/spec-kit) into a unified, token-efficient workflow.
+
+## Architecture
+
+```
+Claude Code
+  ├── codebase-memory-mcp   ← graph queries (cbm_* tools)
+  │         │
+  │         └── large result
+  │                   │
+  └── contextforge-mcp  ← YOU ARE HERE
+            │
+            cf_compress_cbm(result, tool_name)
+            │
+            └── compressed result (60-95% fewer tokens)
+```
+
+**ContextForge does NOT proxy codebase-memory-mcp** — both servers run independently. The agent calls CBM for graph queries, then passes results through ContextForge for compression. This design is reliable, cross-platform, and works with any MCP client.
+
+## Install
+
+```bash
+npm install -g codebase-memory-mcp
+pip install "headroom-ai[all]"
+pip install contextforge-mcp
+```
+
+## Setup
+
+```bash
+# Health check
+contextforge-mcp doctor
+
+# Configure Claude Code (writes .mcp.json with both servers)
+contextforge-mcp install --target claude
+```
+
+## Workflow
+
+```python
+# 1. Query the graph (via codebase-memory-mcp)
+result = cbm_search_graph(name_pattern=".*Payment.*", label="Function")
+
+# 2. Compress the result (via contextforge-mcp)
+compressed = cf_compress_cbm(result=result, tool_name="search_graph")
+# → [ContextForge ✓ search_graph: 8420→612 tokens (93% saved in 45ms)]
+
+# 3. Use compressed result in your context
+# 4. Check savings
+cf_stats()
+```
+
+## Tools (9 total)
+
+### Compression
+| Tool | Description |
+|------|-------------|
+| `cf_compress_cbm(result, tool_name)` | Compress CBM tool output |
+| `cf_compress(text, hint)` | Compress arbitrary text |
+
+### Stats
+| Tool | Description |
+|------|-------------|
+| `cf_stats()` | Session token savings + cost estimate |
+| `cf_reset_stats()` | Reset session counters |
+
+### Spec Kit
+| Tool | Description |
+|------|-------------|
+| `cf_read_spec(feature_id)` | Compressed spec.md |
+| `cf_read_plan(feature_id)` | Compressed plan.md |
+| `cf_read_tasks(feature_id)` | Compressed tasks.md |
+| `cf_read_artifact(artifact, feature_id)` | Any artifact |
+| `cf_implement_context(feature_id)` | Full bundle (spec+plan+tasks) |
+| `cf_speckit_status()` | List all features + phase |
+
+## Supported CBM tool names for cf_compress_cbm
+
+`search_graph` · `search_code` · `get_architecture` · `find_dead_code` · `find_similar_code` · `get_impact` · `trace_path` · `trace_call_path` · `cypher_query` · `get_cross_service_links` · `get_node_details`
+
+## Add to CLAUDE.md
+
+```markdown
+## ContextForge MCP — Compression Workflow
+
+After EVERY codebase-memory-mcp tool call that returns a large result,
+immediately call cf_compress_cbm(result, tool_name) to compress it.
+
+| CBM Query | Then compress with |
+|-----------|-------------------|
+| cbm_search_graph(…) | cf_compress_cbm(result, "search_graph") |
+| cbm_get_architecture() | cf_compress_cbm(result, "get_architecture") |
+| cbm_search_code(…) | cf_compress_cbm(result, "search_code") |
+| cbm_trace_path(…) | cf_compress_cbm(result, "trace_path") |
+| cbm_get_impact(…) | cf_compress_cbm(result, "get_impact") |
+
+Call cf_stats() at end of session to measure total savings.
+```
+
+## Credits
+- [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) — MIT
+- [headroom](https://github.com/headroomlabs-ai/headroom) — Apache 2.0
+- [spec-kit](https://github.com/github/spec-kit) — MIT
+
+## License
+MIT

contextforge_mcp-0.2.1/contextforge-mcp-v2/contextforge-mcp/README.md

@@ -0,0 +1,108 @@
+# contextforge-mcp
+
+**MCP compression middleware** that connects [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) + [headroom](https://github.com/headroomlabs-ai/headroom) + [Spec Kit](https://github.com/github/spec-kit) into a unified, token-efficient workflow.
+
+## Architecture
+
+```
+Claude Code
+  ├── codebase-memory-mcp   ← graph queries (cbm_* tools)
+  │         │
+  │         └── large result
+  │                   │
+  └── contextforge-mcp  ← YOU ARE HERE
+            │
+            cf_compress_cbm(result, tool_name)
+            │
+            └── compressed result (60-95% fewer tokens)
+```
+
+**ContextForge does NOT proxy codebase-memory-mcp** — both servers run independently. The agent calls CBM for graph queries, then passes results through ContextForge for compression. This design is reliable, cross-platform, and works with any MCP client.
+
+## Install
+
+```bash
+npm install -g codebase-memory-mcp
+pip install "headroom-ai[all]"
+pip install contextforge-mcp
+```
+
+## Setup
+
+```bash
+# Health check
+contextforge-mcp doctor
+
+# Configure Claude Code (writes .mcp.json with both servers)
+contextforge-mcp install --target claude
+```
+
+## Workflow
+
+```python
+# 1. Query the graph (via codebase-memory-mcp)
+result = cbm_search_graph(name_pattern=".*Payment.*", label="Function")
+
+# 2. Compress the result (via contextforge-mcp)
+compressed = cf_compress_cbm(result=result, tool_name="search_graph")
+# → [ContextForge ✓ search_graph: 8420→612 tokens (93% saved in 45ms)]
+
+# 3. Use compressed result in your context
+# 4. Check savings
+cf_stats()
+```
+
+## Tools (9 total)
+
+### Compression
+| Tool | Description |
+|------|-------------|
+| `cf_compress_cbm(result, tool_name)` | Compress CBM tool output |
+| `cf_compress(text, hint)` | Compress arbitrary text |
+
+### Stats
+| Tool | Description |
+|------|-------------|
+| `cf_stats()` | Session token savings + cost estimate |
+| `cf_reset_stats()` | Reset session counters |
+
+### Spec Kit
+| Tool | Description |
+|------|-------------|
+| `cf_read_spec(feature_id)` | Compressed spec.md |
+| `cf_read_plan(feature_id)` | Compressed plan.md |
+| `cf_read_tasks(feature_id)` | Compressed tasks.md |
+| `cf_read_artifact(artifact, feature_id)` | Any artifact |
+| `cf_implement_context(feature_id)` | Full bundle (spec+plan+tasks) |
+| `cf_speckit_status()` | List all features + phase |
+
+## Supported CBM tool names for cf_compress_cbm
+
+`search_graph` · `search_code` · `get_architecture` · `find_dead_code` · `find_similar_code` · `get_impact` · `trace_path` · `trace_call_path` · `cypher_query` · `get_cross_service_links` · `get_node_details`
+
+## Add to CLAUDE.md
+
+```markdown
+## ContextForge MCP — Compression Workflow
+
+After EVERY codebase-memory-mcp tool call that returns a large result,
+immediately call cf_compress_cbm(result, tool_name) to compress it.
+
+| CBM Query | Then compress with |
+|-----------|-------------------|
+| cbm_search_graph(…) | cf_compress_cbm(result, "search_graph") |
+| cbm_get_architecture() | cf_compress_cbm(result, "get_architecture") |
+| cbm_search_code(…) | cf_compress_cbm(result, "search_code") |
+| cbm_trace_path(…) | cf_compress_cbm(result, "trace_path") |
+| cbm_get_impact(…) | cf_compress_cbm(result, "get_impact") |
+
+Call cf_stats() at end of session to measure total savings.
+```
+
+## Credits
+- [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) — MIT
+- [headroom](https://github.com/headroomlabs-ai/headroom) — Apache 2.0
+- [spec-kit](https://github.com/github/spec-kit) — MIT
+
+## License
+MIT

{contextforge_mcp-0.2.0 → contextforge_mcp-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "contextforge-mcp"
-version = "0.2.0"
+version = "0.2.1"
 description = "MCP orchestrator: codebase-memory-mcp + headroom + Spec Kit"
 readme = "README.md"
 license = { text = "MIT" }

contextforge_mcp-0.2.1/src/contextforge_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""contextforge-mcp — MCP compression middleware for codebase-memory-mcp + Spec Kit."""
+
+__version__ = "0.2.0"

contextforge_mcp-0.2.1/src/contextforge_mcp/cli.py

@@ -0,0 +1,190 @@
+"""ContextForge MCP CLI."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+app = typer.Typer(
+    name="contextforge-mcp",
+    help="MCP compression middleware: codebase-memory-mcp + headroom + Spec Kit",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command()
+def run() -> None:
+    """Start ContextForge as a stdio MCP server."""
+    from .server import main
+    main()
+
+
+@app.command()
+def doctor() -> None:
+    """Check all dependencies."""
+    console.rule("[bold]ContextForge MCP — Doctor[/bold]")
+    ok = True
+
+    major, minor = sys.version_info[:2]
+    if major == 3 and minor >= 10:
+        console.print(f"  ✅  Python {major}.{minor}")
+    else:
+        console.print(f"  ❌  Python {major}.{minor} — need 3.10+")
+        ok = False
+
+    try:
+        import mcp
+        console.print("  ✅  mcp (Model Context Protocol SDK)")
+    except ImportError:
+        console.print("  ❌  mcp — run: pip install mcp")
+        ok = False
+
+    try:
+        import headroom
+        console.print("  ✅  headroom-ai (compression enabled)")
+    except ImportError:
+        console.print("  ⚠️   headroom-ai not installed — compression disabled")
+        console.print("       Fix: pip install 'headroom-ai[all]'")
+
+    cbm = shutil.which("codebase-memory-mcp") or shutil.which("codebase-memory-mcp.exe")
+    if cbm:
+        console.print(f"  ✅  codebase-memory-mcp → {cbm}")
+    else:
+        console.print("  ❌  codebase-memory-mcp not found")
+        console.print("       Fix: npm install -g codebase-memory-mcp")
+        ok = False
+
+    specify = shutil.which("specify")
+    if specify:
+        console.print(f"  ✅  specify (Spec Kit) → {specify}")
+    else:
+        console.print("  ⚠️   specify not found — optional")
+        console.print("       Fix: pip install specify")
+
+    console.print()
+    if ok:
+        console.print("[green]✅  Everything looks good![/green]")
+        console.print()
+        console.print("[dim]Workflow:[/dim]")
+        console.print("  1. Add contextforge-mcp to .mcp.json")
+        console.print("  2. In Claude Code: cbm_search_graph(...) → cf_compress_cbm(result, 'search_graph')")
+        console.print("  3. cf_stats() to see token savings")
+    else:
+        console.print("[yellow]⚠️   Some dependencies missing. See above.[/yellow]")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def install(
+    target: str = typer.Option("claude", help="claude | speckit | all"),
+    project_dir: Path = typer.Option(Path("."), help="Project directory"),
+) -> None:
+    """Configure ContextForge for Claude Code and/or Spec Kit."""
+
+    if target in ("claude", "all"):
+        _install_claude(project_dir)
+
+    if target in ("speckit", "all"):
+        _install_speckit(project_dir)
+
+    if target not in ("claude", "speckit", "all"):
+        console.print(f"[yellow]Unknown target: {target!r}. Use: claude | speckit | all[/yellow]")
+
+
+def _install_claude(project_dir: Path) -> None:
+    """Write .mcp.json with both codebase-memory-mcp and contextforge-mcp."""
+    import shutil as sh
+
+    mcp_path = project_dir / ".mcp.json"
+    config: dict = {}
+    if mcp_path.exists():
+        try:
+            config = json.loads(mcp_path.read_text())
+        except json.JSONDecodeError:
+            pass
+
+    config.setdefault("mcpServers", {})
+
+    # Add codebase-memory-mcp if not already present
+    cbm_bin = sh.which("codebase-memory-mcp") or "codebase-memory-mcp"
+    if "codebase-memory-mcp" not in config["mcpServers"]:
+        config["mcpServers"]["codebase-memory-mcp"] = {
+            "command": cbm_bin,
+            "args": [],
+        }
+
+    # Add/update contextforge-mcp
+    config["mcpServers"]["contextforge-mcp"] = {
+        "command": "contextforge-mcp",
+        "args": ["run"],
+    }
+
+    # Remove old contextforge entry if present
+    config["mcpServers"].pop("contextforge", None)
+
+    mcp_path.write_text(json.dumps(config, indent=2))
+    console.print(f"✅  Updated {mcp_path}")
+    console.print()
+    console.print("[bold]Two MCP servers configured:[/bold]")
+    console.print("  codebase-memory-mcp  → graph queries (cbm_* tools)")
+    console.print("  contextforge-mcp     → compression middleware (cf_* tools)")
+    console.print()
+    console.print("[dim]Workflow in Claude Code:[/dim]")
+    console.print("  result = cbm_search_graph(name_pattern='.*Payment.*')")
+    console.print("  compressed = cf_compress_cbm(result=result, tool_name='search_graph')")
+    console.print("  cf_stats()  # see token savings")
+
+
+def _install_speckit(project_dir: Path) -> None:
+    import shutil as sh
+    pkg_dir = Path(__file__).parent.parent.parent
+    ext_src = pkg_dir / "extensions" / "speckit"
+
+    if not ext_src.exists():
+        console.print("[yellow]Extension source not found — clone the repo and run from there.[/yellow]")
+        return
+
+    ext_dst = project_dir / ".specify" / "extensions" / "contextforge-mcp"
+    ext_dst.mkdir(parents=True, exist_ok=True)
+    sh.copytree(ext_src, ext_dst, dirs_exist_ok=True)
+    console.print(f"✅  Spec Kit extension → {ext_dst}")
+
+    claude_commands = project_dir / ".claude" / "commands"
+    if (project_dir / ".claude").exists():
+        claude_commands.mkdir(parents=True, exist_ok=True)
+        for f in (ext_src / "commands").glob("*.md"):
+            sh.copy2(f, claude_commands / f.name)
+        console.print(f"✅  Slash commands → {claude_commands}")
+
+
+@app.command()
+def info() -> None:
+    """Show version and info."""
+    from . import __version__
+
+    table = Table(title="ContextForge MCP", show_header=False)
+    table.add_column("Key", style="bold cyan")
+    table.add_column("Value")
+    table.add_row("Version", __version__)
+    table.add_row("Architecture", "Middleware — runs alongside codebase-memory-mcp")
+    table.add_row("Tools", "cf_compress_cbm, cf_compress, cf_stats + Spec Kit tools")
+    table.add_row("", "")
+    table.add_row("Built on", "")
+    table.add_row("  codebase-memory-mcp", "github.com/DeusData/codebase-memory-mcp")
+    table.add_row("  headroom-ai", "github.com/headroomlabs-ai/headroom")
+    table.add_row("  spec-kit", "github.com/github/spec-kit")
+    table.add_row("", "")
+    table.add_row("Repo", "github.com/capatinore/contextforge-mcp")
+    table.add_row("PyPI", "pip install contextforge-mcp")
+    console.print(table)
+
+
+if __name__ == "__main__":
+    app()

contextforge_mcp-0.2.1/src/contextforge_mcp/compressor.py

@@ -0,0 +1,200 @@
+"""Headroom compression layer with per-tool profiles and session stats."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Tools that return large payloads — compress aggressively
+COMPRESS_PROFILES: dict[str, dict[str, Any]] = {
+    "search_graph":        {"max_items": 50},
+    "search_code":         {"max_items": 30},
+    "get_architecture":    {"max_items": 100},
+    "find_dead_code":      {"max_items": 80},
+    "find_similar_code":   {"max_items": 40},
+    "cypher_query":        {"max_items": 60},
+    "get_impact":          {"max_items": 40},
+    "trace_path":          {"max_items": 30},
+    "trace_call_path":     {"max_items": 30},
+    "get_cross_service_links": {"max_items": 50},
+}
+
+# Tools that return small status payloads — skip compression
+SKIP_COMPRESS: set[str] = {
+    "index_repository",
+    "get_indexing_status",
+    "manage_adr",
+    "get_node_details",
+}
+
+
+@dataclass
+class CompressionResult:
+    original_tokens: int
+    compressed_tokens: int
+    tokens_saved: int
+    ratio: float
+    content: str
+    elapsed_ms: float
+    skipped: bool = False
+
+
+@dataclass
+class SessionStats:
+    total_calls: int = 0
+    total_original_tokens: int = 0
+    total_compressed_tokens: int = 0
+    total_elapsed_ms: float = 0.0
+    errors: int = 0
+
+    @property
+    def tokens_saved(self) -> int:
+        return self.total_original_tokens - self.total_compressed_tokens
+
+    @property
+    def overall_ratio(self) -> float:
+        if self.total_original_tokens == 0:
+            return 0.0
+        return 1.0 - (self.total_compressed_tokens / self.total_original_tokens)
+
+    @property
+    def estimated_cost_saved_usd(self) -> float:
+        """Estimate at $3/M tokens (Claude Sonnet input pricing)."""
+        return (self.tokens_saved / 1_000_000) * 3.0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "total_calls": self.total_calls,
+            "total_original_tokens": self.total_original_tokens,
+            "total_compressed_tokens": self.total_compressed_tokens,
+            "tokens_saved": self.tokens_saved,
+            "overall_compression_ratio": f"{self.overall_ratio:.1%}",
+            "estimated_cost_saved_usd": f"${self.estimated_cost_saved_usd:.4f}",
+            "total_elapsed_ms": round(self.total_elapsed_ms, 1),
+            "errors": self.errors,
+        }
+
+
+class HeadroomCompressor:
+    """
+    Wraps headroom-ai compress() with per-tool profiles and session stats.
+    Falls back gracefully when headroom-ai is not installed.
+    """
+
+    def __init__(self, model: str = "claude-sonnet-4-6"):
+        self.model = model
+        self.stats = SessionStats()
+        self._available = self._check_availability()
+
+    async def compress(
+        self,
+        content: Any,
+        tool_name: str = "text",
+        *,
+        force: bool = False,
+    ) -> CompressionResult:
+        """
+        Compress content from a CBM tool or arbitrary text.
+
+        Args:
+            content:   Raw result (str, dict, list).
+            tool_name: CBM tool name or hint (text/code/json/logs).
+            force:     Compress even skip-marked tools.
+        """
+        t0 = time.perf_counter()
+        self.stats.total_calls += 1
+
+        content_str = content if isinstance(content, str) else json.dumps(content, indent=2)
+
+        should_skip = (tool_name in SKIP_COMPRESS and not force) or not self._available
+
+        if should_skip:
+            return self._passthrough(content_str, t0)
+
+        try:
+            return await self._run_headroom(content_str, tool_name, t0)
+        except Exception as exc:
+            logger.warning("Headroom compression failed [%s]: %s", tool_name, exc)
+            self.stats.errors += 1
+            return self._passthrough(content_str, t0)
+
+    def get_stats(self) -> dict[str, Any]:
+        return {
+            "headroom_available": self._available,
+            "model": self.model,
+            **self.stats.to_dict(),
+        }
+
+    def reset_stats(self) -> None:
+        self.stats = SessionStats()
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _passthrough(self, content: str, t0: float) -> CompressionResult:
+        elapsed = (time.perf_counter() - t0) * 1000
+        tokens = len(content.split())
+        self.stats.total_original_tokens += tokens
+        self.stats.total_compressed_tokens += tokens
+        self.stats.total_elapsed_ms += elapsed
+        return CompressionResult(
+            original_tokens=tokens, compressed_tokens=tokens,
+            tokens_saved=0, ratio=0.0,
+            content=content, elapsed_ms=elapsed, skipped=True,
+        )
+
+    async def _run_headroom(self, content: str, tool_name: str, t0: float) -> CompressionResult:
+        import asyncio
+        from headroom import compress  # type: ignore[import]
+
+        profile = COMPRESS_PROFILES.get(tool_name, {})
+        messages = [{"role": "tool", "tool_call_id": f"cf_{tool_name}", "content": content}]
+
+        loop = asyncio.get_event_loop()
+        result = await loop.run_in_executor(
+            None,
+            lambda: compress(
+                messages,
+                model=self.model,
+                headroom_tool_profiles={tool_name: profile} if profile else None,
+            ),
+        )
+
+        elapsed = (time.perf_counter() - t0) * 1000
+        compressed_content = content
+        if result.messages:
+            msg = result.messages[0]
+            if isinstance(msg, dict):
+                compressed_content = msg.get("content", content)
+
+        orig = getattr(result, "tokens_before", len(content.split()))
+        comp = getattr(result, "tokens_after", len(compressed_content.split()))
+        saved = orig - comp
+        ratio = saved / orig if orig > 0 else 0.0
+
+        self.stats.total_original_tokens += orig
+        self.stats.total_compressed_tokens += comp
+        self.stats.total_elapsed_ms += elapsed
+
+        logger.info("[%s] %d→%d tokens (%.0f%% saved) %.1fms", tool_name, orig, comp, ratio * 100, elapsed)
+
+        return CompressionResult(
+            original_tokens=orig, compressed_tokens=comp,
+            tokens_saved=saved, ratio=ratio,
+            content=compressed_content, elapsed_ms=elapsed,
+        )
+
+    @staticmethod
+    def _check_availability() -> bool:
+        try:
+            import headroom  # noqa: F401
+            return True
+        except ImportError:
+            logger.warning("headroom-ai not installed — compression disabled. pip install 'headroom-ai[all]'")
+            return False