codebase-brain-mcp 0.1.0__tar.gz → 0.2.1__tar.gz

{codebase_brain_mcp-0.1.0 → codebase_brain_mcp-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebase-brain-mcp
-Version: 0.1.0
+Version: 0.2.1
 Summary: An MCP server that gives AI agents a cited, searchable memory of a codebase.
 Keywords: mcp,model-context-protocol,rag,code-search,ai-agents,claude,git
 Author: Noman Nazir
@@ -18,6 +18,9 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Dist: fastembed>=0.9.1
 Requires-Dist: mcp>=2.3.0
 Requires-Dist: numpy>=2.5.4
+Requires-Dist: tree-sitter>=0.25.2,<0.26
+Requires-Dist: tree-sitter-javascript>=0.25
+Requires-Dist: tree-sitter-typescript>=0.23.2
 Requires-Python: >=3.12
 Project-URL: Homepage, https://github.com/Nomannazir/codebase-brain-mcp
 Project-URL: Repository, https://github.com/Nomannazir/codebase-brain-mcp
@@ -73,8 +76,10 @@ A plug-in for any AI assistant that turns a codebase into something it can actua
 
 ## Why it's different (technical)
 
-- **Code-aware chunking.** Python is split by function, class and method using the real syntax tree, Markdown by
-  heading. Each chunk knows its symbol (`TimestampSigner.unsign`) and exact lines, so citations point at real code.
+- **Code-aware chunking.** Python (with `ast`) and JavaScript / TypeScript / JSX / TSX (with tree-sitter) are split
+  by function, class, method, arrow function, interface, type and enum, with their doc comments. Markdown is split
+  by heading. Each chunk knows its symbol (`TimestampSigner.unsign`, `Ky.#retry`) and exact lines, so citations
+  point at real code. Other languages are indexed in overlapping line windows.
 - **Hybrid retrieval.** SQLite FTS5 BM25 (with `camelCase` / `snake_case` identifier splitting) plus local
   embeddings, merged with reciprocal-rank fusion. Exact names and fuzzy questions both work.
 - **Local and free.** Embeddings run on your machine (`fastembed`, ONNX). No API keys, and no code leaves your
@@ -85,7 +90,8 @@ A plug-in for any AI assistant that turns a codebase into something it can actua
   the current lines, and links the pull requests behind each change. So agents can answer *"why is it built this
   way?"*, not just *"what does it do?"*.
 - **Impact analysis.** `impact_of_change` lists everything that uses a function, directly and transitively, plus the
-  tests that exercise it, before an agent changes anything.
+  tests that exercise it, before an agent changes anything. It works across Python, JavaScript and TypeScript files,
+  and follows a constructor to the code that builds its class.
 - **Doc-drift detection.** `find_doc_drift` checks Markdown and reStructuredText docs against the code. It finds
   files, functions, settings and flags that don't exist; examples passing parameters a function doesn't take; imports
   that would fail; and sections last edited long before the code they describe changed. Each finding cites the doc
@@ -97,7 +103,7 @@ A plug-in for any AI assistant that turns a codebase into something it can actua
 
 | Tool | What it does |
 |---|---|
-| `index_repo(source, name?)` | Index a local path or an `https://` git URL (shallow clone). Reports progress. |
+| `index_repo(source, name?)` | Index a local path or an `https://` git URL (blobless clone with full history). Reports progress. |
 | `ask_codebase(question, repo?, k?)` | The most relevant code and docs as cited sources, plus related commits, with instructions to answer only from them. |
 | `search(query, repo?, k?, path_prefix?, kinds?)` | Raw hybrid search, filterable by path and chunk kind. |
 | `explain_history(symbol? \| path, start_line?, end_line?, repo?)` | Every commit that changed a function or line range, newest first, with the relevant diff, current authorship, and PR titles and descriptions (GitHub). |
@@ -111,15 +117,67 @@ Also included: the resource `brain://repos`, and the prompt `answer_with_citatio
 
 ## Install
 
-Codebase Brain runs on your own machine, so there's no server or account, and it's free. With
-[uv](https://docs.astral.sh/uv/):
+Codebase Brain runs on your own machine, so there's no server or account, and it's free. It works with any
+MCP-compatible assistant. All you need is [uv](https://docs.astral.sh/uv/), and every client runs the same command:
+`uvx codebase-brain-mcp`.
+
+**Claude Code**
 
 ```bash
-# Claude Code
 claude mcp add codebase-brain -- uvx codebase-brain-mcp
+```
+
+**Cursor:** `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project)
+
+```json
+{
+  "mcpServers": {
+    "codebase-brain": { "command": "uvx", "args": ["codebase-brain-mcp"] }
+  }
+}
+```
+
+**Claude Desktop:** Settings → Developer → Edit Config (`claude_desktop_config.json`), then restart the app
+
+```json
+{
+  "mcpServers": {
+    "codebase-brain": { "command": "uvx", "args": ["codebase-brain-mcp"] }
+  }
+}
+```
+
+**VS Code (GitHub Copilot agent mode):** `.vscode/mcp.json`
+
+```json
+{
+  "servers": {
+    "codebase-brain": { "type": "stdio", "command": "uvx", "args": ["codebase-brain-mcp"] }
+  }
+}
+```
+
+**Windsurf:** `~/.codeium/windsurf/mcp_config.json`. **Gemini CLI:** `~/.gemini/settings.json`. Both use the same
+`mcpServers` block as Cursor.
+
+**OpenAI Codex CLI**
+
+```bash
+codex mcp add codebase-brain -- uvx codebase-brain-mcp
+```
+
+> **Tool doesn't start?** Desktop apps often don't see your shell's `PATH`. Run `which uvx` and put that full
+> path in `"command"`, for example `"/Users/you/.local/bin/uvx"`.
 
