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
refactor(mcp): split tool_context.py into a package + fix truncation O(n^2) (#263)
Swati Ahuja6a0d8d87f4d0
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context.py b/packages/server/src/repowise/server/mcp_server/tool_context.pydeleted file mode 100644index af855fe11..000000000--- a/packages/server/src/repowise/server/mcp_server/tool_context.py+++ /dev/null@@ -1,1342 +0,0 @@-"""MCP Tool: get_context — relationships and triage signals for files / modules / symbols.--Workhorse for "what is this and what touches it" questions. Returns a triage-card by default (title, summary, signatures, hotspot bit, top callers, pointers-to risk / why / symbol). NOT a source-body tool — for raw bytes call-``get_symbol("path::Name")`` instead. The split keeps the cached prompt prefix-small on multi-turn agent sessions: ``get_context`` stays under ~2k tokens for-common targets, while ``get_symbol`` returns bounded bytes for one symbol.--Optional ``include`` parameter widens the response:- - include=["full_doc"] → full wiki markdown content- - include=["callers"] → who calls this symbol (symbol targets only)- - include=["callees"] → what this symbol calls (symbol targets only)- - include=["ownership"] → primary owner, bus factor, contributor count- - include=["last_change"]→ last commit date and author- - include=["metrics"] → PageRank, betweenness, percentile ranks- - include=["community"] → community membership + neighbors- - include=["decisions"] → full decision records (default returns titles only)-"""--from __future__ import annotations--import asyncio-import json-import logging-from typing import Any--logger = logging.getLogger(__name__)--# --- Output size budget --------------------------------------------------------# The Claude Code harness rejects MCP tool results whose stringified form exceeds-# ~10k tokens (it refuses to inline them and then refuses to Read the spilled-# file). When that happens the agent falls back to multiple get_symbol calls,-# each of which re-plays the cached system prompt — a significant cost driver-# on dense files in long multi-turn agent sessions.-#-# We therefore cap get_context output well below that ceiling. 8000 tokens-# leaves headroom for the wrapping JSON envelope and _meta fields the harness-# adds on top. The estimator is intentionally dependency-free: 4 chars/token is-# the widely-quoted average for English + code on BPE tokenizers and is within-# ~20% of tiktoken for typical wiki content. Precise counting is unnecessary-# because we only need to stay comfortably under the hard limit.-_TOKEN_BUDGET = 8000-_CHARS_PER_TOKEN = 4-_CHAR_BUDGET = _TOKEN_BUDGET * _CHARS_PER_TOKEN--from sqlalchemy import select-from sqlalchemy.ext.asyncio import AsyncSession--from repowise.core.persistence.crud import (- get_all_file_metrics,- get_community_members,- get_cross_community_edges,- get_graph_edges_for_node,- get_graph_node,- get_graph_nodes_by_ids,- get_kg_layers,- get_kg_tour_steps,- get_node_degree_counts,-)-from repowise.core.persistence.database import get_session-from repowise.core.persistence.decision_graph import get_governing_decisions-from repowise.core.persistence.models import (- CoverageFile,- DecisionRecord,- GitMetadata,- GraphEdge,- GraphNode,- HealthFileMetric,- HealthFinding,- Page,- Repository,- WikiSymbol,-)-from repowise.server.mcp_server import _state-from repowise.server.mcp_server._helpers import (- _get_repo,- _resolve_repo_context,- _unsupported_repo_all,-)-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.core.registry import mcp_tool_registry as mcp--# Minimum confidence for call edges to filter false positives-_MIN_CALL_CONFIDENCE = 0.7---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.-- Used in --index-only mode (no wiki pages) and as a fallback when an LLM- page predates the summary column. Always returns a non-empty string so the- agent never sees a missing field.- """- name = file_path.rsplit("/", 1)[-1]- parts: list[str] = []- if classes:- head = ", ".join(classes[:3])- more = f" (+{len(classes) - 3} more)" if len(classes) > 3 else ""- parts.append(f"defines {head}{more}")- if functions:- head = ", ".join(functions[:3])- more = f" (+{len(functions) - 3} more)" if len(functions) > 3 else ""- parts.append(f"function{'s' if len(functions) > 1 else ''} {head}{more}")- if not parts:- return f"{name}: empty or non-symbol file"- return f"{name}: " + "; ".join(parts) + "."---async def _resolve_one_target(- session: AsyncSession,- repository: Repository,- target: str,- include: set[str] | None,- compact: bool = False,-) -> 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:- # 1b. Normalise directory targets: strip trailing slash and try module- clean_target = target.rstrip("/")- # 2. Try module page (exact, then cleaned, then partial)- res = await session.execute(- select(Page).where(- Page.repository_id == repo_id,- Page.page_type == "module_page",- Page.target_path == target,- )- )- page = res.scalar_one_or_none()- if page is None and clean_target != target:- res = await session.execute(- select(Page).where(- Page.repository_id == repo_id,- Page.page_type == "module_page",- Page.target_path == clean_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),- )- )- 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,- )- )- 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:- # Fallback 1: index-only mode (no wiki pages) — return graph node + symbols if present- res = await session.execute(- select(GraphNode).where(- GraphNode.repository_id == repo_id,- GraphNode.node_id == target,- )- )- gnode = res.scalar_one_or_none()- if gnode is not None:- target_type = "file"- file_path_for_git = target- page = None # no wiki page; subsequent blocks must guard for this-- # Fallback 2: check git_metadata — file may exist but have no wiki page AND no graph node- if target_type is None:- res = await session.execute(- select(GitMetadata).where(- GitMetadata.repository_id == repo_id,- GitMetadata.file_path == target,- )- )- meta = res.scalar_one_or_none()- if meta:- return {- "target": target,- "error": (- f"'{target}' exists in the repository but has no wiki page. "- "This usually means the file has too few symbols or is below "- "the PageRank threshold. Run `repowise update` to regenerate docs."- ),- "exists_in_git": True,- "last_commit_at": meta.last_commit_at.isoformat()- if meta.last_commit_at- else None,- "primary_owner": meta.primary_owner_name,- "is_hotspot": meta.is_hotspot,- }-- # 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:- # For directory-like targets, suggest files within that directory- dir_prefix = clean_target.rstrip("/") + "/"- res = await session.execute(- select(GitMetadata.file_path)- .where(- GitMetadata.repository_id == repo_id,- GitMetadata.file_path.like(f"{dir_prefix}%"),- )- .limit(5)- )- suggestions = [row[0] for row in res.all()]- if not suggestions:- # Fall back to filename / partial path match- tail = target.rsplit("/", 1)[-1]- res = await session.execute(- select(GitMetadata.file_path)- .where(- GitMetadata.repository_id == repo_id,- GitMetadata.file_path.contains(tail),- )- .limit(5)- )- suggestions = [row[0] for row in res.all() if row[0] != target]- if suggestions:- return {- "target": target,- "error": f"Target not found: '{target}'",- "suggestions": suggestions,- }- return {"target": target, "error": f"Target not found: '{target}'"}-- result_data["target"] = target- result_data["type"] = target_type-- # --- Docs ---- # "full_doc" implies "docs" — entering the docs block whenever either is requested.- if include is None or "docs" in include or "full_doc" in include:- want_full_doc = bool(include and "full_doc" in include)- docs: dict[str, Any] = {}- if target_type == "file":- if page is not None:- docs["title"] = page.title- docs["summary"] = page.summary or ""- if want_full_doc:- docs["content_md"] = page.content- if page.human_notes:- docs["human_notes"] = page.human_notes- # Symbols in this file- res = await session.execute(- select(WikiSymbol).where(- WikiSymbol.repository_id == repo_id,- WikiSymbol.file_path == target,- )- )- symbols = res.scalars().all()- classes = [s.name for s in symbols if s.kind == "class"]- functions = [s.name for s in symbols if s.kind in ("function", "method")]- if compact:- # Compact mode: name+kind+signature+line+symbol_id only. Drops- # docstrings, line ranges, structure, and imported_by — those- # live behind compact=False or include= flags. The symbol_id- # is the canonical handle the caller pipes straight into- # get_symbol when it wants bytes.- #- # Cap at 40 symbols so a dense generated file (protobuf- # wrappers, vendored libs) can't blow the triage card past- # the agent's budget. Order matches WikiSymbol.start_line- # (assigned at index time), so the head is the navigationally- # useful slice.- symbol_cap = 40- visible = list(symbols)[:symbol_cap]- docs["symbols"] = [- {- "name": s.name,- "kind": s.kind,- "signature": s.signature,- "line": s.start_line,- "symbol_id": s.symbol_id,- }- for s in visible- ]- if len(symbols) > symbol_cap:- docs["symbols_truncated"] = {- "shown": symbol_cap,- "total": len(symbols),- "hint": "Call with compact=False or include=['full_doc'] for the full list.",- }- if not docs.get("summary"):- docs["summary"] = _synthesize_structural_summary(target, classes, functions)- else:- docs["symbols"] = [- {- "name": s.name,- "kind": s.kind,- "signature": s.signature,- "start_line": s.start_line,- "end_line": s.end_line,- "docstring": (s.docstring or "")[:400],- }- for s in symbols- ]- # Structure summary block — quick scan of what's in the file- total_loc = max((s.end_line for s in symbols), default=0)- avg_complexity = (- sum(s.complexity_estimate for s in symbols) / len(symbols) if symbols else 0- )- docs["structure"] = {- "classes": classes,- "functions": functions,- "symbol_count": len(symbols),- "total_loc": total_loc,- "avg_complexity": round(avg_complexity, 2),- }- # Fallback summary: if no Page (index-only mode) or page.summary- # is empty, synthesize a deterministic one-liner from structure.- if not docs.get("summary"):- docs["summary"] = _synthesize_structural_summary(target, classes, functions)- # 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]-- # Community info (compact=False only, ~80 bytes)- res = await session.execute(- select(GraphNode).where(- GraphNode.repository_id == repo_id,- GraphNode.node_id == target,- )- )- gn = res.scalar_one_or_none()- if gn and gn.community_id is not None:- _cmeta: dict[str, Any] = {}- try:- _cmeta = json.loads(gn.community_meta_json or "{}")- except (json.JSONDecodeError, TypeError):- pass- docs["community"] = {- "id": gn.community_id,- "label": _cmeta.get("label", ""),- }-- elif target_type == "module":- docs["title"] = page.title- docs["summary"] = page.summary or ""- if want_full_doc:- 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- ]-- 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 summary (full content gated behind include=["full_doc"])- sym_page_id = f"file_page:{sym.file_path}"- sym_page = await session.get(Page, sym_page_id)- if sym_page is not None:- docs["file_summary"] = sym_page.summary or ""- if want_full_doc:- docs["documentation"] = sym_page.content- # 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-- # --- Triage signals (always on) ---------------------------------------- # Two single-bit-ish pointers the agent uses to decide its next move:- # * ``hotspot``: lights the way to ``get_risk`` for files in the 95th+- # churn percentile. Just the boolean — the full risk dossier stays- # in ``get_risk`` so the triage card doesn't grow.- # * ``decision_records``: titles only, no body. Lights the way to- # ``get_why``. We deliberately don't inline the rationale here;- # duplicating it across every ``get_context`` response bloats the- # cached prompt prefix and defeats the split between the two tools.- #- # Cheap: two short queries piggybacking on the session we already opened.- triage_path = file_path_for_git- if target_type == "module" and page:- triage_path = page.target_path- if triage_path:- triage_meta_res = await session.execute(- select(GitMetadata.is_hotspot).where(- GitMetadata.repository_id == repo_id,- GitMetadata.file_path == triage_path,- )- )- triage_meta = triage_meta_res.scalar_one_or_none()- result_data["hotspot"] = bool(triage_meta) if triage_meta is not None else False-- # Bounded graph-link query — replaces full Python scan over all rows.- governing: list[DecisionRecord] = []- seen_ids: set[str] = set()- for lookup_node in dict.fromkeys(- [triage_path, target] if triage_path != target else [triage_path]- ):- if not lookup_node:- continue- for dr in await get_governing_decisions(session, repo_id, lookup_node):- if dr.id not in seen_ids:- seen_ids.add(dr.id)- governing.append(dr)- if governing:- result_data["decision_records"] = [dr.title for dr in governing[:5]]- result_data["decision_records_hint"] = (- "Decisions touch this file. Call get_why(targets=[...]) for rationale."- )- # Compact enriched list — highest-confidence first, capped at 5.- governing_sorted = sorted(governing, key=lambda d: -(d.confidence or 0.0))- result_data["governing_decisions"] = [- {- "id": dr.id,- "title": dr.title,- "status": dr.status,- "staleness_score": dr.staleness_score,- "verification": dr.verification,- "stale": bool(dr.status == "active" and (dr.staleness_score or 0.0) >= 0.5),- }- for dr in governing_sorted[:5]- ]-- # --- 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"] = getattr(meta, "contributor_count", 0) or len(- json.loads(meta.top_authors_json)- )- ownership["bus_factor"] = getattr(meta, "bus_factor", 0) or 0- # Recent owner (who maintains this file now)- recent = getattr(meta, "recent_owner_name", None)- if recent and recent != meta.primary_owner_name:- ownership["recent_owner"] = recent- ownership["recent_owner_pct"] = getattr(meta, "recent_owner_commit_pct", None)- else:- ownership["primary_owner"] = None- ownership["owner_pct"] = None- ownership["contributor_count"] = 0- ownership["bus_factor"] = 0- else:- ownership["primary_owner"] = None- ownership["owner_pct"] = None- ownership["contributor_count"] = 0- ownership["bus_factor"] = 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- or (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-- # --- KG layer + tour context (Phase 9) ---- if target_type == "file" and file_path_for_git:- kg_layers = await get_kg_layers(session, repo_id)- if kg_layers:- for _l in kg_layers:- _l._parsed_node_ids = json.loads(_l.node_ids_json) if _l.node_ids_json else []- file_layer = _find_layer_for_file(file_path_for_git, kg_layers)- if file_layer:- edge_res = await session.execute(- select(GraphEdge).where(- GraphEdge.repository_id == repo_id,- GraphEdge.target_node_id == file_path_for_git,- GraphEdge.edge_type == "imports",- )- )- incoming_edges = list(edge_res.scalars())- result_data["architectural_layer"] = {- "name": file_layer.name,- "description": (file_layer.description or "")[:200],- "role": _classify_file_role(file_path_for_git, file_layer, incoming_edges),- }-- kg_tour = await get_kg_tour_steps(session, repo_id)- if kg_tour:- for _s in kg_tour:- _s._parsed_node_ids = json.loads(_s.node_ids_json) if _s.node_ids_json else []- file_tour_step = _find_tour_step_for_file(file_path_for_git, kg_tour)- if file_tour_step:- result_data["tour_context"] = {- "step": file_tour_step.step_order,- "title": file_tour_step.title,- "why": (file_tour_step.description or "")[:200],- }-- # --- Callers / Callees (replaces get_callers_callees) ---- want_callers = bool(include and "callers" in include)- want_callees = bool(include and "callees" in include)- if want_callers or want_callees:- await _resolve_call_graph(- session,- repository,- target,- target_type,- result_data,- want_callers=want_callers,- want_callees=want_callees,- )-- # --- Metrics (replaces get_graph_metrics) ---- if include and "metrics" in include:- await _resolve_metrics(session, repository, target, result_data)-- # --- Community (replaces get_community) ---- if include and "community" in include:- await _resolve_community(session, repository, target, result_data)-- # --- Code health (Phase 2) ---- if include and "health" in include:- await _resolve_health(session, repository, target, target_type, result_data)-- return result_data---# ----------------------------------------------------------------------------# Merged tool helpers (source, callers/callees, metrics, community)-# ------------------------------------------------------------------------------async def _resolve_call_graph(- session: AsyncSession,- repository: Repository,- target: str,- target_type: str | None,- result_data: dict[str, Any],- *,- want_callers: bool = False,- want_callees: bool = False,-) -> None:- """Resolve callers/callees for a symbol and attach to result_data."""- repo_id = repository.id- limit = 20-- # Resolve to a graph node (symbol)- node = await get_graph_node(session, repo_id, target)- if node is None and "::" in target:- # Fuzzy: try bare name- bare_name = target.split("::")[-1]- res = await session.execute(- select(GraphNode).where(- GraphNode.repository_id == repo_id,- GraphNode.node_type == "symbol",- GraphNode.name == bare_name,- )- )- rows = list(res.scalars().all())- if rows:- file_hint = target.split("::")[0]- node = next((r for r in rows if r.file_path == file_hint), rows[0])-- if node is None or node.node_type != "symbol":- # For file targets, return empty with explanation — callers/callees is symbol-only- if want_callers:- result_data["callers"] = []- if want_callees:- result_data["callees"] = []- if node is not None and node.node_type != "symbol":- result_data["_call_graph_note"] = (- "callers/callees require a symbol target (function/class/method), "- f"but '{target}' is a {node.node_type}. Pass a symbol name or file::Symbol."- )- return-- direction = "both"- if want_callers and not want_callees:- direction = "callers"- elif want_callees and not want_callers:- direction = "callees"-- edges = await get_graph_edges_for_node(- session,- repo_id,- node.node_id,- direction=direction,- edge_types=["calls", "extends", "implements"],- limit=limit,- )-- # Hydrate other nodes- other_ids = list(- {e.source_node_id if e.target_node_id == node.node_id else e.target_node_id for e in edges}- )- node_map = await get_graph_nodes_by_ids(session, repo_id, other_ids)-- callers: list[dict[str, Any]] = []- callees: list[dict[str, Any]] = []-- for e in edges:- # Filter out low-confidence edges (false positives from Tier 3 global resolution)- if (e.confidence or 0) < _MIN_CALL_CONFIDENCE:- continue-- is_caller = e.target_node_id == node.node_id- other_id = e.source_node_id if is_caller else e.target_node_id- other_node = node_map.get(other_id)-- entry: dict[str, Any] = {- "symbol_id": other_id,- "name": other_node.name- if other_node- else (other_id.split("::")[-1] if "::" in other_id else other_id),- "kind": other_node.kind if other_node else None,- "file": other_node.file_path- if other_node- else (other_id.split("::")[0] if "::" in other_id else other_id),- "confidence": e.confidence,- "edge_type": e.edge_type,- }- if is_caller:- callers.append(entry)- else:- callees.append(entry)-- # Sort by confidence DESC- callers.sort(key=lambda x: -(x.get("confidence") or 0))- callees.sort(key=lambda x: -(x.get("confidence") or 0))-- if want_callers:- result_data["callers"] = callers- if want_callees:- result_data["callees"] = callees---async def _resolve_metrics(- session: AsyncSession,- repository: Repository,- target: str,- result_data: dict[str, Any],-) -> None:- """Resolve graph importance metrics and attach to result_data["metrics"]."""- repo_id = repository.id-- node = await get_graph_node(session, repo_id, target)- if node is None:- result_data["metrics"] = None- return-- try:- meta = json.loads(node.community_meta_json or "{}")- except (json.JSONDecodeError, TypeError):- meta = {}-- degrees = await get_node_degree_counts(session, repo_id, node.node_id)-- # Percentile computation against same-type peers- all_nodes = await get_all_file_metrics(session, repo_id)- pr_values = [n.pagerank for n in all_nodes if n.pagerank is not None]- bt_values = [n.betweenness for n in all_nodes if n.betweenness is not None]-- def _pct(value: float, all_vals: list[float]) -> int:- if not all_vals:- return 0- return round(100 * sum(1 for v in all_vals if v < value) / len(all_vals))-- result_data["metrics"] = {- "pagerank": round(node.pagerank or 0.0, 6),- "pagerank_percentile": _pct(node.pagerank or 0.0, pr_values),- "betweenness": round(node.betweenness or 0.0, 6),- "betweenness_percentile": _pct(node.betweenness or 0.0, bt_values),- "in_degree": degrees["in_degree"],- "out_degree": degrees["out_degree"],- "community_id": node.community_id,- "community_label": meta.get("label") or None,- }---async def _resolve_community(- session: AsyncSession,- repository: Repository,- target: str,- result_data: dict[str, Any],-) -> None:- """Resolve community membership and attach to result_data["community"]."""- repo_id = repository.id-- node = await get_graph_node(session, repo_id, target)- if node is None or node.community_id is None:- result_data["community"] = None- return-- try:- meta = json.loads(node.community_meta_json or "{}")- except (json.JSONDecodeError, TypeError):- meta = {}-- label = meta.get("label") or f"cluster_{node.community_id}"- cohesion = float(meta.get("cohesion", 0.0) or 0.0)-- # Get top members (cap at 10 for compact output)- members = await get_community_members(session, repo_id, node.community_id, limit=10)- member_paths = [m.node_id for m in members]-- # Neighboring communities (cap at 5)- cross_edges = await get_cross_community_edges(session, repo_id, node.community_id)- neighbors: list[dict[str, Any]] = []- for ce in cross_edges[:5]:- nid = ce["target_community_id"]- nm = await get_community_members(session, repo_id, nid, limit=1)- nlabel = ""- if nm:- try:- nmeta = json.loads(nm[0].community_meta_json or "{}")- nlabel = nmeta.get("label", "")- except (json.JSONDecodeError, TypeError):- pass- neighbors.append(- {- "id": nid,- "label": nlabel or f"cluster_{nid}",- "cross_edges": ce["edge_count"],- }- )-- result_data["community"] = {- "id": node.community_id,- "label": label,- "cohesion": round(cohesion, 3),- "top_members": member_paths,- "neighbors": neighbors,- }---async def _resolve_health(- session: AsyncSession,- repository: Repository,- target: str,- target_type: str,- result_data: dict[str, Any],-) -> None:- """Attach per-file health metric + top 2 biomarkers + coverage row.-- Only meaningful for *file* targets. For symbol targets we resolve the- enclosing file path via the already-computed ``file_path_for_git`` is- not available here — we fall back to ``target`` when ``target_type``- is ``"file"`` and otherwise inspect the target string for a- ``"path::symbol"`` separator.- """- file_path: str | None- if target_type == "file":- file_path = target- elif "::" in target:- file_path = target.split("::", 1)[0]- else:- file_path = None-- if not file_path:- result_data["health"] = None- return-- repo_id = repository.id- metric = (- await session.execute(- select(HealthFileMetric).where(- HealthFileMetric.repository_id == repo_id,- HealthFileMetric.file_path == file_path,- )- )- ).scalar_one_or_none()-- if metric is None:- result_data["health"] = None- return-- findings_res = await session.execute(- select(HealthFinding)- .where(- HealthFinding.repository_id == repo_id,- HealthFinding.file_path == file_path,- HealthFinding.status == "open",- )- .order_by(HealthFinding.health_impact.desc())- .limit(2)- )- from repowise.core.analysis.health.suggestions import suggestion_for-- top_biomarkers = [- {- "biomarker_type": f.biomarker_type,- "severity": f.severity,- "function_name": f.function_name,- "impact": round(f.health_impact, 2),- "suggestion": suggestion_for(f.biomarker_type),- }- for f in findings_res.scalars().all()- ]-- coverage_row = (- await session.execute(- select(CoverageFile).where(- CoverageFile.repository_id == repo_id,- CoverageFile.file_path == file_path,- )- )- ).scalar_one_or_none()-- health: dict[str, Any] = {- "score": round(metric.score, 2),- "max_ccn": metric.max_ccn,- "max_nesting": metric.max_nesting,- "nloc": metric.nloc,- "has_test_file": metric.has_test_file,- "module": metric.module,- "duplication_pct": metric.duplication_pct,- "top_biomarkers": top_biomarkers,- }- if coverage_row is not None:- health["coverage"] = {- "source_format": coverage_row.source_format,- "line_coverage_pct": coverage_row.line_coverage_pct,- "branch_coverage_pct": coverage_row.branch_coverage_pct,- "total_coverable_lines": coverage_row.total_coverable_lines,- }- elif metric.line_coverage_pct is not None:- health["coverage"] = {- "line_coverage_pct": metric.line_coverage_pct,- "branch_coverage_pct": metric.branch_coverage_pct,- }- result_data["health"] = health---def _find_layer_for_file(path: str, layers: list) -> Any | None:- for layer in layers:- node_ids = getattr(layer, "_parsed_node_ids", None)- if node_ids is None:- node_ids = json.loads(layer.node_ids_json) if layer.node_ids_json else []- if f"file:{path}" in node_ids or path in node_ids:- return layer- return None---def _find_tour_step_for_file(path: str, steps: list) -> Any | None:- for step in steps:- node_ids = getattr(step, "_parsed_node_ids", None)- if node_ids is None:- node_ids = json.loads(step.node_ids_json) if step.node_ids_json else []- if f"file:{path}" in node_ids or path in node_ids:- return step- return None---def _classify_file_role(path: str, layer: Any, incoming_edges: list) -> str:- raw = getattr(layer, "_parsed_node_ids", None)- if raw is None:- raw = json.loads(layer.node_ids_json) if layer.node_ids_json else []- node_ids = set(raw)- cross_layer = [- e- for e in incoming_edges- if f"file:{e.source_node_id}" not in node_ids and e.source_node_id not in node_ids- ]- if cross_layer:- return "edge_connector"- if not incoming_edges:- return "entry_point"- return "internal"---def _estimate_tokens(obj: Any) -> int:- """Cheap upper-bound token estimate for an arbitrary JSON-serialisable object.-- Serialises to compact JSON (the wire format the MCP layer eventually emits)- and divides by ``_CHARS_PER_TOKEN``. We use the serialised form — not just- raw text fields — because structural JSON overhead (quotes, braces, field- names) is non-trivial and is what the downstream tokenizer actually sees.- """- return len(json.dumps(obj, separators=(",", ":"), default=str)) // _CHARS_PER_TOKEN---# Heavy optional fields we can strip from a target's docs block without losing-# its identity. Ordering matters: earlier entries are dropped first because they-# carry the most bytes per unit of navigational value.-_HEAVY_DOC_FIELDS: tuple[str, ...] = ("content_md", "documentation", "file_summary")---def _symbol_priority(sym: dict[str, Any], query_terms: set[str]) -> tuple[int, int, int]:- """Return a sort key (higher = keep) for a symbol within a target.-- Priority order (language-agnostic — no Python-specific heuristics):- 1. Exact name match against any user query term.- 2. Substring / case-insensitive match against query terms.- 3. Kind rank: classes/types outrank functions/methods which outrank the- rest. This mirrors navigational usefulness across Python, TS, Go,- Rust, C++, etc. where a type anchors a module more than a helper fn.- 4. PageRank / centrality if present on the dict (forward-compatible —- ``get_context`` doesn't currently populate it but ``_resolve_one_target``- may in the future).- """- name = (sym.get("name") or "").lower()- exact = 1 if name and name in query_terms else 0- fuzzy = 1 if any(t and t in name for t in query_terms) else 0- kind = (sym.get("kind") or "").lower()- kind_rank = {- "class": 3,- "interface": 3,- "struct": 3,- "trait": 3,- "type": 3,- "enum": 3,- "function": 2,- "method": 2,- }.get(kind, 1)- centrality = int((sym.get("pagerank") or sym.get("centrality") or 0) * 1000)- return (exact * 10 + fuzzy * 5 + kind_rank, centrality, -len(json.dumps(sym, default=str)))---def _query_terms_for(target: str) -> set[str]:- """Derive cheap query terms from a target string for symbol prioritisation.-- ``get_context`` has no explicit query argument, so we fall back to the- target identifier itself — the tail of a file path, or the raw symbol name.- This is deliberately coarse: it just nudges symbol retention toward the- thing the caller asked about.- """- tail = target.rsplit("/", 1)[-1].lower()- # Strip common extension if present (language-agnostic: split once on '.').- if "." in tail:- tail = tail.rsplit(".", 1)[0]- return {t for t in (tail, target.lower()) if t}---def _truncate_to_budget(- result: dict[str, Any],- char_budget: int = _CHAR_BUDGET,-) -> dict[str, Any]:- """Cap the ``get_context`` response at roughly ``_TOKEN_BUDGET`` tokens.-- Strategy (applied in order, stopping as soon as the budget is met):-- 1. **Strip heavy optional doc fields** (``content_md``, ``documentation``,- ``file_summary``) from each target. These are 1–2k tokens apiece and- duplicate information the agent can re-request via ``full_doc``.- 2. **Shrink symbol lists within each target**, keeping the highest-priority- symbols per ``_symbol_priority``. This preserves the navigational index- (names, signatures, line numbers) while dropping bulk docstrings.- 3. **Drop whole targets** from the tail of the list. Per spec we prefer- keeping fewer full-fidelity targets over many stubs, so once symbols- can't shrink further we evict entire targets rather than gutting them.-- Adds ``truncated: bool``, ``dropped_targets: list[str]``, and- ``dropped_symbols: dict[target, list[name]]`` top-level fields — additive- only, existing callers are unaffected.-- Edge cases:- * Empty ``targets`` → returns unchanged with ``truncated=False``.- * A single target whose symbol list alone busts the budget → we reduce- symbols down to 1 and accept the overshoot rather than returning an- empty response. The ``truncated`` flag still fires.- * Targets that carry an ``error`` field (not-found) are cheap and are- preserved unless literally nothing else fits.- """- result.setdefault("truncated", False)- result.setdefault("dropped_targets", [])- result.setdefault("dropped_symbols", {})-- targets: dict[str, Any] = result.get("targets") or {}- if not targets:- return result-- def _size() -> int:- return len(json.dumps(result, separators=(",", ":"), default=str))-- if _size() <= char_budget:- return result-- # Stage 1: strip heavy optional doc fields across all targets.- for name, tgt in targets.items():- docs = tgt.get("docs") if isinstance(tgt, dict) else None- if not isinstance(docs, dict):- continue- for field in _HEAVY_DOC_FIELDS:- if field in docs:- docs.pop(field, None)- result["truncated"] = True- if _size() <= char_budget:- return result-- # Stage 2: prioritise symbols within each target. We iterate from the- # largest target down so the biggest offenders shrink first.- def _target_cost(item: tuple[str, Any]) -> int:- return len(json.dumps(item[1], default=str))-- for tgt_name, tgt in sorted(targets.items(), key=_target_cost, reverse=True):- docs = tgt.get("docs") if isinstance(tgt, dict) else None- if not isinstance(docs, dict):- continue- symbols = docs.get("symbols")- if not isinstance(symbols, list) or not symbols:- continue- query_terms = _query_terms_for(tgt_name)- ordered = sorted(symbols, key=lambda s: _symbol_priority(s, query_terms), reverse=True)- kept: list[dict[str, Any]] = []- dropped: list[str] = []- # Add symbols one at a time from highest priority until we hit the cap.- for sym in ordered:- docs["symbols"] = kept + [sym]- if _size() <= char_budget:- kept.append(sym)- else:- dropped.append(sym.get("name") or "<anonymous>")- if not kept and ordered:- # Edge case: a single symbol is larger than the budget. Keep one- # (truncating its docstring) rather than returning zero symbols —- # the caller at least learns the target resolved.- head = dict(ordered[0])- if isinstance(head.get("docstring"), str):- head["docstring"] = head["docstring"][:200]- kept = [head]- dropped = [s.get("name") or "<anonymous>" for s in ordered[1:]]- docs["symbols"] = kept- if dropped:- result["dropped_symbols"][tgt_name] = dropped- result["truncated"] = True- if _size() <= char_budget:- return result-- # Stage 3: drop whole targets, largest first, until we fit. Prefer to keep- # error-only targets (they're tiny and signal "not found" to the caller).- def _evictable_order() -> list[str]:- items = list(targets.items())- items.sort(- key=lambda kv: (- 0 if isinstance(kv[1], dict) and "error" in kv[1] else 1,- len(json.dumps(kv[1], default=str)),- ),- reverse=True,- )- return [k for k, _ in items]-- for name in _evictable_order():- if len(targets) <= 1:- break- targets.pop(name, None)- result["dropped_targets"].append(name)- result["truncated"] = True- if _size() <= char_budget:- break-- if result["truncated"]:- logger.info(- "get_context truncated to budget",- extra={- "char_budget": char_budget,- "token_budget": _TOKEN_BUDGET,- "final_chars": _size(),- "dropped_targets": result["dropped_targets"],- "dropped_symbol_counts": {k: len(v) for k, v in result["dropped_symbols"].items()},- },- )- return result---async def get_context(- targets: list[str],- include: list[str] | None = None,- compact: bool = True,- repo: str | None = None,-) -> dict:- """Triage card for files / modules / symbols — relationships, not source bytes.-- Returns a compact card the agent can use to decide its next move: title,- summary, signatures, hotspot bit, top callers, and pointers (decision_record- titles, symbol_ids) into the deeper tools. For the actual source body of a- symbol, call ``get_symbol("path/to/file.py::Name")`` — it is cheaper than- Read and returns bounded bytes with exact line numbers.-- Batch multiple targets in one call. In workspace mode responses are- auto-enriched with cross-repo co-change partners and API contract links.-- Include options (everything outside defaults is opt-in):- - "full_doc": full wiki markdown content for the target- - "ownership": primary owner, bus factor, contributor count- - "last_change":last commit date and author- - "callers": who calls this symbol (symbol targets only)- - "callees": what this symbol calls (symbol targets only)- - "metrics": PageRank, betweenness centrality, percentile ranks- - "community": architectural community membership + neighbors- - "decisions": full decision records (default returns titles only)-- Example: get_context(["src/auth/service.py", "src/auth/middleware.py"])- Example: get_context(["src/auth/service.py::verify_token"], include=["callers"])-- Args:- targets: file paths, module paths, or qualified symbol IDs.- include: list of optional data blocks (defaults are always returned).- compact: default True (signatures only). False adds structure+imports+docstrings.- repo: usually omitted.- """- if repo == "all":- return _unsupported_repo_all("get_context")- ctx = await _resolve_repo_context(repo)-- # Default to docs + freshness when include is omitted. Freshness is- # critical for the agent to detect stale index data. The other blocks- # (ownership/last_change/decisions) are 200–500 bytes each and bloat- # every subsequent agent turn via cache replay. Callers that want them- # must pass include explicitly.- include_set = set(include) if include else {"docs", "freshness"}-- import time as _time-- _t0 = _time.perf_counter()- async with get_session(ctx.session_factory) as session:- repository = await _get_repo(session)-- results = await asyncio.gather(- *[- _resolve_one_target(- session,- repository,- t,- include_set,- compact,- )- for t in targets- ]- )-- response: dict[str, Any] = {- "targets": {r["target"]: r for r in results},- "_meta": _build_meta(- timing_ms=(_time.perf_counter() - _t0) * 1000,- hint=_context_hint(targets, compact, include_set),- repository=repository,- ),- }-- # Cross-repo enrichment (Phase 3 + 4)- from repowise.server.mcp_server._helpers import _is_workspace_mode-- enricher = _state._cross_repo_enricher- if enricher is not None and enricher.has_data and _is_workspace_mode():- for target_key, target_data in response["targets"].items():- cross_repo: dict[str, Any] = {}-- partners = enricher.get_cross_repo_partners(ctx.alias, target_key)- if partners:- cross_repo["co_changes_with"] = [- {"repo": p["repo"], "file": p["file"], "strength": p["strength"]}- for p in partners[:5]- ]-- # Contract links (Phase 4)- if enricher.has_contract_data:- provider_links = enricher.get_contract_links_as_provider(ctx.alias, target_key)- consumer_links = enricher.get_contract_links_as_consumer(ctx.alias, target_key)- if provider_links or consumer_links:- contracts: dict[str, Any] = {}- if provider_links:- contracts["consumers"] = [- {- "consumer_repo": lk["consumer_repo"],- "contract_id": lk["contract_id"],- "type": lk["contract_type"],- }- for lk in provider_links[:5]- ]- if consumer_links:- contracts["providers"] = [- {- "provider_repo": lk["provider_repo"],- "contract_id": lk["contract_id"],- "type": lk["contract_type"],- }- for lk in consumer_links[:5]- ]- cross_repo["contracts"] = contracts-- if cross_repo:- target_data["cross_repo"] = cross_repo-- # Enforce the global token cap. See ``_truncate_to_budget`` for strategy.- return _truncate_to_budget(response)diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/__init__.py b/packages/server/src/repowise/server/mcp_server/tool_context/__init__.pynew file mode 100644index 000000000..1f68fe9cb--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_context/__init__.py@@ -0,0 +1,26 @@+"""get_context MCP tool — relationships and triage signals.++Façade: the tool used to be a single 1213-line ``tool_context.py``. It is now+a package (orchestrator + targets / enrichment / kg / truncation). Importers+keep working unchanged — ``from ...tool_context import get_context`` resolves,+importing the package registers the tool via ``@mcp.tool()``, and the+truncation helpers (used by tests) remain importable from the package root.+"""++from __future__ import annotations++from repowise.server.mcp_server.tool_context.context import get_context+from repowise.server.mcp_server.tool_context.truncation import (+ _CHAR_BUDGET,+ _TOKEN_BUDGET,+ _estimate_tokens,+ _truncate_to_budget,+)++__all__ = [+ "_CHAR_BUDGET",+ "_TOKEN_BUDGET",+ "_estimate_tokens",+ "_truncate_to_budget",+ "get_context",+]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.pynew file mode 100644index 000000000..cd8965c90--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_context/context.py@@ -0,0 +1,164 @@+"""MCP Tool: get_context — relationships and triage signals for files / modules / symbols.++Workhorse for "what is this and what touches it" questions. Returns a triage+card by default (title, summary, signatures, hotspot bit, top callers, pointers+to risk / why / symbol). NOT a source-body tool — for raw bytes call+``get_symbol("path::Name")`` instead. The split keeps the cached prompt prefix+small on multi-turn agent sessions: ``get_context`` stays under ~2k tokens for+common targets, while ``get_symbol`` returns bounded bytes for one symbol.++Optional ``include`` parameter widens the response:+ - include=["full_doc"] → full wiki markdown content+ - include=["callers"] → who calls this symbol (symbol targets only)+ - include=["callees"] → what this symbol calls (symbol targets only)+ - include=["ownership"] → primary owner, bus factor, contributor count+ - include=["last_change"]→ last commit date and author+ - include=["metrics"] → PageRank, betweenness, percentile ranks+ - include=["community"] → community membership + neighbors+ - include=["decisions"] → full decision records (default returns titles only)++This module is the orchestrator; single-target resolution lives in+``targets`` and the budget cap in ``truncation``.+"""++from __future__ import annotations++import asyncio+from typing import Any++from repowise.core.persistence.database import get_session+from repowise.core.registry import mcp_tool_registry as mcp+from repowise.server.mcp_server import _state+from repowise.server.mcp_server._helpers import (+ _get_repo,+ _resolve_repo_context,+ _unsupported_repo_all,+)+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+from repowise.server.mcp_server.tool_context.truncation import _truncate_to_budget+++async def get_context(+ targets: list[str],+ include: list[str] | None = None,+ compact: bool = True,+ repo: str | None = None,+) -> dict:+ """Triage card for files / modules / symbols — relationships, not source bytes.++ Returns a compact card the agent can use to decide its next move: title,+ summary, signatures, hotspot bit, top callers, and pointers (decision_record+ titles, symbol_ids) into the deeper tools. For the actual source body of a+ symbol, call ``get_symbol("path/to/file.py::Name")`` — it is cheaper than+ Read and returns bounded bytes with exact line numbers.++ Batch multiple targets in one call. In workspace mode responses are+ auto-enriched with cross-repo co-change partners and API contract links.++ Include options (everything outside defaults is opt-in):+ - "full_doc": full wiki markdown content for the target+ - "ownership": primary owner, bus factor, contributor count+ - "last_change":last commit date and author+ - "callers": who calls this symbol (symbol targets only)+ - "callees": what this symbol calls (symbol targets only)+ - "metrics": PageRank, betweenness centrality, percentile ranks+ - "community": architectural community membership + neighbors+ - "decisions": full decision records (default returns titles only)++ Example: get_context(["src/auth/service.py", "src/auth/middleware.py"])+ Example: get_context(["src/auth/service.py::verify_token"], include=["callers"])++ Args:+ targets: file paths, module paths, or qualified symbol IDs.+ include: list of optional data blocks (defaults are always returned).+ compact: default True (signatures only). False adds structure+imports+docstrings.+ repo: usually omitted.+ """+ if repo == "all":+ return _unsupported_repo_all("get_context")+ ctx = await _resolve_repo_context(repo)++ # Default to docs + freshness when include is omitted. Freshness is+ # critical for the agent to detect stale index data. The other blocks+ # (ownership/last_change/decisions) are 200–500 bytes each and bloat+ # every subsequent agent turn via cache replay. Callers that want them+ # must pass include explicitly.+ include_set = set(include) if include else {"docs", "freshness"}++ import time as _time++ _t0 = _time.perf_counter()+ async with get_session(ctx.session_factory) as session:+ repository = await _get_repo(session)++ results = await asyncio.gather(+ *[+ _resolve_one_target(+ session,+ repository,+ t,+ include_set,+ compact,+ )+ for t in targets+ ]+ )++ response: dict[str, Any] = {+ "targets": {r["target"]: r for r in results},+ "_meta": _build_meta(+ timing_ms=(_time.perf_counter() - _t0) * 1000,+ hint=_context_hint(targets, compact, include_set),+ repository=repository,+ ),+ }++ # Cross-repo enrichment (Phase 3 + 4)+ from repowise.server.mcp_server._helpers import _is_workspace_mode++ enricher = _state._cross_repo_enricher+ if enricher is not None and enricher.has_data and _is_workspace_mode():+ for target_key, target_data in response["targets"].items():+ cross_repo: dict[str, Any] = {}++ partners = enricher.get_cross_repo_partners(ctx.alias, target_key)+ if partners:+ cross_repo["co_changes_with"] = [+ {"repo": p["repo"], "file": p["file"], "strength": p["strength"]}+ for p in partners[:5]+ ]++ # Contract links (Phase 4)+ if enricher.has_contract_data:+ provider_links = enricher.get_contract_links_as_provider(ctx.alias, target_key)+ consumer_links = enricher.get_contract_links_as_consumer(ctx.alias, target_key)+ if provider_links or consumer_links:+ contracts: dict[str, Any] = {}+ if provider_links:+ contracts["consumers"] = [+ {+ "consumer_repo": lk["consumer_repo"],+ "contract_id": lk["contract_id"],+ "type": lk["contract_type"],+ }+ for lk in provider_links[:5]+ ]+ if consumer_links:+ contracts["providers"] = [+ {+ "provider_repo": lk["provider_repo"],+ "contract_id": lk["contract_id"],+ "type": lk["contract_type"],+ }+ for lk in consumer_links[:5]+ ]+ cross_repo["contracts"] = contracts++ if cross_repo:+ target_data["cross_repo"] = cross_repo++ # Enforce the global token cap. See ``_truncate_to_budget`` for strategy.+ return _truncate_to_budget(response)diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.pynew file mode 100644index 000000000..cf22f2f72--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py@@ -0,0 +1,336 @@+"""Optional enrichment blocks for get_context.++Each helper resolves one ``include=`` block (callers/callees, metrics,+community, health) and attaches it to ``result_data`` in place. They are split+out of the main target resolver so the orchestrator and the resolver read as+dispatch rather than one long body.+"""++from __future__ import annotations++import json+from typing import Any++from sqlalchemy import select+from sqlalchemy.ext.asyncio import AsyncSession++from repowise.core.persistence.crud import (+ get_all_file_metrics,+ get_community_members,+ get_cross_community_edges,+ get_graph_edges_for_node,+ get_graph_node,+ get_graph_nodes_by_ids,+ get_node_degree_counts,+)+from repowise.core.persistence.models import (+ CoverageFile,+ GraphNode,+ HealthFileMetric,+ HealthFinding,+ Repository,+)++# Minimum confidence for call edges to filter false positives+_MIN_CALL_CONFIDENCE = 0.7+++async def _resolve_call_graph(+ session: AsyncSession,+ repository: Repository,+ target: str,+ target_type: str | None,+ result_data: dict[str, Any],+ *,+ want_callers: bool = False,+ want_callees: bool = False,+) -> None:+ """Resolve callers/callees for a symbol and attach to result_data."""+ repo_id = repository.id+ limit = 20++ # Resolve to a graph node (symbol)+ node = await get_graph_node(session, repo_id, target)+ if node is None and "::" in target:+ # Fuzzy: try bare name+ bare_name = target.split("::")[-1]+ res = await session.execute(+ select(GraphNode).where(+ GraphNode.repository_id == repo_id,+ GraphNode.node_type == "symbol",+ GraphNode.name == bare_name,+ )+ )+ rows = list(res.scalars().all())+ if rows:+ file_hint = target.split("::")[0]+ node = next((r for r in rows if r.file_path == file_hint), rows[0])++ if node is None or node.node_type != "symbol":+ # For file targets, return empty with explanation — callers/callees is symbol-only+ if want_callers:+ result_data["callers"] = []+ if want_callees:+ result_data["callees"] = []+ if node is not None and node.node_type != "symbol":+ result_data["_call_graph_note"] = (+ "callers/callees require a symbol target (function/class/method), "+ f"but '{target}' is a {node.node_type}. Pass a symbol name or file::Symbol."+ )+ return++ direction = "both"+ if want_callers and not want_callees:+ direction = "callers"+ elif want_callees and not want_callers:+ direction = "callees"++ edges = await get_graph_edges_for_node(+ session,+ repo_id,+ node.node_id,+ direction=direction,+ edge_types=["calls", "extends", "implements"],+ limit=limit,+ )++ # Hydrate other nodes+ other_ids = list(+ {e.source_node_id if e.target_node_id == node.node_id else e.target_node_id for e in edges}+ )+ node_map = await get_graph_nodes_by_ids(session, repo_id, other_ids)++ callers: list[dict[str, Any]] = []+ callees: list[dict[str, Any]] = []++ for e in edges:+ # Filter out low-confidence edges (false positives from Tier 3 global resolution)+ if (e.confidence or 0) < _MIN_CALL_CONFIDENCE:+ continue++ is_caller = e.target_node_id == node.node_id+ other_id = e.source_node_id if is_caller else e.target_node_id+ other_node = node_map.get(other_id)++ entry: dict[str, Any] = {+ "symbol_id": other_id,+ "name": other_node.name+ if other_node+ else (other_id.split("::")[-1] if "::" in other_id else other_id),+ "kind": other_node.kind if other_node else None,+ "file": other_node.file_path+ if other_node+ else (other_id.split("::")[0] if "::" in other_id else other_id),+ "confidence": e.confidence,+ "edge_type": e.edge_type,+ }+ if is_caller:+ callers.append(entry)+ else:+ callees.append(entry)++ # Sort by confidence DESC+ callers.sort(key=lambda x: -(x.get("confidence") or 0))+ callees.sort(key=lambda x: -(x.get("confidence") or 0))++ if want_callers:+ result_data["callers"] = callers+ if want_callees:+ result_data["callees"] = callees+++async def _resolve_metrics(+ session: AsyncSession,+ repository: Repository,+ target: str,+ result_data: dict[str, Any],+) -> None:+ """Resolve graph importance metrics and attach to result_data["metrics"]."""+ repo_id = repository.id++ node = await get_graph_node(session, repo_id, target)+ if node is None:+ result_data["metrics"] = None+ return++ try:+ meta = json.loads(node.community_meta_json or "{}")+ except (json.JSONDecodeError, TypeError):+ meta = {}++ degrees = await get_node_degree_counts(session, repo_id, node.node_id)++ # Percentile computation against same-type peers+ all_nodes = await get_all_file_metrics(session, repo_id)+ pr_values = [n.pagerank for n in all_nodes if n.pagerank is not None]+ bt_values = [n.betweenness for n in all_nodes if n.betweenness is not None]++ def _pct(value: float, all_vals: list[float]) -> int:+ if not all_vals:+ return 0+ return round(100 * sum(1 for v in all_vals if v < value) / len(all_vals))++ result_data["metrics"] = {+ "pagerank": round(node.pagerank or 0.0, 6),+ "pagerank_percentile": _pct(node.pagerank or 0.0, pr_values),+ "betweenness": round(node.betweenness or 0.0, 6),+ "betweenness_percentile": _pct(node.betweenness or 0.0, bt_values),+ "in_degree": degrees["in_degree"],+ "out_degree": degrees["out_degree"],+ "community_id": node.community_id,+ "community_label": meta.get("label") or None,+ }+++async def _resolve_community(+ session: AsyncSession,+ repository: Repository,+ target: str,+ result_data: dict[str, Any],+) -> None:+ """Resolve community membership and attach to result_data["community"]."""+ repo_id = repository.id++ node = await get_graph_node(session, repo_id, target)+ if node is None or node.community_id is None:+ result_data["community"] = None+ return++ try:+ meta = json.loads(node.community_meta_json or "{}")+ except (json.JSONDecodeError, TypeError):+ meta = {}++ label = meta.get("label") or f"cluster_{node.community_id}"+ cohesion = float(meta.get("cohesion", 0.0) or 0.0)++ # Get top members (cap at 10 for compact output)+ members = await get_community_members(session, repo_id, node.community_id, limit=10)+ member_paths = [m.node_id for m in members]++ # Neighboring communities (cap at 5)+ cross_edges = await get_cross_community_edges(session, repo_id, node.community_id)+ neighbors: list[dict[str, Any]] = []+ for ce in cross_edges[:5]:+ nid = ce["target_community_id"]+ nm = await get_community_members(session, repo_id, nid, limit=1)+ nlabel = ""+ if nm:+ try:+ nmeta = json.loads(nm[0].community_meta_json or "{}")+ nlabel = nmeta.get("label", "")+ except (json.JSONDecodeError, TypeError):+ pass+ neighbors.append(+ {+ "id": nid,+ "label": nlabel or f"cluster_{nid}",+ "cross_edges": ce["edge_count"],+ }+ )++ result_data["community"] = {+ "id": node.community_id,+ "label": label,+ "cohesion": round(cohesion, 3),+ "top_members": member_paths,+ "neighbors": neighbors,+ }+++async def _resolve_health(+ session: AsyncSession,+ repository: Repository,+ target: str,+ target_type: str,+ result_data: dict[str, Any],+) -> None:+ """Attach per-file health metric + top 2 biomarkers + coverage row.++ Only meaningful for *file* targets. For symbol targets we resolve the+ enclosing file path via the already-computed ``file_path_for_git`` is+ not available here — we fall back to ``target`` when ``target_type``+ is ``"file"`` and otherwise inspect the target string for a+ ``"path::symbol"`` separator.+ """+ file_path: str | None+ if target_type == "file":+ file_path = target+ elif "::" in target:+ file_path = target.split("::", 1)[0]+ else:+ file_path = None++ if not file_path:+ result_data["health"] = None+ return++ repo_id = repository.id+ metric = (+ await session.execute(+ select(HealthFileMetric).where(+ HealthFileMetric.repository_id == repo_id,+ HealthFileMetric.file_path == file_path,+ )+ )+ ).scalar_one_or_none()++ if metric is None:+ result_data["health"] = None+ return++ findings_res = await session.execute(+ select(HealthFinding)+ .where(+ HealthFinding.repository_id == repo_id,+ HealthFinding.file_path == file_path,+ HealthFinding.status == "open",+ )+ .order_by(HealthFinding.health_impact.desc())+ .limit(2)+ )+ from repowise.core.analysis.health.suggestions import suggestion_for++ top_biomarkers = [+ {+ "biomarker_type": f.biomarker_type,+ "severity": f.severity,+ "function_name": f.function_name,+ "impact": round(f.health_impact, 2),+ "suggestion": suggestion_for(f.biomarker_type),+ }+ for f in findings_res.scalars().all()+ ]++ coverage_row = (+ await session.execute(+ select(CoverageFile).where(+ CoverageFile.repository_id == repo_id,+ CoverageFile.file_path == file_path,+ )+ )+ ).scalar_one_or_none()++ health: dict[str, Any] = {+ "score": round(metric.score, 2),+ "max_ccn": metric.max_ccn,+ "max_nesting": metric.max_nesting,+ "nloc": metric.nloc,+ "has_test_file": metric.has_test_file,+ "module": metric.module,+ "duplication_pct": metric.duplication_pct,+ "top_biomarkers": top_biomarkers,+ }+ if coverage_row is not None:+ health["coverage"] = {+ "source_format": coverage_row.source_format,+ "line_coverage_pct": coverage_row.line_coverage_pct,+ "branch_coverage_pct": coverage_row.branch_coverage_pct,+ "total_coverable_lines": coverage_row.total_coverable_lines,+ }+ elif metric.line_coverage_pct is not None:+ health["coverage"] = {+ "line_coverage_pct": metric.line_coverage_pct,+ "branch_coverage_pct": metric.branch_coverage_pct,+ }+ result_data["health"] = healthdiff --git a/packages/server/src/repowise/server/mcp_server/tool_context/kg.py b/packages/server/src/repowise/server/mcp_server/tool_context/kg.pynew file mode 100644index 000000000..64097635e--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_context/kg.py@@ -0,0 +1,43 @@+"""Knowledge-graph layer / tour / role helpers for get_context."""++from __future__ import annotations++import json+from typing import Any+++def _find_layer_for_file(path: str, layers: list) -> Any | None:+ for layer in layers:+ node_ids = getattr(layer, "_parsed_node_ids", None)+ if node_ids is None:+ node_ids = json.loads(layer.node_ids_json) if layer.node_ids_json else []+ if f"file:{path}" in node_ids or path in node_ids:+ return layer+ return None+++def _find_tour_step_for_file(path: str, steps: list) -> Any | None:+ for step in steps:+ node_ids = getattr(step, "_parsed_node_ids", None)+ if node_ids is None:+ node_ids = json.loads(step.node_ids_json) if step.node_ids_json else []+ if f"file:{path}" in node_ids or path in node_ids:+ return step+ return None+++def _classify_file_role(path: str, layer: Any, incoming_edges: list) -> str:+ raw = getattr(layer, "_parsed_node_ids", None)+ if raw is None:+ raw = json.loads(layer.node_ids_json) if layer.node_ids_json else []+ node_ids = set(raw)+ cross_layer = [+ e+ for e in incoming_edges+ if f"file:{e.source_node_id}" not in node_ids and e.source_node_id not in node_ids+ ]+ if cross_layer:+ return "edge_connector"+ if not incoming_edges:+ return "entry_point"+ return "internal"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.pynew file mode 100644index 000000000..10153d353--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py@@ -0,0 +1,633 @@+"""Single-target resolution for get_context.++``_resolve_one_target`` walks the file → module → symbol → fallback ladder for+one target and assembles its triage card (docs, triage signals, ownership,+last_change, decisions, freshness, KG layer/tour, and the opt-in enrichment+blocks delegated to ``enrichment``).+"""++from __future__ import annotations++import json+from typing import Any++from sqlalchemy import select+from sqlalchemy.ext.asyncio import AsyncSession++from repowise.core.persistence.crud import get_kg_layers, get_kg_tour_steps+from repowise.core.persistence.decision_graph import get_governing_decisions+from repowise.core.persistence.models import (+ DecisionRecord,+ GitMetadata,+ GraphEdge,+ GraphNode,+ Page,+ Repository,+ WikiSymbol,+)+from repowise.server.mcp_server.tool_context.enrichment import (+ _resolve_call_graph,+ _resolve_community,+ _resolve_health,+ _resolve_metrics,+)+from repowise.server.mcp_server.tool_context.kg import (+ _classify_file_role,+ _find_layer_for_file,+ _find_tour_step_for_file,+)+++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.++ Used in --index-only mode (no wiki pages) and as a fallback when an LLM+ page predates the summary column. Always returns a non-empty string so the+ agent never sees a missing field.+ """+ name = file_path.rsplit("/", 1)[-1]+ parts: list[str] = []+ if classes:+ head = ", ".join(classes[:3])+ more = f" (+{len(classes) - 3} more)" if len(classes) > 3 else ""+ parts.append(f"defines {head}{more}")+ if functions:+ head = ", ".join(functions[:3])+ more = f" (+{len(functions) - 3} more)" if len(functions) > 3 else ""+ parts.append(f"function{'s' if len(functions) > 1 else ''} {head}{more}")+ if not parts:+ return f"{name}: empty or non-symbol file"+ return f"{name}: " + "; ".join(parts) + "."+++async def _resolve_one_target(+ session: AsyncSession,+ repository: Repository,+ target: str,+ include: set[str] | None,+ compact: bool = False,+) -> 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:+ # 1b. Normalise directory targets: strip trailing slash and try module+ clean_target = target.rstrip("/")+ # 2. Try module page (exact, then cleaned, then partial)+ res = await session.execute(+ select(Page).where(+ Page.repository_id == repo_id,+ Page.page_type == "module_page",+ Page.target_path == target,+ )+ )+ page = res.scalar_one_or_none()+ if page is None and clean_target != target:+ res = await session.execute(+ select(Page).where(+ Page.repository_id == repo_id,+ Page.page_type == "module_page",+ Page.target_path == clean_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),+ )+ )+ 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,+ )+ )+ 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:+ # Fallback 1: index-only mode (no wiki pages) — return graph node + symbols if present+ res = await session.execute(+ select(GraphNode).where(+ GraphNode.repository_id == repo_id,+ GraphNode.node_id == target,+ )+ )+ gnode = res.scalar_one_or_none()+ if gnode is not None:+ target_type = "file"+ file_path_for_git = target+ page = None # no wiki page; subsequent blocks must guard for this++ # Fallback 2: check git_metadata — file may exist but have no wiki page AND no graph node+ if target_type is None:+ res = await session.execute(+ select(GitMetadata).where(+ GitMetadata.repository_id == repo_id,+ GitMetadata.file_path == target,+ )+ )+ meta = res.scalar_one_or_none()+ if meta:+ return {+ "target": target,+ "error": (+ f"'{target}' exists in the repository but has no wiki page. "+ "This usually means the file has too few symbols or is below "+ "the PageRank threshold. Run `repowise update` to regenerate docs."+ ),+ "exists_in_git": True,+ "last_commit_at": meta.last_commit_at.isoformat()+ if meta.last_commit_at+ else None,+ "primary_owner": meta.primary_owner_name,+ "is_hotspot": meta.is_hotspot,+ }++ # 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:+ # For directory-like targets, suggest files within that directory+ dir_prefix = clean_target.rstrip("/") + "/"+ res = await session.execute(+ select(GitMetadata.file_path)+ .where(+ GitMetadata.repository_id == repo_id,+ GitMetadata.file_path.like(f"{dir_prefix}%"),+ )+ .limit(5)+ )+ suggestions = [row[0] for row in res.all()]+ if not suggestions:+ # Fall back to filename / partial path match+ tail = target.rsplit("/", 1)[-1]+ res = await session.execute(+ select(GitMetadata.file_path)+ .where(+ GitMetadata.repository_id == repo_id,+ GitMetadata.file_path.contains(tail),+ )+ .limit(5)+ )+ suggestions = [row[0] for row in res.all() if row[0] != target]+ if suggestions:+ return {+ "target": target,+ "error": f"Target not found: '{target}'",+ "suggestions": suggestions,+ }+ return {"target": target, "error": f"Target not found: '{target}'"}++ result_data["target"] = target+ result_data["type"] = target_type++ # --- Docs ---+ # "full_doc" implies "docs" — entering the docs block whenever either is requested.+ if include is None or "docs" in include or "full_doc" in include:+ want_full_doc = bool(include and "full_doc" in include)+ docs: dict[str, Any] = {}+ if target_type == "file":+ if page is not None:+ docs["title"] = page.title+ docs["summary"] = page.summary or ""+ if want_full_doc:+ docs["content_md"] = page.content+ if page.human_notes:+ docs["human_notes"] = page.human_notes+ # Symbols in this file+ res = await session.execute(+ select(WikiSymbol).where(+ WikiSymbol.repository_id == repo_id,+ WikiSymbol.file_path == target,+ )+ )+ symbols = res.scalars().all()+ classes = [s.name for s in symbols if s.kind == "class"]+ functions = [s.name for s in symbols if s.kind in ("function", "method")]+ if compact:+ # Compact mode: name+kind+signature+line+symbol_id only. Drops+ # docstrings, line ranges, structure, and imported_by — those+ # live behind compact=False or include= flags. The symbol_id+ # is the canonical handle the caller pipes straight into+ # get_symbol when it wants bytes.+ #+ # Cap at 40 symbols so a dense generated file (protobuf+ # wrappers, vendored libs) can't blow the triage card past+ # the agent's budget. Order matches WikiSymbol.start_line+ # (assigned at index time), so the head is the navigationally+ # useful slice.+ symbol_cap = 40+ visible = list(symbols)[:symbol_cap]+ docs["symbols"] = [+ {+ "name": s.name,+ "kind": s.kind,+ "signature": s.signature,+ "line": s.start_line,+ "symbol_id": s.symbol_id,+ }+ for s in visible+ ]+ if len(symbols) > symbol_cap:+ docs["symbols_truncated"] = {+ "shown": symbol_cap,+ "total": len(symbols),+ "hint": "Call with compact=False or include=['full_doc'] for the full list.",+ }+ if not docs.get("summary"):+ docs["summary"] = _synthesize_structural_summary(target, classes, functions)+ else:+ docs["symbols"] = [+ {+ "name": s.name,+ "kind": s.kind,+ "signature": s.signature,+ "start_line": s.start_line,+ "end_line": s.end_line,+ "docstring": (s.docstring or "")[:400],+ }+ for s in symbols+ ]+ # Structure summary block — quick scan of what's in the file+ total_loc = max((s.end_line for s in symbols), default=0)+ avg_complexity = (+ sum(s.complexity_estimate for s in symbols) / len(symbols) if symbols else 0+ )+ docs["structure"] = {+ "classes": classes,+ "functions": functions,+ "symbol_count": len(symbols),+ "total_loc": total_loc,+ "avg_complexity": round(avg_complexity, 2),+ }+ # Fallback summary: if no Page (index-only mode) or page.summary+ # is empty, synthesize a deterministic one-liner from structure.+ if not docs.get("summary"):+ docs["summary"] = _synthesize_structural_summary(target, classes, functions)+ # 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]++ # Community info (compact=False only, ~80 bytes)+ res = await session.execute(+ select(GraphNode).where(+ GraphNode.repository_id == repo_id,+ GraphNode.node_id == target,+ )+ )+ gn = res.scalar_one_or_none()+ if gn and gn.community_id is not None:+ _cmeta: dict[str, Any] = {}+ try:+ _cmeta = json.loads(gn.community_meta_json or "{}")+ except (json.JSONDecodeError, TypeError):+ pass+ docs["community"] = {+ "id": gn.community_id,+ "label": _cmeta.get("label", ""),+ }++ elif target_type == "module":+ docs["title"] = page.title+ docs["summary"] = page.summary or ""+ if want_full_doc:+ 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+ ]++ 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 summary (full content gated behind include=["full_doc"])+ sym_page_id = f"file_page:{sym.file_path}"+ sym_page = await session.get(Page, sym_page_id)+ if sym_page is not None:+ docs["file_summary"] = sym_page.summary or ""+ if want_full_doc:+ docs["documentation"] = sym_page.content+ # 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++ # --- Triage signals (always on) ---------------------------------------+ # Two single-bit-ish pointers the agent uses to decide its next move:+ # * ``hotspot``: lights the way to ``get_risk`` for files in the 95th++ # churn percentile. Just the boolean — the full risk dossier stays+ # in ``get_risk`` so the triage card doesn't grow.+ # * ``decision_records``: titles only, no body. Lights the way to+ # ``get_why``. We deliberately don't inline the rationale here;+ # duplicating it across every ``get_context`` response bloats the+ # cached prompt prefix and defeats the split between the two tools.+ #+ # Cheap: two short queries piggybacking on the session we already opened.+ triage_path = file_path_for_git+ if target_type == "module" and page:+ triage_path = page.target_path+ if triage_path:+ triage_meta_res = await session.execute(+ select(GitMetadata.is_hotspot).where(+ GitMetadata.repository_id == repo_id,+ GitMetadata.file_path == triage_path,+ )+ )+ triage_meta = triage_meta_res.scalar_one_or_none()+ result_data["hotspot"] = bool(triage_meta) if triage_meta is not None else False++ # Bounded graph-link query — replaces full Python scan over all rows.+ governing: list[DecisionRecord] = []+ seen_ids: set[str] = set()+ for lookup_node in dict.fromkeys(+ [triage_path, target] if triage_path != target else [triage_path]+ ):+ if not lookup_node:+ continue+ for dr in await get_governing_decisions(session, repo_id, lookup_node):+ if dr.id not in seen_ids:+ seen_ids.add(dr.id)+ governing.append(dr)+ if governing:+ result_data["decision_records"] = [dr.title for dr in governing[:5]]+ result_data["decision_records_hint"] = (+ "Decisions touch this file. Call get_why(targets=[...]) for rationale."+ )+ # Compact enriched list — highest-confidence first, capped at 5.+ governing_sorted = sorted(governing, key=lambda d: -(d.confidence or 0.0))+ result_data["governing_decisions"] = [+ {+ "id": dr.id,+ "title": dr.title,+ "status": dr.status,+ "staleness_score": dr.staleness_score,+ "verification": dr.verification,+ "stale": bool(dr.status == "active" and (dr.staleness_score or 0.0) >= 0.5),+ }+ for dr in governing_sorted[:5]+ ]++ # --- 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"] = getattr(meta, "contributor_count", 0) or len(+ json.loads(meta.top_authors_json)+ )+ ownership["bus_factor"] = getattr(meta, "bus_factor", 0) or 0+ # Recent owner (who maintains this file now)+ recent = getattr(meta, "recent_owner_name", None)+ if recent and recent != meta.primary_owner_name:+ ownership["recent_owner"] = recent+ ownership["recent_owner_pct"] = getattr(meta, "recent_owner_commit_pct", None)+ else:+ ownership["primary_owner"] = None+ ownership["owner_pct"] = None+ ownership["contributor_count"] = 0+ ownership["bus_factor"] = 0+ else:+ ownership["primary_owner"] = None+ ownership["owner_pct"] = None+ ownership["contributor_count"] = 0+ ownership["bus_factor"] = 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+ or (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++ # --- KG layer + tour context (Phase 9) ---+ if target_type == "file" and file_path_for_git:+ kg_layers = await get_kg_layers(session, repo_id)+ if kg_layers:+ for _l in kg_layers:+ _l._parsed_node_ids = json.loads(_l.node_ids_json) if _l.node_ids_json else []+ file_layer = _find_layer_for_file(file_path_for_git, kg_layers)+ if file_layer:+ edge_res = await session.execute(+ select(GraphEdge).where(+ GraphEdge.repository_id == repo_id,+ GraphEdge.target_node_id == file_path_for_git,+ GraphEdge.edge_type == "imports",+ )+ )+ incoming_edges = list(edge_res.scalars())+ result_data["architectural_layer"] = {+ "name": file_layer.name,+ "description": (file_layer.description or "")[:200],+ "role": _classify_file_role(file_path_for_git, file_layer, incoming_edges),+ }++ kg_tour = await get_kg_tour_steps(session, repo_id)+ if kg_tour:+ for _s in kg_tour:+ _s._parsed_node_ids = json.loads(_s.node_ids_json) if _s.node_ids_json else []+ file_tour_step = _find_tour_step_for_file(file_path_for_git, kg_tour)+ if file_tour_step:+ result_data["tour_context"] = {+ "step": file_tour_step.step_order,+ "title": file_tour_step.title,+ "why": (file_tour_step.description or "")[:200],+ }++ # --- Callers / Callees (replaces get_callers_callees) ---+ want_callers = bool(include and "callers" in include)+ want_callees = bool(include and "callees" in include)+ if want_callers or want_callees:+ await _resolve_call_graph(+ session,+ repository,+ target,+ target_type,+ result_data,+ want_callers=want_callers,+ want_callees=want_callees,+ )++ # --- Metrics (replaces get_graph_metrics) ---+ if include and "metrics" in include:+ await _resolve_metrics(session, repository, target, result_data)++ # --- Community (replaces get_community) ---+ if include and "community" in include:+ await _resolve_community(session, repository, target, result_data)++ # --- Code health (Phase 2) ---+ if include and "health" in include:+ await _resolve_health(session, repository, target, target_type, result_data)++ return result_datadiff --git a/packages/server/src/repowise/server/mcp_server/tool_context/truncation.py b/packages/server/src/repowise/server/mcp_server/tool_context/truncation.pynew file mode 100644index 000000000..33103077e--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_context/truncation.py@@ -0,0 +1,242 @@+"""Output-size budgeting for get_context.++The Claude Code harness rejects MCP tool results whose stringified form exceeds+~10k tokens, so get_context caps its response well below that. This module owns+the budget constants and the truncation strategy.+"""++from __future__ import annotations++import json+import logging+from typing import Any++logger = logging.getLogger(__name__)++# --- Output size budget -------------------------------------------------------+# The Claude Code harness rejects MCP tool results whose stringified form exceeds+# ~10k tokens (it refuses to inline them and then refuses to Read the spilled+# file). When that happens the agent falls back to multiple get_symbol calls,+# each of which re-plays the cached system prompt — a significant cost driver+# on dense files in long multi-turn agent sessions.+#+# We therefore cap get_context output well below that ceiling. 8000 tokens+# leaves headroom for the wrapping JSON envelope and _meta fields the harness+# adds on top. The estimator is intentionally dependency-free: 4 chars/token is+# the widely-quoted average for English + code on BPE tokenizers and is within+# ~20% of tiktoken for typical wiki content. Precise counting is unnecessary+# because we only need to stay comfortably under the hard limit.+_TOKEN_BUDGET = 8000+_CHARS_PER_TOKEN = 4+_CHAR_BUDGET = _TOKEN_BUDGET * _CHARS_PER_TOKEN+++def _estimate_tokens(obj: Any) -> int:+ """Cheap upper-bound token estimate for an arbitrary JSON-serialisable object.++ Serialises to compact JSON (the wire format the MCP layer eventually emits)+ and divides by ``_CHARS_PER_TOKEN``. We use the serialised form — not just+ raw text fields — because structural JSON overhead (quotes, braces, field+ names) is non-trivial and is what the downstream tokenizer actually sees.+ """+ return len(json.dumps(obj, separators=(",", ":"), default=str)) // _CHARS_PER_TOKEN+++# Heavy optional fields we can strip from a target's docs block without losing+# its identity. Ordering matters: earlier entries are dropped first because they+# carry the most bytes per unit of navigational value.+_HEAVY_DOC_FIELDS: tuple[str, ...] = ("content_md", "documentation", "file_summary")+++def _symbol_priority(sym: dict[str, Any], query_terms: set[str]) -> tuple[int, int, int]:+ """Return a sort key (higher = keep) for a symbol within a target.++ Priority order (language-agnostic — no Python-specific heuristics):+ 1. Exact name match against any user query term.+ 2. Substring / case-insensitive match against query terms.+ 3. Kind rank: classes/types outrank functions/methods which outrank the+ rest. This mirrors navigational usefulness across Python, TS, Go,+ Rust, C++, etc. where a type anchors a module more than a helper fn.+ 4. PageRank / centrality if present on the dict (forward-compatible —+ ``get_context`` doesn't currently populate it but ``_resolve_one_target``+ may in the future).+ """+ name = (sym.get("name") or "").lower()+ exact = 1 if name and name in query_terms else 0+ fuzzy = 1 if any(t and t in name for t in query_terms) else 0+ kind = (sym.get("kind") or "").lower()+ kind_rank = {+ "class": 3,+ "interface": 3,+ "struct": 3,+ "trait": 3,+ "type": 3,+ "enum": 3,+ "function": 2,+ "method": 2,+ }.get(kind, 1)+ centrality = int((sym.get("pagerank") or sym.get("centrality") or 0) * 1000)+ return (exact * 10 + fuzzy * 5 + kind_rank, centrality, -len(json.dumps(sym, default=str)))+++def _query_terms_for(target: str) -> set[str]:+ """Derive cheap query terms from a target string for symbol prioritisation.++ ``get_context`` has no explicit query argument, so we fall back to the+ target identifier itself — the tail of a file path, or the raw symbol name.+ This is deliberately coarse: it just nudges symbol retention toward the+ thing the caller asked about.+ """+ tail = target.rsplit("/", 1)[-1].lower()+ # Strip common extension if present (language-agnostic: split once on '.').+ if "." in tail:+ tail = tail.rsplit(".", 1)[0]+ return {t for t in (tail, target.lower()) if t}+++def _truncate_to_budget(+ result: dict[str, Any],+ char_budget: int = _CHAR_BUDGET,+) -> dict[str, Any]:+ """Cap the ``get_context`` response at roughly ``_TOKEN_BUDGET`` tokens.++ Strategy (applied in order, stopping as soon as the budget is met):++ 1. **Strip heavy optional doc fields** (``content_md``, ``documentation``,+ ``file_summary``) from each target. These are 1–2k tokens apiece and+ duplicate information the agent can re-request via ``full_doc``.+ 2. **Shrink symbol lists within each target**, keeping the highest-priority+ symbols per ``_symbol_priority``. This preserves the navigational index+ (names, signatures, line numbers) while dropping bulk docstrings.+ 3. **Drop whole targets** from the tail of the list. Per spec we prefer+ keeping fewer full-fidelity targets over many stubs, so once symbols+ can't shrink further we evict entire targets rather than gutting them.++ Adds ``truncated: bool``, ``dropped_targets: list[str]``, and+ ``dropped_symbols: dict[target, list[name]]`` top-level fields — additive+ only, existing callers are unaffected.++ Edge cases:+ * Empty ``targets`` → returns unchanged with ``truncated=False``.+ * A single target whose symbol list alone busts the budget → we reduce+ symbols down to 1 and accept the overshoot rather than returning an+ empty response. The ``truncated`` flag still fires.+ * Targets that carry an ``error`` field (not-found) are cheap and are+ preserved unless literally nothing else fits.+ """+ result.setdefault("truncated", False)+ result.setdefault("dropped_targets", [])+ result.setdefault("dropped_symbols", {})++ targets: dict[str, Any] = result.get("targets") or {}+ if not targets:+ return result++ def _size() -> int:+ return len(json.dumps(result, separators=(",", ":"), default=str))++ if _size() <= char_budget:+ return result++ # Stage 1: strip heavy optional doc fields across all targets.+ for name, tgt in targets.items():+ docs = tgt.get("docs") if isinstance(tgt, dict) else None+ if not isinstance(docs, dict):+ continue+ for field in _HEAVY_DOC_FIELDS:+ if field in docs:+ docs.pop(field, None)+ result["truncated"] = True+ if _size() <= char_budget:+ return result++ # Stage 2: prioritise symbols within each target. We iterate from the+ # largest target down so the biggest offenders shrink first.+ def _target_cost(item: tuple[str, Any]) -> int:+ return len(json.dumps(item[1], default=str))++ for tgt_name, tgt in sorted(targets.items(), key=_target_cost, reverse=True):+ docs = tgt.get("docs") if isinstance(tgt, dict) else None+ if not isinstance(docs, dict):+ continue+ symbols = docs.get("symbols")+ if not isinstance(symbols, list) or not symbols:+ continue+ query_terms = _query_terms_for(tgt_name)+ ordered = sorted(symbols, key=lambda s: _symbol_priority(s, query_terms), reverse=True)++ # Per-symbol greedy fit. The cost of the whole response with a symbol+ # list ``S`` is exactly:+ # base + sum(cost(s) for s in S) + max(0, len(S) - 1)+ # where ``base`` is the response size with this target's ``symbols``+ # emptied and ``cost(s)`` is the symbol's compact-JSON length. Both are+ # context-independent under the compact separators we serialise with,+ # so we precompute each symbol's cost ONCE and track a running sum+ # instead of re-serialising the entire response per candidate symbol+ # (the old O(targets × symbols²) behaviour). The keep/drop decision is+ # byte-for-byte identical to the previous ``_size()``-per-symbol loop.+ costs = [len(json.dumps(s, separators=(",", ":"), default=str)) for s in ordered]+ docs["symbols"] = []+ base = _size()+ kept: list[dict[str, Any]] = []+ dropped: list[str] = []+ sum_kept = 0+ for sym, cost in zip(ordered, costs, strict=True):+ # Tentative size if we add this symbol to the current kept set:+ # the +len(kept) term is the comma separators for kept+1 entries.+ tentative = base + sum_kept + cost + len(kept)+ if tentative <= char_budget:+ kept.append(sym)+ sum_kept += cost+ else:+ dropped.append(sym.get("name") or "<anonymous>")+ if not kept and ordered:+ # Edge case: a single symbol is larger than the budget. Keep one+ # (truncating its docstring) rather than returning zero symbols —+ # the caller at least learns the target resolved.+ head = dict(ordered[0])+ if isinstance(head.get("docstring"), str):+ head["docstring"] = head["docstring"][:200]+ kept = [head]+ dropped = [s.get("name") or "<anonymous>" for s in ordered[1:]]+ docs["symbols"] = kept+ if dropped:+ result["dropped_symbols"][tgt_name] = dropped+ result["truncated"] = True+ if _size() <= char_budget:+ return result++ # Stage 3: drop whole targets, largest first, until we fit. Prefer to keep+ # error-only targets (they're tiny and signal "not found" to the caller).+ def _evictable_order() -> list[str]:+ items = list(targets.items())+ items.sort(+ key=lambda kv: (+ 0 if isinstance(kv[1], dict) and "error" in kv[1] else 1,+ len(json.dumps(kv[1], default=str)),+ ),+ reverse=True,+ )+ return [k for k, _ in items]++ for name in _evictable_order():+ if len(targets) <= 1:+ break+ targets.pop(name, None)+ result["dropped_targets"].append(name)+ result["truncated"] = True+ if _size() <= char_budget:+ break++ if result["truncated"]:+ logger.info(+ "get_context truncated to budget",+ extra={+ "char_budget": char_budget,+ "token_budget": _TOKEN_BUDGET,+ "final_chars": _size(),+ "dropped_targets": result["dropped_targets"],+ "dropped_symbol_counts": {k: len(v) for k, v in result["dropped_symbols"].items()},+ },+ )+ return resultdiff --git a/tests/unit/server/test_truncate_budget_equivalence.py b/tests/unit/server/test_truncate_budget_equivalence.pynew file mode 100644index 000000000..8222eec67--- /dev/null+++ b/tests/unit/server/test_truncate_budget_equivalence.py@@ -0,0 +1,167 @@+"""Characterisation test for the _truncate_to_budget O(n^2) -> O(n) optimisation.++The split of ``tool_context.py`` replaced the per-symbol full-response+re-serialisation in stage 2 of ``_truncate_to_budget`` with a precomputed+per-symbol cost + running sum. This test pins that the optimised implementation+produces a **byte-identical** result to the original implementation (embedded+here verbatim as ``_reference_truncate``) across a range of over-budget fixtures.+"""++from __future__ import annotations++import copy+import json++import pytest++from repowise.server.mcp_server.tool_context.truncation import (+ _HEAVY_DOC_FIELDS,+ _query_terms_for,+ _symbol_priority,+ _truncate_to_budget,+)+++def _reference_truncate(result: dict, char_budget: int) -> dict:+ """Verbatim copy of the original (pre-optimisation) _truncate_to_budget.++ Stage 2 re-serialises the whole response once per candidate symbol — the+ O(targets x symbols^2) behaviour the optimisation removes. Kept here purely+ as the oracle the optimised implementation must match exactly.+ """+ result.setdefault("truncated", False)+ result.setdefault("dropped_targets", [])+ result.setdefault("dropped_symbols", {})++ targets = result.get("targets") or {}+ if not targets:+ return result++ def _size() -> int:+ return len(json.dumps(result, separators=(",", ":"), default=str))++ if _size() <= char_budget:+ return result++ for _name, tgt in targets.items():+ docs = tgt.get("docs") if isinstance(tgt, dict) else None+ if not isinstance(docs, dict):+ continue+ for field in _HEAVY_DOC_FIELDS:+ if field in docs:+ docs.pop(field, None)+ result["truncated"] = True+ if _size() <= char_budget:+ return result++ def _target_cost(item):+ return len(json.dumps(item[1], default=str))++ for tgt_name, tgt in sorted(targets.items(), key=_target_cost, reverse=True):+ docs = tgt.get("docs") if isinstance(tgt, dict) else None+ if not isinstance(docs, dict):+ continue+ symbols = docs.get("symbols")+ if not isinstance(symbols, list) or not symbols:+ continue+ query_terms = _query_terms_for(tgt_name)+ ordered = sorted(symbols, key=lambda s: _symbol_priority(s, query_terms), reverse=True)+ kept: list[dict] = []+ dropped: list[str] = []+ for sym in ordered:+ docs["symbols"] = [*kept, sym]+ if _size() <= char_budget:+ kept.append(sym)+ else:+ dropped.append(sym.get("name") or "<anonymous>")+ if not kept and ordered:+ head = dict(ordered[0])+ if isinstance(head.get("docstring"), str):+ head["docstring"] = head["docstring"][:200]+ kept = [head]+ dropped = [s.get("name") or "<anonymous>" for s in ordered[1:]]+ docs["symbols"] = kept+ if dropped:+ result["dropped_symbols"][tgt_name] = dropped+ result["truncated"] = True+ if _size() <= char_budget:+ return result++ def _evictable_order():+ items = list(targets.items())+ items.sort(+ key=lambda kv: (+ 0 if isinstance(kv[1], dict) and "error" in kv[1] else 1,+ len(json.dumps(kv[1], default=str)),+ ),+ reverse=True,+ )+ return [k for k, _ in items]++ for name in _evictable_order():+ if len(targets) <= 1:+ break+ targets.pop(name, None)+ result["dropped_targets"].append(name)+ result["truncated"] = True+ if _size() <= char_budget:+ break++ return result+++def _make_response(n_targets: int, n_symbols: int, body_chars: int, docstring_chars: int) -> dict:+ """Build a synthetic get_context response large enough to exceed a budget."""+ targets: dict[str, dict] = {}+ for ti in range(n_targets):+ path = f"src/pkg{ti}/module_{ti}.py"+ symbols = [+ {+ "name": f"sym_{ti}_{si}",+ "kind": ["class", "function", "method", "helper"][si % 4],+ "signature": f"def sym_{ti}_{si}(arg0, arg1, arg2) -> None",+ "start_line": si * 5 + 1,+ "end_line": si * 5 + 4,+ "docstring": ("d" * docstring_chars),+ }+ for si in range(n_symbols)+ ]+ targets[path] = {+ "target": path,+ "type": "file",+ "docs": {+ "title": f"Module {ti}",+ "summary": "s" * 80,+ "content_md": "m" * body_chars,+ "symbols": symbols,+ },+ "hotspot": ti % 2 == 0,+ }+ return {"targets": targets, "_meta": {"timing_ms": 1.0}}+++ ("n_targets", "n_symbols", "body_chars", "docstring_chars", "budget"),+ [+ (4, 30, 4000, 120, 8000),+ (6, 60, 5000, 200, 8000),+ (1, 200, 0, 300, 8000), # single dense target, busts on symbols alone+ (3, 10, 0, 50, 2000), # tiny budget forces target eviction+ (10, 5, 1500, 40, 6000),+ (2, 1, 0, 50000, 4000), # single symbol larger than budget+ ],+)+def test_optimised_matches_reference(n_targets, n_symbols, body_chars, docstring_chars, budget):+ fixture = _make_response(n_targets, n_symbols, body_chars, docstring_chars)++ optimised = _truncate_to_budget(copy.deepcopy(fixture), char_budget=budget)+ reference = _reference_truncate(copy.deepcopy(fixture), char_budget=budget)++ # Byte-identical serialisation is the strongest possible equality check.+ assert json.dumps(optimised, sort_keys=True, default=str) == json.dumps(+ reference, sort_keys=True, default=str+ )+ # And the structural bookkeeping fields match exactly.+ assert optimised["truncated"] == reference["truncated"]+ assert optimised["dropped_targets"] == reference["dropped_targets"]+ assert optimised["dropped_symbols"] == reference["dropped_symbols"]