Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

docs(architecture): sync MCP inventory with the 11-tool default surface (#1174)

Felix-Ayush5686917190f8
diff --git a/README.md b/README.md
index 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 tools
Every response carries an `_meta` envelope with `index_age_days`, `indexed_commit`, and
a `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-shaped
surface is easier for an agent to choose from than a large one. Worked example (*"add
rate limiting to all API endpoints"* in 5 calls instead of ~30 greps and reads), the
opt-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.md
index 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) are
candidates 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 UI
If 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