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.

fix(mcp): harden get_context — segment-boundary partial match, git-file fall-through, batch isolation (#401)

Swati Ahujaf5e760b7dbca
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/context.py b/packages/server/src/repowise/server/mcp_server/tool_context/context.py
index da037b11f..2f3d00e29 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/context.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/context.py
@@ -25,6 +25,7 @@ This module is the orchestrator; single-target resolution lives in
from __future__ import annotations
import asyncio
+import logging
from typing import Any
from repowise.core.persistence.database import get_session
@@ -41,6 +42,8 @@ from repowise.server.mcp_server._meta import build_meta as _build_meta
from repowise.server.mcp_server._meta import context_hint as _context_hint
from repowise.server.mcp_server.tool_context.targets import _resolve_one_target
+_log = logging.getLogger("repowise.mcp.context")
+
@mcp.tool()
async def get_context(
@@ -102,7 +105,12 @@ async def get_context(
async with get_session(ctx.session_factory) as session:
repository = await _get_repo(session)
- results = await asyncio.gather(
+ # return_exceptions=True isolates a single target's failure: one
+ # target raising (e.g. a malformed lookup) must not sink the whole
+ # batch. Any exception is converted below into a per-target error
+ # entry that carries "target", so the comprehension keyed on target
+ # below never KeyErrors.
+ raw_results = await asyncio.gather(
*[
_resolve_one_target(
session,
@@ -114,9 +122,28 @@ async def get_context(
repo_root=ctx.path,
)
for t in targets
- ]
+ ],
+ return_exceptions=True,
)
+ results: list[dict[str, Any]] = []
+ for t, r in zip(targets, raw_results, strict=True):
+ if isinstance(r, BaseException) and not isinstance(r, Exception):
+ # CancelledError / KeyboardInterrupt / SystemExit must propagate:
+ # converting them to per-target errors would break cooperative
+ # cancellation (a cancelled request would run to completion).
+ raise r
+ if isinstance(r, BaseException):
+ _log.exception("get_context: resolving target %r failed", t, exc_info=r)
+ results.append(
+ {
+ "target": t,
+ "error": f"Internal error resolving '{t}': {type(r).__name__}",
+ }
+ )
+ else:
+ results.append(r)
+
response: dict[str, Any] = {
"targets": {r["target"]: r for r in results},
"_meta": _build_meta(
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 bd793b8ce..c290fdfc6 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
@@ -10,9 +10,10 @@ from __future__ import annotations
import contextlib
import json
+import re
from typing import Any
-from sqlalchemy import select
+from sqlalchemy import or_, select
from sqlalchemy.ext.asyncio import AsyncSession
from repowise.core.persistence.crud import get_kg_layers, get_kg_tour_steps
@@ -45,6 +46,15 @@ from repowise.server.mcp_server.tool_context.kg import (
)
+def _escape_like(value: str) -> str:
+ """Escape LIKE metacharacters (``%``, ``_``) and the escape char itself.
+
+ Paired with ``escape="\\"`` on every ``.like()`` so a target containing
+ ``_`` or ``%`` is matched literally instead of as a wildcard.
+ """
+ return value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+
+
def _synthesize_structural_summary(file_path: str, classes: list[str], functions: list[str]) -> str:
"""Build a deterministic 1-line summary when no LLM-generated summary exists.
@@ -122,15 +132,45 @@ async def _resolve_one_target(
)
page = res.scalar_one_or_none()
if page is None:
- # Partial match fallback for modules
- res = await session.execute(
- select(Page).where(
- Page.repository_id == repo_id,
- Page.page_type == "module_page",
- Page.target_path.contains(clean_target),
+ # Partial match fallback for modules — but only on a path-segment
+ # boundary, so "api" matches "src/api" yet "apiclient"/"pi" do not.
+ # Curated module ids are path-shaped, so a raw substring match can
+ # (a) hit 2+ module paths (→ MultipleResultsFound) and (b) shadow a
+ # real file of the same name. Guard against both here.
+ #
+ # First: if the target is itself a known real file (present in
+ # git_metadata, the same source the git fallback rung uses), do NOT
+ # let a partial module match preempt that — fall through so the
+ # ladder reaches the "exists but no wiki page" rung below.
+ file_meta_res = await session.execute(
+ select(GitMetadata.file_path).where(
+ GitMetadata.repository_id == repo_id,
+ GitMetadata.file_path == clean_target,
)
)
- page = res.scalar_one_or_none()
+ is_known_file = file_meta_res.scalar_one_or_none() is not None
+ if not is_known_file:
+ esc = _escape_like(clean_target)
+ res = await session.execute(
+ select(Page).where(
+ Page.repository_id == repo_id,
+ Page.page_type == "module_page",
+ or_(
+ Page.target_path == clean_target,
+ Page.target_path.like(f"%/{esc}", escape="\\"),
+ Page.target_path.like(f"{esc}/%", escape="\\"),
+ Page.target_path.like(f"%/{esc}/%", escape="\\"),
+ ),
+ )
+ )
+ # Deterministic pick when several module paths match: shortest
+ # target_path first, ties broken lexicographically. Module
+ # counts are small, so picking in Python is robust and cheap.
+ candidates = sorted(
+ res.scalars().all(), key=lambda p: (len(p.target_path), p.target_path)
+ )
+ if candidates:
+ page = candidates[0]
if page:
target_type = "module"
else:
@@ -208,6 +248,30 @@ async def _resolve_one_target(
"is_hotspot": meta.is_hotspot,
}
+ # Fallback 2b: legacy module ids. Wiki modules used to be keyed by
+ # community ordinal ("community-12"); they are now keyed by directory
+ # path. Point old agent habits at the new vocabulary.
+ if target_type is None and re.fullmatch(r"community[-_]\d+", clean_target, re.IGNORECASE):
+ res = await session.execute(
+ select(Page.target_path)
+ .where(
+ Page.repository_id == repo_id,
+ Page.page_type == "module_page",
+ )
+ .order_by(Page.target_path)
+ .limit(10)
+ )
+ module_paths = filter_path_list([row[0] for row in res.all()], exclude_spec)
+ return {
+ "target": target,
+ "error": (
+ f"Target not found: '{target}'. Module pages are no longer "
+ "keyed by community ordinal — pass the module's directory "
+ "path instead (see suggestions)."
+ ),
+ "suggestions": module_paths,
+ }
+
# Fallback 3: fuzzy path suggestions — match by filename or partial path.
# Only runs if the prior fallbacks didn't resolve the target.
if target_type is None:
diff --git a/tests/unit/server/mcp/test_context.py b/tests/unit/server/mcp/test_context.py
index 04115bab4..4d6f10ad0 100644
--- a/tests/unit/server/mcp/test_context.py
+++ b/tests/unit/server/mcp/test_context.py
@@ -7,9 +7,108 @@ test data, mirroring the conftest pattern from the REST API tests.
from __future__ import annotations
import json
+from datetime import UTC, datetime
import pytest
+from repowise.core.persistence.models import GitMetadata, Page
+from repowise.core.persistence.vector_store import InMemoryVectorStore
+from repowise.core.providers.embedding.base import MockEmbedder
+
+_NOW = datetime(2026, 3, 19, 12, 0, 0, tzinfo=UTC)
+
+
+async def multi_module_db(session, populated_db):
+ """populated_db + extra module pages that trigger partial-match collisions.
+
+ Adds path-shaped module ids that share the "api" segment so a bare "api"
+ target hits more than one module path (the MultipleResultsFound trigger),
+ plus a git-only file whose name substring-matches a module path.
+ """
+ rid = populated_db
+
+ def _module(path: str, title: str) -> Page:
+ return Page(
+ id=f"module_page:{path}",
+ repository_id=rid,
+ page_type="module_page",
+ title=title,
+ content=f"# {title}\n\nmodule body.",
+ target_path=path,
+ source_hash=f"mod-{path}",
+ model_name="mock",
+ provider_name="mock",
+ generation_level=4,
+ confidence=0.9,
+ freshness_status="fresh",
+ metadata_json="{}",
+ created_at=_NOW,
+ updated_at=_NOW,
+ )
+
+ # "api" appears as a segment in two distinct module paths -> would raise
+ # MultipleResultsFound under the old substring + scalar_one_or_none rung.
+ session.add(_module("src/api", "API Module"))
+ session.add(_module("pkg/api", "Pkg API Module"))
+ # A different segment that must NOT match a bare "api" target.
+ session.add(_module("src/rapid", "Rapid Module"))
+ # A module path containing a literal "_" so LIKE-metachar escaping matters.
+ session.add(_module("src/a_b", "Underscore Module"))
+
+ # A real file present in git_metadata, with NO file_page, whose path
+ # substring-matches the "src/api" module path. Must resolve via the git
+ # fallback (target_type file/git), not as the module.
+ session.add(
+ GitMetadata(
+ id="gm-apiclient",
+ repository_id=rid,
+ file_path="src/api/client.py",
+ commit_count_total=3,
+ commit_count_90d=1,
+ commit_count_30d=0,
+ first_commit_at=datetime(2025, 6, 1, tzinfo=UTC),
+ last_commit_at=datetime(2026, 1, 2, tzinfo=UTC),
+ primary_owner_name="Carol",
+ primary_owner_email="[email protected]",
+ primary_owner_commit_pct=1.0,
+ top_authors_json=json.dumps([{"name": "Carol", "count": 3}]),
+ significant_commits_json=json.dumps([]),
+ co_change_partners_json=json.dumps([]),
+ is_hotspot=False,
+ is_stable=True,
+ churn_percentile=0.1,
+ age_days=200,
+ created_at=_NOW,
+ updated_at=_NOW,
+ )
+ )
+ await session.flush()
+ return rid
+
+
+async def setup_mcp_multi(factory, fts, vector_store, multi_module_db):
+ """Wire MCP globals to the multi-module database."""
+ import repowise.server.mcp_server as mcp_mod
+
+ 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 multi_module_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
+ mcp_mod._registry = None
+ mcp_mod._workspace_root = None
+ mcp_mod._embedder_status = None
+
@pytest.mark.asyncio
async def test_get_context_single_file(setup_mcp):
@@ -120,6 +219,20 @@ async def test_get_context_not_found(setup_mcp):
assert "error" in t
+async def test_get_context_legacy_community_id_hint(setup_mcp):
+ """Old community-ordinal module ids get a redirect to path-shaped ids."""
+ from repowise.server.mcp_server import get_context
+
+ result = await get_context(["community-12"])
+ t = result["targets"]["community-12"]
+ assert "error" in t
+ assert "directory" in t["error"]
+ # Suggestions list the real module pages by their directory path.
+ assert "src/auth" in t["suggestions"]
+ assert "src/db" in t["suggestions"]
+
+
def _make_big_response(n_targets: int = 5, n_symbols: int = 80, body_chars: int = 4000) -> dict:
"""Build a synthetic get_context response well over the 32 KB budget."""
targets = {}
@@ -204,3 +317,121 @@ def test_truncate_noop_when_under_budget():
assert out["dropped_targets"] == []
assert out["dropped_symbols"] == {}
assert "content_md" not in out["targets"]["a.py"]["docs"] # wasn't there anyway
+
+
+# --- Partial-module-match hardening (segment boundary + LIKE escaping) -------
+
+
+async def test_partial_module_multi_match_does_not_raise(setup_mcp_multi):
+ """A target matching 2+ module paths resolves deterministically, no raise."""
+ from repowise.server.mcp_server import get_context
+
+ result = await get_context(["api"])
+ t = result["targets"]["api"]
+ # Old code raised MultipleResultsFound here. Now it picks the shortest,
+ # lexicographically-first matching module path: "pkg/api" vs "src/api"
+ # both len 7 -> lexicographic -> "pkg/api".
+ assert t.get("type") == "module"
+ assert t["docs"]["title"] == "Pkg API Module"
+
+
+async def test_partial_module_segment_boundary(setup_mcp_multi):
+ """Substrings that aren't whole path segments must not match a module."""
+ from repowise.server.mcp_server import get_context
+
+ # "apiclient" / "pi" are substrings of "src/api" but not path segments.
+ result = await get_context(["apiclient", "pi", "rapid"])
+ targets = result["targets"]
+ # apiclient: not a module, not a file -> error
+ assert "error" in targets["apiclient"]
+ assert targets["apiclient"].get("type") != "module"
+ # pi: substring of "rapid"/"api" but not a segment -> not a module
+ assert targets["pi"].get("type") != "module"
+ # rapid: a full segment of "src/rapid" -> resolves as that module, and a
+ # bare "api" must NOT have matched it.
+ assert targets["rapid"].get("type") == "module"
+ assert targets["rapid"]["docs"]["title"] == "Rapid Module"
+
+
+async def test_partial_module_api_matches_only_api_segment(setup_mcp_multi):
+ """'api' resolves to an api module, never to 'src/rapid'."""
+ from repowise.server.mcp_server import get_context
+
+ result = await get_context(["api"])
+ t = result["targets"]["api"]
+ assert t["type"] == "module"
+ assert "Rapid" not in t["docs"]["title"]
+
+
+async def test_partial_module_like_metachars_not_wildcards(setup_mcp_multi):
+ """A target with '_' / '%' must match literally, not as a SQL wildcard."""
+ from repowise.server.mcp_server import get_context
+
+ # "a%b" would wildcard-match "a_b" if % were treated as a metachar.
+ # "axb" would match "a_b" if _ were treated as a single-char wildcard.
+ result = await get_context(["a%b", "axb"])
+ targets = result["targets"]
+ assert targets["a%b"].get("type") != "module"
+ assert "error" in targets["a%b"]
+ assert targets["axb"].get("type") != "module"
+ assert "error" in targets["axb"]
+ # Sanity: the literal "a_b" segment DOES resolve as the module.
+ result2 = await get_context(["a_b"])
+ assert result2["targets"]["a_b"]["type"] == "module"
+
+
+async def test_file_on_git_preferred_over_partial_module(setup_mcp_multi):
+ """A git-only file substring-matching a module resolves via git, not module."""
+ from repowise.server.mcp_server import get_context
+
+ # "src/api/client.py" is in git_metadata, has no file_page, and contains
+ # the "src/api" module path as a prefix segment. It must resolve via the
+ # git fallback rung, not be captured as the "src/api" module.
+ result = await get_context(["src/api/client.py"])
+ t = result["targets"]["src/api/client.py"]
+ assert t.get("type") != "module"
+ assert t.get("exists_in_git") is True
+ assert t["primary_owner"] == "Carol"
+ assert "error" in t # "exists but has no wiki page" shape
+
+
+async def test_legacy_community_hint_unaffected_by_multi_module(setup_mcp_multi):
+ """Extra module pages don't break the legacy community-N redirect rung."""
+ from repowise.server.mcp_server import get_context
+
+ result = await get_context(["community-12"])
+ t = result["targets"]["community-12"]
+ assert "error" in t
+ assert "directory" in t["error"]
+ assert "src/auth" in t["suggestions"]
+
+
+async def test_batch_isolation_one_target_errors(setup_mcp, monkeypatch):
+ """One target raising internally yields an error entry; siblings resolve."""
+ import repowise.server.mcp_server.tool_context.context as ctx_mod
+ from repowise.server.mcp_server import get_context
+
+ real_resolver = ctx_mod._resolve_one_target
+
+ async def flaky(session, repository, target, *args, **kwargs):
+ if target == "boom":
+ raise RuntimeError("synthetic resolver failure")
+ return await real_resolver(session, repository, target, *args, **kwargs)
+
+ monkeypatch.setattr(ctx_mod, "_resolve_one_target", flaky)
+
+ result = await get_context(["src/auth/service.py", "boom"])
+ targets = result["targets"]
+ # Sibling still resolves normally.
+ assert targets["src/auth/service.py"]["type"] == "file"
+ # Failing target carries a per-target error entry (keyed on its target).
+ assert "boom" in targets
+ assert "error" in targets["boom"]
+ assert targets["boom"]["target"] == "boom"