Metadata-Version: 2.4
Name: context-compiler-mcp
Version: 1.1.0
Summary: Local context compiler for AI coding assistants — smallest correct context bundle with rationale
Project-URL: Repository, https://github.com/bytewise-ca/context-compiler
Author: sumesh
License: Apache-2.0
License-File: LICENSE
Keywords: claude,code-intelligence,context,copilot,cursor,gemini,llm,mcp,tree-sitter,windsurf
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: fastmcp>=2.0
Requires-Dist: kuzu>=0.7
Requires-Dist: pydantic>=2.0
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: tree-sitter-javascript>=0.23
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter>=0.23
Provides-Extra: dev
Requires-Dist: datamodel-code-generator>=0.25; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: semantic
Requires-Dist: fastembed>=0.4; extra == 'semantic'
Description-Content-Type: text/markdown

# context-compiler

An MCP server that indexes your codebase into a dependency graph and returns the **smallest correct context** for any coding task: exact line ranges per symbol, with a rationale for each one.

**Runs entirely on your machine.** No cloud, no LLM API calls, no embeddings server, no internet connection required. Your source code and task descriptions never leave your laptop. The base install is lightweight: pure Python, no GPU, no heavy ML framework.

---

## Getting started

```bash
pip install context-compiler-mcp
cd /your/project
context-compiler init
```

By default `init` registers with **Claude Code**. Pass `--client` to target a different assistant:

```bash
context-compiler init --client claude    # Claude Code (default)
context-compiler init --client gemini    # Gemini CLI
context-compiler init --client codex     # OpenAI Codex CLI
```

`init` indexes your codebase and registers the MCP server with your chosen assistant. For Claude Code it also adds instructions to `CLAUDE.md` so it calls `get_context` automatically before reading files.

Requires Python 3.11+.

### Multi-repo projects

```bash
context-compiler init --dependencies ../repo1,../repo2
context-compiler init --client codex --dependencies ../repo1,../repo2
```

Each repo is indexed separately. `get_context` queries all graphs and returns the best-matching symbols across all repos. The dependency list is saved and picked up automatically on next start.

### Other commands

```bash
context-compiler index                        # re-index after large changes
context-compiler explain --task "<prompt>"    # preview what context a task returns
```

### Optional: semantic search

```bash
pip install "context-compiler-mcp[semantic]"
```

Enables embedding-based fallback for cases where task terms don't appear in symbol names (e.g. "fix login flow" finds `authenticate_user`). Downloads a 23MB ONNX model once, no PyTorch required.

---

## How it works

Every step runs locally with no external calls:

1. Classify the task: `BUG_FIX`, `NEW_FEATURE`, or `REFACTOR` (keyword scoring, no LLM)
2. Find entry nodes via BM25 over symbol names, file paths, and docstrings
3. Traverse the dependency graph with a strategy tuned per task type
4. Score candidates, enforce a token budget, return slices with rationale

The graph is stored in an embedded KuzuDB database in your project folder. No server process, no port, no auth.

Same repo + same task = same output, every time.

---

## Output

```json
{
  "slices": [
    {
      "file_path": "/abs/path/payments/processor.py",
      "line_start": 6,
      "line_end": 24,
      "rationale": "Included PaymentProcessor as primary task location (matched 'payment')"
    },
    {
      "file_path": "/abs/path/payments/retry_handler.py",
      "line_start": 12,
      "line_end": 38,
      "rationale": "Included RetryHandler because it is called by PaymentProcessor (depth 1)"
    }
  ]
}
```

Each slice points to the specific function or class that's relevant. A 500-line file with one relevant function costs ~40 tokens, not 500.

---

## Supported languages

| Language | Parsing |
|---|---|
| Python | tree-sitter-python |
| TypeScript / TSX | tree-sitter-typescript |
| JavaScript / JSX | tree-sitter-javascript |

---

## License

Apache 2.0
