Skip to content

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

Consolidate MCP server from 16 to 8 tools, fix search, add reindex command

RaghavChamadiya7c35e972e8e9
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 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 like
If you delete the vector store (LanceDB directory or pgvector embeddings), search
quality 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 Config
diff --git a/docs/MCP_AND_STATE_REVIEW.md b/docs/MCP_AND_STATE_REVIEW.md
index 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.py
index 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.py
new file mode 100644
index 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]("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.py
index 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_command
from wikicode.cli.commands.export_cmd import export_command
from wikicode.cli.commands.init_cmd import init_command
from wikicode.cli.commands.mcp_cmd import mcp_command
+from wikicode.cli.commands.reindex_cmd import reindex_command
from wikicode.cli.commands.search_cmd import search_command
from wikicode.cli.commands.serve_cmd import serve_command
from 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.py
index 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.md
index 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:
```bash
wikicode 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.py
index 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 asyncio
import json
import os
+import os.path
from contextlib import asynccontextmanager
from 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) -> Repositor
return 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:
+ pass
output = []
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.py
index 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 project
async with factory() as session:
@@ -192,6 +193,7 @@ async def mcp_env():
mcp_mod._session_factory = factory
mcp_mod._fts = fts
mcp_mod._vector_store = vector_store
+ mcp_mod._decision_store = decision_store
mcp_mod._repo_path = "/tmp/sample-project"
yield
@@ -199,8 +201,10 @@ async def mcp_env():
mcp_mod._session_factory = None
mcp_mod._fts = None
mcp_mod._vector_store = None
+ mcp_mod._decision_store = None
mcp_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.asyncio
async 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 overview
overview = await get_overview()
@@ -226,20 +225,26 @@ async def test_mcp_full_exploration_flow(mcp_env):
assert len(overview["key_modules"]) == 2
assert 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.asyncio
async 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 code
dead = await get_dead_code()
assert dead["summary"]["total_findings"] == 1
assert 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.asyncio
diff --git a/tests/unit/server/test_mcp.py b/tests/unit/server/test_mcp.py
index 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-populated
test data, mirroring the conftest pattern from the REST API tests.
"""
@@ -18,6 +18,7 @@ from wikicode.core.persistence.database import init_db
from wikicode.core.persistence.embedder import MockEmbedder
from 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 = factory
mcp_mod._fts = fts
mcp_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 = None
mcp_mod._fts = None
mcp_mod._vector_store = None
+ mcp_mod._decision_store = None
mcp_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