java-codebase-rag 0.1.0__tar.gz → 0.2.0__tar.gz

java_codebase_rag-0.2.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: java-codebase-rag
+Version: 0.2.0
+Summary: MCP server for semantic + structural search over Java codebases
+Author: HumanBean17
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/HumanBean17/java-codebase-rag
+Project-URL: Repository, https://github.com/HumanBean17/java-codebase-rag
+Project-URL: Issues, https://github.com/HumanBean17/java-codebase-rag/issues
+Keywords: mcp,java,rag,code-search,graph,lancedb,kuzu
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: kuzu<0.12,>=0.11.3
+Requires-Dist: lancedb<0.31,>=0.25.3
+Requires-Dist: mcp<2,>=1.27.0
+Requires-Dist: numpy<2.5,>=1.26.4
+Requires-Dist: pathspec<2,>=1.0.4
+Requires-Dist: pyarrow<24,>=23.0.1
+Requires-Dist: PyYAML<7,>=6.0.3
+Requires-Dist: sentence-transformers<6,>=5.4.0
+Requires-Dist: tree-sitter<0.26,>=0.25.2
+Requires-Dist: tree-sitter-java<0.24,>=0.23.5
+Requires-Dist: unidiff<1,>=0.7.3
+Dynamic: license-file
+
+# java-codebase-rag
+
+A graph-native code intelligence layer for Java microservice estates, exposed to LLM agents via the **Model Context Protocol (MCP)**.
+
+The system extracts a deterministic property graph from Java source (tree-sitter), stores it in **Kuzu** (graph) alongside a **LanceDB** vector index (chunks), and exposes a deliberately small MCP surface — **five tools**: `search`, `find`, `describe`, `neighbors`, `resolve` — that collapse onto three primitive agent operations: **locate**, **inspect**, **walk**.
+
+> **What this MCP is:** a **GPS for code navigation**, not a reasoning engine.
+> Agents use a simple loop:
+>
+> 1. **Locate** entry nodes (`search` / `find`, or identifier-shaped **`resolve`**)
+> 2. **Inspect** what a node is (`describe`)
+> 3. **Walk** one hop at a time (`neighbors`) until enough evidence is gathered
+>
+> The MCP exposes structure and adjacency; the agent owns multi-hop reasoning and stop conditions.
+
+For the design rationale, the GPS metaphor, and the full ontology, see [`docs/paper/paper.pdf`](./docs/paper/paper.pdf) (architecture report).
+
+---
+
+## Install
+
+```bash
+pip install java-codebase-rag
+```
+
+Python **3.11+** required. After install, `java-codebase-rag --help` should print the CLI groups.
+
+> **Stability disclaimer.** This package does **not** promise backward compatibility. MCP tool contracts, env vars, Lance/Kuzu schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change.
+
+---
+
+## 5-minute walkthrough — index this repo's bank-chat fixture
+
+This repo ships a small multi-module Spring fixture under [`tests/bank-chat-system/`](./tests/bank-chat-system/) (`chat-core` + `chat-assign`) that the test suite uses for calibration. You can index it and confirm the install works end-to-end in under five minutes — no agent host required.
+
+```bash
+# 1. Clone the repo to get the fixture (the published package doesn't include tests/)
+git clone https://github.com/HumanBean17/java-codebase-rag
+cd java-codebase-rag
+
+# 2. Build the index (Lance vectors + Kuzu graph). First run downloads the
+#    embedding model (~90 MB) and takes ~30-60s on the fixture.
+java-codebase-rag init --source-root tests/bank-chat-system --index-dir /tmp/bank-chat-index
+
+# 3. Inspect what landed (resolved config, edge counts, ontology version)
+java-codebase-rag meta --source-root tests/bank-chat-system --index-dir /tmp/bank-chat-index
+```
+
+Smoke-test the index with two checks (`search_lancedb` ships with the package):
+
+```bash
+# Vector search — proves the LanceDB side works
+JAVA_CODEBASE_RAG_INDEX_DIR=/tmp/bank-chat-index \
+  python -m search_lancedb "chat ingress controller" --table java --limit 3
+
+# Vector + graph expansion — proves Kuzu is wired in
+JAVA_CODEBASE_RAG_INDEX_DIR=/tmp/bank-chat-index \
+  python -m search_lancedb "chat ingress controller" --table java --limit 3 \
+    --graph-expand --expand-depth 2
+```
+
+If vector hits come back and graph expansion adds neighbor symbols, the install works end-to-end. Wire it into your agent next — the five MCP tools (`search`, `find`, `describe`, `neighbors`, `resolve`) are reachable over stdio.
+
+---
+
+## Wire into an MCP host
+
+### Claude Code
+
+With the package installed, the console script `java-codebase-rag-mcp` is on your `PATH`. Register it project-scoped:
+
+```bash
+claude mcp add --transport stdio java-codebase-rag -- java-codebase-rag-mcp
+```
+
+Then set env vars (`JAVA_CODEBASE_RAG_INDEX_DIR`, `JAVA_CODEBASE_RAG_SOURCE_ROOT`, `SBERT_MODEL`, …) in `.mcp.json` or your shell profile. For a project-scoped `.mcp.json` template, see [`mcp.json.example`](./mcp.json.example). Official docs: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings).
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`) and add under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "java-codebase-rag": {
+      "command": "java-codebase-rag-mcp",
+      "env": {
+        "JAVA_CODEBASE_RAG_INDEX_DIR": "/ABSOLUTE/PATH/TO/.java-codebase-rag",
+        "JAVA_CODEBASE_RAG_SOURCE_ROOT": "/ABSOLUTE/PATH/TO/your-java-project"
+      }
+    }
+  }
+}
+```
+
+See [`mcp.json.example`](./mcp.json.example) for the same shape in `.mcp.json` (Claude Code project-scoped) form.
+
+### Driving the MCP from an agent
+
+Pick **one** of two options (not both — they cover the same navigation intents):
+
+1. **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** (recommended for most) — standalone MCP operating manual. Copy-paste the `BEGIN`/`END` block into your project's `QWEN.md`, `CLAUDE.md`, or `AGENTS.md`. Contains: five-tool reference, `NodeFilter` / edge taxonomy, ontology glossary, recovery playbook, and inline slash-style aliases (`/callers`, `/callees`, `/routes`, etc.) as prompt templates. Self-contained — no external file dependencies.
+
+2. **[`skills/`](./skills/)** (for hosts with skill discovery) — 15 shipped `SKILL.md` files. If your MCP host supports skill discovery (Claude Code, Qwen Code, Cursor), the same navigation intents are available as discoverable `/` commands. Tier 1 = deterministic MCP chains (`/callers`, `/callees`, `/routes`, `/controllers`, `/clients`, `/producers`, `/handlers`, `/who-hits-route`, `/implements`, `/injects`, `/nl`). Tier 2 = bounded workflows (`/explain-feature`, `/impact-of`, `/trace-request-flow`, `/mini-map`). See [`skills/README.md`](./skills/README.md) for the full index.
+
+Also: **[`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md)** — 7-phase agent-driven verification you run after indexing your real project.
+
+---
+
+## The five tools, at a glance
+
+| Tool | Purpose | Required args |
+|---|---|---|
+| `search` | Locate nodes by NL / code text. | `query` |
+| `find` | Locate nodes by structured filter. | `kind`, `filter` |
+| `describe` | Full record + edge counts for one node. | `id` |
+| `resolve` | Identifier-shaped lookup (FQN-collision-safe). Returns `one` / `many` / `none`. | `identifier` |
+| `neighbors` | Graph walk, one hop. | `ids`, `direction`, `edge_types` |
+
+Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live in [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md). Edge types and traversal directions are listed in [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md).
+
+### Three-layer architecture
+
+Layer 1 (storage) → Layer 2 (5 MCP tools) → Layer 3 (skills). Navigation skills in [`skills/`](./skills/) wrap the MCP tools into deterministic chains (Tier 1) and bounded workflows (Tier 2). See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
+
+---
+
+## Configuration
+
+The operator-facing surface is small: pick an index dir, pick an embedding model, optionally drop a `.java-codebase-rag.yml` at your project root for microservice layout and brownfield overrides.
+
+| If you want to… | See |
+|---|---|
+| Set env vars and override precedence | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §1 |
+| Configure microservice roots and embeddings via YAML | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §2 |
+| Understand the graph (nodes, edges, capabilities, ranking) | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §3 |
+| Steer a brownfield Java tree (custom stereotypes, non-Spring stacks) | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §4 |
+| Control which files the indexer walks | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §5 |
+| Check whether your repo fits this tool's assumptions | [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) |
+
+---
+
+## CLI cheat sheet
+
+Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook with workflows, exit codes, and env alignment lives in [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md).
+
+| Group | Subcommand | What it does |
+|---|---|---|
+| Lifecycle | `init` | First-time index. Refuses if artifacts already exist. |
+| Lifecycle | `increment` | CocoIndex catch-up (Lance only); Kuzu stays stale until `reprocess`. |
+| Lifecycle | `reprocess` | Full Lance + Kuzu rebuild. `--vectors-only` / `--graph-only` for a single phase. |
+| Lifecycle | `erase` | Delete index artifacts. Requires `--yes` or TTY confirm. |
+| Introspection | `meta`, `tables`, `diagnose-ignore`, `unresolved-calls` | Health, table listing, ignore-layer diagnostics, receiver-failure call sites. |
+| Analysis | `analyze-pr` | Blast-radius / risk from a unified diff. |
+
+---
+
+## Further reading
+
+| Document | What's in it |
+|---|---|
+| [`docs/paper/paper.pdf`](./docs/paper/paper.pdf) | Architecture report — design rationale, GPS metaphor, three-layer architecture, design principles, future work. |
+| [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md) | Agent-facing guide. Copy-paste into `QWEN.md` / `CLAUDE.md` / `AGENTS.md`. |
+| [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) | Environment variables, project YAML, graph ontology, brownfield overrides, ignore patterns. |
+| [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) | CLI operator playbook: workflows, exit codes, env alignment. |
+| [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) | MCP-traversable edges, directions, dot-key composition. |
+| [`skills/`](./skills/) | 15 navigation and workflow skills for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
+| [`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md) | 7-phase agent-driven verification after indexing your project. |
+| [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) | Assumptions about your Java repo + per-file edit map for non-conforming codebases. |
+| [`automation/cursor_propose_only/README.md`](./automation/cursor_propose_only/README.md) | Optional proposal orchestration workflow (single-command autopilot, planning bundles, automated execution/review loops). |
+| [`docs/PRODUCT-VISION.md`](./docs/PRODUCT-VISION.md) | Long-term product direction. |
+
+---
+
+## Install from source (contributors)
+
+```bash
+git clone https://github.com/HumanBean17/java-codebase-rag
+cd java-codebase-rag
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+```
+
+The `cocoindex` package is **only** needed for lifecycle commands that run the indexer (`init`, `increment`, `reprocess`, `erase`). Search and MCP navigation work without it.
+
+The default embedding model is `sentence-transformers/all-MiniLM-L6-v2` (downloaded on first `init`). Override via the `EMBEDDING_MODEL` env var — see [`docs/CONFIGURATION.md` §1](./docs/CONFIGURATION.md#1-environment-variables).
+
+---
+
+## Roadmap (graph layer)
+
+- `get_service_topology` — microservice-level summary aggregating `HTTP_CALLS` / `ASYNC_CALLS`.
+- Agentic routing layer (query classifier → vector / graph / both).
+- Incremental Kuzu updates (per-changed-file) — see [`propose/TIER2-INCREMENTAL-REBUILD-PROPOSE.md`](./propose/TIER2-INCREMENTAL-REBUILD-PROPOSE.md) and [`propose/INDEX-AUTO-MODE-PROPOSE.md`](./propose/INDEX-AUTO-MODE-PROPOSE.md).
+- Optional `codegraph_nodes` LanceDB table embedding symbol summaries so the graph itself is vector-searchable.

java_codebase_rag-0.2.0/README.md

@@ -0,0 +1,195 @@
+# java-codebase-rag
+
+A graph-native code intelligence layer for Java microservice estates, exposed to LLM agents via the **Model Context Protocol (MCP)**.
+
+The system extracts a deterministic property graph from Java source (tree-sitter), stores it in **Kuzu** (graph) alongside a **LanceDB** vector index (chunks), and exposes a deliberately small MCP surface — **five tools**: `search`, `find`, `describe`, `neighbors`, `resolve` — that collapse onto three primitive agent operations: **locate**, **inspect**, **walk**.
+
+> **What this MCP is:** a **GPS for code navigation**, not a reasoning engine.
+> Agents use a simple loop:
+>
+> 1. **Locate** entry nodes (`search` / `find`, or identifier-shaped **`resolve`**)
+> 2. **Inspect** what a node is (`describe`)
+> 3. **Walk** one hop at a time (`neighbors`) until enough evidence is gathered
+>
+> The MCP exposes structure and adjacency; the agent owns multi-hop reasoning and stop conditions.
+
+For the design rationale, the GPS metaphor, and the full ontology, see [`docs/paper/paper.pdf`](./docs/paper/paper.pdf) (architecture report).
+
+---
+
+## Install
+
+```bash
+pip install java-codebase-rag
+```
+
+Python **3.11+** required. After install, `java-codebase-rag --help` should print the CLI groups.
+
+> **Stability disclaimer.** This package does **not** promise backward compatibility. MCP tool contracts, env vars, Lance/Kuzu schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change.
+
+---
+
+## 5-minute walkthrough — index this repo's bank-chat fixture
+
+This repo ships a small multi-module Spring fixture under [`tests/bank-chat-system/`](./tests/bank-chat-system/) (`chat-core` + `chat-assign`) that the test suite uses for calibration. You can index it and confirm the install works end-to-end in under five minutes — no agent host required.
+
+```bash
+# 1. Clone the repo to get the fixture (the published package doesn't include tests/)
+git clone https://github.com/HumanBean17/java-codebase-rag
+cd java-codebase-rag
+
+# 2. Build the index (Lance vectors + Kuzu graph). First run downloads the
+#    embedding model (~90 MB) and takes ~30-60s on the fixture.
+java-codebase-rag init --source-root tests/bank-chat-system --index-dir /tmp/bank-chat-index
+
+# 3. Inspect what landed (resolved config, edge counts, ontology version)
+java-codebase-rag meta --source-root tests/bank-chat-system --index-dir /tmp/bank-chat-index
+```
+
+Smoke-test the index with two checks (`search_lancedb` ships with the package):
+
+```bash
+# Vector search — proves the LanceDB side works
+JAVA_CODEBASE_RAG_INDEX_DIR=/tmp/bank-chat-index \
+  python -m search_lancedb "chat ingress controller" --table java --limit 3
+
+# Vector + graph expansion — proves Kuzu is wired in
+JAVA_CODEBASE_RAG_INDEX_DIR=/tmp/bank-chat-index \
+  python -m search_lancedb "chat ingress controller" --table java --limit 3 \
+    --graph-expand --expand-depth 2
+```
+
+If vector hits come back and graph expansion adds neighbor symbols, the install works end-to-end. Wire it into your agent next — the five MCP tools (`search`, `find`, `describe`, `neighbors`, `resolve`) are reachable over stdio.
+
+---
+
+## Wire into an MCP host
+
+### Claude Code
+
+With the package installed, the console script `java-codebase-rag-mcp` is on your `PATH`. Register it project-scoped:
+
+```bash
+claude mcp add --transport stdio java-codebase-rag -- java-codebase-rag-mcp
+```
+
+Then set env vars (`JAVA_CODEBASE_RAG_INDEX_DIR`, `JAVA_CODEBASE_RAG_SOURCE_ROOT`, `SBERT_MODEL`, …) in `.mcp.json` or your shell profile. For a project-scoped `.mcp.json` template, see [`mcp.json.example`](./mcp.json.example). Official docs: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings).
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`) and add under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "java-codebase-rag": {
+      "command": "java-codebase-rag-mcp",
+      "env": {
+        "JAVA_CODEBASE_RAG_INDEX_DIR": "/ABSOLUTE/PATH/TO/.java-codebase-rag",
+        "JAVA_CODEBASE_RAG_SOURCE_ROOT": "/ABSOLUTE/PATH/TO/your-java-project"
+      }
+    }
+  }
+}
+```
+
+See [`mcp.json.example`](./mcp.json.example) for the same shape in `.mcp.json` (Claude Code project-scoped) form.
+
+### Driving the MCP from an agent
+
+Pick **one** of two options (not both — they cover the same navigation intents):
+
+1. **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** (recommended for most) — standalone MCP operating manual. Copy-paste the `BEGIN`/`END` block into your project's `QWEN.md`, `CLAUDE.md`, or `AGENTS.md`. Contains: five-tool reference, `NodeFilter` / edge taxonomy, ontology glossary, recovery playbook, and inline slash-style aliases (`/callers`, `/callees`, `/routes`, etc.) as prompt templates. Self-contained — no external file dependencies.
+
+2. **[`skills/`](./skills/)** (for hosts with skill discovery) — 15 shipped `SKILL.md` files. If your MCP host supports skill discovery (Claude Code, Qwen Code, Cursor), the same navigation intents are available as discoverable `/` commands. Tier 1 = deterministic MCP chains (`/callers`, `/callees`, `/routes`, `/controllers`, `/clients`, `/producers`, `/handlers`, `/who-hits-route`, `/implements`, `/injects`, `/nl`). Tier 2 = bounded workflows (`/explain-feature`, `/impact-of`, `/trace-request-flow`, `/mini-map`). See [`skills/README.md`](./skills/README.md) for the full index.
+
+Also: **[`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md)** — 7-phase agent-driven verification you run after indexing your real project.
+
+---
+
+## The five tools, at a glance
+
+| Tool | Purpose | Required args |
+|---|---|---|
+| `search` | Locate nodes by NL / code text. | `query` |
+| `find` | Locate nodes by structured filter. | `kind`, `filter` |
+| `describe` | Full record + edge counts for one node. | `id` |
+| `resolve` | Identifier-shaped lookup (FQN-collision-safe). Returns `one` / `many` / `none`. | `identifier` |
+| `neighbors` | Graph walk, one hop. | `ids`, `direction`, `edge_types` |
+
+Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live in [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md). Edge types and traversal directions are listed in [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md).
+
+### Three-layer architecture
+
+Layer 1 (storage) → Layer 2 (5 MCP tools) → Layer 3 (skills). Navigation skills in [`skills/`](./skills/) wrap the MCP tools into deterministic chains (Tier 1) and bounded workflows (Tier 2). See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
+
+---
+
+## Configuration
+
+The operator-facing surface is small: pick an index dir, pick an embedding model, optionally drop a `.java-codebase-rag.yml` at your project root for microservice layout and brownfield overrides.
+
+| If you want to… | See |
+|---|---|
+| Set env vars and override precedence | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §1 |
+| Configure microservice roots and embeddings via YAML | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §2 |
+| Understand the graph (nodes, edges, capabilities, ranking) | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §3 |
+| Steer a brownfield Java tree (custom stereotypes, non-Spring stacks) | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §4 |
+| Control which files the indexer walks | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §5 |
+| Check whether your repo fits this tool's assumptions | [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) |
+
+---
+
+## CLI cheat sheet
+
+Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook with workflows, exit codes, and env alignment lives in [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md).
+
+| Group | Subcommand | What it does |
+|---|---|---|
+| Lifecycle | `init` | First-time index. Refuses if artifacts already exist. |
+| Lifecycle | `increment` | CocoIndex catch-up (Lance only); Kuzu stays stale until `reprocess`. |
+| Lifecycle | `reprocess` | Full Lance + Kuzu rebuild. `--vectors-only` / `--graph-only` for a single phase. |
+| Lifecycle | `erase` | Delete index artifacts. Requires `--yes` or TTY confirm. |
+| Introspection | `meta`, `tables`, `diagnose-ignore`, `unresolved-calls` | Health, table listing, ignore-layer diagnostics, receiver-failure call sites. |
+| Analysis | `analyze-pr` | Blast-radius / risk from a unified diff. |
+
+---
+
+## Further reading
+
+| Document | What's in it |
+|---|---|
+| [`docs/paper/paper.pdf`](./docs/paper/paper.pdf) | Architecture report — design rationale, GPS metaphor, three-layer architecture, design principles, future work. |
+| [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md) | Agent-facing guide. Copy-paste into `QWEN.md` / `CLAUDE.md` / `AGENTS.md`. |
+| [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) | Environment variables, project YAML, graph ontology, brownfield overrides, ignore patterns. |
+| [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) | CLI operator playbook: workflows, exit codes, env alignment. |
+| [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) | MCP-traversable edges, directions, dot-key composition. |
+| [`skills/`](./skills/) | 15 navigation and workflow skills for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
+| [`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md) | 7-phase agent-driven verification after indexing your project. |
+| [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) | Assumptions about your Java repo + per-file edit map for non-conforming codebases. |
+| [`automation/cursor_propose_only/README.md`](./automation/cursor_propose_only/README.md) | Optional proposal orchestration workflow (single-command autopilot, planning bundles, automated execution/review loops). |
+| [`docs/PRODUCT-VISION.md`](./docs/PRODUCT-VISION.md) | Long-term product direction. |
+
+---
+
+## Install from source (contributors)
+
+```bash
+git clone https://github.com/HumanBean17/java-codebase-rag
+cd java-codebase-rag
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+```
+
+The `cocoindex` package is **only** needed for lifecycle commands that run the indexer (`init`, `increment`, `reprocess`, `erase`). Search and MCP navigation work without it.
+
+The default embedding model is `sentence-transformers/all-MiniLM-L6-v2` (downloaded on first `init`). Override via the `EMBEDDING_MODEL` env var — see [`docs/CONFIGURATION.md` §1](./docs/CONFIGURATION.md#1-environment-variables).
+
+---
+
+## Roadmap (graph layer)
+
+- `get_service_topology` — microservice-level summary aggregating `HTTP_CALLS` / `ASYNC_CALLS`.
+- Agentic routing layer (query classifier → vector / graph / both).
+- Incremental Kuzu updates (per-changed-file) — see [`propose/TIER2-INCREMENTAL-REBUILD-PROPOSE.md`](./propose/TIER2-INCREMENTAL-REBUILD-PROPOSE.md) and [`propose/INDEX-AUTO-MODE-PROPOSE.md`](./propose/INDEX-AUTO-MODE-PROPOSE.md).
+- Optional `codegraph_nodes` LanceDB table embedding symbol summaries so the graph itself is vector-searchable.

java_codebase_rag-0.2.0/java_codebase_rag.egg-info/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: java-codebase-rag
+Version: 0.2.0
+Summary: MCP server for semantic + structural search over Java codebases
+Author: HumanBean17
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/HumanBean17/java-codebase-rag
+Project-URL: Repository, https://github.com/HumanBean17/java-codebase-rag
+Project-URL: Issues, https://github.com/HumanBean17/java-codebase-rag/issues
+Keywords: mcp,java,rag,code-search,graph,lancedb,kuzu
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: kuzu<0.12,>=0.11.3
+Requires-Dist: lancedb<0.31,>=0.25.3
+Requires-Dist: mcp<2,>=1.27.0
+Requires-Dist: numpy<2.5,>=1.26.4
+Requires-Dist: pathspec<2,>=1.0.4
+Requires-Dist: pyarrow<24,>=23.0.1
+Requires-Dist: PyYAML<7,>=6.0.3
+Requires-Dist: sentence-transformers<6,>=5.4.0
+Requires-Dist: tree-sitter<0.26,>=0.25.2
+Requires-Dist: tree-sitter-java<0.24,>=0.23.5
+Requires-Dist: unidiff<1,>=0.7.3
+Dynamic: license-file
+
+# java-codebase-rag
+
+A graph-native code intelligence layer for Java microservice estates, exposed to LLM agents via the **Model Context Protocol (MCP)**.
+
+The system extracts a deterministic property graph from Java source (tree-sitter), stores it in **Kuzu** (graph) alongside a **LanceDB** vector index (chunks), and exposes a deliberately small MCP surface — **five tools**: `search`, `find`, `describe`, `neighbors`, `resolve` — that collapse onto three primitive agent operations: **locate**, **inspect**, **walk**.
+
+> **What this MCP is:** a **GPS for code navigation**, not a reasoning engine.
+> Agents use a simple loop:
+>
+> 1. **Locate** entry nodes (`search` / `find`, or identifier-shaped **`resolve`**)
+> 2. **Inspect** what a node is (`describe`)
+> 3. **Walk** one hop at a time (`neighbors`) until enough evidence is gathered
+>
+> The MCP exposes structure and adjacency; the agent owns multi-hop reasoning and stop conditions.
+
+For the design rationale, the GPS metaphor, and the full ontology, see [`docs/paper/paper.pdf`](./docs/paper/paper.pdf) (architecture report).
+
+---
+
+## Install
+
+```bash
+pip install java-codebase-rag
+```
+
+Python **3.11+** required. After install, `java-codebase-rag --help` should print the CLI groups.
+
+> **Stability disclaimer.** This package does **not** promise backward compatibility. MCP tool contracts, env vars, Lance/Kuzu schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change.
+
+---
+
+## 5-minute walkthrough — index this repo's bank-chat fixture
+
+This repo ships a small multi-module Spring fixture under [`tests/bank-chat-system/`](./tests/bank-chat-system/) (`chat-core` + `chat-assign`) that the test suite uses for calibration. You can index it and confirm the install works end-to-end in under five minutes — no agent host required.
+
+```bash
+# 1. Clone the repo to get the fixture (the published package doesn't include tests/)
+git clone https://github.com/HumanBean17/java-codebase-rag
+cd java-codebase-rag
+
+# 2. Build the index (Lance vectors + Kuzu graph). First run downloads the
+#    embedding model (~90 MB) and takes ~30-60s on the fixture.
+java-codebase-rag init --source-root tests/bank-chat-system --index-dir /tmp/bank-chat-index
+
+# 3. Inspect what landed (resolved config, edge counts, ontology version)
+java-codebase-rag meta --source-root tests/bank-chat-system --index-dir /tmp/bank-chat-index
+```
+
+Smoke-test the index with two checks (`search_lancedb` ships with the package):
+
+```bash
+# Vector search — proves the LanceDB side works
+JAVA_CODEBASE_RAG_INDEX_DIR=/tmp/bank-chat-index \
+  python -m search_lancedb "chat ingress controller" --table java --limit 3
+
+# Vector + graph expansion — proves Kuzu is wired in
+JAVA_CODEBASE_RAG_INDEX_DIR=/tmp/bank-chat-index \
+  python -m search_lancedb "chat ingress controller" --table java --limit 3 \
+    --graph-expand --expand-depth 2
+```
+
+If vector hits come back and graph expansion adds neighbor symbols, the install works end-to-end. Wire it into your agent next — the five MCP tools (`search`, `find`, `describe`, `neighbors`, `resolve`) are reachable over stdio.
+
+---
+
+## Wire into an MCP host
+
+### Claude Code
+
+With the package installed, the console script `java-codebase-rag-mcp` is on your `PATH`. Register it project-scoped:
+
+```bash
+claude mcp add --transport stdio java-codebase-rag -- java-codebase-rag-mcp
+```
+
+Then set env vars (`JAVA_CODEBASE_RAG_INDEX_DIR`, `JAVA_CODEBASE_RAG_SOURCE_ROOT`, `SBERT_MODEL`, …) in `.mcp.json` or your shell profile. For a project-scoped `.mcp.json` template, see [`mcp.json.example`](./mcp.json.example). Official docs: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings).
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`) and add under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "java-codebase-rag": {
+      "command": "java-codebase-rag-mcp",
+      "env": {
+        "JAVA_CODEBASE_RAG_INDEX_DIR": "/ABSOLUTE/PATH/TO/.java-codebase-rag",
+        "JAVA_CODEBASE_RAG_SOURCE_ROOT": "/ABSOLUTE/PATH/TO/your-java-project"
+      }
+    }
+  }
+}
+```
+
+See [`mcp.json.example`](./mcp.json.example) for the same shape in `.mcp.json` (Claude Code project-scoped) form.
+
+### Driving the MCP from an agent
+
+Pick **one** of two options (not both — they cover the same navigation intents):
+
+1. **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** (recommended for most) — standalone MCP operating manual. Copy-paste the `BEGIN`/`END` block into your project's `QWEN.md`, `CLAUDE.md`, or `AGENTS.md`. Contains: five-tool reference, `NodeFilter` / edge taxonomy, ontology glossary, recovery playbook, and inline slash-style aliases (`/callers`, `/callees`, `/routes`, etc.) as prompt templates. Self-contained — no external file dependencies.
+
+2. **[`skills/`](./skills/)** (for hosts with skill discovery) — 15 shipped `SKILL.md` files. If your MCP host supports skill discovery (Claude Code, Qwen Code, Cursor), the same navigation intents are available as discoverable `/` commands. Tier 1 = deterministic MCP chains (`/callers`, `/callees`, `/routes`, `/controllers`, `/clients`, `/producers`, `/handlers`, `/who-hits-route`, `/implements`, `/injects`, `/nl`). Tier 2 = bounded workflows (`/explain-feature`, `/impact-of`, `/trace-request-flow`, `/mini-map`). See [`skills/README.md`](./skills/README.md) for the full index.
+
+Also: **[`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md)** — 7-phase agent-driven verification you run after indexing your real project.
+
+---
+
+## The five tools, at a glance
+
+| Tool | Purpose | Required args |
+|---|---|---|
+| `search` | Locate nodes by NL / code text. | `query` |
+| `find` | Locate nodes by structured filter. | `kind`, `filter` |
+| `describe` | Full record + edge counts for one node. | `id` |
+| `resolve` | Identifier-shaped lookup (FQN-collision-safe). Returns `one` / `many` / `none`. | `identifier` |
+| `neighbors` | Graph walk, one hop. | `ids`, `direction`, `edge_types` |
+
+Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live in [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md). Edge types and traversal directions are listed in [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md).
+
+### Three-layer architecture
+
+Layer 1 (storage) → Layer 2 (5 MCP tools) → Layer 3 (skills). Navigation skills in [`skills/`](./skills/) wrap the MCP tools into deterministic chains (Tier 1) and bounded workflows (Tier 2). See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
+
+---
+
+## Configuration
+
+The operator-facing surface is small: pick an index dir, pick an embedding model, optionally drop a `.java-codebase-rag.yml` at your project root for microservice layout and brownfield overrides.
+
+| If you want to… | See |
+|---|---|
+| Set env vars and override precedence | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §1 |
+| Configure microservice roots and embeddings via YAML | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §2 |
+| Understand the graph (nodes, edges, capabilities, ranking) | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §3 |
+| Steer a brownfield Java tree (custom stereotypes, non-Spring stacks) | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §4 |
+| Control which files the indexer walks | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §5 |
+| Check whether your repo fits this tool's assumptions | [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) |
+
+---
+
+## CLI cheat sheet
+
+Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook with workflows, exit codes, and env alignment lives in [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md).
+
+| Group | Subcommand | What it does |
+|---|---|---|
+| Lifecycle | `init` | First-time index. Refuses if artifacts already exist. |
+| Lifecycle | `increment` | CocoIndex catch-up (Lance only); Kuzu stays stale until `reprocess`. |
+| Lifecycle | `reprocess` | Full Lance + Kuzu rebuild. `--vectors-only` / `--graph-only` for a single phase. |
+| Lifecycle | `erase` | Delete index artifacts. Requires `--yes` or TTY confirm. |
+| Introspection | `meta`, `tables`, `diagnose-ignore`, `unresolved-calls` | Health, table listing, ignore-layer diagnostics, receiver-failure call sites. |
+| Analysis | `analyze-pr` | Blast-radius / risk from a unified diff. |
+
+---
+
+## Further reading
+
+| Document | What's in it |
+|---|---|
+| [`docs/paper/paper.pdf`](./docs/paper/paper.pdf) | Architecture report — design rationale, GPS metaphor, three-layer architecture, design principles, future work. |
+| [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md) | Agent-facing guide. Copy-paste into `QWEN.md` / `CLAUDE.md` / `AGENTS.md`. |
+| [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) | Environment variables, project YAML, graph ontology, brownfield overrides, ignore patterns. |
+| [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) | CLI operator playbook: workflows, exit codes, env alignment. |
+| [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) | MCP-traversable edges, directions, dot-key composition. |
+| [`skills/`](./skills/) | 15 navigation and workflow skills for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
+| [`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md) | 7-phase agent-driven verification after indexing your project. |
+| [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) | Assumptions about your Java repo + per-file edit map for non-conforming codebases. |
+| [`automation/cursor_propose_only/README.md`](./automation/cursor_propose_only/README.md) | Optional proposal orchestration workflow (single-command autopilot, planning bundles, automated execution/review loops). |
+| [`docs/PRODUCT-VISION.md`](./docs/PRODUCT-VISION.md) | Long-term product direction. |
+
+---
+
+## Install from source (contributors)
+
+```bash
+git clone https://github.com/HumanBean17/java-codebase-rag
+cd java-codebase-rag
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+```
+
+The `cocoindex` package is **only** needed for lifecycle commands that run the indexer (`init`, `increment`, `reprocess`, `erase`). Search and MCP navigation work without it.
+
+The default embedding model is `sentence-transformers/all-MiniLM-L6-v2` (downloaded on first `init`). Override via the `EMBEDDING_MODEL` env var — see [`docs/CONFIGURATION.md` §1](./docs/CONFIGURATION.md#1-environment-variables).
+
+---
+
+## Roadmap (graph layer)
+
+- `get_service_topology` — microservice-level summary aggregating `HTTP_CALLS` / `ASYNC_CALLS`.
+- Agentic routing layer (query classifier → vector / graph / both).
+- Incremental Kuzu updates (per-changed-file) — see [`propose/TIER2-INCREMENTAL-REBUILD-PROPOSE.md`](./propose/TIER2-INCREMENTAL-REBUILD-PROPOSE.md) and [`propose/INDEX-AUTO-MODE-PROPOSE.md`](./propose/INDEX-AUTO-MODE-PROPOSE.md).
+- Optional `codegraph_nodes` LanceDB table embedding symbol summaries so the graph itself is vector-searchable.

{java_codebase_rag-0.1.0 → java_codebase_rag-0.2.0}/java_codebase_rag.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ java_codebase_rag.egg-info/dependency_links.txt
 java_codebase_rag.egg-info/entry_points.txt
 java_codebase_rag.egg-info/requires.txt
 java_codebase_rag.egg-info/top_level.txt
+tests/test_agent_skills_static.py
 tests/test_assign_endpoint_client_extraction.py
 tests/test_ast_graph_build.py
 tests/test_ast_java_calls.py