-# Any MCP client (Claude Desktop, Cursor, ...): add this server to its config
-{ "command": "uvx", "args": ["codebase-brain-mcp"] }
+Optional: install the [skill](https://github.com/Nomannazir/codebase-brain-mcp/blob/main/skills/codebase-brain/SKILL.md).
+It tells the agent which tool fits which question, to cite every claim, to check history before removing odd code,
+and to run impact analysis before editing. For Claude Code, run the commands below. Other agents that read
+`SKILL.md` files take the same file in their own skills folder.
+
+```bash
+mkdir -p ~/.claude/skills/codebase-brain
+curl -fsSL https://raw.githubusercontent.com/Nomannazir/codebase-brain-mcp/main/skills/codebase-brain/SKILL.md \
+  -o ~/.claude/skills/codebase-brain/SKILL.md
 ```
 
 ## Quick start
@@ -148,7 +206,7 @@ src/itsdangerous/timed.py:72-158
   ...
 ```
 
-### Use it from Claude Code
+### Use a local checkout instead (for development)
 
 ```bash
 claude mcp add codebase-brain -- uv run --directory /path/to/codebase-brain-mcp codebase-brain
@@ -209,10 +267,14 @@ because they're supposed to mention removed things.
 ## Evaluation
 
 Does search actually put the right code in front of the model? `codebase-brain eval` answers that with a benchmark.
-The benchmark has 32 questions about [pallets/itsdangerous](https://github.com/pallets/itsdangerous), pinned to
-commit `672971d`, each with the code or docs a good answer must come from. The questions are in
-[`evals/datasets/itsdangerous.toml`](https://github.com/Nomannazir/codebase-brain-mcp/blob/main/evals/datasets/itsdangerous.toml). They were written by reading the code
-before any results were measured, and haven't been changed since.
+There are two, each with 32 questions pinned to one commit, and each question lists the code or docs a good answer
+must come from. The questions were written by reading the code before any results were measured, and haven't been
+changed since.
+
+### Python: pallets/itsdangerous
+
+32 questions about [pallets/itsdangerous](https://github.com/pallets/itsdangerous) at commit `672971d`, in
+[`evals/datasets/itsdangerous.toml`](https://github.com/Nomannazir/codebase-brain-mcp/blob/main/evals/datasets/itsdangerous.toml).
 
 | Mode | Hit@1 | Hit@3 | Hit@5 | Hit@10 | MRR@10 (95% CI) | nDCG@10 | p50 latency |
 |---|---|---|---|---|---|---|---|
@@ -236,10 +298,40 @@ before any results were measured, and haven't been changed since.
   the top 5. They're listed in [`evals/results/itsdangerous.md`](https://github.com/Nomannazir/codebase-brain-mcp/blob/main/evals/results/itsdangerous.md) and are the next
   thing to improve. A larger, held-out question set will come first, so any tuning isn't fitted to these 32.
 
-Reproduce it (the first run downloads the repo and the embedding model):
+### TypeScript: sindresorhus/ky
+
+32 questions about [sindresorhus/ky](https://github.com/sindresorhus/ky) at commit `3541888`, in
+[`evals/datasets/ky.toml`](https://github.com/Nomannazir/codebase-brain-mcp/blob/main/evals/datasets/ky.toml).
+The readme is one 2,000-line file, so docs questions must find the right *section*, not just the file.
+
+| Mode | Hit@1 | Hit@3 | Hit@5 | Hit@10 | MRR@10 (95% CI) | nDCG@10 | p50 latency |
+|---|---|---|---|---|---|---|---|
+| **hybrid** (default) | 47% | 66% | 69% | 78% | 0.563 (0.41–0.71) | 0.576 | 6 ms |
+| keyword only (BM25) | 38% | 44% | 53% | 62% | 0.436 (0.29–0.59) | 0.455 | 1 ms |
+| vector only (bge-small) | 47% | **69%** | **75%** | 78% | **0.594** (0.46–0.74) | **0.604** | 5 ms |
+
+| Hit@5 by question type | describes behaviour (14) | about the docs (7) | names the code (11) |
+|---|---|---|---|
+| hybrid | 36% | **100%** | 91% |
+| keyword only | 7% | 86% | 91% |
+| vector only | **43%** | **100%** | **100%** |
+
+**What this shows:**
+- **Naming the code or asking about the docs works well:** 91–100% in the top 5.
+- **Describing behaviour in plain words is the weak spot (36%).** ky has about 25,000 lines of tests next to
+  5,000 lines of source, and the tests describe the same behaviour in plain words, so they outrank the source.
+  Every miss is listed in [`evals/results/ky.md`](https://github.com/Nomannazir/codebase-brain-mcp/blob/main/evals/results/ky.md).
+- **Hybrid is not better than vector-only here.** The intervals overlap heavily (hybrid beats vector on 5
+  questions and loses on 9), so neither is proven better. Keyword-only is clearly worst: hybrid beats it on 12
+  questions and loses on none.
+- These results are published as measured. Tuning (for example, ranking source above tests) will be checked
+  against a new held-out set, so it isn't fitted to these questions.
+
+Reproduce either benchmark (the first run downloads the repo and the embedding model):
 
 ```bash
 uv run codebase-brain eval evals/datasets/itsdangerous.toml --out evals/results
+uv run codebase-brain eval evals/datasets/ky.toml --out evals/results
 ```
 
 How it's measured:
@@ -248,14 +340,15 @@ How it's measured:
 - **nDCG@10:** each target is credited once, so duplicate chunks don't inflate the score.
 - **Confidence intervals:** 95% bootstrap over questions, seeded.
 - **Relevance:** a result is relevant if it's in the target file and, when the target names a symbol, is that symbol
-  or one of its methods.
+  or one of its methods. A docs target can name a section (`FAQ > How do I stop retrying early?`), and then that
+  section or one of its subsections counts.
 - **Dataset rot:** the harness fails if a target no longer exists at the pinned commit.
 
 ## How it works
 
 ```
-source ─► resolve (local dir / shallow https clone) ─► list files (.gitignore-aware, skips binaries and lockfiles)
-       ─► chunk (ast / headings / line windows) ─► embed (fastembed) ─► SQLite: chunks + vectors + FTS5
+source ─► resolve (local dir / blobless https clone) ─► list files (.gitignore-aware, skips binaries and lockfiles)
+       ─► chunk (ast / tree-sitter / headings / windows) ─► embed (fastembed) ─► SQLite: chunks + vectors + FTS5
 query  ─► BM25 top 50 ┐
        ─► vector top 50 ┴─► reciprocal-rank fusion ─► filters ─► cited sources
 ```
@@ -274,7 +367,7 @@ query  ─► BM25 top 50 ┐
 ## Development
 
 ```bash
-uv run pytest           # 54 tests, offline (hash embedder, temporary git repos, in-process MCP client)
+uv run pytest           # 67 tests, offline (hash embedder, temporary git repos, in-process MCP client)
 uv run ruff check .     # lint
 uv run ruff format .    # format
 uv run pyright          # types
@@ -285,9 +378,11 @@ uv run pyright          # types
 - [x] Git history and PR discussions: `explain_history`, `search_history`
 - [x] Symbol references and transitive dependents: `impact_of_change`
 - [x] `find_doc_drift`: Markdown and reStructuredText, signatures, imports, settings, flags, staleness
-- [ ] tree-sitter chunking for more languages
+- [x] JavaScript and TypeScript (tree-sitter): chunking, references, impact analysis
+- [ ] More languages (Go, Rust, Java) with tree-sitter
 - [x] Retrieval evals with confidence intervals (`codebase-brain eval`)
 - [ ] Larger held-out eval set, then retrieval tuning (reranking, query expansion)
 - [x] Streamable HTTP with bearer-token auth, Docker image
-- [ ] Hosted demo, PyPI package, MCP Registry listing
+- [x] PyPI package, MCP Registry listing
+- [ ] Hosted demo
 - [ ] OpenTelemetry tracing

{codebase_brain_mcp-0.1.0 → codebase_brain_mcp-0.2.1}/README.md

@@ -47,8 +47,10 @@ A plug-in for any AI assistant that turns a codebase into something it can actua
 
 ## Why it's different (technical)
 
-- **Code-aware chunking.** Python is split by function, class and method using the real syntax tree, Markdown by
-  heading. Each chunk knows its symbol (`TimestampSigner.unsign`) and exact lines, so citations point at real code.
+- **Code-aware chunking.** Python (with `ast`) and JavaScript / TypeScript / JSX / TSX (with tree-sitter) are split
+  by function, class, method, arrow function, interface, type and enum, with their doc comments. Markdown is split
+  by heading. Each chunk knows its symbol (`TimestampSigner.unsign`, `Ky.#retry`) and exact lines, so citations
+  point at real code. Other languages are indexed in overlapping line windows.
 - **Hybrid retrieval.** SQLite FTS5 BM25 (with `camelCase` / `snake_case` identifier splitting) plus local
   embeddings, merged with reciprocal-rank fusion. Exact names and fuzzy questions both work.
 - **Local and free.** Embeddings run on your machine (`fastembed`, ONNX). No API keys, and no code leaves your
@@ -59,7 +61,8 @@ A plug-in for any AI assistant that turns a codebase into something it can actua
   the current lines, and links the pull requests behind each change. So agents can answer *"why is it built this
   way?"*, not just *"what does it do?"*.
 - **Impact analysis.** `impact_of_change` lists everything that uses a function, directly and transitively, plus the
-  tests that exercise it, before an agent changes anything.
+  tests that exercise it, before an agent changes anything. It works across Python, JavaScript and TypeScript files,
+  and follows a constructor to the code that builds its class.
 - **Doc-drift detection.** `find_doc_drift` checks Markdown and reStructuredText docs against the code. It finds
   files, functions, settings and flags that don't exist; examples passing parameters a function doesn't take; imports
   that would fail; and sections last edited long before the code they describe changed. Each finding cites the doc
@@ -71,7 +74,7 @@ A plug-in for any AI assistant that turns a codebase into something it can actua
 
 | Tool | What it does |
 |---|---|
-| `index_repo(source, name?)` | Index a local path or an `https://` git URL (shallow clone). Reports progress. |
+| `index_repo(source, name?)` | Index a local path or an `https://` git URL (blobless clone with full history). Reports progress. |
 | `ask_codebase(question, repo?, k?)` | The most relevant code and docs as cited sources, plus related commits, with instructions to answer only from them. |
 | `search(query, repo?, k?, path_prefix?, kinds?)` | Raw hybrid search, filterable by path and chunk kind. |
 | `explain_history(symbol? \| path, start_line?, end_line?, repo?)` | Every commit that changed a function or line range, newest first, with the relevant diff, current authorship, and PR titles and descriptions (GitHub). |
@@ -85,15 +88,67 @@ Also included: the resource `brain://repos`, and the prompt `answer_with_citatio
 
 ## Install
 
-Codebase Brain runs on your own machine, so there's no server or account, and it's free. With
-[uv](https://docs.astral.sh/uv/):
+Codebase Brain runs on your own machine, so there's no server or account, and it's free. It works with any
+MCP-compatible assistant. All you need is [uv](https://docs.astral.sh/uv/), and every client runs the same command:
+`uvx codebase-brain-mcp`.
+
+**Claude Code**
 
 ```bash
-# Claude Code
 claude mcp add codebase-brain -- uvx codebase-brain-mcp
+```
+
+**Cursor:** `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project)
+
+```json
+{
+  "mcpServers": {
+    "codebase-brain": { "command": "uvx", "args": ["codebase-brain-mcp"] }
+  }
+}
+```
+
+**Claude Desktop:** Settings → Developer → Edit Config (`claude_desktop_config.json`), then restart the app
+
+```json
+{
+  "mcpServers": {
+    "codebase-brain": { "command": "uvx", "args": ["codebase-brain-mcp"] }
+  }
+}
+```
+
+**VS Code (GitHub Copilot agent mode):** `.vscode/mcp.json`
+
+```json
+{
+  "servers": {
+    "codebase-brain": { "type": "stdio", "command": "uvx", "args": ["codebase-brain-mcp"] }
+  }
+}
+```
+
+**Windsurf:** `~/.codeium/windsurf/mcp_config.json`. **Gemini CLI:** `~/.gemini/settings.json`. Both use the same
+`mcpServers` block as Cursor.
+
+**OpenAI Codex CLI**
+
+```bash
+codex mcp add codebase-brain -- uvx codebase-brain-mcp
+```
+
+> **Tool doesn't start?** Desktop apps often don't see your shell's `PATH`. Run `which uvx` and put that full
+> path in `"command"`, for example `"/Users/you/.local/bin/uvx"`.
 
-# Any MCP client (Claude Desktop, Cursor, ...): add this server to its config
-{ "command": "uvx", "args": ["codebase-brain-mcp"] }
+Optional: install the [skill](https://github.com/Nomannazir/codebase-brain-mcp/blob/main/skills/codebase-brain/SKILL.md).
+It tells the agent which tool fits which question, to cite every claim, to check history before removing odd code,
+and to run impact analysis before editing. For Claude Code, run the commands below. Other agents that read
+`SKILL.md` files take the same file in their own skills folder.
+
+```bash
+mkdir -p ~/.claude/skills/codebase-brain
+curl -fsSL https://raw.githubusercontent.com/Nomannazir/codebase-brain-mcp/main/skills/codebase-brain/SKILL.md \
+  -o ~/.claude/skills/codebase-brain/SKILL.md
 ```
 
 ## Quick start
@@ -122,7 +177,7 @@ src/itsdangerous/timed.py:72-158
   ...
 ```
 
-### Use it from Claude Code
+### Use a local checkout instead (for development)
 
 ```bash
 claude mcp add codebase-brain -- uv run --directory /path/to/codebase-brain-mcp codebase-brain
@@ -183,10 +238,14 @@ because they're supposed to mention removed things.
 ## Evaluation
 
 Does search actually put the right code in front of the model? `codebase-brain eval` answers that with a benchmark.
-The benchmark has 32 questions about [pallets/itsdangerous](https://github.com/pallets/itsdangerous), pinned to
-commit `672971d`, each with the code or docs a good answer must come from. The questions are in
-[`evals/datasets/itsdangerous.toml`](https://github.com/Nomannazir/codebase-brain-mcp/blob/main/evals/datasets/itsdangerous.toml). They were written by reading the code
-before any results were measured, and haven't been changed since.
+There are two, each with 32 questions pinned to one commit, and each question lists the code or docs a good answer
+must come from. The questions were written by reading the code before any results were measured, and haven't been
+changed since.
+
+### Python: pallets/itsdangerous
+
+32 questions about [pallets/itsdangerous](https://github.com/pallets/itsdangerous) at commit `672971d`, in
+[`evals/datasets/itsdangerous.toml`](https://github.com/Nomannazir/codebase-brain-mcp/blob/main/evals/datasets/itsdangerous.toml).
 
 | Mode | Hit@1 | Hit@3 | Hit@5 | Hit@10 | MRR@10 (95% CI) | nDCG@10 | p50 latency |
 |---|---|---|---|---|---|---|---|
@@ -210,10 +269,40 @@ before any results were measured, and haven't been changed since.
   the top 5. They're listed in [`evals/results/itsdangerous.md`](https://github.com/Nomannazir/codebase-brain-mcp/blob/main/evals/results/itsdangerous.md) and are the next
   thing to improve. A larger, held-out question set will come first, so any tuning isn't fitted to these 32.
 
-Reproduce it (the first run downloads the repo and the embedding model):
+### TypeScript: sindresorhus/ky
+
+32 questions about [sindresorhus/ky](https://github.com/sindresorhus/ky) at commit `3541888`, in
+[`evals/datasets/ky.toml`](https://github.com/Nomannazir/codebase-brain-mcp/blob/main/evals/datasets/ky.toml).
+The readme is one 2,000-line file, so docs questions must find the right *section*, not just the file.
+
+| Mode | Hit@1 | Hit@3 | Hit@5 | Hit@10 | MRR@10 (95% CI) | nDCG@10 | p50 latency |
+|---|---|---|---|---|---|---|---|
+| **hybrid** (default) | 47% | 66% | 69% | 78% | 0.563 (0.41–0.71) | 0.576 | 6 ms |
+| keyword only (BM25) | 38% | 44% | 53% | 62% | 0.436 (0.29–0.59) | 0.455 | 1 ms |
+| vector only (bge-small) | 47% | **69%** | **75%** | 78% | **0.594** (0.46–0.74) | **0.604** | 5 ms |
+
+| Hit@5 by question type | describes behaviour (14) | about the docs (7) | names the code (11) |
+|---|---|---|---|
+| hybrid | 36% | **100%** | 91% |
+| keyword only | 7% | 86% | 91% |
+| vector only | **43%** | **100%** | **100%** |
+
+**What this shows:**
+- **Naming the code or asking about the docs works well:** 91–100% in the top 5.
+- **Describing behaviour in plain words is the weak spot (36%).** ky has about 25,000 lines of tests next to
+  5,000 lines of source, and the tests describe the same behaviour in plain words, so they outrank the source.
+  Every miss is listed in [`evals/results/ky.md`](https://github.com/Nomannazir/codebase-brain-mcp/blob/main/evals/results/ky.md).
+- **Hybrid is not better than vector-only here.** The intervals overlap heavily (hybrid beats vector on 5
+  questions and loses on 9), so neither is proven better. Keyword-only is clearly worst: hybrid beats it on 12
+  questions and loses on none.
+- These results are published as measured. Tuning (for example, ranking source above tests) will be checked
+  against a new held-out set, so it isn't fitted to these questions.
+
+Reproduce either benchmark (the first run downloads the repo and the embedding model):
 
 ```bash
 uv run codebase-brain eval evals/datasets/itsdangerous.toml --out evals/results
+uv run codebase-brain eval evals/datasets/ky.toml --out evals/results
 ```
 
 How it's measured:
@@ -222,14 +311,15 @@ How it's measured:
 - **nDCG@10:** each target is credited once, so duplicate chunks don't inflate the score.
 - **Confidence intervals:** 95% bootstrap over questions, seeded.
 - **Relevance:** a result is relevant if it's in the target file and, when the target names a symbol, is that symbol
-  or one of its methods.
+  or one of its methods. A docs target can name a section (`FAQ > How do I stop retrying early?`), and then that
+  section or one of its subsections counts.
 - **Dataset rot:** the harness fails if a target no longer exists at the pinned commit.
 
 ## How it works
 
 ```
-source ─► resolve (local dir / shallow https clone) ─► list files (.gitignore-aware, skips binaries and lockfiles)
-       ─► chunk (ast / headings / line windows) ─► embed (fastembed) ─► SQLite: chunks + vectors + FTS5
+source ─► resolve (local dir / blobless https clone) ─► list files (.gitignore-aware, skips binaries and lockfiles)
+       ─► chunk (ast / tree-sitter / headings / windows) ─► embed (fastembed) ─► SQLite: chunks + vectors + FTS5
 query  ─► BM25 top 50 ┐
        ─► vector top 50 ┴─► reciprocal-rank fusion ─► filters ─► cited sources
 ```
@@ -248,7 +338,7 @@ query  ─► BM25 top 50 ┐
 ## Development
 
 ```bash
-uv run pytest           # 54 tests, offline (hash embedder, temporary git repos, in-process MCP client)
+uv run pytest           # 67 tests, offline (hash embedder, temporary git repos, in-process MCP client)
 uv run ruff check .     # lint
 uv run ruff format .    # format
 uv run pyright          # types
@@ -259,9 +349,11 @@ uv run pyright          # types
 - [x] Git history and PR discussions: `explain_history`, `search_history`
 - [x] Symbol references and transitive dependents: `impact_of_change`
 - [x] `find_doc_drift`: Markdown and reStructuredText, signatures, imports, settings, flags, staleness
-- [ ] tree-sitter chunking for more languages
+- [x] JavaScript and TypeScript (tree-sitter): chunking, references, impact analysis
+- [ ] More languages (Go, Rust, Java) with tree-sitter
 - [x] Retrieval evals with confidence intervals (`codebase-brain eval`)
 - [ ] Larger held-out eval set, then retrieval tuning (reranking, query expansion)
 - [x] Streamable HTTP with bearer-token auth, Docker image
-- [ ] Hosted demo, PyPI package, MCP Registry listing
+- [x] PyPI package, MCP Registry listing
+- [ ] Hosted demo
 - [ ] OpenTelemetry tracing

{codebase_brain_mcp-0.1.0 → codebase_brain_mcp-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codebase-brain-mcp"
-version = "0.1.0"
+version = "0.2.1"
 description = "An MCP server that gives AI agents a cited, searchable memory of a codebase."
 readme = "README.md"
 license = "MIT"
@@ -29,6 +29,9 @@ dependencies = [
     "fastembed>=0.9.1",
     "mcp>=2.3.0",
     "numpy>=2.5.4",
+    "tree-sitter>=0.25.2,<0.26",
+    "tree-sitter-javascript>=0.25",
+    "tree-sitter-typescript>=0.23.2",
 ]
 
 [[project.authors]]

{codebase_brain_mcp-0.1.0 → codebase_brain_mcp-0.2.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "codebase-brain-mcp"
-version = "0.1.0"
+version = "0.2.1"
 description = "An MCP server that gives AI agents a cited, searchable memory of a codebase."
 readme = "README.md"
 authors = [
@@ -24,6 +24,9 @@ dependencies = [
     "fastembed>=0.9.1",
     "mcp>=2.3.0",
     "numpy>=2.5.4",
+    "tree-sitter>=0.25.2,<0.26",  # 0.26.0 crashes the process (SIGBUS) while walking big files
+    "tree-sitter-javascript>=0.25",
+    "tree-sitter-typescript>=0.23.2",
 ]
 
 [project.urls]

{codebase_brain_mcp-0.1.0 → codebase_brain_mcp-0.2.1}/src/codebase_brain_mcp/analysis.py

@@ -13,10 +13,12 @@ from datetime import datetime, timedelta
 from pathlib import Path
 
 from . import history
+from .chunking import DEFINITION_KINDS
 from .sources import SourceError
 from .store import Store, StoredChunk
 
 MAX_PER_LEVEL = 60
+STRUCTURED_SUFFIXES = (".py", ".pyi", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx")
 STALE_AFTER = timedelta(days=180)
 MAX_STALENESS_CHECKS = 40
 _FENCE = re.compile(r"^(`{3,}|~{3,})\s*([\w+-]*)[^\n]*\n(.*?)^\1\s*$", re.MULTILINE | re.DOTALL)
@@ -31,7 +33,7 @@ _PATH = re.compile(r"^\.?/?[\w.-]+(/[\w.-]+)+/?$")
 _ENV = re.compile(r"^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$")
 _FLAG = re.compile(r"^(--[a-z][a-z0-9-]+)(=\S*)?$")
 _SYMBOL = re.compile(r"^[A-Za-z_]\w*(\.[A-Za-z_]\w*)*(\(\))?$")
-_TEST_PATH = re.compile(r"(^|/)(tests?|testing)/|(^|/)test_[^/]+$|_test\.\w+$")
+_TEST_PATH = re.compile(r"(^|/)(tests?|testing|__tests__)/|(^|/)test_[^/]+$|_test\.\w+$|\.(test|spec)\.[jt]sx?$")
 _COMMON = set(dir(builtins)) | set(keyword.kwlist) | {"true", "false", "null", "none", "self", "cls"}
 _SEVERITY_ORDER = {"high": 0, "medium": 1, "low": 2}
 _CHANGELOG = re.compile(
@@ -57,6 +59,8 @@ def definition_span(matches: list[StoredChunk]) -> tuple[str, int, int, str | No
 
 # ---- impact_of_change -------------------------------------------------------------------------
 
+_CONSTRUCTORS = {"__init__", "__new__", "constructor"}
+
 
 @dataclass(frozen=True)
 class Dependent:
@@ -79,13 +83,21 @@ class ImpactReport:
     notes: list[str] = field(default_factory=list)
 
 
+def _used_as(symbol: str) -> str:
+    """The name other code uses to reach ``symbol``: a constructor is reached through its class."""
+    owner, _, short = symbol.rpartition(".")
+    if short in _CONSTRUCTORS and owner:
+        return owner.rsplit(".", 1)[-1]
+    return short
+
+
 def impact_of_change(store: Store, target: StoredChunk, span: tuple[int, int], depth: int = 2) -> ImpactReport:
     """Everything that uses ``target`` by name, directly and (up to ``depth``) transitively."""
     symbol = target.symbol or ""
     short = symbol.rsplit(".", 1)[-1]
     excluded = {c.id for c in store.find_symbol(symbol, target.path)}
     dependents: list[Dependent] = []
-    frontier = [short]
+    frontier = [_used_as(symbol)]
     for level in range(1, max(1, min(depth, 3)) + 1):
         next_frontier: list[str] = []
         for name in frontier:
@@ -97,8 +109,8 @@ def impact_of_change(store: Store, target: StoredChunk, span: tuple[int, int], d
                 dependents.append(
                     Dependent(chunk=chunk, via=name, level=level, is_test=bool(_TEST_PATH.search(chunk.path)))
                 )
-                if chunk.symbol and chunk.kind in ("function", "method", "class"):
-                    next_frontier.append(chunk.symbol.rsplit(".", 1)[-1])
+                if chunk.symbol and chunk.kind in DEFINITION_KINDS:
+                    next_frontier.append(_used_as(chunk.symbol))
         frontier = list(dict.fromkeys(next_frontier))
         if not frontier:
             break
@@ -114,8 +126,8 @@ def impact_of_change(store: Store, target: StoredChunk, span: tuple[int, int], d
             f"{len(twins)} other definition(s) share the name {short!r}; some dependents may use those "
             "instead. Check the import or receiver before changing anything."
         )
-    if not target.path.endswith((".py", ".pyi")):
-        notes.append("Only Python is analysed structurally; for other languages, also run search for the name.")
+    if not target.path.endswith(STRUCTURED_SUFFIXES):
+        notes.append("Only Python, JS and TS are analysed structurally; for other languages, also search the name.")
     notes.append("Found by name, so dynamic calls (getattr, string dispatch, callbacks) aren't included.")
     return ImpactReport(
         symbol=symbol,