projectbrain-mcp 0.2.0__tar.gz

projectbrain_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,106 @@
+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`.

projectbrain_mcp-0.2.0/README.md

@@ -0,0 +1,83 @@
+# 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`.

projectbrain_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=61.0,<77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "projectbrain-mcp"
+version = "0.2.0"
+description = "Surgical AST Context Compiler, Closed-World Dossier & Anchor Patch Engine for AI Coding Agents (-75% to -88% tokens)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["ai", "agents", "mcp", "ast", "tree-sitter", "context-compression", "code-graph", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Compilers",
+]
+dependencies = [
+    "mcp",
+    "tree-sitter>=0.23",
+    "tree-sitter-python",
+    "tree-sitter-javascript",
+    "tree-sitter-typescript",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "build", "twine"]
+
+[project.scripts]
+projectbrain = "projectbrain.cli:main"
+projectbrain-mcp = "projectbrain.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

projectbrain_mcp-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

projectbrain_mcp-0.2.0/src/projectbrain/__init__.py

@@ -0,0 +1,3 @@
+from .brain import ProjectBrain
+
+__all__ = ["ProjectBrain"]