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.

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.md
index 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.py
index 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_id
try:
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 = None
Args:
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 mode
ws_footer = _build_workspace_footer()
diff --git a/tests/unit/server/mcp/test_overview.py b/tests/unit/server/mcp/test_overview.py
index 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.py
index 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 annotations
from 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.py
index 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 kd
reversals = 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) <= 5
diff --git a/tests/unit/server/test_mcp_kg_enrichment.py b/tests/unit/server/test_mcp_kg_enrichment.py
index 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_overview
result = 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"}
# ---------------------------------------------------------------------------