Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(mcp): make get_overview's onboarding blocks opt-in (#1868)
Raghav Chamadiya78036e1d538f
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.mdindex 2e80a98dc..3111e8f6a 100644--- a/docs/agent/MCP_TOOLS.md+++ b/docs/agent/MCP_TOOLS.md@@ -187,16 +187,27 @@ well as a float. `get_health` reports the same thing under its own older name,## `get_overview`-Architecture summary, module map, entry points, git health, and community summary.+Architecture summary, module map, and entry points.**Parameters:**| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| `repo` | string | No | *(workspace only)* Target repo alias, or `"all"` |-| `include` | list[string] | No | `"content"` returns the full overview essay in `content_md` instead of the compact summary section |+| `include` | list[string] | No | Opt-in blocks, any combination of `"content"`, `"outline"`, `"tour"`, `"decisions"`, `"graph"`, `"ownership"` (see below) |-**Returns:** Architecture description, key modules with purpose and owner, entry points, tech stack, hotspot files, knowledge silos, community summary (top communities by size with labels and cohesion scores). `content_md` is compact by default (summary + tech stack + layers); pass `include=["content"]` for the full essay.+**Returns (default):** `title`, `content_md` (the overview essay's summary section), `key_modules` (name, path, outline section), `entry_points`, `architecture` (layer names, file counts, layer order), `code_health`, `git_health`, `_meta`, and in workspace mode a `workspace` footer. The response's `more` field names the opt-in blocks.++**Opt-in blocks** — omitted unless named in `include`, and not computed at all when they are not:++| `include` key | Adds |+|---|---|+| `"content"` | the full overview essay in `content_md` |+| `"outline"` | `outline` — the stored wiki page tree, two rungs deep. `key_modules[].section` indexes into it |+| `"tour"` | `guided_tour` and `reading_order` — onboarding walks |+| `"decisions"` | `key_decisions`. `get_why` is the richer route |+| `"graph"` | `community_summary` — code-community clusters |+| `"ownership"` | `knowledge_map` — top owners and knowledge silos |**When to use:** First call on any unfamiliar codebase. Gives the agent a mental map before diving into specifics. Skip on later calls in the same session; it doesn't change mid-session.@@ -204,9 +215,15 @@ Architecture summary, module map, entry points, git health, and community summar```get_overview()-get_overview(include=["content"])+get_overview(include=["outline", "content"])```+> **Output-schema change.** `guided_tour`, `reading_order`, `key_decisions`,+> `community_summary` and `knowledge_map` moved behind `include`; `outline` did+> too (`include=["outline"]` previously only deepened an always-present tree).+> `key_modules` no longer carries `description`, `page_id` or `parent_page_id`,+> and `architecture.layers[].description` is gone.+---## `get_answer`diff --git a/packages/server/src/repowise/server/mcp_server/tool_overview.py b/packages/server/src/repowise/server/mcp_server/tool_overview.pyindex 472f7407e..caf923888 100644--- a/packages/server/src/repowise/server/mcp_server/tool_overview.py+++ b/packages/server/src/repowise/server/mcp_server/tool_overview.py@@ -62,9 +62,6 @@ from repowise.server.mcp_server._helpers import ()from repowise.server.mcp_server._meta import build_meta as _build_meta-# Leading markdown-header boilerplate on module page content ("## Overview").-_MD_HEADER_RE = re.compile(r"^\s*#{1,6}\s+.*$", re.MULTILINE)-# Orientation, not a directory listing — the top few modules are enough to# point a fresh agent at the interesting subsystems. The rest are persisted# to the omission store, not dropped.@@ -87,24 +84,6 @@ def _compact_overview_content(content: str) -> str:return _H2_SPLIT_RE.split(text, maxsplit=1)[0].strip()-def _truncate_at_word(text: str, limit: int) -> str:- """Truncate at a word boundary with an ellipsis — never mid-word.-- Hard slices ("request/response ha") read as rendering bugs to the- caller; same budget, honest cut.- """- text = text.strip()- if len(text) <= limit:- return text- return text[:limit].rsplit(" ", 1)[0].rstrip(".,;:") + "…"---def _module_description(content: str, limit: int = 200) -> str:- """First prose of a module page, minus the "## Overview" boilerplate."""- prose = _MD_HEADER_RE.sub("", content or "").strip()- return _truncate_at_word(prose, limit)--# ---------------------------------------------------------------------------# repo="all" — workspace-level summary# ---------------------------------------------------------------------------@@ -524,10 +503,10 @@ async def _build_architecture(session: Any, repository: Any) -> dict[str, Any]:if not kg_layers:return {}return {+ # Names and sizes only: the layer prose restates the overview essay."layers": [{"name": layer.name,- "description": _truncate_at_word(layer.description or "", 120),"file_count": len(json.loads(layer.node_ids_json) if layer.node_ids_json else []),}for layer in kg_layers@@ -858,16 +837,19 @@ def _dedupe_tour_steps(tour: list[dict[str, Any]]) -> list[dict[str, Any]]:def _build_guided_tour(- overview_page: Page, result: dict[str, Any], sections: dict[str, str | None]+ overview_page: Page,+ result: dict[str, Any],+ sections: dict[str, str | None],+ want_tour: bool,) -> None:- """Attach the topology-driven guided tour + layer order from overview page metadata."""+ """Attach the layer order always; the tour steps only behind include=["tour"]."""from repowise.core.generation.models import compute_page_idtry:ov_meta = json.loads(overview_page.metadata_json or "{}")except (json.JSONDecodeError, TypeError):ov_meta = {}- tour = _dedupe_tour_steps(ov_meta.get("guided_tour") or [])+ tour = _dedupe_tour_steps(ov_meta.get("guided_tour") or []) if want_tour else []if tour:steps = []for s in tour:@@ -901,16 +883,15 @@ def _build_guided_tour(async def get_overview(repo: str | None = None, include: list[str] | None = None) -> dict:"""Architecture map for an unfamiliar repo — first call when you don't know your way around.- Returns the synthesised overview plus the wiki outline (the stored page- tree, top rung), key modules, entry points, repo-wide git health (hotspot- count, churn trend, bus-factor distribution), the knowledge map (top- owners, knowledge silos), and the community summary.+ Returns the synthesised overview summary, key modules, entry points,+ architecture layers, code health, and repo-wide git health (hotspot count,+ churn trend, bus-factor distribution).Skip this on subsequent calls — once you have the map, jump straight to``get_context`` / ``get_answer``.Compact by default: ``content_md`` carries only the overview essay's summary- section — the rest of the essay repeats ``key_modules`` / ``entry_points`` /- ``architecture.layers``. Pass ``include=["content"]`` for the full essay.+ section, and the outline, onboarding, ownership and graph blocks ship only+ on request. The response's ``more`` field names them.In workspace mode:- Omit ``repo`` for the default repo's overview plus a workspace footer.@@ -920,9 +901,13 @@ async def get_overview(repo: str | None = None, include: list[str] | None = NoneArgs:repo: Repository alias, path, or ID. Use ``"all"`` for workspace overview.- include: Opt-in extras. ``"content"`` returns the full overview essay in- ``content_md`` instead of the compact summary section. ``"outline"``- expands the page tree one rung deeper (modules under their layer).+ include: Opt-in extras, any combination of:+ ``"content"`` — the full overview essay instead of its summary.+ ``"outline"`` — the stored wiki page tree, two rungs deep.+ ``"tour"`` — ``guided_tour`` + ``reading_order`` onboarding walks.+ ``"decisions"`` — ``key_decisions``; ``get_why`` is richer.+ ``"graph"`` — ``community_summary``, code-community clusters.+ ``"ownership"`` — ``knowledge_map``: top owners, knowledge silos."""if repo == "all":return await _workspace_overview()@@ -947,44 +932,64 @@ async def get_overview(repo: str | None = None, include: list[str] | None = None)all_git = filter_rows_by_attr(list(git_res.scalars().all()), "file_path", exclude_spec)+ want = set(include or [])+ want_full_content = "content" in want+git_health = _build_git_health(all_git)- knowledge_map = _build_knowledge_map(all_git)- all_nodes = await _load_community_nodes(session, repository, exclude_spec, all_git)- community_summary = _build_community_summary(all_nodes)architecture = await _build_architecture(session, repository)- reading_order = await _build_reading_order(session, repository)- tree_rows = await _load_tree_rows(session, repository)- sections = {r.id: r.section_number for r in tree_rows}- outline = _build_outline(tree_rows, 2 if "outline" in set(include or []) else 1, collector)title = _resolve_title(overview_page, repository)code_health = await _build_code_health(session, repository)- key_decisions_section = await _build_key_decisions(session, repository, exclude_spec)++ # Gated blocks: not built at all unless asked for.+ knowledge_map = _build_knowledge_map(all_git) if "ownership" in want else {}+ community_summary: list[dict[str, Any]] = []+ if "graph" in want:+ all_nodes = await _load_community_nodes(session, repository, exclude_spec, all_git)+ community_summary = _build_community_summary(all_nodes)+ reading_order = await _build_reading_order(session, repository) if "tour" in want else []+ key_decisions_section = (+ await _build_key_decisions(session, repository, exclude_spec)+ if "decisions" in want+ else []+ )++ # The tree backs the outline and the tour's section labels.+ sections: dict[str, str | None] = {}+ outline: dict[str, Any] = {}+ if want & {"outline", "tour"}:+ tree_rows = await _load_tree_rows(session, repository)+ sections = {r.id: r.section_number for r in tree_rows}+ if "outline" in want:+ outline = _build_outline(tree_rows, 2, collector)full_content = overview_page.content if overview_page else "No overview generated yet."- want_full_content = "content" in set(include or [])content_md = full_content if want_full_content else _compact_overview_content(full_content)result = {"title": title,"content_md": content_md,"code_health": code_health,+ # Names and paths only. get_context(path) carries the prose, and+ # section indexes into include=["outline"]."key_modules": [- {- "name": p.title,- "path": p.target_path,- "description": _module_description(p.content),- "page_id": p.id,- "section": p.section_number,- "parent_page_id": p.parent_page_id,- }+ {"name": p.title, "path": p.target_path, "section": p.section_number}for p in module_pages],"entry_points": _capped_entry_points(entry_point_ids, collector),"git_health": git_health,- "knowledge_map": knowledge_map,- "community_summary": community_summary,+ "more": (+ 'get_overview(include=[...]) also serves: "outline" (the wiki '+ 'page tree), "tour" (guided_tour + reading_order), "decisions", '+ '"graph" (code communities), "ownership" (top owners, silos), '+ '"content" (the full essay).'+ ),}+ if knowledge_map:+ result["knowledge_map"] = knowledge_map+ if community_summary:+ result["community_summary"] = community_summary+if not want_full_content and content_md != full_content:result["content_hint"] = ("Overview essay trimmed to its summary section. "@@ -997,9 +1002,8 @@ async def get_overview(repo: str | None = None, include: list[str] | None = None"The stored page tree — the same outline the web app and the ""editor extension render. Every 'section' in this response ""indexes into it, and 'descendants' is how much sits below an "- "entry. Top rung only by default; call "- 'get_overview(include=["outline"]) for one level deeper, then '- "get_context on an entry's target_path to read it."+ "entry. Two rungs deep; get_context on an entry's target_path "+ "to read it.")if architecture:@@ -1020,7 +1024,7 @@ async def get_overview(repo: str | None = None, include: list[str] | None = None# from the import graph (entry points first, then inward, infra last).# Persisted on the repo_overview page metadata at generation time.if overview_page:- _build_guided_tour(overview_page, result, sections)+ _build_guided_tour(overview_page, result, sections, "tour" in want)# Append workspace context footer when in workspace modews_footer = _build_workspace_footer()diff --git a/tests/unit/server/mcp/test_overview.py b/tests/unit/server/mcp/test_overview.pyindex 900813a38..52f5454c2 100644--- a/tests/unit/server/mcp/test_overview.py+++ b/tests/unit/server/mcp/test_overview.py@@ -59,3 +59,44 @@ async def test_get_overview_repo_not_found(setup_mcp):with pytest.raises(LookupError, match="not found"):await get_overview(repo="/nonexistent")+++_GATED_KEYS = {+ "outline": "outline",+ "tour": "guided_tour",+ "decisions": "key_decisions",+ "graph": "community_summary",+ "ownership": "knowledge_map",+}+++async def test_default_overview_omits_every_gated_block(setup_mcp):+ from repowise.server.mcp_server import get_overview++ result = await get_overview()+ for key in (*_GATED_KEYS.values(), "reading_order", "outline_hint"):+ assert key not in result, f"{key} should be opt-in"+ assert "include=[" in result["more"]+++async def test_orientation_blocks_carry_no_prose(setup_mcp):+ from repowise.server.mcp_server import get_overview++ result = await get_overview()+ assert result["key_modules"]+ assert all("description" not in m for m in result["key_modules"])+ for layer in result.get("architecture", {}).get("layers", []):+ assert "description" not in layer+++ ("flag", "key"),+ [("tour", "reading_order"), ("graph", "community_summary"), ("ownership", "knowledge_map")],+)+async def test_include_flag_restores_its_block(setup_mcp, flag, key):+ from repowise.server.mcp_server import get_overview++ assert key in await get_overview(include=[flag])diff --git a/tests/unit/server/mcp/test_overview_helpers.py b/tests/unit/server/mcp/test_overview_helpers.pyindex eb2194b43..42d76d74d 100644--- a/tests/unit/server/mcp/test_overview_helpers.py+++ b/tests/unit/server/mcp/test_overview_helpers.py@@ -5,44 +5,9 @@ from __future__ import annotationsfrom repowise.server.mcp_server.tool_overview import (_compact_overview_content,_dedupe_tour_steps,- _module_description,- _truncate_at_word,)-class TestTruncateAtWord:- def test_short_unchanged(self):- assert _truncate_at_word("short", 120) == "short"-- def test_cuts_at_word_boundary_with_ellipsis(self):- text = (- "Implements the server-side application logic for MCP tooling, "- "including budget/risk/meta helpers and request/response handling"- )- out = _truncate_at_word(text, 120)- assert out.endswith("…")- # No mid-word fragment: every word emitted exists in the source.- for word in out.rstrip("…").split():- assert word in text---class TestModuleDescription:- def test_strips_overview_boilerplate(self):- content = "## Overview\n\nThe `core/distill` module is the distillation subsystem."- out = _module_description(content)- assert not out.startswith("##")- assert out.startswith("The `core/distill` module")-- def test_truncates_long_prose_at_word(self):- content = "## Overview\n\n" + ("word " * 100)- out = _module_description(content, limit=50)- assert len(out) <= 51- assert out.endswith("…")-- def test_empty_content(self):- assert _module_description("") == ""--class TestCompactOverviewContent:def test_keeps_only_first_section(self):content = (diff --git a/tests/unit/server/test_mcp_decision_graph.py b/tests/unit/server/test_mcp_decision_graph.pyindex 7629b7055..34c3bdef9 100644--- a/tests/unit/server/test_mcp_decision_graph.py+++ b/tests/unit/server/test_mcp_decision_graph.py@@ -630,7 +630,8 @@ async def test_get_overview_key_decisions_present(setup_mcp_decisions):"""get_overview returns key_decisions when active decisions exist."""from repowise.server.mcp_server import get_overview- result = await get_overview()+ assert "key_decisions" not in await get_overview(), "key_decisions is opt-in"+ result = await get_overview(include=["decisions"])assert "key_decisions" in result, "key_decisions should appear when active decisions exist"kd = result["key_decisions"]@@ -660,7 +661,7 @@ async def test_get_overview_key_decisions_sorted_by_confidence(setup_mcp_decisio"""top_active is sorted by confidence descending."""from repowise.server.mcp_server import get_overview- result = await get_overview()+ result = await get_overview(include=["decisions"])top = result["key_decisions"]["top_active"]if len(top) > 1:confidences = [e["confidence"] for e in top]@@ -675,7 +676,7 @@ async def test_get_overview_recent_reversals(setup_mcp_decisions):"""recent_reversals lists supersedes edges with src/dst titles."""from repowise.server.mcp_server import get_overview- result = await get_overview()+ result = await get_overview(include=["decisions"])kd = result["key_decisions"]assert "recent_reversals" in kdreversals = kd["recent_reversals"]@@ -704,6 +705,6 @@ async def test_get_overview_key_decisions_capped_at_five(setup_mcp_decisions):"""top_active is capped at 5 entries."""from repowise.server.mcp_server import get_overview- result = await get_overview()+ result = await get_overview(include=["decisions"])top = result["key_decisions"]["top_active"]assert len(top) <= 5diff --git a/tests/unit/server/test_mcp_kg_enrichment.py b/tests/unit/server/test_mcp_kg_enrichment.pyindex 3f9d5a8f3..0a448ea8e 100644--- a/tests/unit/server/test_mcp_kg_enrichment.py+++ b/tests/unit/server/test_mcp_kg_enrichment.py@@ -373,12 +373,16 @@ async def test_overview_layer_file_count(setup_mcp_with_kg):@pytest.mark.asyncio-async def test_overview_layer_description_truncated(setup_mcp_with_kg):+async def test_overview_layers_carry_names_and_counts_only(setup_mcp_with_kg):from repowise.server.mcp_server import get_overviewresult = await get_overview()- for layer in result["architecture"]["layers"]:- assert len(layer["description"]) <= 120+ layers = result["architecture"]["layers"]+ assert layers+ # The layer prose restated the overview essay; get_context on a layer file+ # is the route to it now.+ for layer in layers:+ assert set(layer) == {"name", "file_count"}# ---------------------------------------------------------------------------