contextforge-mcp 0.1.0__py3-none-any.whl

contextforge_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""contextforge-mcp — MCP orchestrator for codebase-memory-mcp + headroom + Spec Kit."""
+
+__version__ = "0.1.0"

contextforge_mcp/cbm_client.py

@@ -0,0 +1,132 @@
+"""Client for codebase-memory-mcp binary over stdio JSON-RPC 2.0."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import shutil
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+CBM_TOOLS: list[str] = [
+    "index_repository", "search_graph", "search_code", "trace_path",
+    "trace_call_path", "get_architecture", "get_node_details", "find_dead_code",
+    "find_similar_code", "get_impact", "cypher_query", "manage_adr",
+    "get_cross_service_links", "get_indexing_status",
+]
+
+HIGH_TOKEN_TOOLS: set[str] = {
+    "search_graph", "search_code", "get_architecture",
+    "find_dead_code", "find_similar_code", "cypher_query",
+}
+
+
+class CBMClient:
+    def __init__(self, binary_path: str | None = None):
+        self.binary_path = binary_path or self._find_binary()
+        self._process: asyncio.subprocess.Process | None = None
+        self._request_id = 0
+        self._lock = asyncio.Lock()
+
+    async def start(self) -> None:
+        if not self.binary_path:
+            raise RuntimeError(
+                "codebase-memory-mcp binary not found. "
+                "Install with: npm install -g codebase-memory-mcp"
+            )
+        self._process = await asyncio.create_subprocess_exec(
+            self.binary_path,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        await self._initialize()
+
+    async def stop(self) -> None:
+        if self._process and self._process.returncode is None:
+            self._process.terminate()
+            try:
+                await asyncio.wait_for(self._process.wait(), timeout=5.0)
+            except asyncio.TimeoutError:
+                self._process.kill()
+
+    async def __aenter__(self) -> "CBMClient":
+        await self.start()
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.stop()
+
+    async def call_tool(self, tool_name: str, arguments: dict[str, Any]) -> Any:
+        if tool_name not in CBM_TOOLS:
+            raise ValueError(f"Unknown CBM tool: {tool_name!r}")
+        async with self._lock:
+            return await self._send({
+                "jsonrpc": "2.0",
+                "id": self._next_id(),
+                "method": "tools/call",
+                "params": {"name": tool_name, "arguments": arguments},
+            })
+
+    def is_high_token_tool(self, tool_name: str) -> bool:
+        return tool_name in HIGH_TOKEN_TOOLS
+
+    @property
+    def available(self) -> bool:
+        return self.binary_path is not None
+
+    async def _initialize(self) -> None:
+        await self._send({
+            "jsonrpc": "2.0", "id": self._next_id(), "method": "initialize",
+            "params": {
+                "protocolVersion": "2024-11-05", "capabilities": {},
+                "clientInfo": {"name": "contextforge-mcp", "version": "0.1.0"},
+            },
+        })
+        await self._write({"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}})
+
+    async def _send(self, payload: dict[str, Any]) -> Any:
+        assert self._process and self._process.stdin and self._process.stdout
+        await self._write(payload)
+        target_id = payload.get("id")
+        while True:
+            line = await asyncio.wait_for(self._process.stdout.readline(), timeout=30.0)
+            if not line:
+                raise ConnectionError("codebase-memory-mcp subprocess closed")
+            line = line.decode().strip()
+            if not line:
+                continue
+            try:
+                response = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if response.get("id") == target_id:
+                if "error" in response:
+                    raise RuntimeError(f"CBM error: {response['error']}")
+                return response.get("result")
+
+    async def _write(self, payload: dict[str, Any]) -> None:
+        assert self._process and self._process.stdin
+        self._process.stdin.write((json.dumps(payload) + "\n").encode())
+        await self._process.stdin.drain()
+
+    def _next_id(self) -> int:
+        self._request_id += 1
+        return self._request_id
+
+    @staticmethod
+    def _find_binary() -> str | None:
+        for name in ["codebase-memory-mcp", "codebase-memory-mcp.exe"]:
+            found = shutil.which(name)
+            if found:
+                return found
+        for p in [
+            Path.home() / ".local" / "bin" / "codebase-memory-mcp",
+            Path("/usr/local/bin/codebase-memory-mcp"),
+        ]:
+            if p.exists():
+                return str(p)
+        return None

contextforge_mcp/cli.py

@@ -0,0 +1,127 @@
+"""ContextForge MCP CLI."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(name="contextforge-mcp", help="MCP orchestrator: 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")
+    except ImportError:
+        console.print("  ❌  mcp — pip install mcp"); ok = False
+
+    try:
+        import headroom; console.print("  ✅  headroom-ai")
+    except ImportError:
+        console.print("  ⚠️   headroom-ai not installed — 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 — 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 — pip install spec-kit  (optional)")
+
+    console.print()
+    if ok:
+        console.print("[green]✅  Everything looks good![/green]")
+    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 MCP for Claude Code and/or Spec Kit."""
+
+    if target in ("claude", "all"):
+        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", {})
+        config["mcpServers"]["contextforge-mcp"] = {
+            "command": "contextforge-mcp",
+            "args": ["run"],
+        }
+        mcp_path.write_text(json.dumps(config, indent=2))
+        console.print(f"✅  Updated {mcp_path}")
+
+    if target in ("speckit", "all"):
+        _install_speckit(project_dir)
+
+    if target not in ("claude", "speckit", "all"):
+        console.print(f"[yellow]Unknown target: {target!r}[/yellow]")
+
+
+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 first.[/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__
+    console.print(f"[bold]contextforge-mcp[/bold] v{__version__}")
+    console.print("  codebase-memory-mcp: github.com/DeusData/codebase-memory-mcp")
+    console.print("  headroom:            github.com/headroomlabs-ai/headroom")
+    console.print("  spec-kit:            github.com/github/spec-kit")
+    console.print("  repo:                github.com/capatinore/contextforge-mcp")
+
+
+if __name__ == "__main__":
+    app()

contextforge_mcp/compressor.py

@@ -0,0 +1,138 @@
+"""Headroom compression layer with stats tracking."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+SKIP_TOOLS: set[str] = {"index_repository", "get_indexing_status"}
+
+
+@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)
+
+    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%}",
+            "total_elapsed_ms": round(self.total_elapsed_ms, 1),
+            "errors": self.errors,
+        }
+
+
+class HeadroomCompressor:
+    def __init__(self, model: str = "claude-sonnet-4-6"):
+        self.model = model
+        self.stats = SessionStats()
+        self._available = self._check_availability()
+
+    async def compress_tool_result(
+        self, tool_name: str, result: Any, *, force: bool = False
+    ) -> CompressionResult:
+        t0 = time.perf_counter()
+        self.stats.total_calls += 1
+        content_str = result if isinstance(result, str) else json.dumps(result, indent=2)
+
+        if (tool_name in SKIP_TOOLS and not force) or not self._available:
+            elapsed = (time.perf_counter() - t0) * 1000
+            token_est = len(content_str.split())
+            self.stats.total_original_tokens += token_est
+            self.stats.total_compressed_tokens += token_est
+            return CompressionResult(
+                original_tokens=token_est, compressed_tokens=token_est,
+                tokens_saved=0, ratio=0.0, content=content_str,
+                elapsed_ms=elapsed, skipped=True,
+            )
+
+        try:
+            return await self._compress(content_str, t0)
+        except Exception as exc:
+            logger.warning("Headroom compression failed for %s: %s", tool_name, exc)
+            self.stats.errors += 1
+            elapsed = (time.perf_counter() - t0) * 1000
+            token_est = len(content_str.split())
+            return CompressionResult(
+                original_tokens=token_est, compressed_tokens=token_est,
+                tokens_saved=0, ratio=0.0, content=content_str,
+                elapsed_ms=elapsed, skipped=True,
+            )
+
+    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()
+
+    async def _compress(self, content: str, t0: float) -> CompressionResult:
+        import asyncio
+        from headroom import compress  # type: ignore[import]
+
+        messages = [{"role": "tool", "tool_call_id": "cf", "content": content}]
+        loop = asyncio.get_event_loop()
+        result = await loop.run_in_executor(
+            None, lambda: compress(messages, model=self.model)
+        )
+        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
+
+        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.")
+            return False

contextforge_mcp/server.py

@@ -0,0 +1,203 @@
+"""ContextForge MCP Server — codebase-memory-mcp + headroom + Spec Kit."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from .cbm_client import CBMClient, CBM_TOOLS
+from .compressor import HeadroomCompressor
+from .speckit import read_and_compress, implement_context, status as speckit_status
+
+logging.basicConfig(level=os.environ.get("CF_LOG_LEVEL", "WARNING").upper())
+logger = logging.getLogger("contextforge-mcp")
+
+mcp = FastMCP("contextforge-mcp")
+
+_cbm = CBMClient(binary_path=os.environ.get("CBM_BINARY_PATH"))
+_compressor = HeadroomCompressor(
+    model=os.environ.get("CF_MODEL", "claude-sonnet-4-6")
+)
+
+
+async def _cbm_call(tool_name: str, arguments: dict[str, Any]) -> str:
+    if not _cbm.available:
+        return json.dumps({"error": "codebase-memory-mcp not found", "hint": "npm install -g codebase-memory-mcp"})
+    if _cbm._process is None:
+        await _cbm.start()
+    try:
+        raw = await _cbm.call_tool(tool_name, arguments)
+    except Exception as exc:
+        return json.dumps({"error": str(exc), "tool": tool_name})
+    compressed = await _compressor.compress_tool_result(tool_name, raw)
+    if compressed.skipped:
+        return compressed.content
+    return (
+        f"[ContextForge: {compressed.original_tokens}→{compressed.compressed_tokens} "
+        f"tokens ({compressed.ratio:.0%} saved)]\n\n{compressed.content}"
+    )
+
+
+# ── CBM Tools ────────────────────────────────────────────────────────────────
+
+@mcp.tool()
+async def cbm_index_repository(repo_path: str, incremental: bool = True) -> str:
+    """Index a repository into the knowledge graph. Run before any other cbm_* tool."""
+    return await _cbm_call("index_repository", {"repo_path": repo_path, "incremental": incremental})
+
+@mcp.tool()
+async def cbm_search_graph(name_pattern: str, label: str = "Function", limit: int = 50, file_pattern: str | None = None) -> str:
+    """Search the knowledge graph by name pattern (regex). label: Function|Class|Method|Interface."""
+    args: dict[str, Any] = {"name_pattern": name_pattern, "label": label, "limit": limit}
+    if file_pattern:
+        args["file_pattern"] = file_pattern
+    return await _cbm_call("search_graph", args)
+
+@mcp.tool()
+async def cbm_search_code(query: str, mode: str = "compact", limit: int = 30) -> str:
+    """Full-text + graph-ranked code search. mode: compact|full|files."""
+    return await _cbm_call("search_code", {"query": query, "mode": mode, "limit": limit})
+
+@mcp.tool()
+async def cbm_trace_path(function_name: str, direction: str = "both", depth: int = 5) -> str:
+    """Trace call paths for a function. direction: inbound|outbound|both."""
+    return await _cbm_call("trace_path", {"function_name": function_name, "direction": direction, "depth": depth})
+
+@mcp.tool()
+async def cbm_trace_call_path(function_name: str, direction: str = "both") -> str:
+    """Trace the full call chain for a function across the knowledge graph."""
+    return await _cbm_call("trace_call_path", {"function_name": function_name, "direction": direction})
+
+@mcp.tool()
+async def cbm_get_architecture(include_external: bool = False, service_filter: str | None = None) -> str:
+    """Get high-level architecture view: modules, services, HTTP routes."""
+    args: dict[str, Any] = {"include_external": include_external}
+    if service_filter:
+        args["service_filter"] = service_filter
+    return await _cbm_call("get_architecture", args)
+
+@mcp.tool()
+async def cbm_get_node_details(node_id: str) -> str:
+    """Get detailed information about a specific graph node."""
+    return await _cbm_call("get_node_details", {"node_id": node_id})
+
+@mcp.tool()
+async def cbm_find_dead_code(confidence: str = "high", label: str | None = None) -> str:
+    """Detect unreachable/unused code. confidence: high|medium|low."""
+    args: dict[str, Any] = {"confidence": confidence}
+    if label:
+        args["label"] = label
+    return await _cbm_call("find_dead_code", args)
+
+@mcp.tool()
+async def cbm_find_similar_code(node_id: str, threshold: float = 0.8, limit: int = 20) -> str:
+    """Find code clones and similar implementations in the codebase."""
+    return await _cbm_call("find_similar_code", {"node_id": node_id, "threshold": threshold, "limit": limit})
+
+@mcp.tool()
+async def cbm_get_impact(node_id: str, depth: int = 3) -> str:
+    """Analyze what would break if this function/class changes."""
+    return await _cbm_call("get_impact", {"node_id": node_id, "depth": depth})
+
+@mcp.tool()
+async def cbm_cypher_query(query: str, limit: int = 100) -> str:
+    """Run a raw Cypher-like query against the knowledge graph."""
+    return await _cbm_call("cypher_query", {"query": query, "limit": limit})
+
+@mcp.tool()
+async def cbm_manage_adr(action: str, title: str | None = None, content: str | None = None, adr_id: str | None = None) -> str:
+    """Manage Architecture Decision Records. action: create|list|get|update."""
+    args: dict[str, Any] = {"action": action}
+    if title: args["title"] = title
+    if content: args["content"] = content
+    if adr_id: args["adr_id"] = adr_id
+    return await _cbm_call("manage_adr", args)
+
+@mcp.tool()
+async def cbm_get_cross_service_links(service_name: str | None = None, protocol: str | None = None) -> str:
+    """Get cross-service HTTP/gRPC/GraphQL links detected in the codebase."""
+    args: dict[str, Any] = {}
+    if service_name: args["service_name"] = service_name
+    if protocol: args["protocol"] = protocol
+    return await _cbm_call("get_cross_service_links", args)
+
+@mcp.tool()
+async def cbm_get_indexing_status() -> str:
+    """Get the current indexing status."""
+    return await _cbm_call("get_indexing_status", {})
+
+
+# ── ContextForge Meta Tools ───────────────────────────────────────────────────
+
+@mcp.tool()
+async def cf_stats() -> str:
+    """Show ContextForge session compression statistics and token savings."""
+    return json.dumps({
+        "contextforge_mcp_version": "0.1.0",
+        "cbm_available": _cbm.available,
+        "cbm_binary": _cbm.binary_path,
+        "compression": _compressor.get_stats(),
+    }, indent=2)
+
+@mcp.tool()
+async def cf_compress(text: str, hint: str = "text") -> str:
+    """Compress arbitrary text through headroom. hint: text|code|json|logs."""
+    compressed = await _compressor.compress_tool_result(f"cf_{hint}", text, force=True)
+    if compressed.skipped:
+        return f"[headroom unavailable]\n\n{text}"
+    return (
+        f"[ContextForge: {compressed.original_tokens}→{compressed.compressed_tokens} "
+        f"tokens ({compressed.ratio:.0%} saved)]\n\n{compressed.content}"
+    )
+
+@mcp.tool()
+async def cf_reset_stats() -> str:
+    """Reset ContextForge session compression counters."""
+    _compressor.reset_stats()
+    return json.dumps({"status": "reset"})
+
+
+# ── Spec Kit Tools ────────────────────────────────────────────────────────────
+
+@mcp.tool()
+async def cf_read_spec(feature_id: str | None = None) -> str:
+    """Read and compress spec.md for a Spec Kit feature."""
+    return await read_and_compress(_compressor, feature_id, "spec.md")
+
+@mcp.tool()
+async def cf_read_plan(feature_id: str | None = None) -> str:
+    """Read and compress plan.md for a Spec Kit feature."""
+    return await read_and_compress(_compressor, feature_id, "plan.md")
+
+@mcp.tool()
+async def cf_read_tasks(feature_id: str | None = None) -> str:
+    """Read and compress tasks.md for a Spec Kit feature."""
+    return await read_and_compress(_compressor, feature_id, "tasks.md")
+
+@mcp.tool()
+async def cf_read_artifact(artifact: str, feature_id: str | None = None) -> str:
+    """Read and compress any Spec Kit artifact. artifact: filename like data-model.md."""
+    return await read_and_compress(_compressor, feature_id, artifact)
+
+@mcp.tool()
+async def cf_implement_context(feature_id: str | None = None) -> str:
+    """Load compressed spec+plan+tasks+context bundle for /speckit.cf-implement."""
+    return await implement_context(_compressor, feature_id)
+
+@mcp.tool()
+async def cf_speckit_status() -> str:
+    """List all Spec Kit features and their current phase."""
+    return json.dumps(await speckit_status(), indent=2)
+
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+
+def main() -> None:
+    mcp.run(transport="stdio")
+
+if __name__ == "__main__":
+    main()

contextforge_mcp/speckit.py

@@ -0,0 +1,125 @@
+"""Spec Kit integration — read and compress SDD artifacts."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def _specs_dir(base: str = ".") -> Path:
+    for parent in [Path(base), *Path(base).parents[:3]]:
+        candidate = parent / "specs"
+        if candidate.is_dir():
+            return candidate
+    return Path(base) / "specs"
+
+
+def _feature_dir(feature_id: str | None, specs: Path) -> Path | None:
+    if not specs.exists():
+        return None
+    if feature_id:
+        exact = specs / feature_id
+        if exact.is_dir():
+            return exact
+        matches = [d for d in specs.iterdir() if d.is_dir() and d.name.startswith(feature_id)]
+        return matches[0] if matches else None
+    dirs = [d for d in specs.iterdir() if d.is_dir()]
+    return max(dirs, key=lambda d: d.stat().st_mtime) if dirs else None
+
+
+def _read(feature_dir: Path, filename: str) -> str | None:
+    path = feature_dir / filename
+    return path.read_text(encoding="utf-8") if path.exists() else None
+
+
+async def read_and_compress(compressor: Any, feature_id: str | None, artifact: str, base: str = ".") -> str:
+    specs = _specs_dir(base)
+    feat = _feature_dir(feature_id, specs)
+
+    if feat is None:
+        return json.dumps({
+            "error": f"No feature found in {specs}",
+            "hint": "Run /speckit.specify first.",
+            "feature_id": feature_id,
+        })
+
+    content = _read(feat, artifact)
+    if content is None:
+        return json.dumps({
+            "error": f"{artifact} not found in {feat.name}",
+            "available": [f.name for f in feat.iterdir() if f.is_file()],
+        })
+
+    compressed = await compressor.compress_tool_result(f"speckit_{artifact}", content, force=True)
+    header = (
+        f"[ContextForge: {artifact} — "
+        f"{compressed.original_tokens}→{compressed.compressed_tokens} tokens "
+        f"({compressed.ratio:.0%} saved) | {feat.name}]\n\n"
+    )
+    return header + compressed.content
+
+
+async def implement_context(compressor: Any, feature_id: str | None, base: str = ".") -> str:
+    specs = _specs_dir(base)
+    feat = _feature_dir(feature_id, specs)
+
+    if feat is None:
+        return json.dumps({"error": "Feature not found", "specs_dir": str(specs)})
+
+    artifacts = ["spec.md", "plan.md", "tasks.md", "context.md", "data-model.md"]
+    sections = []
+    total_orig = total_comp = 0
+
+    for artifact in artifacts:
+        content = _read(feat, artifact)
+        if content is None:
+            continue
+        r = await compressor.compress_tool_result(f"speckit_{artifact}", content, force=True)
+        total_orig += r.original_tokens
+        total_comp += r.compressed_tokens
+        sections.append(f"## {artifact}\n\n{r.content}")
+
+    if not sections:
+        return json.dumps({"error": "No Spec Kit artifacts found", "feature_dir": str(feat)})
+
+    ratio = 1 - (total_comp / total_orig) if total_orig > 0 else 0
+    header = (
+        f"[ContextForge: implement context — {feat.name} — "
+        f"{total_orig}→{total_comp} tokens ({ratio:.0%} saved)]\n\n"
+    )
+    return header + "\n\n---\n\n".join(sections)
+
+
+async def status(base: str = ".") -> dict[str, Any]:
+    specs = _specs_dir(base)
+    if not specs.exists():
+        return {"exists": False, "specs_dir": str(specs), "features": []}
+
+    features = []
+    for feat in sorted(specs.iterdir()):
+        if not feat.is_dir():
+            continue
+        files = {f.name for f in feat.iterdir() if f.is_file()}
+        phase = "empty"
+        if "spec.md" in files:
+            phase = "specified"
+        if "plan.md" in files:
+            phase = "planned"
+        if "tasks.md" in files:
+            phase = "tasked"
+
+        tasks_done = tasks_total = 0
+        tasks_content = _read(feat, "tasks.md")
+        if tasks_content:
+            lines = tasks_content.splitlines()
+            tasks_total = sum(1 for l in lines if l.strip().startswith("- ["))
+            tasks_done = sum(1 for l in lines if l.strip().startswith("- [x]"))
+
+        features.append({
+            "id": feat.name, "phase": phase,
+            "cf_analyzed": "context.md" in files,
+            "tasks": {"done": tasks_done, "total": tasks_total},
+        })
+
+    return {"exists": True, "feature_count": len(features), "features": features}

contextforge_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: contextforge-mcp
+Version: 0.1.0
+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 orchestrator combining [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 single pipeline.**
+
+```
+Agent (Claude Code / Cursor / Codex)
+  │
+  ▼
+contextforge-mcp  ←── single MCP server
+  │
+  ├── codebase-memory-mcp  (knowledge graph: 99% fewer retrieval tokens)
+  ├── headroom             (compression: 60–95% fewer prompt tokens)
+  └── Spec Kit             (SDD workflow: spec → plan → tasks → implement)
+```
+
+---
+
+## Install
+
+```bash
+# Prerequisites
+npm install -g codebase-memory-mcp
+pip install "headroom-ai[all]"
+pip install spec-kit
+
+# Install contextforge-mcp
+pip install contextforge-mcp
+```
+
+## Setup
+
+```bash
+# Health check
+contextforge-mcp doctor
+
+# Configure Claude Code (writes .mcp.json)
+contextforge-mcp install --target claude
+
+# Configure Spec Kit extension
+contextforge-mcp install --target speckit
+
+# Both at once
+contextforge-mcp install --target all
+```
+
+## Usage in Claude Code
+
+```
+# 1. Index the codebase (once per session)
+cbm_index_repository(repo_path=".")
+
+# 2. Query the graph (instead of grep/read)
+cbm_search_graph(name_pattern=".*Payment.*")
+cbm_trace_path(function_name="processPayment")
+cbm_get_architecture()
+
+# 3. Check token savings
+cf_stats()
+```
+
+## Spec Kit workflow
+
+```
+/speckit.constitution
+/speckit.specify
+/speckit.cf-analyze      ← analyze codebase before planning
+/speckit.plan
+/speckit.tasks
+/speckit.cf-index        ← index before implementing
+/speckit.cf-implement    ← graph-aware implementation
+/speckit.cf-stats        ← token savings report
+```
+
+## Tools (23 total)
+
+| Prefix | Count | Description |
+|--------|-------|-------------|
+| `cbm_*` | 14 | codebase-memory-mcp graph tools |
+| `cf_*` | 9 | ContextForge meta + Spec Kit tools |
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CBM_BINARY_PATH` | auto | Path to codebase-memory-mcp binary |
+| `CF_MODEL` | `claude-sonnet-4-6` | Model hint for headroom |
+| `CF_LOG_LEVEL` | `WARNING` | Log level |
+
+## 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.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+contextforge_mcp/__init__.py,sha256=dM-AYU2hQF_EQp_C4om1s4FFFTX2lCkwdaCzXwRopEo,114
+contextforge_mcp/cbm_client.py,sha256=ben6fRaQwumZIN5t_FXN8RGeuTUSIRU5tZC_GO8DQcc,4661
+contextforge_mcp/cli.py,sha256=mHbPSOj-Wpu2t3oRHs5kfsORvJDhMldKNNcFMVWSAf8,4328
+contextforge_mcp/compressor.py,sha256=gcBpmEQPc-oqpmt2IjsohV1hX0K2-JyDQDeBlB-dv1w,4795
+contextforge_mcp/server.py,sha256=nITVgmKHVJTvGIAlEbaACrn6HyHt-2HVcsX4Hn80Zv0,8843
+contextforge_mcp/speckit.py,sha256=hKASEM90NxPR3f9pDjBho2Q1AZz5UnuJHKkIyviDdbw,4332
+contextforge_mcp-0.1.0.dist-info/METADATA,sha256=YuHjXVT1qEIo_S9WX9jH1e3N5iRHeC8Go9-izY5aZ-g,3161
+contextforge_mcp-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+contextforge_mcp-0.1.0.dist-info/entry_points.txt,sha256=E8S63Mm75wGZZSq48-SmkR4B8JATfan9fsj-VtJNZWY,62
+contextforge_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=b6yZCptmfb19UpXurEv9CJsqCk5JZEAOIdys2z5KA20,1071
+contextforge_mcp-0.1.0.dist-info/RECORD,,

contextforge_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

contextforge_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+contextforge-mcp = contextforge_mcp.cli:app

contextforge_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Camilo Patiño
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.