contextforge-mcp 0.1.0__tar.gz

contextforge_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v3
+      - run: |
+          uv venv
+          uv pip install -e ".[dev]"
+          uv run pytest tests/ -v

contextforge_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v3
+      - name: Build wheel and sdist
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/contextforge-mcp/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

contextforge_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.cbm_store/
+node_modules/

contextforge_mcp-0.1.0/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.

contextforge_mcp-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,97 @@
+# 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/extensions/speckit/commands/cf-analyze.md

@@ -0,0 +1,14 @@
+# /speckit.cf-analyze
+
+Analyze the existing codebase and compress the current spec before planning.
+Run after `/speckit.specify`, before `/speckit.plan`.
+
+## Steps
+
+1. `cf_read_spec()` — load and compress the current spec
+2. `cbm_search_graph(name_pattern="<pattern from spec>")` — find related code
+3. `cbm_get_architecture()` — understand where the feature fits
+4. `cbm_find_similar_code(node_id="<key node>")` — avoid duplicating existing code
+5. `cbm_get_impact(node_id="<key node>")` — identify risk areas
+6. Write `specs/$FEATURE_ID/context.md` with findings
+7. `cf_stats()` — report token savings

contextforge_mcp-0.1.0/extensions/speckit/commands/cf-implement.md

@@ -0,0 +1,41 @@
+# /speckit.cf-implement
+
+Graph-aware implementation. Uses ContextForge instead of file reads.
+
+## Arguments
+- `$FEATURE_ID` — feature directory under `specs/`
+- `$TASK_ID` — (optional) specific task number
+
+## Steps
+
+### Phase 0 — Load context
+```
+cf_implement_context(feature_id="$FEATURE_ID")
+```
+
+### Phase 1 — Understand the task
+For each task, query the graph:
+```
+cbm_search_graph(name_pattern="<function from task>")
+cbm_trace_path(function_name="<target>", direction="inbound")
+cbm_get_impact(node_id="<node>")
+```
+Only read the actual file when you need to edit it.
+
+### Phase 2 — Implement
+- Make minimum change that satisfies the task
+- Mark task complete in `tasks.md`
+- Check `cbm_find_similar_code` before writing new functions
+
+### Phase 3 — Validate
+```
+cbm_trace_path(function_name="<modified>", direction="both")
+cbm_find_dead_code(confidence="high")
+```
+
+### Phase 4 — Report
+- Mark task complete
+- `cf_stats()` — show token savings
+- State next task
+
+## Rule: never grep. Always use `cbm_*` for discovery.

contextforge_mcp-0.1.0/extensions/speckit/commands/cf-index.md

@@ -0,0 +1,15 @@
+# /speckit.cf-index
+
+Index the codebase into the ContextForge knowledge graph before implementing.
+
+## Steps
+
+1. Call `cf_stats()` — confirm ContextForge is connected
+2. Call `cbm_index_repository(repo_path=".")` — build the knowledge graph
+3. Call `cbm_get_indexing_status()` — confirm completion
+4. Call `cbm_get_architecture()` — show compressed architecture overview
+5. Report: files indexed, modules detected, token savings, ready for `/speckit.cf-implement`
+
+## Notes
+- Re-run after significant refactoring
+- Use `cbm_*` tools instead of grep/Read for ALL structural queries after indexing

contextforge_mcp-0.1.0/extensions/speckit/commands/cf-stats.md

@@ -0,0 +1,18 @@
+# /speckit.cf-stats
+
+Show ContextForge token savings for this session.
+
+## Steps
+
+Call `cf_stats()` and present as a table:
+
+| Metric | Value |
+|--------|-------|
+| Total calls | X |
+| Original tokens | X |
+| Compressed tokens | X |
+| Tokens saved | X |
+| Compression ratio | X% |
+
+Estimate cost savings at $3/M tokens (Claude Sonnet).
+To reset: `cf_reset_stats()`

contextforge_mcp-0.1.0/extensions/speckit/extension.json

@@ -0,0 +1,16 @@
+{
+  "name": "contextforge-mcp",
+  "version": "0.1.0",
+  "description": "Integrates contextforge-mcp (codebase-memory-mcp + headroom) into Spec Kit — adds code intelligence and context compression to the SDD workflow.",
+  "author": "Camilo Patiño",
+  "license": "MIT",
+  "repository": "https://github.com/capatinore/contextforge-mcp",
+  "tags": ["code-intelligence", "context-compression", "mcp", "tokens"],
+  "effect": "Read+Write",
+  "commands": [
+    { "name": "cf-index", "description": "Index codebase before implementing" },
+    { "name": "cf-analyze", "description": "Analyze codebase and compress spec before planning" },
+    { "name": "cf-implement", "description": "Graph-aware implement command" },
+    { "name": "cf-stats", "description": "Show token savings for this session" }
+  ]
+}

contextforge_mcp-0.1.0/extensions/speckit/templates/CONTEXTFORGE.md

@@ -0,0 +1,14 @@
+# ContextForge MCP — Reference
+
+Use `cbm_*` tools for ALL structural queries. Never grep.
+
+| Instead of...              | Use...                                  |
+|----------------------------|-----------------------------------------|
+| Grep for function name     | `cbm_search_graph(name_pattern="...")`  |
+| Read files for callers     | `cbm_trace_path(direction="inbound")`   |
+| Explore architecture       | `cbm_get_architecture()`                |
+| Text search across files   | `cbm_search_code(query="...")`          |
+| Read spec/plan/tasks       | `cf_read_spec/plan/tasks()`             |
+| Full implement context     | `cf_implement_context(feature_id="...")`|
+
+Run `cf_stats()` at end of session to see token savings.

contextforge_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "contextforge-mcp"
+version = "0.1.0"
+description = "MCP orchestrator: codebase-memory-mcp + headroom + Spec Kit"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["mcp", "llm", "context", "compression", "code-intelligence", "spec-kit", "ai-agents"]
+authors = [{ name = "Camilo Patiño", email = "capatinore@github.com" }]
+
+dependencies = [
+    "mcp>=1.0.0",
+    "headroom-ai>=0.9.0",
+    "httpx>=0.27.0",
+    "anyio>=4.0.0",
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[project.scripts]
+contextforge-mcp = "contextforge_mcp.cli:app"
+
+[project.urls]
+Repository = "https://github.com/capatinore/contextforge-mcp"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/contextforge_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

contextforge_mcp-0.1.0/src/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-0.1.0/src/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