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
Consolidate MCP server from 16 to 8 tools, fix search, add reindex command
RaghavChamadiya7c35e972e8e9
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex b7643d333..783e383c3 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -76,7 +76,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) (16 tools) (CI/CD) │+│ jobs, symbols, │ │ (Next.js) (8 tools) (CI/CD) ││ versions) │ │ ││ │ │ wikicode CLI ││ Vector (LanceDB / │ │ (init, update, watch, │@@ -155,13 +155,13 @@ wikicode/│ ├── server/ # Python: FastAPI REST API + MCP server│ │ └── src/wikicode/server/│ │ ├── api/ # FastAPI routers (repos, pages, jobs, symbols, graph, git, dead-code, decisions, search)-│ │ ├── mcp_server.py # MCP server (16 tools)+│ │ ├── mcp_server.py # MCP server (8 tools)│ │ ├── webhooks/ # GitHub + GitLab handlers│ │ └── scheduler.py # APScheduler background jobs│ ││ ├── cli/ # Python: wikicode CLI (click + rich)│ │ └── src/wikicode/cli/-│ │ └── commands/ # init, update, watch, serve, search, export, status, doctor, dead-code, decision, mcp+│ │ └── commands/ # init, update, watch, serve, search, export, status, doctor, dead-code, decision, mcp, reindex│ ││ └── web/ # Next.js 15 frontend│ ├── src/app/ # App Router pages (dashboard, wiki, search, graph, symbols, …)@@ -255,7 +255,8 @@ natural language query. This is better than full-text search for questions likeIf you delete the vector store (LanceDB directory or pgvector embeddings), searchquality degrades and generation context becomes shallower — rebuild it by running-`wikicode index --rebuild` which re-embeds all existing SQL pages.+`wikicode reindex` which re-embeds all existing SQL pages into LanceDB using+the configured embedder (Gemini or OpenAI). No LLM calls — only embedding API calls.### 3.3 Graph Store (NetworkX / SQLite-backed)@@ -902,9 +903,8 @@ was recorded. Decisions with `staleness_score > 0.5` are flagged as stale.### MCP Tools-- `get_decisions(module?, tag?, include_proposed?, include_stale?)` — query decision records-- `get_why(query)` — semantic search over decisions + documentation, answers "why" questions-- `get_decision_health()` — stale decisions, ungoverned hotspots, proposed decisions needing review+- `get_why(query?)` — three modes: natural language search over decisions, path-based lookup for decisions governing a file, or no-arg for decision health dashboard (stale decisions, ungoverned hotspots, proposed decisions needing review)+- `get_context(targets, include?)` — includes decisions governing each target in its response### CLI Commands@@ -925,7 +925,7 @@ wikicode decision health # health summary| `core/analysis/decision_extractor.py` | All 4 capture sources + staleness computation || `core/persistence/models.py` | `DecisionRecord` ORM model || `core/persistence/crud.py` | 8 decision CRUD functions |-| `server/mcp_server.py` | 3 MCP tools (get_decisions, get_why, get_decision_health) |+| `server/mcp_server.py` | MCP tool `get_why` (3-mode: search, path, health dashboard) || `server/routers/decisions.py` | REST API endpoints || `cli/commands/decision_cmd.py` | CLI command group (7 subcommands) |@@ -939,30 +939,25 @@ can call in real time.Instead of an AI assistant reading 40 source files to understand a codebase,it calls `get_overview()` and gets a structured, always-current architecture summary.-Instead of grepping for a function, it calls `get_symbol("AuthService.login")`.+Instead of calling 5 tools one at a time, it calls `get_context(["src/auth/service.py", "AuthService"])` and gets docs, ownership, decisions, and freshness for all targets in one call.The server is implemented using the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)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--| Tool | What it answers |-|------|----------------|-| `get_overview` | Architecture summary, module map, entry points. Best first call. |-| `get_module_docs` | Wiki page for a package/directory. Public API + file map. |-| `get_file_docs` | Wiki page for a specific file. Symbols, imports, freshness. |-| `get_symbol` | Any function/class/method by name. Fuzzy match if exact fails. |-| `search_codebase` | Semantic search over the full wiki. Natural language. |-| `get_architecture_diagram` | Mermaid diagram for repo or specific module. |-| `get_dependency_path` | How is symbol A connected to symbol B? |-| `get_stale_pages` | Which pages have confidence score below threshold. |-| `get_file_history` | Git history for a file: ownership, significant commits, co-changes. |-| `get_hotspots` | High-churn + high-complexity files — most likely to contain bugs. |-| `get_codebase_ownership` | Ownership breakdown by file/module/package. Identifies silos. |-| `get_co_changes` | Files that change together without import link — hidden coupling. |-| `get_dead_code` | Dead/unused code findings sorted by confidence and cleanup impact. |+### Tools (8 total)++| 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_architecture_diagram` | Mermaid diagram for repo or specific module. | For documentation or presentation. |### Auto-generated Configdiff --git a/docs/MCP_AND_STATE_REVIEW.md b/docs/MCP_AND_STATE_REVIEW.mdindex fd5f9b2e1..47693cc6f 100644--- a/docs/MCP_AND_STATE_REVIEW.md+++ b/docs/MCP_AND_STATE_REVIEW.md@@ -72,27 +72,24 @@ server process.## 2. MCP Tools Inventory-The server implements **16 tools**, though documentation in multiple places-incorrectly states 13. The 3 decision intelligence tools were added later.+The server implements **8 tools** (consolidated from 16 on 2026-03-25 to reduce+sequential tool calls for common tasks).| # | Tool | Category | What It Answers ||---|------|----------|----------------|| 1 | `get_overview` | Navigation | Architecture summary, module map, entry points |-| 2 | `get_module_docs` | Navigation | Wiki page for a package/directory |-| 3 | `get_file_docs` | Navigation | Wiki page for a specific file with symbols |-| 4 | `get_symbol` | Lookup | Any function/class/method by name (fuzzy match) |+| 2 | `get_context(targets, include?)` | Context | Docs, ownership, history, decisions, freshness for files/modules/symbols. Multi-target, single call. |+| 3 | `get_risk(targets)` | Risk | Hotspot score, dependents, co-change partners, risk summary. Multi-target, single call. |+| 4 | `get_why(query?)` | Decision Intelligence | 3 modes: NL search, path-based decisions, no-arg health dashboard || 5 | `search_codebase` | Search | Semantic search over full wiki (natural language) |-| 6 | `get_architecture_diagram` | Visualization | Mermaid diagram for repo/module/file |-| 7 | `get_dependency_path` | Graph | How two files/modules are connected |-| 8 | `get_stale_pages` | Quality | Pages with confidence below threshold |-| 9 | `get_file_history` | Git Intelligence | Git history, ownership, significant commits |-| 10 | `get_hotspots` | Git Intelligence | High-churn + high-complexity files |-| 11 | `get_codebase_ownership` | Git Intelligence | Ownership breakdown, knowledge silos |-| 12 | `get_co_changes` | Git Intelligence | Files that change together (hidden coupling) |-| 13 | `get_dead_code` | Analysis | Dead/unused code findings |-| 14 | `get_decisions` | Decision Intelligence | Architectural decision records |-| 15 | `get_why` | Decision Intelligence | "Why is X built this way?" queries |-| 16 | `get_decision_health` | Decision Intelligence | Stale decisions, ungoverned hotspots |+| 6 | `get_dependency_path` | Graph | How two files/modules are connected |+| 7 | `get_dead_code` | Analysis | Dead/unused code findings |+| 8 | `get_architecture_diagram` | Visualization | Mermaid diagram for repo/module/file |++**Consolidation mapping** (old → new):+- `get_module_docs`, `get_file_docs`, `get_symbol`, `get_file_history`, `get_codebase_ownership` (partial), `get_stale_pages` → **`get_context`**+- `get_hotspots`, `get_co_changes`, `get_codebase_ownership` (partial) → **`get_risk`**+- `get_decisions`, old `get_why`, `get_decision_health` → **`get_why`** (3-mode)### Tool Design Patterns@@ -276,28 +273,46 @@ This is genuinely useful documentation that would take a human engineer signific## 7. MCP Tool-by-Tool Assessment (Live Test Results)-All 16 tools were tested live against the interview-coach wiki database on 2026-03-25.+All tools were tested live against the interview-coach wiki database on 2026-03-25+(originally 16 tools; consolidated to 8 tools on 2026-03-25).### Result Summary+| # | Tool | Status | Verdict |+|---|------|--------|---------|+**Post-consolidation (8 tools, tested 2026-03-25):**++| # | Tool | Status | Verdict |+|---|------|--------|---------|+| 1 | `get_overview` | **PASS** | Rich response: overview, 6 modules, 45 entry points |+| 2 | `get_context` | **PASS** | Multi-target (file+module+symbol) resolved in one call. Docs, ownership, decisions, freshness all returned. |+| 3 | `get_risk` | **PASS** | DSAPatternTable at 100% hotspot, 43 co-change partners, 26 dependents. Global hotspots exclude targets. |+| 4 | `get_why` (3 modes) | **PASS** | Search mode finds keyword-matched decisions; path mode returns governing decisions; health mode shows dashboard |+| 5 | `search_codebase` | **PASS** | Semantic search via LanceDB + Gemini. "payment system" → payment_service.py (score 6.72). FTS fallback also works. |+| 6 | `get_dependency_path` | **PASS** | Correctly finds 1-hop path tiro_router → tiro/service |+| 7 | `get_dead_code` | **PASS** | 1,232 findings, 48,780 deletable lines, sorted by confidence desc |+| 8 | `get_architecture_diagram` | **PASS** | Repo scope returns pre-gen Mermaid; module scope generates dynamic |++**Original 16-tool results (pre-consolidation, for reference):**+| # | Tool | Status | Verdict ||---|------|--------|---------|| 1 | `get_overview` | **PASS** | Rich response: overview, 6 modules, 45 entry points || 2 | `get_module_docs` | **PASS** | Returns full module page + 200+ child file listings || 3 | `get_file_docs` | **PASS** | Returns page content, 11 symbols, 3 importers, confidence 1.0 || 4 | `get_symbol` | **PASS** | Exact match works, returns `candidates` array for disambiguation |-| 5 | `search_codebase` | **FAIL** | Returns `{"results": []}` for all queries |+| 5 | `search_codebase` | **PASS** (was FAIL) | Fixed: FTS fallback + LanceDB + stop word stripping || 6 | `get_architecture_diagram` | **PASS** | Repo scope returns pre-gen Mermaid; module scope generates dynamic || 7 | `get_dependency_path` | **PASS** | Correctly finds 1-hop path tiro_router → tiro/service |-| 8 | `get_stale_pages` | **PASS** | Empty (all pages fresh at 1.0) — correct behavior |-| 9 | `get_file_history` | **PARTIAL** | Ownership, hotspot, commits work; co_change counts all 0 |-| 10 | `get_hotspots` | **PASS** | Returns top 5 hotspots with churn percentiles + stable files |-| 11 | `get_codebase_ownership` | **PASS** | Correctly identifies 3 knowledge silos (blogs, hire-backend, hire-frontend) |-| 12 | `get_co_changes` | **FAIL** | Returns `{"co_change_partners": []}` — data not persisted correctly |-| 13 | `get_dead_code` | **PASS** | Summary correct; default min_confidence filters out zombies (see note) |-| 14 | `get_decisions` | **PASS** | Returns all 23 proposed decisions with full context |-| 15 | `get_why` | **FAIL** | Returns empty for "why is pipecat used for interviews" |-| 16 | `get_decision_health` | **PASS** | Shows 0 active, 23 proposed, 505 ungoverned hotspots |+| 8 | `get_stale_pages` | **PASS** | Empty (all pages fresh at 1.0) — correct behavior. Now part of `get_context` freshness. |+| 9 | `get_file_history` | **PARTIAL** | Ownership, hotspot, commits work; co_change counts all 0 (fixed via key mismatch fix) |+| 10 | `get_hotspots` | **PASS** | Returns top 5 hotspots with churn percentiles + stable files. Now part of `get_risk`. |+| 11 | `get_codebase_ownership` | **PASS** | Correctly identifies 3 knowledge silos. Now part of `get_context`/`get_risk`. |+| 12 | `get_co_changes` | **PASS** (was FAIL) | Fixed via co_change_count key mismatch fix (M10). Now part of `get_risk`. |+| 13 | `get_dead_code` | **PASS** | Summary correct; default min_confidence lowered to 0.5. |+| 14 | `get_decisions` | **PASS** | Returns all 23 proposed decisions with full context. Now part of `get_why`. |+| 15 | `get_why` | **PASS** (was FAIL) | Fixed: include_proposed=True + real embedder + FTS fallback. Now 3-mode tool. |+| 16 | `get_decision_health` | **PASS** | Shows 0 active, 23 proposed, 505 ungoverned hotspots. Now `get_why()` no-arg mode. |### Detailed Test Results@@ -356,21 +371,24 @@ symbols share a name is very useful for AI assistants.----#### Tool 5: `search_codebase` — FAIL+#### Tool 5: `search_codebase` — PASS (after fixes)**Test:** `search_codebase("how does the payment system work")`-**Result:** `{"results": []}` — completely empty--**Root cause (confirmed by live test):** Two cascading failures:-1. `MockEmbedder` produces zero-dimension or random vectors → semantic search returns nothing-2. FTS fallback also returns empty — the FTS index may not contain this query's terms,- or the exception path in the fallback is swallowing errors silently--**Impact:** HIGH — this is the primary natural-language search tool. Without it,-AI assistants must know exact file/symbol names instead of asking conceptual questions.--**Fix needed:** Resolve real embedder from `.wikicode/config.yaml`. Additionally,-the FTS fallback should be verified independently.+**Result (after fix):** 5 results, topped by `backend/services/payment_service.py` (score 6.72)++**Original failures and fixes (2026-03-25):**+1. `MockEmbedder` produced random vectors → Fixed by `_resolve_embedder()` reading config.yaml+2. FTS fallback never triggered (vector store returned empty list, not exception) → Fixed: now+ falls back to FTS when vector results are empty+3. FTS used exact phrase match for multi-word queries → Fixed: `_build_fts5_query()` strips+ stop words and joins terms with OR + prefix matching+4. No LanceDB directory existed (init never persisted embeddings) → Fixed: `init_cmd.py` now+ tries LanceDB before InMemoryVectorStore; added `wikicode reindex` command to embed+ existing pages without re-generating+5. `lancedb` package not installed → Installed; 721 pages + 23 decisions indexed via Gemini embedder++**Current status:** Semantic search via LanceDB + Gemini embeddings fully operational.+FTS fallback also works for environments without LanceDB.---@@ -490,25 +508,20 @@ useful architectural context.----#### Tool 15: `get_why` — FAIL--**Test:** `query="why is pipecat used for interviews"`-**Result:** `{"query": "...", "decisions": [], "related_documentation": []}` — all empty+#### Tool 15 (now part of `get_why`): `get_why` — PASS (after fixes)-**Root causes (multiple):**-1. **Keyword search excludes proposed decisions:** `_list_decisions(..., include_proposed=False)`- returns 0 results because ALL 23 decisions are "proposed". The keyword matching- has no data to search over.-2. **Semantic search uses MockEmbedder:** Both `_decision_store.search()` and- `_vector_store.search()` return nothing due to mock embedder.-3. **FTS fallback also empty:** Same issue as Tool 5.+**Original failure:** `include_proposed=False` excluded all 23 decisions; MockEmbedder+returned nothing; FTS fallback never triggered.-**Impact:** HIGH — this is the flagship "why" tool. It should be the most valuable-tool for preventing re-introduction of solved problems, but it returns nothing.+**Fixes applied (2026-03-25):**+- Changed to `include_proposed=True` so keyword search finds proposed decisions+- Real embedder (Gemini) now used; LanceDB decision_records table populated via `wikicode reindex`+- FTS fallback improved (stop word stripping, OR-based matching)-**Fix needed:**-- Change `include_proposed=False` to `include_proposed=True` in `get_why`-- Fix the MockEmbedder issue (same as Tool 5)+**Current status (consolidated `get_why` tool — 3 modes):**+- `get_why("why is JWT used")` → mode="search", returns keyword-matched decisions. **PASS**+- `get_why("src/auth/service.py")` → mode="path", returns decisions governing that file. **PASS**+- `get_why()` → mode="health", returns dashboard with 23 proposed, 505 ungoverned. **PASS**---@@ -533,7 +546,7 @@ files that are actively being changed but have no documented architectural decis|---|-------|----------|-------------|| C1 | **DB filename mismatch** (FIXED) | `mcp_server.py:64` | MCP server looked for `.wikicode/wikicode.db` but CLI creates `.wikicode/wiki.db`. Fixed 2026-03-25: changed to `wiki.db`. || C2 | **LanceDB filter injection** (FIXED) | `vector_store.py:240,274` | `f"page_id = '{page_id}'"` — string interpolation in LanceDB delete filter. Fixed 2026-03-25: single quotes in page_id are now escaped before interpolation. |-| C3 | **Tool count mismatch in docs** (FIXED) | Multiple files | Updated "13 tools" → "16 tools" in mcp_server.py, mcp_cmd.py, ARCHITECTURE.md, server README, cli README, test_mcp.py. Added 3 decision tools to server README tool table. |+| C3 | **Tool count mismatch in docs** (FIXED) | Multiple files | Updated "13 tools" → "16 tools" → "8 tools" (after consolidation) in mcp_server.py, ARCHITECTURE.md, server README. |### MAJOR (significant impact)@@ -547,7 +560,7 @@ files that are actively being changed but have no documented architectural decis| M6 | ~~`get_repo_structure()` arg mismatch~~ (NOT A BUG) | `update_cmd.py:97` | The `files` parameter is optional (`files: list[FileInfo] | None = None`). Calling without args triggers a fresh traversal. || M7 | `wikicode-server` not auto-installed | `Makefile` / README | Running `wikicode mcp` fails with `ModuleNotFoundError` unless server package is explicitly installed. Not documented. || M8 | `completed_pages > total_pages` | `job_system.py` | Multiple jobs show completed exceeding total. The total estimate is not updated as levels are processed. |-| M9 | **`search_codebase` returns empty** (FIXED) | `mcp_server.py:82,469-473` | Fixed by M1 — real embedder now used. FTS fallback also functional. |+| M9 | **`search_codebase` returns empty** (FIXED) | `mcp_server.py`, `search.py`, `init_cmd.py` | Fixed: (a) FTS fallback triggers on empty results not just exceptions, (b) FTS query builder strips stop words and uses OR + prefix matching, (c) `init_cmd.py` now uses LanceDB when available, (d) added `wikicode reindex` command. LanceDB indexed with 721 pages + 23 decisions via Gemini embedder. || M10 | **Co-change counts all zero** (FIXED) | `mcp_server.py` | Root cause: key mismatch — data stores `"co_change_count"` but MCP tools read `"count"`. Fixed 2026-03-25: tools now check both keys via `p.get("co_change_count", p.get("count", 0))`. || M11 | **`get_why` excludes all decisions** (FIXED) | `mcp_server.py:1155-1156` | `include_proposed=False` returned 0 results. Fixed 2026-03-25: changed to `include_proposed=True`. |@@ -564,7 +577,7 @@ files that are actively being changed but have no documented architectural decis| m7 | Ownership grouping too coarse | `mcp_server.py:858` | Groups by first directory only — too coarse for nested monorepos. || m8 | Architecture diagram edge limit | `mcp_server.py:561` | Dynamic diagrams capped at 50 edges with no prioritization strategy. || m9 | All decisions are "proposed" | DB content | No inline markers found — all 23 are auto-extracted. Expected but worth noting. |-| m10 | `_decision_store` may be empty InMemory | `mcp_server.py:103-104` | Falls back to empty `InMemoryVectorStore` when no LanceDB decision table exists. |+| m10 | **`_decision_store` may be empty InMemory** (FIXED) | `mcp_server.py:103-104` | Fixed: `wikicode reindex` now indexes 23 decision records into LanceDB `decision_records` table. MCP server loads this on startup when `.wikicode/lancedb/` exists. || m11 | **`get_dead_code` default hides zombies** (FIXED) | `mcp_server.py:982` | Default `min_confidence` was 0.6, hiding 0.5-confidence zombie findings. Fixed 2026-03-25: lowered default to 0.5. || m12 | `wikicode-server` not installed by default | `Makefile` / setup | Running `wikicode mcp` fails with `ModuleNotFoundError` unless server package is explicitly installed. Not documented in quick-start. |diff --git a/packages/cli/src/wikicode/cli/commands/init_cmd.py b/packages/cli/src/wikicode/cli/commands/init_cmd.pyindex cb845b09b..5f90594ac 100644--- a/packages/cli/src/wikicode/cli/commands/init_cmd.py+++ b/packages/cli/src/wikicode/cli/commands/init_cmd.py@@ -577,7 +577,15 @@ def init_command(embedder_impl = MockEmbedder()else:embedder_impl = MockEmbedder()- vector_store = InMemoryVectorStore(embedder_impl)+ # Try LanceDB for persistent vector storage, fall back to in-memory+ lance_dir = repo_path / ".wikicode" / "lancedb"+ try:+ from wikicode.core.persistence.vector_store import LanceDBVectorStore++ lance_dir.mkdir(parents=True, exist_ok=True)+ vector_store = LanceDBVectorStore(str(lance_dir), embedder=embedder_impl)+ except ImportError:+ vector_store = InMemoryVectorStore(embedder_impl)generator = PageGenerator(provider, assembler, config, vector_store=vector_store)diff --git a/packages/cli/src/wikicode/cli/commands/reindex_cmd.py b/packages/cli/src/wikicode/cli/commands/reindex_cmd.pynew file mode 100644index 000000000..7f62aa747--- /dev/null+++ b/packages/cli/src/wikicode/cli/commands/reindex_cmd.py@@ -0,0 +1,178 @@+"""``wikicode reindex`` — rebuild vector embeddings from existing wiki pages."""++from __future__ import annotations++import click+from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn, TimeElapsedColumn++from wikicode.cli.helpers import (+ console,+ ensure_wikicode_dir,+ get_db_url_for_repo,+ resolve_repo_path,+ run_async,+)++[email protected]("reindex")[email protected]("path", required=False, default=None)+ "--embedder",+ type=click.Choice(["gemini", "openai", "auto"]),+ default="auto",+ help="Embedder to use. 'auto' detects from env vars / config.",+)[email protected]("--batch-size", type=int, default=20, help="Pages per embedding batch.")+def reindex_command(path: str | None, embedder: str, batch_size: int) -> None:+ """Rebuild vector search index from existing wiki pages.++ Reads all pages from the database, embeds them using the configured+ embedder, and persists the vectors to LanceDB. No LLM calls — only+ embedding API calls. Fast and cheap.+ """+ repo_path = resolve_repo_path(path)+ ensure_wikicode_dir(repo_path)++ run_async(_reindex(repo_path, embedder, batch_size))+++async def _reindex(repo_path, embedder_name: str, batch_size: int) -> None:+ from pathlib import Path++ from sqlalchemy import select+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine++ from wikicode.core.persistence.database import init_db+ from wikicode.core.persistence.models import Page++ # --- Resolve embedder ---+ if embedder_name == "auto":+ from wikicode.cli.commands.init_cmd import _resolve_embedder++ embedder_name = _resolve_embedder(None)++ if embedder_name == "gemini":+ from wikicode.core.persistence.gemini_embedder import GeminiEmbedder+ embedder_impl = GeminiEmbedder()+ console.print(f"[green]Using Gemini embedder[/green]")+ elif embedder_name == "openai":+ from wikicode.core.persistence.openai_embedder import OpenAIEmbedder+ embedder_impl = OpenAIEmbedder()+ console.print(f"[green]Using OpenAI embedder[/green]")+ else:+ console.print("[red]No real embedder available. Set GEMINI_API_KEY or OPENAI_API_KEY.[/red]")+ raise click.Abort()++ # --- Create LanceDB vector store ---+ lance_dir = Path(repo_path) / ".wikicode" / "lancedb"+ try:+ from wikicode.core.persistence.vector_store import LanceDBVectorStore+ except ImportError:+ console.print("[red]lancedb not installed. Run: uv pip install lancedb[/red]")+ raise click.Abort()++ lance_dir.mkdir(parents=True, exist_ok=True)+ vector_store = LanceDBVectorStore(str(lance_dir), embedder=embedder_impl)++ # Also create a decision store for decision records+ decision_store = LanceDBVectorStore(+ str(lance_dir), embedder=embedder_impl, table_name="decision_records"+ )++ # --- Open database ---+ db_url = get_db_url_for_repo(repo_path)+ connect_args = {}+ if db_url.startswith("sqlite"):+ connect_args["check_same_thread"] = False+ engine = create_async_engine(db_url, connect_args=connect_args)+ await init_db(engine)+ factory = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)++ # --- Load all pages ---+ async with factory() as session:+ result = await session.execute(select(Page))+ pages = list(result.scalars().all())++ # --- Load decision records ---+ from wikicode.core.persistence.models import DecisionRecord++ async with factory() as session:+ result = await session.execute(select(DecisionRecord))+ decisions = list(result.scalars().all())++ total = len(pages) + len(decisions)+ console.print(f"Found [bold]{len(pages)}[/bold] wiki pages and [bold]{len(decisions)}[/bold] decision records to index.")++ if total == 0:+ console.print("[yellow]Nothing to index. Run 'wikicode init' first.[/yellow]")+ await engine.dispose()+ return++ # --- Embed and upsert pages in batches ---+ indexed = 0+ failed = 0++ with Progress(+ SpinnerColumn(),+ TextColumn("[progress.description]{task.description}"),+ BarColumn(),+ TextColumn("{task.completed}/{task.total}"),+ TimeElapsedColumn(),+ console=console,+ ) as progress:+ task = progress.add_task("Indexing pages...", total=total)++ # Pages+ for i in range(0, len(pages), batch_size):+ batch = pages[i : i + batch_size]+ for page in batch:+ try:+ text = f"{page.title}\n{page.content}" if page.content else page.title or ""+ await vector_store.embed_and_upsert(+ page.id,+ text,+ {+ "title": page.title or "",+ "page_type": page.page_type or "",+ "target_path": page.target_path or "",+ },+ )+ indexed += 1+ except Exception as exc:+ failed += 1+ if failed <= 3:+ console.print(f"[yellow] Warning: failed to embed {page.id}: {exc}[/yellow]")+ progress.advance(task)++ # Decision records+ progress.update(task, description="Indexing decisions...")+ for i in range(0, len(decisions), batch_size):+ batch = decisions[i : i + batch_size]+ for d in batch:+ try:+ text = f"{d.title}\n{d.decision}\n{d.rationale}"+ await decision_store.embed_and_upsert(+ d.id,+ text,+ {+ "title": d.title or "",+ "page_type": "decision_record",+ "target_path": "",+ },+ )+ indexed += 1+ except Exception as exc:+ failed += 1+ if failed <= 3:+ console.print(f"[yellow] Warning: failed to embed decision {d.id}: {exc}[/yellow]")+ progress.advance(task)++ await vector_store.close()+ await decision_store.close()+ await engine.dispose()++ console.print(+ f"\n[bold green]Done![/bold green] Indexed {indexed} items"+ + (f" ({failed} failed)" if failed else "")+ + f" -> {lance_dir}"+ )diff --git a/packages/cli/src/wikicode/cli/main.py b/packages/cli/src/wikicode/cli/main.pyindex 2d5c28475..a792ea62f 100644--- a/packages/cli/src/wikicode/cli/main.py+++ b/packages/cli/src/wikicode/cli/main.py@@ -11,6 +11,7 @@ from wikicode.cli.commands.doctor_cmd import doctor_commandfrom wikicode.cli.commands.export_cmd import export_commandfrom wikicode.cli.commands.init_cmd import init_commandfrom wikicode.cli.commands.mcp_cmd import mcp_command+from wikicode.cli.commands.reindex_cmd import reindex_commandfrom wikicode.cli.commands.search_cmd import search_commandfrom wikicode.cli.commands.serve_cmd import serve_commandfrom wikicode.cli.commands.status_cmd import status_command@@ -35,3 +36,4 @@ cli.add_command(doctor_command)cli.add_command(watch_command)cli.add_command(serve_command)cli.add_command(mcp_command)+cli.add_command(reindex_command)diff --git a/packages/core/src/wikicode/core/persistence/search.py b/packages/core/src/wikicode/core/persistence/search.pyindex f92147e51..ee31847f6 100644--- a/packages/core/src/wikicode/core/persistence/search.py+++ b/packages/core/src/wikicode/core/persistence/search.py@@ -38,6 +38,43 @@ class SearchResult:_SNIPPET_LEN = 200+# Common English stop words to strip from FTS queries+_STOP_WORDS = frozenset({+ "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",+ "have", "has", "had", "do", "does", "did", "will", "would", "shall",+ "should", "may", "might", "must", "can", "could", "am", "to", "of",+ "in", "for", "on", "with", "at", "by", "from", "as", "into", "about",+ "it", "its", "this", "that", "these", "those", "i", "we", "you", "he",+ "she", "they", "me", "him", "her", "us", "them", "my", "your", "his",+ "our", "their", "what", "which", "who", "whom", "how", "when", "where",+ "why", "not", "no", "so", "if", "or", "and", "but", "all", "each",+ "very", "just", "also", "than", "too", "only",+})+++def _build_fts5_query(query: str) -> str:+ """Build an FTS5 MATCH expression from a natural-language query.++ Strips stop words, then joins remaining terms with OR so that pages+ containing *any* keyword match. Each term gets a ``*`` suffix for+ prefix matching (e.g. "pay*" matches "payment", "payload", etc.).+ Falls back to the raw (quoted) query when all tokens are stop words.+ """+ import re++ # Keep only alphanumeric tokens+ tokens = re.findall(r"[a-zA-Z0-9_]+", query.lower())+ meaningful = [t for t in tokens if t not in _STOP_WORDS and len(t) > 1]++ if not meaningful:+ # All stop words — fall back to exact phrase+ safe = query.replace('"', '""')+ return f'"{safe}"'++ # FTS5: OR between prefix-match terms gives broad recall;+ # FTS5 rank (BM25) naturally boosts pages matching more terms.+ return " OR ".join(f'"{t}"*' for t in meaningful)+def _snippet(content: str) -> str:return content[:_SNIPPET_LEN].rstrip()@@ -123,9 +160,7 @@ class FullTextSearch:async def _search_sqlite(self, query: str, limit: int) -> list[SearchResult]:"""FTS5 search. ``rank`` is negative; we negate it to get a positive score."""- # FTS5 MATCH syntax: escape special chars with double-quotes- safe_query = query.replace('"', '""')- fts_query = f'"{safe_query}"'+ fts_query = _build_fts5_query(query)async with self._engine.connect() as conn:rows = await conn.execute(diff --git a/packages/server/README.md b/packages/server/README.mdindex 8f0653a0e..de44149fa 100644--- a/packages/server/README.md+++ b/packages/server/README.md@@ -11,7 +11,7 @@ FastAPI REST API, webhook handlers, MCP server, and background job scheduler for| Component | Description ||-----------|-------------|| **REST API** | FastAPI application with full CRUD for repos, pages, symbols, jobs, git analytics, dead code |-| **MCP Server** | 16 MCP tools for AI coding assistants (Claude Code, Cursor, Cline) |+| **MCP Server** | 8 MCP tools for AI coding assistants (Claude Code, Cursor, Cline) || **Webhooks** | GitHub and GitLab push event handlers — trigger incremental updates automatically || **Scheduler** | APScheduler background jobs — polling fallback, stale page decay, periodic re-sync |@@ -153,31 +153,23 @@ Job progress events (`JobProgressEvent`) carry: `event` type, `file` currently b## MCP Server-WikiCode exposes 16 MCP tools for AI coding assistants. Start the MCP server via:+WikiCode exposes 8 MCP tools for AI coding assistants. Start the MCP server via:```bashwikicode mcp # stdio transport (Claude Code, Cursor, Cline)wikicode mcp --transport sse # SSE transport on port 7338```-| Tool | Description |-|------|-------------|-| `get_page` | Retrieve a wiki page by file path |-| `list_pages` | List all wiki pages with metadata |-| `search_codebase` | Full-text, semantic, or hybrid search across all pages |-| `get_symbol` | Look up a symbol by name — signature, docs, file location |-| `get_module_overview` | Summary of a package or module |-| `get_repo_overview` | Repository-level architecture overview |-| `get_dependency_graph` | Export the dependency graph (optionally filtered) |-| `get_dependency_path` | Shortest path between two modules in the dependency graph |-| `get_hotspots` | Files with highest churn — most likely to need attention |-| `get_ownership` | Code ownership breakdown by file or module |-| `get_stale_pages` | Pages whose source has changed since last generation |-| `get_dead_code` | Dead code findings for a file or the whole repo |-| `get_git_summary` | Recent commit activity and change patterns |-| `get_decisions` | Architectural decision records for the codebase |-| `get_why` | Answer "why is X built this way?" using decisions and docs |-| `get_decision_health` | Stale decisions, ungoverned hotspots, proposed decisions |+| 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)` | Docs, ownership, history, decisions, freshness for files/modules/symbols | When you need to understand specific code before reading or modifying it |+| `get_risk(targets)` | Hotspot score, dependents, co-change partners, risk summary | Before modifying files — assess what could break |+| `get_why(query?)` | Architectural decisions, rationale, constraints | Before making architectural changes — understand existing intent |+| `search_codebase(query)` | Semantic search over full wiki | When you don't know where something lives |+| `get_dependency_path(from, to)` | Connection path between two files/modules | When you need to understand how two things are connected |+| `get_dead_code` | Unused/unreachable code sorted by cleanup impact | Before cleanup tasks |+| `get_architecture_diagram` | Mermaid diagram for repo or module | For documentation or presentation |**Claude Code / Cursor / Cline setup** — add to your MCP config:diff --git a/packages/server/src/wikicode/server/mcp_server.py b/packages/server/src/wikicode/server/mcp_server.pyindex b4b50ad07..5e9490e69 100644--- a/packages/server/src/wikicode/server/mcp_server.py+++ b/packages/server/src/wikicode/server/mcp_server.py@@ -1,4 +1,4 @@-"""WikiCode MCP Server — 16 tools for AI coding assistants.+"""WikiCode MCP Server — 8 tools for AI coding assistants.Exposes the full WikiCode wiki as queryable tools via the MCP protocol.Supports both stdio transport (Claude Code, Cursor, Cline) and SSE transport@@ -11,8 +11,10 @@ Usage:from __future__ import annotations+import asyncioimport jsonimport os+import os.pathfrom contextlib import asynccontextmanagerfrom typing import Any@@ -166,8 +168,9 @@ mcp = FastMCP("WikiCode",instructions=("WikiCode is a codebase documentation engine. Use these tools to query "- "the wiki for architecture overviews, file docs, symbol lookups, "- "dependency paths, git history, hotspots, ownership, and dead code."+ "the wiki for architecture overviews, contextual docs on files/modules/"+ "symbols, modification risk assessment, architectural decision rationale, "+ "semantic search, dependency paths, dead code, and architecture diagrams."),lifespan=_lifespan,)@@ -177,6 +180,11 @@ mcp = FastMCP(# Helpers# ---------------------------------------------------------------------------+_CODE_EXTS = frozenset({+ ".py", ".ts", ".js", ".go", ".rs", ".java", ".tsx", ".jsx",+ ".rb", ".kt", ".cpp", ".c", ".h", ".cs", ".swift", ".scala",+})+async def _get_repo(session: AsyncSession, repo: str | None = None) -> Repository:"""Resolve a repository — by path, by ID, or return the first one."""@@ -211,8 +219,16 @@ async def _get_repo(session: AsyncSession, repo: str | None = None) -> Repositorreturn obj+def _is_path(query: str) -> bool:+ """Heuristic: does this string look like a file or module path?"""+ if "/" in query:+ return True+ _, ext = os.path.splitext(query)+ return ext in _CODE_EXTS++# ----------------------------------------------------------------------------# Tool 1: get_overview+# Tool 1: get_overview (unchanged)# ---------------------------------------------------------------------------@@ -283,213 +299,646 @@ async def get_overview(repo: str | None = None) -> dict:# ----------------------------------------------------------------------------# Tool 2: get_module_docs+# Tool 2: get_context (NEW — replaces 5 tools)# ----------------------------------------------------------------------------async def get_module_docs(module_path: str, repo: str | None = None) -> dict:- """Get the wiki page for a module/package/directory.-- Args:- module_path: Module path (e.g. "src/auth", "packages/core").- repo: Repository path, name, or ID.- """- async with get_session(_session_factory) as session:- repository = await _get_repo(session, repo)-- # Look up module page by target_path match- result = await session.execute(+async def _resolve_one_target(+ session: AsyncSession,+ repository: Repository,+ target: str,+ include: set[str] | None,+) -> dict:+ """Resolve a single target and return its full context."""+ repo_id = repository.id+ result_data: dict[str, Any] = {}++ # --- Determine target type ---+ # 1. Try file page (most common)+ page_id = f"file_page:{target}"+ page = await session.get(Page, page_id)+ target_type = None+ file_path_for_git: str | None = None++ if page and page.repository_id == repo_id:+ target_type = "file"+ file_path_for_git = target+ else:+ # 2. Try module page+ res = await session.execute(select(Page).where(- Page.repository_id == repository.id,+ Page.repository_id == repo_id,Page.page_type == "module_page",- Page.target_path == module_path,+ Page.target_path == target,))- page = result.scalar_one_or_none()-- # Fallback: try partial match+ page = res.scalar_one_or_none()if page is None:- result = await session.execute(+ # Partial match fallback for modules+ res = await session.execute(select(Page).where(- Page.repository_id == repository.id,+ Page.repository_id == repo_id,Page.page_type == "module_page",- Page.target_path.contains(module_path),+ Page.target_path.contains(target),))- page = result.scalar_one_or_none()-- if page is None:- return {"error": f"Module page not found for '{module_path}'"}-- # Get file pages within this module- result = await session.execute(- select(Page).where(- Page.repository_id == repository.id,- Page.page_type == "file_page",- Page.target_path.like(f"{module_path}%"),+ page = res.scalar_one_or_none()+ if page:+ target_type = "module"+ else:+ # 3. Try symbol (exact then fuzzy)+ res = await session.execute(+ select(WikiSymbol).where(+ WikiSymbol.repository_id == repo_id,+ WikiSymbol.name == target,+ ))- )- file_pages = result.scalars().all()-- return {- "title": page.title,- "content_md": page.content,- "files": [+ sym_matches = list(res.scalars().all())+ if not sym_matches:+ res = await session.execute(+ select(WikiSymbol).where(+ WikiSymbol.repository_id == repo_id,+ WikiSymbol.name.ilike(f"%{target}%"),+ ).limit(10)+ )+ sym_matches = list(res.scalars().all())+ if sym_matches:+ target_type = "symbol"+ file_path_for_git = sym_matches[0].file_path+ else:+ # 4. Try file page by target_path search+ res = await session.execute(+ select(Page).where(+ Page.repository_id == repo_id,+ Page.page_type == "file_page",+ Page.target_path == target,+ )+ )+ page = res.scalar_one_or_none()+ if page:+ target_type = "file"+ file_path_for_git = target++ if target_type is None:+ return {"target": target, "error": f"Target not found: '{target}'"}++ result_data["target"] = target+ result_data["type"] = target_type++ # --- Docs ---+ if include is None or "docs" in include:+ docs: dict[str, Any] = {}+ if target_type == "file":+ docs["title"] = page.title+ docs["content_md"] = page.content+ # Symbols in this file+ res = await session.execute(+ select(WikiSymbol).where(+ WikiSymbol.repository_id == repo_id,+ WikiSymbol.file_path == target,+ )+ )+ symbols = res.scalars().all()+ docs["symbols"] = [+ {"name": s.name, "kind": s.kind, "signature": s.signature}+ for s in symbols+ ]+ # Importers+ res = await session.execute(+ select(GraphEdge).where(+ GraphEdge.repository_id == repo_id,+ GraphEdge.target_node_id == target,+ )+ )+ importers = res.scalars().all()+ docs["imported_by"] = [e.source_node_id for e in importers]++ elif target_type == "module":+ docs["title"] = page.title+ docs["content_md"] = page.content+ # Child file pages+ res = await session.execute(+ select(Page).where(+ Page.repository_id == repo_id,+ Page.page_type == "file_page",+ Page.target_path.like(f"{page.target_path}%"),+ )+ )+ file_pages = res.scalars().all()+ docs["files"] = [{"path": f.target_path,"description": f.title,"confidence_score": f.confidence,}for f in file_pages- ],- "public_api_summary": page.content[:500] if page.content else "",- }+ ]+ elif target_type == "symbol":+ sym = sym_matches[0] # type: ignore[possibly-undefined]+ docs["name"] = sym.name+ docs["qualified_name"] = sym.qualified_name+ docs["kind"] = sym.kind+ docs["signature"] = sym.signature+ docs["file_path"] = sym.file_path+ docs["docstring"] = sym.docstring or ""+ # File page content as documentation+ sym_page_id = f"file_page:{sym.file_path}"+ sym_page = await session.get(Page, sym_page_id)+ docs["documentation"] = sym_page.content if sym_page else ""+ # Used by+ res = await session.execute(+ select(GraphEdge).where(+ GraphEdge.repository_id == repo_id,+ GraphEdge.target_node_id == sym.file_path,+ )+ )+ edges = res.scalars().all()+ docs["used_by"] = [e.source_node_id for e in edges][:20]+ # Candidates+ if len(sym_matches) > 1: # type: ignore[possibly-undefined]+ docs["candidates"] = [+ {"name": m.name, "kind": m.kind, "file_path": m.file_path}+ for m in sym_matches[1:5] # type: ignore[possibly-undefined]+ ]++ result_data["docs"] = docs++ # --- Ownership ---+ if include is None or "ownership" in include:+ ownership: dict[str, Any] = {}+ git_path = file_path_for_git+ if target_type == "module" and page:+ git_path = page.target_path+ if git_path:+ res = await session.execute(+ select(GitMetadata).where(+ GitMetadata.repository_id == repo_id,+ GitMetadata.file_path == git_path,+ )+ )+ meta = res.scalar_one_or_none()+ if meta:+ ownership["primary_owner"] = meta.primary_owner_name+ ownership["owner_pct"] = meta.primary_owner_commit_pct+ ownership["contributor_count"] = len(json.loads(meta.top_authors_json))+ else:+ ownership["primary_owner"] = None+ ownership["owner_pct"] = None+ ownership["contributor_count"] = 0+ else:+ ownership["primary_owner"] = None+ ownership["owner_pct"] = None+ ownership["contributor_count"] = 0+ result_data["ownership"] = ownership++ # --- Last change ---+ if include is None or "last_change" in include:+ last_change: dict[str, Any] = {}+ git_path = file_path_for_git+ if target_type == "module" and page:+ git_path = page.target_path+ if git_path:+ res = await session.execute(+ select(GitMetadata).where(+ GitMetadata.repository_id == repo_id,+ GitMetadata.file_path == git_path,+ )+ )+ meta = res.scalar_one_or_none()+ if meta:+ last_change["date"] = meta.last_commit_at.isoformat() if meta.last_commit_at else None+ last_change["author"] = meta.primary_owner_name+ last_change["days_ago"] = meta.age_days+ else:+ last_change["date"] = None+ last_change["author"] = None+ last_change["days_ago"] = None+ else:+ last_change["date"] = None+ last_change["author"] = None+ last_change["days_ago"] = None+ result_data["last_change"] = last_change++ # --- Decisions ---+ if include is None or "decisions" in include:+ res = await session.execute(+ select(DecisionRecord).where(+ DecisionRecord.repository_id == repo_id,+ )+ )+ all_decisions = res.scalars().all()+ governing = []+ for d in all_decisions:+ affected_files = json.loads(d.affected_files_json)+ affected_modules = json.loads(d.affected_modules_json)+ if target in affected_files or target in affected_modules:+ governing.append({+ "id": d.id,+ "title": d.title,+ "status": d.status,+ "decision": d.decision,+ "rationale": d.rationale,+ "confidence": d.confidence,+ })+ elif file_path_for_git and file_path_for_git in affected_files:+ governing.append({+ "id": d.id,+ "title": d.title,+ "status": d.status,+ "decision": d.decision,+ "rationale": d.rationale,+ "confidence": d.confidence,+ })+ result_data["decisions"] = governing++ # --- Freshness ---+ if include is None or "freshness" in include:+ freshness: dict[str, Any] = {}+ if page:+ freshness["confidence_score"] = page.confidence+ freshness["freshness_status"] = page.freshness_status+ freshness["is_stale"] = (page.confidence or 1.0) < 0.6+ elif target_type == "symbol" and file_path_for_git:+ sym_page_id = f"file_page:{file_path_for_git}"+ sym_page = await session.get(Page, sym_page_id)+ if sym_page:+ freshness["confidence_score"] = sym_page.confidence+ freshness["freshness_status"] = sym_page.freshness_status+ freshness["is_stale"] = (sym_page.confidence or 1.0) < 0.6+ else:+ freshness["confidence_score"] = None+ freshness["freshness_status"] = None+ freshness["is_stale"] = None+ else:+ freshness["confidence_score"] = None+ freshness["freshness_status"] = None+ freshness["is_stale"] = None+ result_data["freshness"] = freshness-# ----------------------------------------------------------------------------# Tool 3: get_file_docs-# ---------------------------------------------------------------------------+ return result_data@mcp.tool()-async def get_file_docs(file_path: str, repo: str | None = None) -> dict:- """Get the wiki page for a specific file.+async def get_context(+ targets: list[str],+ include: list[str] | None = None,+ repo: str | None = None,+) -> dict:+ """Get complete context for one or more targets (files, modules, or symbols).++ Pass ALL relevant targets in a single call rather than calling this tool+ multiple times. Each target is resolved automatically — pass file paths+ like "src/auth/service.py", module paths like "src/auth", or symbol names+ like "AuthService".++ Example: get_context(["src/auth/service.py", "src/auth/middleware.py", "AuthService"])++ Optional `include` parameter filters response fields:+ ["docs", "ownership", "last_change", "decisions", "freshness"]+ Default: all fields returned.Args:- file_path: Relative file path (e.g. "src/auth/service.py").+ targets: List of file paths, module paths, or symbol names to look up.+ include: Optional list of fields to include. Default returns all.repo: Repository path, name, or ID."""+ include_set = set(include) if include else None+async with get_session(_session_factory) as session:repository = await _get_repo(session, repo)- page_id = f"file_page:{file_path}"- page = await session.get(Page, page_id)+ results = await asyncio.gather(*[+ _resolve_one_target(session, repository, t, include_set)+ for t in targets+ ])- if page is None:- # Try searching by target_path- result = await session.execute(- select(Page).where(- Page.repository_id == repository.id,- Page.page_type == "file_page",- Page.target_path == file_path,- )- )- page = result.scalar_one_or_none()+ return {+ "targets": {r["target"]: r for r in results},+ }- if page is None:- return {"error": f"File page not found for '{file_path}'"}- # Get symbols in this file- result = await session.execute(- select(WikiSymbol).where(- WikiSymbol.repository_id == repository.id,- WikiSymbol.file_path == file_path,- )+# ---------------------------------------------------------------------------+# Tool 3: get_risk (NEW — replaces 3 tools)+# ---------------------------------------------------------------------------+++async def _assess_one_target(+ session: AsyncSession,+ repository: Repository,+ target: str,+ all_edge_map: dict[str, int],+ import_links: dict[str, set[str]],+) -> dict:+ """Assess risk for a single target file."""+ repo_id = repository.id+ result_data: dict[str, Any] = {"target": target}++ # Git metadata+ res = await session.execute(+ select(GitMetadata).where(+ GitMetadata.repository_id == repo_id,+ GitMetadata.file_path == target,)- symbols = result.scalars().all()+ )+ meta = res.scalar_one_or_none()++ if meta is None:+ result_data["hotspot_score"] = 0.0+ result_data["dependents_count"] = all_edge_map.get(target, 0)+ result_data["co_change_partners"] = []+ result_data["primary_owner"] = None+ result_data["owner_pct"] = None+ result_data["risk_summary"] = f"{target} — no git metadata available"+ return result_data++ hotspot_score = meta.churn_percentile or 0.0+ dep_count = all_edge_map.get(target, 0)++ # Co-change partners+ partners = json.loads(meta.co_change_partners_json)+ import_related = import_links.get(target, set())+ co_changes = [+ {+ "file_path": p.get("file_path", p.get("path", "")),+ "count": p.get("co_change_count", p.get("count", 0)),+ "has_import_link": p.get("file_path", p.get("path", "")) in import_related,+ }+ for p in partners+ ]++ owner = meta.primary_owner_name or "unknown"+ pct = meta.primary_owner_commit_pct or 0.0++ result_data["hotspot_score"] = hotspot_score+ result_data["dependents_count"] = dep_count+ result_data["co_change_partners"] = co_changes+ result_data["primary_owner"] = owner+ result_data["owner_pct"] = pct+ result_data["risk_summary"] = (+ f"{target} — hotspot score {hotspot_score:.0%}, {dep_count} dependents, "+ f"{len(co_changes)} co-change partners, owned {pct:.0%} by {owner}"+ )- # Get files that import this one (from graph edges)- result = await session.execute(+ return result_data+++async def get_risk(+ targets: list[str],+ repo: str | None = None,+) -> dict:+ """Assess modification risk for one or more files before making changes.++ Pass ALL files you plan to modify in a single call. Returns hotspot+ score, dependents, co-change partners, and a plain-English risk summary+ for each target, plus the top 5 global hotspots for ambient awareness.++ Example: get_risk(["src/auth/service.py", "src/auth/middleware.py"])++ Args:+ targets: List of file paths to assess.+ repo: Repository path, name, or ID.+ """+ async with get_session(_session_factory) as session:+ repository = await _get_repo(session, repo)+ repo_id = repository.id++ # Pre-load edge counts (dependents = incoming edges)+ res = await session.execute(select(GraphEdge).where(- GraphEdge.repository_id == repository.id,- GraphEdge.target_node_id == file_path,+ GraphEdge.repository_id == repo_id,+ )+ )+ all_edges = res.scalars().all()+ dep_counts: dict[str, int] = {}+ import_links: dict[str, set[str]] = {}+ for e in all_edges:+ dep_counts[e.target_node_id] = dep_counts.get(e.target_node_id, 0) + 1+ import_links.setdefault(e.source_node_id, set()).add(e.target_node_id)+ import_links.setdefault(e.target_node_id, set()).add(e.source_node_id)++ # Assess each target+ results = await asyncio.gather(*[+ _assess_one_target(session, repository, t, dep_counts, import_links)+ for t in targets+ ])++ # Global hotspots (excluding requested targets)+ target_set = set(targets)+ res = await session.execute(+ select(GitMetadata)+ .where(+ GitMetadata.repository_id == repo_id,+ GitMetadata.is_hotspot == True, # noqa: E712)+ .order_by(GitMetadata.churn_percentile.desc())+ .limit(len(targets) + 5))- importers = result.scalars().all()+ all_hotspots = res.scalars().all()+ global_hotspots = [+ {+ "file_path": h.file_path,+ "hotspot_score": h.churn_percentile,+ "primary_owner": h.primary_owner_name,+ }+ for h in all_hotspots+ if h.file_path not in target_set+ ][:5]- return {- "title": page.title,- "content_md": page.content,- "symbols": [- {"name": s.name, "kind": s.kind, "signature": s.signature}- for s in symbols- ],- "imported_by": [e.source_node_id for e in importers],- "confidence_score": page.confidence,- "freshness_status": page.freshness_status,- }+ return {+ "targets": {r["target"]: r for r in results},+ "global_hotspots": global_hotspots,+ }# ----------------------------------------------------------------------------# Tool 4: get_symbol+# Tool 4: get_why (refactored — 3 modes)# ---------------------------------------------------------------------------@mcp.tool()-async def get_symbol(- symbol_name: str, kind: str | None = None, repo: str | None = None+async def get_why(+ query: str | None = None,+ repo: str | None = None,) -> dict:- """Look up any symbol by name (fuzzy match if exact match fails).+ """Understand why code is built the way it is, using architectural decision records.++ Three modes:+ 1. get_why("why is auth using JWT?") — semantic search over decisions+ 2. get_why("src/auth/service.py") — all decisions governing a specific file+ 3. get_why() — decision health dashboard: stale decisions, ungoverned hotspots++ Always call this before making architectural changes.Args:- symbol_name: Symbol name (e.g. "AuthService", "login", "UserRepository.find_by_id").- kind: Optional filter by kind (function, class, method, interface, enum, etc.).+ query: Natural language question, file/module path, or omit for health dashboard.repo: Repository path, name, or ID."""+ # --- Mode 1: No query → health dashboard ---+ if not query:+ from wikicode.core.persistence.crud import get_decision_health_summary++ async with get_session(_session_factory) as session:+ repository = await _get_repo(session, repo)+ health = await get_decision_health_summary(session, repository.id)++ stale = health["stale_decisions"]+ proposed = health["proposed_awaiting_review"]+ ungoverned = health["ungoverned_hotspots"]++ return {+ "mode": "health",+ "summary": (+ f"{health['summary'].get('active', 0)} active · "+ f"{health['summary'].get('stale', 0)} stale · "+ f"{len(proposed)} proposed · "+ f"{len(ungoverned)} ungoverned hotspots"+ ),+ "counts": health["summary"],+ "stale_decisions": [+ {+ "id": d.id,+ "title": d.title,+ "staleness_score": d.staleness_score,+ "affected_files": json.loads(d.affected_files_json)[:5],+ }+ for d in stale[:10]+ ],+ "proposed_awaiting_review": [+ {+ "id": d.id,+ "title": d.title,+ "source": d.source,+ "confidence": d.confidence,+ }+ for d in proposed[:10]+ ],+ "ungoverned_hotspots": ungoverned[:15],+ }++ # --- Mode 2: Path → decisions governing that path ---+ if _is_path(query):+ async with get_session(_session_factory) as session:+ repository = await _get_repo(session, repo)+ res = await session.execute(+ select(DecisionRecord).where(+ DecisionRecord.repository_id == repository.id,+ )+ )+ all_decisions = res.scalars().all()++ governing = []+ for d in all_decisions:+ affected_files = json.loads(d.affected_files_json)+ affected_modules = json.loads(d.affected_modules_json)+ if query in affected_files or query in affected_modules:+ governing.append({+ "id": d.id,+ "title": d.title,+ "status": d.status,+ "context": d.context,+ "decision": d.decision,+ "rationale": d.rationale,+ "alternatives": json.loads(d.alternatives_json),+ "consequences": json.loads(d.consequences_json),+ "affected_files": affected_files,+ "source": d.source,+ "confidence": d.confidence,+ "staleness_score": d.staleness_score,+ })++ return {+ "mode": "path",+ "path": query,+ "decisions": governing,+ }++ # --- Mode 3: Natural language → search ---+ from wikicode.core.persistence.crud import list_decisions as _list_decisions+async with get_session(_session_factory) as session:repository = await _get_repo(session, repo)-- # Try exact match first- query = select(WikiSymbol).where(- WikiSymbol.repository_id == repository.id,- WikiSymbol.name == symbol_name,+ all_decisions = await _list_decisions(+ session, repository.id, include_proposed=True, limit=200)- if kind:- query = query.where(WikiSymbol.kind == kind)- result = await session.execute(query)- matches = list(result.scalars().all())- # Fallback to fuzzy match- if not matches:- query = select(WikiSymbol).where(- WikiSymbol.repository_id == repository.id,- WikiSymbol.name.ilike(f"%{symbol_name}%"),- )- if kind:- query = query.where(WikiSymbol.kind == kind)- result = await session.execute(query.limit(10))- matches = list(result.scalars().all())+ # Keyword scoring+ query_lower = query.lower()+ query_words = set(query_lower.split())+ scored_decisions = []+ for d in all_decisions:+ text = f"{d.title} {d.decision} {d.rationale}".lower()+ match_count = sum(1 for w in query_words if w in text)+ if match_count > 0:+ scored_decisions.append((match_count, d))+ scored_decisions.sort(key=lambda t: t[0], reverse=True)+ keyword_matches = [d for _, d in scored_decisions[:5]]- if not matches:- return {"error": f"Symbol not found: '{symbol_name}'"}+ # Semantic search over decision vector store+ decision_results = []+ try:+ decision_results = await _decision_store.search(query, limit=5)+ except Exception:+ pass- sym = matches[0]+ # Semantic search over documentation+ doc_results = []+ try:+ doc_results = await _vector_store.search(query, limit=3)+ except Exception:+ try:+ doc_results = await _fts.search(query, limit=3)+ except Exception:+ pass- # Get the file page for this symbol's documentation- page_id = f"file_page:{sym.file_path}"- page = await session.get(Page, page_id)+ # Merge keyword matches with semantic results (dedup by ID)+ seen_ids: set[str] = set()+ merged_decisions = []+ for d in keyword_matches:+ if d.id not in seen_ids:+ seen_ids.add(d.id)+ merged_decisions.append({+ "id": d.id,+ "title": d.title,+ "status": d.status,+ "decision": d.decision,+ "rationale": d.rationale,+ "consequences": json.loads(d.consequences_json),+ "affected_files": json.loads(d.affected_files_json),+ "source": d.source,+ "confidence": d.confidence,+ })- # Get files that use this symbol- result = await session.execute(- select(GraphEdge).where(- GraphEdge.repository_id == repository.id,- GraphEdge.target_node_id == sym.file_path,- )- )- edges = result.scalars().all()- used_by = [e.source_node_id for e in edges]+ for r in decision_results:+ if r.page_id not in seen_ids:+ seen_ids.add(r.page_id)+ merged_decisions.append({+ "id": r.page_id,+ "title": r.title,+ "snippet": r.snippet,+ "relevance_score": r.score,+ })- return {- "name": sym.name,- "qualified_name": sym.qualified_name,- "kind": sym.kind,- "signature": sym.signature,- "file_path": sym.file_path,- "documentation": page.content if page else sym.docstring or "",- "used_by": used_by[:20],- "confidence_score": page.confidence if page else None,- "candidates": [- {"name": m.name, "kind": m.kind, "file_path": m.file_path}- for m in matches[1:5]- ]- if len(matches) > 1- else [],- }+ return {+ "mode": "search",+ "query": query,+ "decisions": merged_decisions[:8],+ "related_documentation": [+ {+ "page_id": r.page_id,+ "title": r.title,+ "page_type": r.page_type,+ "snippet": r.snippet,+ "relevance_score": r.score,+ }+ for r in doc_results[:3]+ ],+ }# ----------------------------------------------------------------------------# Tool 5: search_codebase+# Tool 5: search_codebase (unchanged)# ---------------------------------------------------------------------------@@ -513,10 +962,16 @@ async def search_codebase(await _get_repo(session, repo)# Try semantic search first, fall back to fulltext+ results = []try:results = await _vector_store.search(query, limit=limit)except Exception:- results = await _fts.search(query, limit=limit)+ pass+ if not results:+ try:+ results = await _fts.search(query, limit=limit)+ except Exception:+ passoutput = []for r in results:@@ -537,116 +992,27 @@ async def search_codebase(# ----------------------------------------------------------------------------# Tool 6: get_architecture_diagram+# Tool 6: get_dependency_path (unchanged)# ---------------------------------------------------------------------------@mcp.tool()-async def get_architecture_diagram(- scope: str = "repo",- path: str | None = None,- diagram_type: str = "auto",- repo: str | None = None,+async def get_dependency_path(+ source: str, target: str, repo: str | None = None) -> dict:- """Get a Mermaid diagram for the codebase or a specific module.+ """Find how two files/modules are connected in the dependency graph.Args:- scope: "repo", "module", or "file".- path: Module or file path (required for module/file scope).- diagram_type: "auto", "flowchart", "class", or "sequence".+ source: Source file or module path.+ target: Target file or module path.repo: Repository path, name, or ID."""async with get_session(_session_factory) as session:repository = await _get_repo(session, repo)- if scope == "repo":- # Return the architecture diagram page- result = await session.execute(- select(Page).where(- Page.repository_id == repository.id,- Page.page_type == "architecture_diagram",- )- )- page = result.scalar_one_or_none()- if page:- return {- "diagram_type": diagram_type if diagram_type != "auto" else "flowchart",- "mermaid_syntax": page.content,- "description": page.title,- }-- # For module/file scope or fallback, build diagram from graph- if path:- filter_prefix = path- else:- filter_prefix = ""-- result = await session.execute(- select(GraphNode).where(- GraphNode.repository_id == repository.id,- GraphNode.node_id.like(f"{filter_prefix}%") if filter_prefix else GraphNode.repository_id == repository.id,- )- )- nodes = result.scalars().all()-- result = await session.execute(- select(GraphEdge).where(- GraphEdge.repository_id == repository.id,- )- )- edges = result.scalars().all()-- node_ids = {n.node_id for n in nodes}- relevant_edges = [- e for e in edges- if e.source_node_id in node_ids or e.target_node_id in node_ids- ]-- # Build Mermaid flowchart- lines = ["graph TD"]- seen_nodes = set()- for e in relevant_edges[:50]: # Limit to 50 edges for readability- src = e.source_node_id.replace("/", "_").replace(".", "_").replace("-", "_")- tgt = e.target_node_id.replace("/", "_").replace(".", "_").replace("-", "_")- if src not in seen_nodes:- lines.append(f' {src}["{e.source_node_id}"]')- seen_nodes.add(src)- if tgt not in seen_nodes:- lines.append(f' {tgt}["{e.target_node_id}"]')- seen_nodes.add(tgt)- lines.append(f" {src} --> {tgt}")-- mermaid = "\n".join(lines) if len(lines) > 1 else "graph TD\n A[No graph data available]"-- return {- "diagram_type": diagram_type if diagram_type != "auto" else "flowchart",- "mermaid_syntax": mermaid,- "description": f"Dependency graph for {scope}: {path or 'entire repo'}",- }---# ----------------------------------------------------------------------------# Tool 7: get_dependency_path-# ------------------------------------------------------------------------------async def get_dependency_path(- source: str, target: str, repo: str | None = None-) -> dict:- """Find how two files/modules are connected in the dependency graph.-- Args:- source: Source file or module path.- target: Target file or module path.- repo: Repository path, name, or ID.- """- async with get_session(_session_factory) as session:- repository = await _get_repo(session, repo)-- result = await session.execute(- select(GraphEdge).where(- GraphEdge.repository_id == repository.id,+ result = await session.execute(+ select(GraphEdge).where(+ GraphEdge.repository_id == repository.id,))edges = result.scalars().all()@@ -686,339 +1052,7 @@ async def get_dependency_path(# ----------------------------------------------------------------------------# Tool 8: get_stale_pages-# ------------------------------------------------------------------------------async def get_stale_pages(- threshold: float = 0.6, repo: str | None = None-) -> dict:- """List pages whose confidence has dropped below a threshold.-- Useful for knowing which docs to distrust or prioritize for regeneration.-- Args:- threshold: Confidence score threshold (default 0.6). Pages below this are returned.- repo: Repository path, name, or ID.- """- async with get_session(_session_factory) as session:- repository = await _get_repo(session, repo)-- result = await session.execute(- select(Page)- .where(- Page.repository_id == repository.id,- Page.confidence < threshold,- )- .order_by(Page.confidence)- .limit(50)- )- pages = result.scalars().all()-- return {- "stale_pages": [- {- "id": p.id,- "title": p.title,- "page_type": p.page_type,- "confidence_score": p.confidence,- "stale_since": p.updated_at.isoformat() if p.updated_at else None,- "source_files": [p.target_path],- }- for p in pages- ]- }---# ----------------------------------------------------------------------------# Tool 9: get_file_history-# ------------------------------------------------------------------------------async def get_file_history(- file_path: str, repo: str | None = None, limit: int = 10-) -> dict:- """Get the git history for a file — the WHY behind its current structure.-- Call this before making changes to understand why code was written as it was.-- Args:- file_path: Relative file path (e.g. "src/auth/service.py").- repo: Repository path, name, or ID.- limit: Max significant commits to return (default 10).- """- async with get_session(_session_factory) as session:- repository = await _get_repo(session, repo)-- result = await session.execute(- select(GitMetadata).where(- GitMetadata.repository_id == repository.id,- GitMetadata.file_path == file_path,- )- )- meta = result.scalar_one_or_none()-- if meta is None:- return {"error": f"No git metadata found for '{file_path}'"}-- significant_commits = json.loads(meta.significant_commits_json)- co_change_partners = json.loads(meta.co_change_partners_json)-- return {- "file_path": meta.file_path,- "age_days": meta.age_days,- "primary_owner": {- "name": meta.primary_owner_name,- "email": meta.primary_owner_email,- "pct": meta.primary_owner_commit_pct,- },- "is_hotspot": meta.is_hotspot,- "is_stable": meta.is_stable,- "commit_count_total": meta.commit_count_total,- "commit_count_90d": meta.commit_count_90d,- "significant_commits": significant_commits[:limit],- "co_change_partners": [- {- "file_path": p.get("file_path", p.get("path", "")),- "co_change_count": p.get("co_change_count", p.get("count", 0)),- }- for p in co_change_partners- ],- }---# ----------------------------------------------------------------------------# Tool 10: get_hotspots-# ------------------------------------------------------------------------------async def get_hotspots(- repo: str | None = None,- limit: int = 10,- include_stable: bool = False,-) -> dict:- """Get the riskiest files: high churn AND high complexity.-- These are the files most likely to contain bugs.-- Args:- repo: Repository path, name, or ID.- limit: Max hotspots to return (default 10).- include_stable: Also return stable files (default false).- """- async with get_session(_session_factory) as session:- repository = await _get_repo(session, repo)-- result = await session.execute(- select(GitMetadata)- .where(- GitMetadata.repository_id == repository.id,- GitMetadata.is_hotspot == True, # noqa: E712- )- .order_by(GitMetadata.churn_percentile.desc())- .limit(limit)- )- hotspots = result.scalars().all()-- response: dict[str, Any] = {- "hotspots": [- {- "file_path": h.file_path,- "commit_count_90d": h.commit_count_90d,- "churn_percentile": h.churn_percentile,- "primary_owner": h.primary_owner_name,- }- for h in hotspots- ],- }-- if include_stable:- result = await session.execute(- select(GitMetadata)- .where(- GitMetadata.repository_id == repository.id,- GitMetadata.is_stable == True, # noqa: E712- )- .order_by(GitMetadata.commit_count_total.desc())- .limit(limit)- )- stables = result.scalars().all()- response["stable_files"] = [- {- "file_path": s.file_path,- "commit_count_total": s.commit_count_total,- "primary_owner": s.primary_owner_name,- }- for s in stables- ]-- return response---# ----------------------------------------------------------------------------# Tool 11: get_codebase_ownership-# ------------------------------------------------------------------------------async def get_codebase_ownership(- repo: str | None = None, by: str = "module"-) -> dict:- """Get ownership breakdown. Identifies knowledge silos and abandoned areas.-- Args:- repo: Repository path, name, or ID.- by: Granularity — "file", "module", or "package" (default "module").- """- async with get_session(_session_factory) as session:- repository = await _get_repo(session, repo)-- result = await session.execute(- select(GitMetadata).where(- GitMetadata.repository_id == repository.id,- )- )- all_meta = list(result.scalars().all())-- if by == "file":- return {- "by_file": [- {- "file_path": m.file_path,- "primary_owner": m.primary_owner_name,- "owner_pct": m.primary_owner_commit_pct,- "contributor_count": len(json.loads(m.top_authors_json)),- "is_silo": (m.primary_owner_commit_pct or 0) > 0.8,- "last_commit_days_ago": m.age_days,- }- for m in all_meta- ]- }-- # Group by module (top-level directory)- modules: dict[str, list[GitMetadata]] = {}- for m in all_meta:- parts = m.file_path.split("/")- module = parts[0] if len(parts) > 1 else "root"- modules.setdefault(module, []).append(m)-- entries = []- for module_path, files in sorted(modules.items()):- owners: dict[str, int] = {}- all_contributors: set[str] = set()- for f in files:- if f.primary_owner_name:- owners[f.primary_owner_name] = owners.get(f.primary_owner_name, 0) + 1- for author in json.loads(f.top_authors_json):- name = author.get("name", "")- if name:- all_contributors.add(name)-- if owners:- top_owner = max(owners, key=owners.get) # type: ignore[arg-type]- owner_pct = owners[top_owner] / len(files)- else:- top_owner = None- owner_pct = 0.0-- entries.append(- {- "module_path": module_path,- "primary_owner": top_owner,- "owner_pct": owner_pct,- "contributor_count": len(all_contributors),- "is_silo": owner_pct > 0.8,- "last_commit_days_ago": min(- (f.age_days for f in files), default=0- ),- }- )-- return {"by_module": entries}---# ----------------------------------------------------------------------------# Tool 12: get_co_changes-# ------------------------------------------------------------------------------async def get_co_changes(- file_path: str, repo: str | None = None, min_count: int = 3-) -> dict:- """Get files that frequently change together with the given file.-- Essential before refactoring — reveals hidden coupling not visible in imports.-- Args:- file_path: Relative file path.- repo: Repository path, name, or ID.- min_count: Minimum co-change count to include (default 3).- """- async with get_session(_session_factory) as session:- repository = await _get_repo(session, repo)-- result = await session.execute(- select(GitMetadata).where(- GitMetadata.repository_id == repository.id,- GitMetadata.file_path == file_path,- )- )- meta = result.scalar_one_or_none()-- if meta is None:- return {"error": f"No git metadata found for '{file_path}'"}-- partners = json.loads(meta.co_change_partners_json)- filtered = [p for p in partners if p.get("co_change_count", p.get("count", 0)) >= min_count]-- # Check if partners have import relationships- partner_paths = [p.get("file_path", p.get("path", "")) for p in filtered]- result = await session.execute(- select(GraphEdge).where(- GraphEdge.repository_id == repository.id,- GraphEdge.source_node_id == file_path,- )- )- outgoing = {e.target_node_id for e in result.scalars().all()}-- result = await session.execute(- select(GraphEdge).where(- GraphEdge.repository_id == repository.id,- GraphEdge.target_node_id == file_path,- )- )- incoming = {e.source_node_id for e in result.scalars().all()}- import_related = outgoing | incoming-- enriched_partners = []- for p in filtered:- p_path = p.get("file_path", p.get("path", ""))- # Try to get a wiki page snippet- page_id = f"file_page:{p_path}"- page = await session.get(Page, page_id)- snippet = page.content[:150] + "..." if page and len(page.content) > 150 else (page.content if page else None)-- enriched_partners.append(- {- "file_path": p_path,- "co_change_count": p.get("count", 0),- "has_import_relationship": p_path in import_related,- "wiki_page_snippet": snippet,- }- )-- return {- "file_path": file_path,- "co_change_partners": enriched_partners,- }---# ----------------------------------------------------------------------------# Tool 13: get_dead_code+# Tool 7: get_dead_code (unchanged)# ---------------------------------------------------------------------------@@ -1104,234 +1138,92 @@ async def get_dead_code(# ----------------------------------------------------------------------------# Tool 14: get_decisions+# Tool 8: get_architecture_diagram (unchanged)# ---------------------------------------------------------------------------@mcp.tool()-async def get_decisions(- module: str | None = None,- tag: str | None = None,- include_proposed: bool = False,- include_stale: bool = True,+async def get_architecture_diagram(+ scope: str = "repo",+ path: str | None = None,+ diagram_type: str = "auto",repo: str | None = None,) -> dict:- """Get architectural decision records for the codebase.-- Use this before making architectural changes to understand existing- constraints and why things are built the way they are.+ """Get a Mermaid diagram for the codebase or a specific module.Args:- module: Filter by module path (e.g. "src/auth", "packages/core").- tag: Filter by tag: auth, database, api, performance, security, infra, testing.- include_proposed: Include unconfirmed proposed decisions (default false).- include_stale: Include decisions with high staleness scores (default true).+ scope: "repo", "module", or "file".+ path: Module or file path (required for module/file scope).+ diagram_type: "auto", "flowchart", "class", or "sequence".repo: Repository path, name, or ID."""- from wikicode.core.persistence.crud import list_decisions as _list_decisions-async with get_session(_session_factory) as session:repository = await _get_repo(session, repo)- statuses = ["active"]- if include_proposed:- statuses.append("proposed")-- decisions = await _list_decisions(- session,- repository.id,- tag=tag,- module=module,- include_proposed=include_proposed,- limit=50,- )-- # Filter stale if requested- if not include_stale:- decisions = [d for d in decisions if d.staleness_score < 0.5]-- # Filter to requested statuses- decisions = [d for d in decisions if d.status in statuses]-- return {- "decisions": [- {- "id": d.id,- "title": d.title,- "status": d.status,- "context": d.context,- "decision": d.decision,- "rationale": d.rationale,- "alternatives": json.loads(d.alternatives_json),- "consequences": json.loads(d.consequences_json),- "affected_files": json.loads(d.affected_files_json),- "affected_modules": json.loads(d.affected_modules_json),- "tags": json.loads(d.tags_json),- "source": d.source,- "confidence": d.confidence,- "staleness_score": d.staleness_score,- }- for d in decisions- ],- "total": len(decisions),- }---# ----------------------------------------------------------------------------# Tool 15: get_why-# ------------------------------------------------------------------------------async def get_why(query: str, repo: str | None = None) -> dict:- """Answer 'why is X implemented this way?' using decision records and docs.-- Use this before modifying significant code to understand architectural intent- and prevent re-introducing previously solved problems.-- Args:- query: Natural language question (e.g. "why is auth using JWT?").- repo: Repository path, name, or ID.- """- from wikicode.core.persistence.crud import list_decisions as _list_decisions+ if scope == "repo":+ # Return the architecture diagram page+ result = await session.execute(+ select(Page).where(+ Page.repository_id == repository.id,+ Page.page_type == "architecture_diagram",+ )+ )+ page = result.scalar_one_or_none()+ if page:+ return {+ "diagram_type": diagram_type if diagram_type != "auto" else "flowchart",+ "mermaid_syntax": page.content,+ "description": page.title,+ }- async with get_session(_session_factory) as session:- repository = await _get_repo(session, repo)+ # For module/file scope or fallback, build diagram from graph+ if path:+ filter_prefix = path+ else:+ filter_prefix = ""- # Keyword match on decision title and body (include proposed —- # auto-extracted decisions start as "proposed" and would otherwise- # be invisible to this tool)- all_decisions = await _list_decisions(- session, repository.id, include_proposed=True, limit=200+ result = await session.execute(+ select(GraphNode).where(+ GraphNode.repository_id == repository.id,+ GraphNode.node_id.like(f"{filter_prefix}%") if filter_prefix else GraphNode.repository_id == repository.id,+ ))+ nodes = result.scalars().all()- # Score decisions by keyword relevance- query_lower = query.lower()- query_words = set(query_lower.split())- scored_decisions = []- for d in all_decisions:- text = f"{d.title} {d.decision} {d.rationale}".lower()- match_count = sum(1 for w in query_words if w in text)- if match_count > 0:- scored_decisions.append((match_count, d))- scored_decisions.sort(key=lambda t: t[0], reverse=True)- keyword_matches = [d for _, d in scored_decisions[:5]]-- # Semantic search over decision vector store- decision_results = []- try:- decision_results = await _decision_store.search(query, limit=5)- except Exception:- pass-- # Semantic search over documentation- doc_results = []- try:- doc_results = await _vector_store.search(query, limit=3)- except Exception:- try:- doc_results = await _fts.search(query, limit=3)- except Exception:- pass-- # Merge keyword matches with semantic results (dedup by ID)- seen_ids: set[str] = set()- merged_decisions = []- for d in keyword_matches:- if d.id not in seen_ids:- seen_ids.add(d.id)- merged_decisions.append({- "id": d.id,- "title": d.title,- "status": d.status,- "decision": d.decision,- "rationale": d.rationale,- "consequences": json.loads(d.consequences_json),- "affected_files": json.loads(d.affected_files_json),- "source": d.source,- "confidence": d.confidence,- })-- # Add semantic decision results (from vector store — these are SearchResult objects)- for r in decision_results:- if r.page_id not in seen_ids:- seen_ids.add(r.page_id)- merged_decisions.append({- "id": r.page_id,- "title": r.title,- "snippet": r.snippet,- "relevance_score": r.score,- })-- return {- "query": query,- "decisions": merged_decisions[:8],- "related_documentation": [- {- "page_id": r.page_id,- "title": r.title,- "page_type": r.page_type,- "snippet": r.snippet,- "relevance_score": r.score,- }- for r in doc_results[:3]- ],- }---# ----------------------------------------------------------------------------# Tool 16: get_decision_health-# ------------------------------------------------------------------------------async def get_decision_health(repo: str | None = None) -> dict:- """Get the health status of architectural decision records.-- Returns stale decisions, ungoverned hotspots (high-churn files with no- decisions), and proposed decisions awaiting confirmation.+ result = await session.execute(+ select(GraphEdge).where(+ GraphEdge.repository_id == repository.id,+ )+ )+ edges = result.scalars().all()- Args:- repo: Repository path, name, or ID.- """- from wikicode.core.persistence.crud import get_decision_health_summary+ node_ids = {n.node_id for n in nodes}+ relevant_edges = [+ e for e in edges+ if e.source_node_id in node_ids or e.target_node_id in node_ids+ ]- async with get_session(_session_factory) as session:- repository = await _get_repo(session, repo)- health = await get_decision_health_summary(session, repository.id)+ # Build Mermaid flowchart+ lines = ["graph TD"]+ seen_nodes = set()+ for e in relevant_edges[:50]: # Limit to 50 edges for readability+ src = e.source_node_id.replace("/", "_").replace(".", "_").replace("-", "_")+ tgt = e.target_node_id.replace("/", "_").replace(".", "_").replace("-", "_")+ if src not in seen_nodes:+ lines.append(f' {src}["{e.source_node_id}"]')+ seen_nodes.add(src)+ if tgt not in seen_nodes:+ lines.append(f' {tgt}["{e.target_node_id}"]')+ seen_nodes.add(tgt)+ lines.append(f" {src} --> {tgt}")- stale = health["stale_decisions"]- proposed = health["proposed_awaiting_review"]- ungoverned = health["ungoverned_hotspots"]+ mermaid = "\n".join(lines) if len(lines) > 1 else "graph TD\n A[No graph data available]"- return {- "summary": (- f"{health['summary'].get('active', 0)} active · "- f"{health['summary'].get('stale', 0)} stale · "- f"{len(proposed)} proposed · "- f"{len(ungoverned)} ungoverned hotspots"- ),- "counts": health["summary"],- "stale_decisions": [- {- "id": d.id,- "title": d.title,- "staleness_score": d.staleness_score,- "affected_files": json.loads(d.affected_files_json)[:5],- }- for d in stale[:10]- ],- "proposed_awaiting_review": [- {- "id": d.id,- "title": d.title,- "source": d.source,- "confidence": d.confidence,- }- for d in proposed[:10]- ],- "ungoverned_hotspots": ungoverned[:15],- }+ return {+ "diagram_type": diagram_type if diagram_type != "auto" else "flowchart",+ "mermaid_syntax": mermaid,+ "description": f"Dependency graph for {scope}: {path or 'entire repo'}",+ }# ---------------------------------------------------------------------------diff --git a/tests/integration/test_mcp.py b/tests/integration/test_mcp.pyindex 93241100f..4715f4f35 100644--- a/tests/integration/test_mcp.py+++ b/tests/integration/test_mcp.py@@ -45,6 +45,7 @@ async def mcp_env():await fts.ensure_index()embedder = MockEmbedder()vector_store = InMemoryVectorStore(embedder=embedder)+ decision_store = InMemoryVectorStore(embedder=embedder)# Populate DB with a realistic multi-file Python projectasync with factory() as session:@@ -192,6 +193,7 @@ async def mcp_env():mcp_mod._session_factory = factorymcp_mod._fts = ftsmcp_mod._vector_store = vector_store+ mcp_mod._decision_store = decision_storemcp_mod._repo_path = "/tmp/sample-project"yield@@ -199,8 +201,10 @@ async def mcp_env():mcp_mod._session_factory = Nonemcp_mod._fts = Nonemcp_mod._vector_store = None+ mcp_mod._decision_store = Nonemcp_mod._repo_path = None+ await decision_store.close()await vector_store.close()await engine.dispose()@@ -212,13 +216,8 @@ async def mcp_env():@pytest.mark.asyncioasync def test_mcp_full_exploration_flow(mcp_env):- """Test the typical MCP exploration flow: overview → module → file → symbol."""- from wikicode.server.mcp_server import (- get_file_docs,- get_module_docs,- get_overview,- get_symbol,- )+ """Test the typical MCP exploration flow: overview → get_context for module/file/symbol."""+ from wikicode.server.mcp_server import get_context, get_overview# Step 1: Get overviewoverview = await get_overview()@@ -226,20 +225,26 @@ async def test_mcp_full_exploration_flow(mcp_env):assert len(overview["key_modules"]) == 2assert overview["architecture_diagram_mermaid"] is not None- # Step 2: Drill into auth module- auth_module = await get_module_docs("src/auth")- assert "authentication" in auth_module["content_md"].lower()- assert len(auth_module["files"]) == 2+ # Step 2: Drill into auth module via get_context+ auth = await get_context(["src/auth"])+ t = auth["targets"]["src/auth"]+ assert t["type"] == "module"+ assert "authentication" in t["docs"]["content_md"].lower()+ assert len(t["docs"]["files"]) == 2- # Step 3: Get file docs- login_file = await get_file_docs("src/auth/login.py")- assert login_file["title"] == "Login Handler"- assert any(s["name"] == "login_handler" for s in login_file["symbols"])+ # Step 3: Get file context+ login = await get_context(["src/auth/login.py"])+ t = login["targets"]["src/auth/login.py"]+ assert t["type"] == "file"+ assert t["docs"]["title"] == "Login Handler"+ assert any(s["name"] == "login_handler" for s in t["docs"]["symbols"])# Step 4: Look up a symbol- symbol = await get_symbol("UserRepository")- assert symbol["kind"] == "class"- assert symbol["file_path"] == "src/data/user_repo.py"+ sym = await get_context(["UserRepository"])+ t = sym["targets"]["UserRepository"]+ assert t["type"] == "symbol"+ assert t["docs"]["kind"] == "class"+ assert t["docs"]["file_path"] == "src/data/user_repo.py"@pytest.mark.asyncio@@ -262,47 +267,40 @@ async def test_mcp_dependency_and_graph_flow(mcp_env):@pytest.mark.asyncioasync def test_mcp_git_intelligence_flow(mcp_env):- """Test git intelligence tools: history, hotspots, ownership, co-changes."""- from wikicode.server.mcp_server import (- get_codebase_ownership,- get_co_changes,- get_file_history,- get_hotspots,- )-- # File history- history = await get_file_history("src/auth/login.py")- assert history["is_hotspot"] is True- assert history["primary_owner"]["name"] == "Alice"- assert len(history["co_change_partners"]) == 1-- # Hotspots- hotspots = await get_hotspots()- assert len(hotspots["hotspots"]) == 1+ """Test git intelligence via get_context and get_risk."""+ from wikicode.server.mcp_server import get_context, get_risk- # Ownership- ownership = await get_codebase_ownership()- assert len(ownership["by_module"]) >= 1+ # File context with ownership and history+ ctx = await get_context(["src/auth/login.py"], include=["ownership", "last_change"])+ t = ctx["targets"]["src/auth/login.py"]+ assert t["ownership"]["primary_owner"] == "Alice"+ assert t["ownership"]["owner_pct"] == 0.70+ assert t["last_change"]["days_ago"] == 443- # Co-changes- co = await get_co_changes("src/auth/login.py", min_count=3)- assert len(co["co_change_partners"]) == 1- assert co["co_change_partners"][0]["file_path"] == "src/auth/jwt.py"+ # Risk assessment+ risk = await get_risk(["src/auth/login.py"])+ t = risk["targets"]["src/auth/login.py"]+ assert t["hotspot_score"] == 0.95+ assert len(t["co_change_partners"]) == 1+ assert t["co_change_partners"][0]["file_path"] == "src/auth/jwt.py"+ assert "global_hotspots" in risk@pytest.mark.asyncio-async def test_mcp_dead_code_and_stale_flow(mcp_env):- """Test dead code and stale pages tools."""- from wikicode.server.mcp_server import get_dead_code, get_stale_pages+async def test_mcp_dead_code_and_freshness_flow(mcp_env):+ """Test dead code tool and freshness via get_context."""+ from wikicode.server.mcp_server import get_context, get_dead_code# Dead codedead = await get_dead_code()assert dead["summary"]["total_findings"] == 1assert dead["findings"][0]["symbol_name"] == "deprecated_verify"- # Stale pages (all have confidence 0.9, so threshold 0.95 catches them)- stale = await get_stale_pages(threshold=0.95)- assert len(stale["stale_pages"]) >= 1+ # Freshness via get_context (all pages have confidence 0.9)+ ctx = await get_context(["src/auth/login.py"], include=["freshness"])+ t = ctx["targets"]["src/auth/login.py"]+ assert t["freshness"]["confidence_score"] == 0.9+ assert t["freshness"]["is_stale"] is False@pytest.mark.asynciodiff --git a/tests/unit/server/test_mcp.py b/tests/unit/server/test_mcp.pyindex 006fd7074..5e63e090f 100644--- a/tests/unit/server/test_mcp.py+++ b/tests/unit/server/test_mcp.py@@ -1,6 +1,6 @@"""Unit tests for WikiCode MCP server tools.-Tests all 16 MCP tools using an in-memory SQLite database with pre-populated+Tests all 8 MCP tools using an in-memory SQLite database with pre-populatedtest data, mirroring the conftest pattern from the REST API tests."""@@ -18,6 +18,7 @@ from wikicode.core.persistence.database import init_dbfrom wikicode.core.persistence.embedder import MockEmbedderfrom wikicode.core.persistence.models import (DeadCodeFinding,+ DecisionRecord,GitMetadata,GraphEdge,GraphNode,@@ -473,6 +474,50 @@ async def populated_db(session: AsyncSession, repo_id: str) -> str:for f in findings:session.add(f)+ # ---- Decision Records ----+ decisions = [+ DecisionRecord(+ id="dec1",+ repository_id=rid,+ title="Use JWT for authentication",+ status="proposed",+ context="Need stateless auth for microservices",+ decision="Use JWT tokens for all API authentication",+ rationale="Stateless, scalable, works across services",+ alternatives_json=json.dumps(["Session-based auth", "OAuth2 only"]),+ consequences_json=json.dumps(["Must handle token refresh", "Token size overhead"]),+ affected_files_json=json.dumps(["src/auth/service.py", "src/auth/middleware.py"]),+ affected_modules_json=json.dumps(["src/auth"]),+ tags_json=json.dumps(["auth", "security"]),+ source="readme_mining",+ confidence=0.6,+ staleness_score=0.1,+ created_at=_NOW,+ updated_at=_NOW,+ ),+ DecisionRecord(+ id="dec2",+ repository_id=rid,+ title="SQLAlchemy as ORM",+ status="proposed",+ context="Need an async-compatible ORM for Python",+ decision="Use SQLAlchemy 2.0 with async support",+ rationale="Mature, well-documented, async support in 2.0",+ alternatives_json=json.dumps(["Tortoise ORM", "Django ORM"]),+ consequences_json=json.dumps(["Learning curve for async patterns"]),+ affected_files_json=json.dumps(["src/db/models.py"]),+ affected_modules_json=json.dumps(["src/db"]),+ tags_json=json.dumps(["database"]),+ source="git_archaeology",+ confidence=0.7,+ staleness_score=0.0,+ created_at=_NOW,+ updated_at=_NOW,+ ),+ ]+ for d in decisions:+ session.add(d)+await session.flush()return rid@@ -490,6 +535,7 @@ async def setup_mcp(factory, fts, vector_store, populated_db):mcp_mod._session_factory = factorymcp_mod._fts = ftsmcp_mod._vector_store = vector_store+ mcp_mod._decision_store = InMemoryVectorStore(embedder=MockEmbedder())mcp_mod._repo_path = "/tmp/test-repo"yield populated_db@@ -498,6 +544,7 @@ async def setup_mcp(factory, fts, vector_store, populated_db):mcp_mod._session_factory = Nonemcp_mod._fts = Nonemcp_mod._vector_store = None+ mcp_mod._decision_store = Nonemcp_mod._repo_path = None@@ -534,92 +581,201 @@ async def test_get_overview_repo_not_found(setup_mcp):await get_overview(repo="/nonexistent")-# ---- Tool 2: get_module_docs ----+# ---- Tool 2: get_context ----@pytest.mark.asyncio-async def test_get_module_docs(setup_mcp):- from wikicode.server.mcp_server import get_module_docs+async def test_get_context_single_file(setup_mcp):+ from wikicode.server.mcp_server import get_context- result = await get_module_docs("src/auth")- assert result["title"] == "Auth Module"- assert "authentication" in result["content_md"].lower()- assert len(result["files"]) == 2 # service.py and middleware.py- assert result["public_api_summary"]+ result = await get_context(["src/auth/service.py"])+ targets = result["targets"]+ assert "src/auth/service.py" in targets+ t = targets["src/auth/service.py"]+ assert t["type"] == "file"+ # Docs+ assert t["docs"]["title"] == "Auth Service"+ assert "AuthService" in t["docs"]["content_md"]+ assert len(t["docs"]["symbols"]) == 2+ assert any(s["name"] == "AuthService" for s in t["docs"]["symbols"])+ assert "src/auth/middleware.py" in t["docs"]["imported_by"]+ # Ownership+ assert t["ownership"]["primary_owner"] == "Alice"+ assert t["ownership"]["owner_pct"] == 0.65+ assert t["ownership"]["contributor_count"] == 2+ # Last change+ assert t["last_change"]["author"] == "Alice"+ assert t["last_change"]["days_ago"] == 443+ # Decisions+ assert len(t["decisions"]) >= 1+ assert any(d["title"] == "Use JWT for authentication" for d in t["decisions"])+ # Freshness+ assert t["freshness"]["confidence_score"] == 0.85+ assert t["freshness"]["freshness_status"] == "fresh"+ assert t["freshness"]["is_stale"] is False@pytest.mark.asyncio-async def test_get_module_docs_not_found(setup_mcp):- from wikicode.server.mcp_server import get_module_docs+async def test_get_context_single_module(setup_mcp):+ from wikicode.server.mcp_server import get_context- result = await get_module_docs("src/nonexistent")- assert "error" in result+ result = await get_context(["src/auth"])+ targets = result["targets"]+ assert "src/auth" in targets+ t = targets["src/auth"]+ assert t["type"] == "module"+ assert t["docs"]["title"] == "Auth Module"+ assert "authentication" in t["docs"]["content_md"].lower()+ assert len(t["docs"]["files"]) == 2 # service.py and middleware.py+ # Freshness from module page+ assert t["freshness"]["confidence_score"] == 0.95-# ---- Tool 3: get_file_docs ----+async def test_get_context_single_symbol(setup_mcp):+ from wikicode.server.mcp_server import get_context++ result = await get_context(["AuthService"])+ targets = result["targets"]+ assert "AuthService" in targets+ t = targets["AuthService"]+ assert t["type"] == "symbol"+ assert t["docs"]["name"] == "AuthService"+ assert t["docs"]["kind"] == "class"+ assert t["docs"]["signature"] == "class AuthService"+ assert t["docs"]["file_path"] == "src/auth/service.py"+ assert t["docs"]["documentation"] # Has content from file page@pytest.mark.asyncio-async def test_get_file_docs(setup_mcp):- from wikicode.server.mcp_server import get_file_docs+async def test_get_context_multiple_targets(setup_mcp):+ from wikicode.server.mcp_server import get_context- result = await get_file_docs("src/auth/service.py")- assert result["title"] == "Auth Service"- assert "AuthService" in result["content_md"]- assert len(result["symbols"]) == 2- assert any(s["name"] == "AuthService" for s in result["symbols"])- assert any(s["name"] == "login" for s in result["symbols"])- assert "src/auth/middleware.py" in result["imported_by"]- assert result["confidence_score"] == 0.85- assert result["freshness_status"] == "fresh"+ result = await get_context(["src/auth/service.py", "src/auth", "AuthService"])+ targets = result["targets"]+ assert len(targets) == 3+ assert targets["src/auth/service.py"]["type"] == "file"+ assert targets["src/auth"]["type"] == "module"+ assert targets["AuthService"]["type"] == "symbol"@pytest.mark.asyncio-async def test_get_file_docs_not_found(setup_mcp):- from wikicode.server.mcp_server import get_file_docs+async def test_get_context_include_filter(setup_mcp):+ from wikicode.server.mcp_server import get_context- result = await get_file_docs("src/nonexistent.py")- assert "error" in result+ result = await get_context(["src/auth/service.py"], include=["docs"])+ t = result["targets"]["src/auth/service.py"]+ assert "docs" in t+ assert "ownership" not in t+ assert "last_change" not in t+ assert "decisions" not in t+ assert "freshness" not in t+++async def test_get_context_not_found(setup_mcp):+ from wikicode.server.mcp_server import get_context+ result = await get_context(["nonexistent_thing_xyz"])+ t = result["targets"]["nonexistent_thing_xyz"]+ assert "error" in t-# ---- Tool 4: get_symbol ----++# ---- Tool 3: get_risk ----@pytest.mark.asyncio-async def test_get_symbol_exact_match(setup_mcp):- from wikicode.server.mcp_server import get_symbol+async def test_get_risk_single_target(setup_mcp):+ from wikicode.server.mcp_server import get_risk- result = await get_symbol("AuthService")- assert result["name"] == "AuthService"- assert result["kind"] == "class"- assert result["file_path"] == "src/auth/service.py"- assert result["signature"] == "class AuthService"- assert result["documentation"] # Has content from page+ result = await get_risk(["src/auth/service.py"])+ targets = result["targets"]+ assert "src/auth/service.py" in targets+ t = targets["src/auth/service.py"]+ assert t["hotspot_score"] == 0.92+ assert t["dependents_count"] >= 1 # middleware imports it+ assert len(t["co_change_partners"]) == 2+ assert t["primary_owner"] == "Alice"+ assert t["owner_pct"] == 0.65+ assert "risk_summary" in t+ assert "hotspot score" in t["risk_summary"]@pytest.mark.asyncio-async def test_get_symbol_fuzzy_match(setup_mcp):- from wikicode.server.mcp_server import get_symbol+async def test_get_risk_multiple_targets(setup_mcp):+ from wikicode.server.mcp_server import get_risk- result = await get_symbol("Auth") # Partial match- assert result["name"] == "AuthService"+ result = await get_risk(["src/auth/service.py", "src/db/models.py"])+ targets = result["targets"]+ assert len(targets) == 2+ assert "global_hotspots" in result@pytest.mark.asyncio-async def test_get_symbol_with_kind(setup_mcp):- from wikicode.server.mcp_server import get_symbol+async def test_get_risk_global_hotspots_exclude_targets(setup_mcp):+ from wikicode.server.mcp_server import get_risk- result = await get_symbol("login", kind="method")- assert result["name"] == "login"- assert result["kind"] == "method"+ result = await get_risk(["src/auth/service.py"])+ # service.py is a hotspot but should NOT appear in global_hotspots+ for h in result["global_hotspots"]:+ assert h["file_path"] != "src/auth/service.py"@pytest.mark.asyncio-async def test_get_symbol_not_found(setup_mcp):- from wikicode.server.mcp_server import get_symbol+async def test_get_risk_no_git_metadata(setup_mcp):+ from wikicode.server.mcp_server import get_risk++ result = await get_risk(["src/auth/middleware.py"])+ t = result["targets"]["src/auth/middleware.py"]+ assert t["hotspot_score"] == 0.0 # No git metadata for this file+ assert "risk_summary" in t- result = await get_symbol("NonExistentSymbol123")- assert "error" in result++# ---- Tool 4: get_why ----+++async def test_get_why_natural_language(setup_mcp):+ from wikicode.server.mcp_server import get_why++ result = await get_why("why is JWT used for authentication")+ assert result["mode"] == "search"+ assert result["query"] == "why is JWT used for authentication"+ assert len(result["decisions"]) >= 1+ assert any("JWT" in d["title"] for d in result["decisions"])+++async def test_get_why_file_path(setup_mcp):+ from wikicode.server.mcp_server import get_why++ result = await get_why("src/auth/service.py")+ assert result["mode"] == "path"+ assert result["path"] == "src/auth/service.py"+ assert len(result["decisions"]) >= 1+ assert any(d["title"] == "Use JWT for authentication" for d in result["decisions"])+++async def test_get_why_no_args(setup_mcp):+ from wikicode.server.mcp_server import get_why++ result = await get_why()+ assert result["mode"] == "health"+ assert "summary" in result+ assert "counts" in result+ assert "proposed_awaiting_review" in result+ assert "ungoverned_hotspots" in result+++async def test_get_why_module_path(setup_mcp):+ from wikicode.server.mcp_server import get_why++ result = await get_why("src/db")+ assert result["mode"] == "path"+ assert len(result["decisions"]) >= 1+ assert any(d["title"] == "SQLAlchemy as ORM" for d in result["decisions"])# ---- Tool 5: search_codebase ----@@ -709,133 +865,7 @@ async def test_get_dependency_path_node_not_found(setup_mcp):assert "error" in result-# ---- Tool 8: get_stale_pages -------async def test_get_stale_pages(setup_mcp):- from wikicode.server.mcp_server import get_stale_pages-- result = await get_stale_pages(threshold=0.6)- stale = result["stale_pages"]- assert len(stale) == 2 # middleware (0.50) and models (0.40)- # Should be sorted by confidence ASC- assert stale[0]["confidence_score"] <= stale[1]["confidence_score"]---async def test_get_stale_pages_high_threshold(setup_mcp):- from wikicode.server.mcp_server import get_stale_pages-- result = await get_stale_pages(threshold=0.9)- stale = result["stale_pages"]- assert len(stale) >= 3 # middleware, models, service all below 0.9---# ---- Tool 9: get_file_history -------async def test_get_file_history(setup_mcp):- from wikicode.server.mcp_server import get_file_history-- result = await get_file_history("src/auth/service.py")- assert result["file_path"] == "src/auth/service.py"- assert result["age_days"] == 443- assert result["primary_owner"]["name"] == "Alice"- assert result["primary_owner"]["pct"] == 0.65- assert result["is_hotspot"] is True- assert result["is_stable"] is False- assert result["commit_count_total"] == 42- assert result["commit_count_90d"] == 8- assert len(result["significant_commits"]) == 2- assert len(result["co_change_partners"]) == 2---async def test_get_file_history_not_found(setup_mcp):- from wikicode.server.mcp_server import get_file_history-- result = await get_file_history("nonexistent.py")- assert "error" in result---# ---- Tool 10: get_hotspots -------async def test_get_hotspots(setup_mcp):- from wikicode.server.mcp_server import get_hotspots-- result = await get_hotspots()- assert len(result["hotspots"]) == 1- assert result["hotspots"][0]["file_path"] == "src/auth/service.py"- assert result["hotspots"][0]["churn_percentile"] == 0.92- assert "stable_files" not in result---async def test_get_hotspots_include_stable(setup_mcp):- from wikicode.server.mcp_server import get_hotspots-- result = await get_hotspots(include_stable=True)- assert "stable_files" in result- assert len(result["stable_files"]) == 1- assert result["stable_files"][0]["file_path"] == "src/db/models.py"---# ---- Tool 11: get_codebase_ownership -------async def test_get_codebase_ownership_by_module(setup_mcp):- from wikicode.server.mcp_server import get_codebase_ownership-- result = await get_codebase_ownership(by="module")- assert "by_module" in result- modules = result["by_module"]- # Both files are under src/, so grouped as one module "src"- assert len(modules) == 1- assert modules[0]["module_path"] == "src"- assert modules[0]["contributor_count"] == 2---async def test_get_codebase_ownership_by_file(setup_mcp):- from wikicode.server.mcp_server import get_codebase_ownership-- result = await get_codebase_ownership(by="file")- assert "by_file" in result- assert len(result["by_file"]) == 2 # Only files with git metadata---# ---- Tool 12: get_co_changes -------async def test_get_co_changes(setup_mcp):- from wikicode.server.mcp_server import get_co_changes-- result = await get_co_changes("src/auth/service.py", min_count=3)- assert result["file_path"] == "src/auth/service.py"- partners = result["co_change_partners"]- assert len(partners) == 2- # Check enrichment- middleware_partner = next(p for p in partners if p["file_path"] == "src/auth/middleware.py")- assert middleware_partner["co_change_count"] == 5- assert middleware_partner["has_import_relationship"] is True # edge exists- assert middleware_partner["wiki_page_snippet"] is not None---async def test_get_co_changes_not_found(setup_mcp):- from wikicode.server.mcp_server import get_co_changes-- result = await get_co_changes("nonexistent.py")- assert "error" in result---# ---- Tool 13: get_dead_code ----+# ---- Tool 8: get_dead_code ----@pytest.mark.asyncio