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): get_context surfaces concept-tree position (#1056)

Raghav Chamadiya3cb8e0e6311e
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
index 11ca97141..cbff34ad0 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
@@ -349,6 +349,27 @@ async def _resolve_one_target(
result_data["hint"] = f"Content moved; call get_context on {successors[0]!r} instead."
return result_data
+ # --- Parent page (position in the concept tree) -----------------------
+ # Every placed page now carries parent_page_id, so a file target can point
+ # up to the subsystem/concept page that documents it, and a concept page
+ # up to its layer. One extra get() on the already-open session; the row is
+ # a full ORM object here, so parent_page_id is already loaded.
+ if page is not None and page.parent_page_id:
+ parent = await session.get(Page, page.parent_page_id)
+ if (
+ parent is not None
+ and parent.repository_id == repo_id
+ and getattr(parent, "freshness_status", "") != "tombstone"
+ ):
+ # Skip a tombstoned parent: pointing an agent up-tree at a page
+ # whose directory was deleted or renamed since indexing is the
+ # same trap the target's own tombstone redirect above avoids.
+ result_data["parent_page"] = {
+ "title": parent.title,
+ "target_path": parent.target_path,
+ "section": parent.section_number,
+ }
+
want_skeleton = bool(include and "skeleton" in include)
auto_skeleton = False
@@ -487,8 +508,39 @@ async def _resolve_one_target(
elif target_type == "module":
docs["title"] = page.title
docs["summary"] = page.summary or ""
+ if page.section_number:
+ docs["section"] = page.section_number
if want_full_doc:
docs["content_md"] = page.content
+ # Direct sub-concept children in the tree (nested subsystems, api
+ # contracts, symbol spotlights). File children are covered by the
+ # member "files" list below, so listing them here too would just
+ # double the response; this surfaces the tree's real sub-structure
+ # where it exists and is omitted when there is none.
+ res = await session.execute(
+ select(Page)
+ .where(
+ Page.repository_id == repo_id,
+ Page.parent_page_id == page.id,
+ Page.page_type != "file_page",
+ )
+ .order_by(Page.display_order, Page.target_path)
+ )
+ child_pages = res.scalars().all()
+ if child_pages:
+ docs["children"] = filter_dicts_by_key(
+ [
+ {
+ "title": ch.title,
+ "target_path": ch.target_path,
+ "page_type": ch.page_type,
+ "section": ch.section_number,
+ }
+ for ch in child_pages
+ ],
+ "target_path",
+ exclude_spec,
+ )
# Child file pages
res = await session.execute(
select(Page).where(
diff --git a/tests/unit/server/mcp/test_context.py b/tests/unit/server/mcp/test_context.py
index 4d2fc2d5c..77bdd32f9 100644
--- a/tests/unit/server/mcp/test_context.py
+++ b/tests/unit/server/mcp/test_context.py
@@ -586,3 +586,113 @@ async def test_high_fan_in_callers_signal_truncation(setup_mcp, session):
assert t["callers_total"] == n_callers # true total surfaced
assert t["callers_truncated"] is True
assert "grep" in t["_callers_note"]
+
+
+# --- Structural retrieval: parent page + concept-page tree position ---------
+
+
+async def _add_tree(session) -> None:
+ """Wire a layer -> concept -> file/sub-concept tree onto the populated db.
+
+ ``layer:core`` (§1) -> ``src/payments`` concept (§1.2) -> a file page (§1.2.1)
+ and a ``src/payments/providers`` sub-concept child (§1.2.3).
+ """
+ from repowise.core.persistence.models import Repository
+
+ rid = (
+ await session.execute(__import__("sqlalchemy").select(Repository))
+ ).scalars().first().id
+
+ def _page(pid, ptype, title, path, *, parent=None, section=None, order=0):
+ return Page(
+ id=pid,
+ repository_id=rid,
+ page_type=ptype,
+ title=title,
+ content=f"# {title}\n\nbody for {title}.",
+ summary=f"{title} summary.",
+ target_path=path,
+ source_hash=f"h-{pid}",
+ model_name="mock",
+ provider_name="mock",
+ generation_level=2,
+ confidence=0.9,
+ freshness_status="fresh",
+ metadata_json="{}",
+ parent_page_id=parent,
+ section_number=section,
+ display_order=order,
+ created_at=_NOW,
+ updated_at=_NOW,
+ )
+
+ session.add_all(
+ [
+ _page("layer_page:layer:core", "layer_page", "Layer: Core", "layer:core", section="1"),
+ _page(
+ "module_page:src/payments",
+ "module_page",
+ "Payments Module",
+ "src/payments",
+ parent="layer_page:layer:core",
+ section="1.2",
+ ),
+ _page(
+ "file_page:src/payments/charge.py",
+ "file_page",
+ "Charge",
+ "src/payments/charge.py",
+ parent="module_page:src/payments",
+ section="1.2.1",
+ order=1,
+ ),
+ _page(
+ "module_page:src/payments/providers",
+ "module_page",
+ "Payment Providers",
+ "src/payments/providers",
+ parent="module_page:src/payments",
+ section="1.2.3",
+ order=2,
+ ),
+ ]
+ )
+ await session.flush()
+
+
+async def test_file_target_surfaces_parent_concept_page(setup_mcp, session):
+ """A file target points up to the subsystem page that documents it."""
+ from repowise.server.mcp_server import get_context
+
+ await _add_tree(session)
+ result = await get_context(["src/payments/charge.py"])
+ t = result["targets"]["src/payments/charge.py"]
+ assert t["type"] == "file"
+ parent = t["parent_page"]
+ assert parent["title"] == "Payments Module"
+ assert parent["target_path"] == "src/payments"
+ assert parent["section"] == "1.2"
+
+
+async def test_concept_target_returns_section_and_children(setup_mcp, session):
+ """A concept target carries its tree position (section, parent) and its
+ non-file sub-concept children, not just the flat member-file list."""
+ from repowise.server.mcp_server import get_context
+
+ await _add_tree(session)
+ result = await get_context(["src/payments"])
+ t = result["targets"]["src/payments"]
+ assert t["type"] == "module"
+ # Own tree position.
+ assert t["docs"]["section"] == "1.2"
+ assert t["parent_page"]["title"] == "Layer: Core"
+ # Sub-concept child surfaced; the file child stays in "files", not "children".
+ children = t["docs"].get("children", [])
+ assert any(
+ c["target_path"] == "src/payments/providers" and c["page_type"] == "module_page"
+ for c in children
+ )
+ assert all(c["page_type"] != "file_page" for c in children)
+ assert any(f["path"] == "src/payments/charge.py" for f in t["docs"]["files"])