Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
docs(architecture): sync MCP inventory with the 11-tool default surface (#1174)
Felix-Ayush5686917190f8
diff --git a/README.md b/README.mdindex 6c988ed2d..3cd8a49c5 100644--- a/README.md+++ b/README.md@@ -65,7 +65,7 @@ Free and self-hosted, runs on your machine, and the first index needs no API key<picture><source media="(prefers-color-scheme: dark)" srcset=".github/assets/one-index-dark.svg" />- <img src=".github/assets/one-index.svg" alt="One index producing code health, a dependency graph, git history, generated docs, architectural decisions, and ten MCP tools" width="100%" />+ <img src=".github/assets/one-index.svg" alt="One index producing code health, a dependency graph, git history, generated docs, architectural decisions, and eleven MCP tools" width="100%" /></picture></div>@@ -509,7 +509,7 @@ Full walkthrough: **[docs/start/QUICKSTART.md →](docs/start/QUICKSTART.md)**----## The ten MCP tools+## The eleven MCP toolsEvery response carries an `_meta` envelope with `index_age_days`, `indexed_commit`, anda `stale_warning` that fires only when the indexed HEAD diverges from live `.git/HEAD`,@@ -527,8 +527,9 @@ so your agent always knows how much to trust what it just read.| `get_why(query?, targets?)` | Architectural decisions and their verbatim evidence spans, stamped exact / fuzzy / unverified. Falls back to git archaeology when no decisions exist. || `get_dead_code(...)` | Unreachable code by confidence tier with cleanup-impact estimates, and cross-repo consumer detection in workspace mode. || `get_health(targets?, include?)` | Per-file marker scores across all three signals. `include` opens coverage, trends, per-file signals, the accuracy self-check, and structured refactoring plans. |+| `list_repos()` | Repo aliases this server is serving. Discover `repo=` targets (especially in a workspace). |-Ten is a deliberate ceiling rather than a limit we ran into: a small, task-shaped+Eleven is a deliberate ceiling rather than a limit we ran into: a small, task-shapedsurface is easier for an agent to choose from than a large one. Worked example (*"addrate limiting to all API endpoints"* in 5 calls instead of ~30 greps and reads), theopt-in tools, and the full reference: **[docs/agent/MCP_TOOLS.md →](docs/agent/MCP_TOOLS.md)**@@ -585,7 +586,7 @@ agent over MCP.|---|---|---|---|---|| Self-hostable, open source | ✅ AGPL-3.0 | ✅ | ✅ | ❌ cloud only || Private repo, no cloud | ✅ | ✅ | ✅ | ❌ OSS forks only |-| MCP tools served | 10 | 1 | 29 | 3 |+| MCP tools served | 11 | 1 | 29 | 3 || **Finds the gold files** *([measured](docs/BENCHMARKS.md#1-finding-the-right-files), n=42 sealed)* | ✅ **0.876** | 0.610 | not in this run | not measured || **Output tokens vs a bare agent** *([measured](docs/BENCHMARKS.md#2-what-changes-in-a-real-agent-loop), n=43)* | ✅ **-31.6%** | -24.4% | -14.8% | not measured || **Index time, django** *([measured](docs/BENCHMARKS.md#6-indexing-time-the-row-we-lose))* | ⚠️ **366.8s**, slowest here | ✅ **16.4s** | not measured | n/a, cloud |diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.mdindex b637398fc..63ccacdf3 100644--- a/docs/architecture/ARCHITECTURE.md+++ b/docs/architecture/ARCHITECTURE.md@@ -78,7 +78,7 @@ For per-package detail (installation, full API reference, all CLI flags, file ma│ Three Stores │ │ Consumers ││ │ │ ││ SQL (wiki pages, │ │ Web UI MCP Server GitHub Action │-│ jobs, symbols, │ │ (Next.js) (10 tools) (CI/CD) │+│ jobs, symbols, │ │ (Next.js) (11 tools) (CI/CD) ││ versions) │ │ ││ │ │ repowise CLI ││ Vector (LanceDB / │ │ (init, update, watch, │@@ -172,7 +172,7 @@ repowise/│ ├── server/ # Python: FastAPI REST API + MCP server│ │ └── src/repowise/server/│ │ ├── routers/ # FastAPI routers (repos, pages, jobs, symbols, graph, git, dead-code, decisions, search, claude-md)-│ │ ├── mcp_server/ # MCP server package (10 tools, split into focused modules)+│ │ ├── mcp_server/ # MCP server package (11 default tools, split into focused modules)│ │ ├── webhooks/ # GitHub + GitLab handlers│ │ ├── job_executor.py # Background pipeline executor — bridges REST endpoints to core pipeline│ │ └── scheduler.py # APScheduler background jobs@@ -310,7 +310,7 @@ The graph is used for:as dashed purple lines. They do NOT affect PageRank.- **Dead code detection** — files with `in_degree == 0` (no importers) arecandidates for unreachable file detection-- **MCP `get_dependency_path` tool** — answers "how is module A connected to module B?"+- **MCP `get_dependency_path` tool** *(opt-in)* — answers "how is module A connected to module B?"- **D3 graph visualization** in the web UIIf you delete the graph, repowise loses change propagation and generation ordering.@@ -1048,19 +1048,27 @@ and supports two transports:- **stdio** — for Claude Code, Cursor, Cline (add to their MCP config)- **SSE** — for web-based MCP clients (served on port 7338)-### Tools (9 total)+### Tools (11 default in single-repo mode)++Canonical reference: [`docs/agent/MCP_TOOLS.md`](../agent/MCP_TOOLS.md).+A single-repo server advertises **11** tools by default (ten flagship ++`list_repos`). Workspace mode adds `get_architecture` and `get_blast_radius`.+Four more are registered but opt-in (`get_dependency_path`,+`get_execution_flows`, `generate_refactoring_code`, `get_conformance`).| Tool | What it answers | When to call ||------|----------------|-------------|| `get_overview` | Architecture summary, module map, entry points. | First call when exploring an unfamiliar codebase. |-| `get_context(targets, include?)` | Docs, ownership, history, decisions, freshness for files/modules/symbols. Pass multiple targets in one call. | When you need to understand specific code before reading or modifying it. |-| `get_risk(targets)` | Hotspot score, dependents, co-change partners, risk summary per target. Also returns top 5 global hotspots. | Before modifying files — assess what could break. |-| `get_why(query?)` | Three modes: NL search over decisions, path-based decisions for a file, no-arg health dashboard. | Before making architectural changes — understand existing intent. |-| `search_codebase(query)` | Semantic search over the full wiki. Natural language. | When you don't know where something lives. |-| `get_dependency_path(from, to)` | Connection path between two files/modules in the dependency graph. | When you need to understand how two things are connected. |-| `get_dead_code` | Dead/unused code findings sorted by confidence and cleanup impact. | Before cleanup tasks. |-| `get_answer` | One-call RAG: confidence-gated synthesis with cited answers and question cache. | First call on any code question — collapses search → read → reason. |+| `get_answer` | One-call RAG: confidence-gated synthesis with cited answers. | First call on any code question. |+| `get_context(targets, include?)` | Docs, ownership, history, decisions, freshness for files/modules/symbols. | Before reading or modifying specific code. || `get_symbol` | Resolve a qualified symbol id to source body, signature, and docstring. | When the question names a specific class, function, or method. |+| `search_codebase(query)` | Hybrid symbol / path / wiki search. | When you don't know where something lives. |+| `get_risk(targets)` | Hotspot score, dependents, co-change partners, risk summary per target. | Before modifying indexed files. |+| `get_change_risk(revspec?)` | Live commit / range defect score from the diff itself. | Before merging a commit or PR range. |+| `get_why(query?)` | Architectural decisions and git archaeology. | Before making architectural changes. |+| `get_dead_code` | Dead/unused code findings sorted by confidence. | Before cleanup tasks. |+| `get_health` | Code-health marker scores (defect / maintainability / performance). | Self-check before a PR or refactor. |+| `list_repos` | Repo aliases this server is serving. | Discover `repo=` targets (especially in a workspace). |### Auto-generated Config