java-codebase-rag 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

mcp_v2.py

@@ -31,7 +31,7 @@ from index_common import SBERT_MODEL
 from java_codebase_rag.config import resolved_sbert_model_for_process_env
 from java_ontology import EDGE_SCHEMA, ResolveReason
 from kuzu_queries import KuzuGraph, OVERRIDE_AXIS_COMPOSED_EDGE_TYPES
-from mcp_hints import MCP_HINTS_FIELD_DESCRIPTION, generate_hints
+from mcp_hints import generate_hints, MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION
 from search_lancedb import TABLES, run_search
 
 DeclarationSymbolKind = Literal["class", "interface", "enum", "record", "annotation", "method", "constructor"]
@@ -175,6 +175,14 @@ class EdgeFilter(BaseModel):
 _NODEFILTER_FIELD_ORDER: tuple[str, ...] = tuple(NodeFilter.model_fields.keys())
 _EDGEFILTER_FIELD_ORDER: tuple[str, ...] = tuple(EdgeFilter.model_fields.keys())
 
+
+class StructuredHint(BaseModel):
+    label: str = ""
+    tool: Literal["search", "find", "describe", "neighbors", "resolve"]
+    args: dict[str, Any]
+    actionable: bool = True
+    reason: str = ""
+
 # Populated EdgeFilter field -> EDGE_SCHEMA attribute name used in Cypher pushdown.
 _EDGEFILTER_FIELD_TO_ATTR: dict[str, str] = {
     "min_confidence": "confidence",
@@ -340,6 +348,10 @@ def _edgefilter_applicability_error(edge_types: list[str], ef: EdgeFilter) -> st
     return None
 
 
+def _to_structured_hints(raw: list[Any]) -> list[StructuredHint]:
+    return [StructuredHint(label=h.label, tool=h.tool, args=h.args, actionable=h.actionable, reason=h.reason) for h in raw]
+
+
 def _coerce_edge_filter(
     value: EdgeFilter | dict[str, Any] | str | None,
 ) -> EdgeFilter | dict[str, Any] | None:
@@ -452,7 +464,8 @@ class SearchOutput(BaseModel):
         default=None,
         description="Echoed from the request — the page offset the server applied. None on success=False.",
     )
-    hints: list[str] = Field(default_factory=list, description=MCP_HINTS_FIELD_DESCRIPTION)
+    advisories: list[str] = Field(default_factory=list, description="Pure informational text with no tool call suggestion")
+    hints_structured: list[StructuredHint] = Field(default_factory=list, description=MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION)
 
 
 class FindOutput(BaseModel):
@@ -467,14 +480,16 @@ class FindOutput(BaseModel):
         default=None,
         description="Echoed from the request — the page offset the server applied. None on success=False.",
     )
-    hints: list[str] = Field(default_factory=list, description=MCP_HINTS_FIELD_DESCRIPTION)
+    advisories: list[str] = Field(default_factory=list, description="Pure informational text with no tool call suggestion")
+    hints_structured: list[StructuredHint] = Field(default_factory=list, description=MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION)
 
 
 class DescribeOutput(BaseModel):
     success: bool
     record: NodeRecord | None = None
     message: str | None = None
-    hints: list[str] = Field(default_factory=list, description=MCP_HINTS_FIELD_DESCRIPTION)
+    advisories: list[str] = Field(default_factory=list, description="Pure informational text with no tool call suggestion")
+    hints_structured: list[StructuredHint] = Field(default_factory=list, description=MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION)
 
 
 class NeighborsOutput(BaseModel):
@@ -485,7 +500,8 @@ class NeighborsOutput(BaseModel):
         default_factory=list,
         description="Echo of neighbors(edge_types=...) from the request; empty when success=False.",
     )
-    hints: list[str] = Field(default_factory=list, description=MCP_HINTS_FIELD_DESCRIPTION)
+    advisories: list[str] = Field(default_factory=list, description="Pure informational text with no tool call suggestion")
+    hints_structured: list[StructuredHint] = Field(default_factory=list, description=MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION)
 
 
 ResolveStatus = Literal["one", "many", "none"]
