Metadata-Version: 2.2
Name: projectbrain-mcp
Version: 0.2.0
Summary: Surgical AST Context Compiler, Closed-World Dossier & Anchor Patch Engine for AI Coding Agents (-75% to -88% tokens)
License: MIT
Keywords: ai,agents,mcp,ast,tree-sitter,context-compression,code-graph,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: mcp
Requires-Dist: tree-sitter>=0.23
Requires-Dist: tree-sitter-python
Requires-Dist: tree-sitter-javascript
Requires-Dist: tree-sitter-typescript
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# ProjectBrain (`projectbrain-mcp`)

**Local-first AST Context Compiler, Closed-World Dossier, and Surgical Anchor Patch Engine for AI Coding Agents.**

ProjectBrain indexes your codebase into a typed AST & call-graph (`file`, `fn`, `cls`, `route`, `mod`) in ~`90ms` and cuts coding-agent token bills by **60%–65%** while speeding up multi-file debugging by **30%–42%**:
- **Input Token Reduction (`-81.3%` to `-88.3%` code tokens, `-73.2%` to `-76.3%` billed prompt tokens):** Compiles module constants, smart-folded AST function slices, 1–3 hop bidirectional call chains with `@L<line>` caller windows, and a **Closed-World Exhaustive Repo Scan** into a single `<800`-line `.projectbrain_dossier.md` read in **1 `read_file` call**.
- **Output Token Reduction (`-63.2%` to `-77.3%` edit output tokens):** Replaces verbatim `Target` + `Replacement` repetition (`edit_file`) with a compact Anchor Patch DSL (`@file`, `@sub`, `@replace`, `@insert_after`, `@delete`) validated by Tree-sitter in `<5ms`.
- **Live ROI & Savings Ledger (`projectbrain stats`):** Tracks cumulative input/output tokens saved, file reads avoided, estimated USD saved, and developer wait-time saved in `.projectbrain_ledger.json`.

---

## Quick Start (60 Seconds)

```bash
pip install projectbrain-mcp
projectbrain --path /path/to/repo init
```

Or run as a zero-install MCP server via `uvx`:
```json
{
  "mcpServers": {
    "projectbrain": {
      "command": "uvx",
      "args": ["projectbrain-mcp"]
    }
  }
}
```

`projectbrain init` indexes the repository, updates `.gitignore`, writes `.mcp.json` (for Claude Code, Cursor, Windsurf, Antigravity), and creates `.agents/rules/projectbrain.md` so agents automatically use `brain_dossier` and `brain_patch`.

---

## Verified A/B Benchmark Results (`142`-File Production Repo)

| Benchmark Scenario | Metric | Baseline Agent (No Brain) | ProjectBrain Agent | Improvement |
| :--- | :--- | :---: | :---: | :---: |
| **Scenario 1: Targeted 3-Part Engineering Analysis** | Code Output Ingested | `67,319` tok | **`12,569` tok** | **`-81.3%` (`5.35x` smaller)** |
| | Total Prompt Tokens Billed | `655,391` tok | **`155,052` tok** | **`-76.3%` (`4.23x` fewer)** |
| | File Reads (`read_file`) | `16` | **`2`** | **`-87.5%`** |
| | Net API Cost | `$0.6723` | **`$0.2590`** | **`-61.5%` (`2.60x` cheaper)** |
| **Scenario 2: Unseen Open-Ended Bug Report (Zero Identifiers)** | Code Output Ingested | `351,658` tok (`1.40M` chars) | **`40,982` tok (`163.9k` chars)** | **`-88.3%` (`8.58x` smaller)** |
| | Total Prompt Tokens Billed | `4,561,692` tok | **`1,220,579` tok** | **`-73.2%` (`-3.34M` tokens)** |
| | File Reads (`read_file`) | `84` (`19` re-reads) | **`6` (`0` re-reads)** | **`-92.9%` (`14.0x` fewer reads)** |
| | Multi-File Patch Output Tokens | `3,359` tok (`edit_file`) | **`529` – `1,237` tok** | **`-63.2%` to `-77.3%` edit output** |
| | Net API Cost | `$3.2712` | **`$1.1557`** | **`-64.7%` (`2.83x` cheaper)** |

---

## CLI Reference

```bash
# 1. One-command repo initialization (index + .gitignore + .mcp.json + agent rules)
projectbrain --path <repo> init

# 2. Compile a single-read (<800-line) Engineering Dossier (.projectbrain_dossier.md)
projectbrain --path <repo> dossier "<question_or_bug_1>" "<question_or_bug_2>"

# 3. Apply or dry-run a Surgical Anchor Patch spec (.projectbrain_patch.diff)
projectbrain --path <repo> patch --spec "@file src/App.tsx
@sub L84 \`!profileCompleted\` -> \`isHydrated && !profileCompleted\`" [--apply]

# 4. View Live ROI & Token Savings Dashboard
projectbrain --path <repo> stats --summary

# 5. Additional granular tools
projectbrain --path <repo> slice --summary <file:symbol_or_start-end>
projectbrain --path <repo> compile "<task>" --summary
projectbrain --path <repo> explore <symbol_or_route> [target_b]
projectbrain --path <repo> impact <file1> [file2 ...]
projectbrain --path <repo> remember <symbol_or_file> "<architectural_note>"
```

---

## MCP Server (`projectbrain-mcp`)

Exposes native MCP tools for Claude Code, Cursor, Windsurf, and Antigravity:
- `brain_dossier(tasks, impact_files=None, repo_path=None)` — Compiles `<800`-line `.projectbrain_dossier.md` with module globals, folded AST slices, call chains, and Closed-World Exhaustive Repo Scan.
- `brain_patch(spec, apply=False, repo_path=None)` — Executes or dry-runs Anchor Patch DSL (`@file`, `@sub L<n>|*|ALL|<symbol>`, `@replace`, `@insert_after`, `@delete`) with Tree-sitter syntax verification.
- `brain_stats(repo_path=None, reset=False)` — Returns cumulative token, dollar, and time savings from `.projectbrain_ledger.json`.
- `brain_slice`, `brain_context`, `brain_explore`, `brain_check`, `brain_remember`.