@@ -555,7 +571,8 @@ class ResolveOutput(BaseModel):
     candidates: list[ResolveCandidate] = Field(default_factory=list)
     message: str | None = None
     resolved_identifier: str | None = None
-    hints: list[str] = Field(default_factory=list, description=MCP_HINTS_FIELD_DESCRIPTION)
+    advisories: list[str] = Field(default_factory=list, description="Pure informational text with no tool call suggestion")
+    hints_structured: list[StructuredHint] = Field(default_factory=list, description=MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION)
 
 
 def _node_kind_from_id(
@@ -873,16 +890,16 @@ def search_v2(
             return SearchOutput(
                 success=False,
                 message=_filter_validation_error_message(exc),
-                hints=[],
+                advisories=[],
                 limit=None,
                 offset=None,
             )
         if nf and (err := _nodefilter_applicability_error("symbol", nf)):
             _log_fail_loud("applicability")
-            return SearchOutput(success=False, message=err, hints=[], limit=None, offset=None)
+            return SearchOutput(success=False, message=err, advisories=[], limit=None, offset=None)
         if nf and (err := _validate_no_wildcards(nf)):
             _log_fail_loud("wildcard")
-            return SearchOutput(success=False, message=err, hints=[], limit=None, offset=None)
+            return SearchOutput(success=False, message=err, advisories=[], limit=None, offset=None)
         model_name = resolved_sbert_model_for_process_env(SBERT_MODEL)
         device = os.environ.get("SBERT_DEVICE") or None
         model = _get_sentence_transformer(model_name, device)
@@ -920,15 +937,17 @@ def search_v2(
             "limit": limit,
             "offset": offset,
         }
+        raw_struct, raw_advisories = generate_hints("search", hint_payload)
         return SearchOutput(
             success=True,
             results=hits,
             limit=limit,
             offset=offset,
-            hints=generate_hints("search", hint_payload),
+            advisories=raw_advisories,
+            hints_structured=_to_structured_hints(raw_struct),
         )
     except Exception as exc:
-        return SearchOutput(success=False, message=str(exc), hints=[], limit=None, offset=None)
+        return SearchOutput(success=False, message=str(exc), advisories=[], limit=None, offset=None)
 
 
 def find_v2(
@@ -950,16 +969,16 @@ def find_v2(
             return FindOutput(
                 success=False,
                 message=_filter_validation_error_message(exc),
-                hints=[],
+                advisories=[],
                 limit=None,
                 offset=None,
             )
         if err := _nodefilter_applicability_error(kind, nf):
             _log_fail_loud("applicability")
-            return FindOutput(success=False, message=err, hints=[], limit=None, offset=None)
+            return FindOutput(success=False, message=err, advisories=[], limit=None, offset=None)
         if err := _validate_no_wildcards(nf):
             _log_fail_loud("wildcard")
-            return FindOutput(success=False, message=err, hints=[], limit=None, offset=None)
+            return FindOutput(success=False, message=err, advisories=[], limit=None, offset=None)
         fetch_cap = int(limit) + int(offset) + 1
         if kind == "symbol":
             where, params = _symbol_where_from_filter(nf)
@@ -1009,15 +1028,17 @@ def find_v2(
             "filter": filter_dump,
             "has_more_results": has_more_results,
         }
+        raw_struct, raw_advisories = generate_hints("find", hint_payload)
         return FindOutput(
             success=True,
             results=refs,
             limit=limit,
             offset=offset,
-            hints=generate_hints("find", hint_payload),
+            advisories=raw_advisories,
+            hints_structured=_to_structured_hints(raw_struct),
         )
     except Exception as exc:
-        return FindOutput(success=False, message=str(exc), hints=[], limit=None, offset=None)
+        return FindOutput(success=False, message=str(exc), advisories=[], limit=None, offset=None)
 
 
 _DESCRIBE_UCS_ID_MESSAGE = (
@@ -1061,10 +1082,10 @@ def describe_v2(
                 )
         kind = _resolve_node_kind(g, node_id)
         if kind == "unresolved_call_site":
-            return DescribeOutput(success=False, message=_DESCRIBE_UCS_ID_MESSAGE, hints=[])
+            return DescribeOutput(success=False, message=_DESCRIBE_UCS_ID_MESSAGE, advisories=[])
         row = _load_node_record(g, node_id, kind)
         if row is None:
-            return DescribeOutput(success=False, message=f"No node found for `{node_id}`", hints=[])
+            return DescribeOutput(success=False, message=f"No node found for `{node_id}`", advisories=[])
         ref = _node_ref_from_row(kind, row)
         edge_summary = _edge_summary_for_node(g, node_id, kind=kind, row=row)
         data = dict(row)
@@ -1087,16 +1108,18 @@ def describe_v2(
                         f"java-codebase-rag unresolved-calls list --method-id {node_id} for the full list"
                     )
         record = NodeRecord(id=ref.id, kind=kind, fqn=ref.fqn, data=data, edge_summary=edge_summary)
+        raw_struct, raw_advisories = generate_hints("describe", {"success": True, "record": record.model_dump()})
         return DescribeOutput(
             success=True,
             record=record,
             message=hint_message,
-            hints=generate_hints("describe", {"success": True, "record": record.model_dump()}),
+            advisories=raw_advisories,
+            hints_structured=_to_structured_hints(raw_struct),
         )
     except ValueError as exc:
-        return DescribeOutput(success=False, message=str(exc), hints=[])
+        return DescribeOutput(success=False, message=str(exc), advisories=[])
     except Exception as exc:
-        return DescribeOutput(success=False, message=str(exc), hints=[])
+        return DescribeOutput(success=False, message=str(exc), advisories=[])
 
 
 def _resolve_validate_identifier(raw: str) -> tuple[str | None, str | None]:
@@ -1415,7 +1438,11 @@ def _resolve_finalize_success(
         "path_prefix_seed": path_prefix_seed,
         "target_service_seed": target_service_seed,
     }
-    out = out.model_copy(update={"hints": generate_hints("resolve", hint_payload)})
+    raw_struct, raw_advisories = generate_hints("resolve", hint_payload)
+    out = out.model_copy(update={
+        "advisories": raw_advisories,
+        "hints_structured": _to_structured_hints(raw_struct),
+    })
     _resolve_assert_invariants(out)
     return out
 
@@ -1432,7 +1459,7 @@ def resolve_v2(
                 success=False,
                 status="none",
                 message=err,
-                hints=[],
+                advisories=[],
                 resolved_identifier=None,
             )
             _resolve_assert_invariants(out)
@@ -1463,7 +1490,7 @@ def resolve_v2(
             success=False,
             status="none",
             message=str(exc),
-            hints=[],
+            advisories=[],
             resolved_identifier=None,
         )
         _resolve_assert_invariants(out)
@@ -1700,7 +1727,7 @@ def neighbors_v2(
             return NeighborsOutput(
                 success=False,
                 message=_filter_validation_error_message(exc),
-                hints=[],
+                advisories=[],
                 requested_edge_types=[],
             )
         try:
@@ -1715,7 +1742,7 @@ def neighbors_v2(
             return NeighborsOutput(
                 success=False,
                 message=_filter_validation_error_message(exc),
-                hints=[],
+                advisories=[],
                 requested_edge_types=[],
             )
         except ValueError as exc:
@@ -1945,13 +1972,15 @@ def neighbors_v2(
             "unresolved_count": unresolved_count,
             "calls_row_count": calls_row_count,
         }
+        raw_struct, raw_advisories = generate_hints("neighbors", neigh_payload)
         return NeighborsOutput(
             success=True,
             results=sliced,
             requested_edge_types=requested_edge_types,
-            hints=generate_hints("neighbors", neigh_payload),
+            advisories=raw_advisories,
+            hints_structured=_to_structured_hints(raw_struct),
         )
     except ValidationError:
         raise
     except Exception as exc:
-        return NeighborsOutput(success=False, message=str(exc), hints=[], requested_edge_types=[])
+        return NeighborsOutput(success=False, message=str(exc), advisories=[], requested_edge_types=[])

server.py

@@ -341,7 +341,7 @@ def create_mcp_server() -> FastMCP:
             "structured DSL inside `query`; structured predicates belong in `find`. "
             "For identifier-shaped lookups (FQN, id prefix, route/client identifiers, …), use `resolve` first; "
             "use `search` for natural-language or ranked fuzzy discovery. "
-            "Successful responses echo `limit`/`offset` and may include `hints` (advisory next-step strings)."
+            "Successful responses echo `limit`/`offset` and may include `hints_structured` (tool call suggestions with `reason` field) and `advisories` (pure informational text)."
         ),
     )
     async def search(
@@ -390,7 +390,7 @@ def create_mcp_server() -> FastMCP:
             "module, source_layer, producer_kind, topic_prefix. "
             "Wildcards in prefix fields are rejected. An empty filter (`{}`) or `filter=None` means no predicate (all nodes of "
             "that kind; use pagination). Unknown keys or inapplicable populated fields return success=false. "
-            "Successful responses echo `limit`/`offset` and may include `hints` (advisory next-step strings)."
+            "Successful responses echo `limit`/`offset` and may include `hints_structured` (tool call suggestions with `reason` field) and `advisories` (pure informational text)."
         ),
     )
     async def find(
@@ -426,7 +426,7 @@ def create_mcp_server() -> FastMCP:
             "Pass `id` for any kind, or exact `fqn` for Symbol lookup (`id` wins when both are set). "
             "`describe(fqn=…)` keeps the first graph row when multiple symbols share that FQN; when an FQN may collide, "
             "prefer `resolve(identifier=…, hint_kind='symbol')` first, then `describe(id=…)` on the chosen node. "
-            "Successful responses may include `hints` (advisory next-step strings)."
+            "Successful responses may include `hints_structured` (tool call suggestions with `reason` field) and `advisories` (pure informational text)."
         ),
     )
     async def describe(
@@ -460,8 +460,7 @@ def create_mcp_server() -> FastMCP:
             "Optional `edge_filter` requires edge_types=['CALLS'] only (no composed dot-keys or extra stored "
             "labels); projects the ordered CALLS stream by edge attributes (min_confidence, strategies, "
             "callee_declaring_role). Wildcards in prefix fields are rejected. Unknown filter keys return success=false. "
-            "Successful responses echo `requested_edge_types` and may include `hints` (advisory next-step strings; "
-            "empty results may include EDGE_SCHEMA-driven traversal hints). "
+            "Successful responses echo `requested_edge_types` and may include `hints_structured` (tool call suggestions with `reason` field) and `advisories` (pure informational text). "
             "Each edge's `attrs.strategy` indicates resolution quality (brownfield/fallback vs primary paths)."
         ),
     )
@@ -546,7 +545,7 @@ def create_mcp_server() -> FastMCP:
             "status=one (single node), many (≥2 ranked candidates with reason), or none "
             "(no match — fall back to search(query=...) for natural language or fuzzy text). "
             "Optional hint_kind narrows to symbol, route, client, or producer. "
-            "Successful responses may include advisory hints (same contract as other v2 tools). "
+            "Successful responses may include hints_structured (tool call suggestions with `reason` field) and advisories (pure informational text) — same contract as other v2 tools. "
             "Malformed empty/whitespace identifier returns success=false. "
             "Examples: resolve('com.foo.Bar', hint_kind='symbol'); "
             "resolve('GET /api/v1/customers', hint_kind='route'); "