feat(mcp): EdgeFilter on neighbors_v2 with CALLS ordering and pushdown

Add typed edge_filter for CALLS-only projection (confidence, strategies,
callee_declaring_role) with fail-loud schema validation, ORDER BY call site
in Kuzu before pagination, and Decision 20/30 hints. Supersedes MCP-V2
no per-edge filter on neighbors (Decision 16).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: HumanBean17

docs/AGENT-GUIDE.md

@@ -261,7 +261,12 @@ Virtual keys (`OVERRIDDEN_BY`, …) are **not** valid `neighbors` arguments —
 #### `neighbors`
 
 - **Purpose:** One hop over explicit edge types; returns **edges** with attributes (`confidence`, `strategy`, `match`, …) and the **`other`** node.
-- **Args:** `ids` (string or array — batch allowed), **`direction`** (`in`|`out`), **`edge_types`** (non-empty list), `limit`, `offset`, optional `filter` on the other node.
+- **Args:** `ids` (string or array — batch allowed), **`direction`** (`in`|`out`), **`edge_types`** (non-empty list), `limit`, `offset`, optional `filter` on the other node, optional **`edge_filter`** on CALLS edge attributes (single edge type only; fail-loud if an attribute is not on every requested label).
+- **CALLS ordering:** `edge_types=['CALLS']` results are delivered in **source order** (`call_site_line`, then `call_site_byte`). `edge_filter` predicates are applied in the graph query **before** `offset`/`limit`.
+- **`edge_filter` (CALLS):** `min_confidence`, `include_strategies` / `exclude_strategies` (mutually exclusive), `callee_declaring_role`, `callee_declaring_roles`, `exclude_callee_declaring_roles`. Example: `edge_filter={{"callee_declaring_role":"SERVICE"}}` for delegation hops; `exclude_callee_declaring_roles: ["ENTITY","DTO"]` drops accessor noise. **`exclude_callee_declaring_roles: ["OTHER"]` also drops known-external rows** (JDK/library callees are typically `OTHER`).
+- **`exclude_external` is for `find_callers` / `find_callees` only** (FQN-prefix trimming). On CALLS hops, trim JDK/library noise via `edge_filter` (`min_confidence`, `exclude_strategies`, role axes) — not FQN-prefix rules.
+- **Role-filter trap:** `NodeFilter.role` filters the **neighbor node's** role (method Symbols are almost always `OTHER`). `edge_filter.callee_declaring_role` filters the **callee declaring type's** stereotype — use that for “does this method call a repository/service?”.
+- **Accessor noise:** `exclude_callee_declaring_roles` helps; entity getter/setter heuristics live in the `/mini-map` skill ([`propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](../propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md)).
 - **Batching:** Multiple origins are expanded; pagination slices the **combined** edge list — use larger `limit` when batching many ids.
 - **Mixed flat + composed `edge_types`:** flat edges are appended before composed edges, then `limit`/`offset` apply. A small `limit` with e.g. `["DECLARES", "DECLARES.DECLARES_CLIENT"]` may return only member Symbols and no Clients — use the dot-key alone when enumerating terminals.
 - **Confidence:** Cross-service edges (`HTTP_CALLS`, `ASYNC_CALLS`) carry confidence, strategy, and match metadata on `edge.attrs` (`attrs.confidence`, `attrs.strategy`, `attrs.match`). Low confidence means the resolver had to guess at the route binding — treat it as a **resolver gap signal**, not a hallucination. Report low-confidence edges with their confidence value, not as facts. Intra-service edges (`CALLS`, `INJECTS`, `IMPLEMENTS`, `EXTENDS`, `DECLARES`, `DECLARES_CLIENT`, `EXPOSES`, `OVERRIDES`) faithfully represent the static graph; the resolved set is still a **lower bound** under reflection / dynamic dispatch (see *What this MCP is NOT*).

kuzu_queries.py

@@ -667,6 +667,76 @@ def member_edge_traversal_for(self, type_id: str, composed_key: str) -> list[dic
             {"id": type_id, "rel": rel},
         )
 
+    def count_calls_for_symbol(self, origin_id: str, *, direction: Literal["in", "out"]) -> int:
+        """Count CALLS edges incident on a Symbol (hints / diagnostics)."""
+        if direction == "out":
+            pattern = "MATCH (origin:Symbol {id: $id})-[e:CALLS]->() RETURN count(e) AS n"
+        else:
+            pattern = "MATCH (origin:Symbol {id: $id})<-[e:CALLS]-() RETURN count(e) AS n"
+        rows = self._rows(pattern, {"id": origin_id})
+        return int(rows[0].get("n") or 0) if rows else 0
+
+    def neighbor_calls_for_symbol(
+        self,
+        origin_id: str,
+        *,
+        direction: Literal["in", "out"],
+        offset: int = 0,
+        limit: int | None = None,
+        sql_pagination: bool = True,
+        min_confidence: float | None = None,
+        include_strategies: list[str] | None = None,
+        exclude_strategies: list[str] | None = None,
+        callee_declaring_role: str | None = None,
+        callee_declaring_roles: list[str] | None = None,
+        exclude_callee_declaring_roles: list[str] | None = None,
+    ) -> list[dict[str, Any]]:
+        """CALLS neighbors with source-order delivery and optional edge-attribute pushdown.
+
+        When ``sql_pagination`` is True and ``limit`` is set, ``SKIP``/``LIMIT`` apply after
+        ``ORDER BY e.call_site_line, e.call_site_byte``. Otherwise the full ordered stream is
+        returned for caller-side ``NodeFilter`` / pagination.
+        """
+        wh_parts = ["origin.id = $id"]
+        params: dict[str, Any] = {"id": origin_id}
+        if min_confidence is not None:
+            wh_parts.append("e.confidence >= $min_confidence")
+            params["min_confidence"] = min_confidence
+        if include_strategies:
+            wh_parts.append("e.strategy IN $include_strategies")
+            params["include_strategies"] = include_strategies
+        if exclude_strategies:
+            wh_parts.append("NOT (e.strategy IN $exclude_strategies)")
+            params["exclude_strategies"] = exclude_strategies
+        if callee_declaring_role is not None:
+            wh_parts.append("e.callee_declaring_role = $callee_declaring_role")
+            params["callee_declaring_role"] = callee_declaring_role
+        if callee_declaring_roles:
+            wh_parts.append("e.callee_declaring_role IN $callee_declaring_roles")
+            params["callee_declaring_roles"] = callee_declaring_roles
+        if exclude_callee_declaring_roles:
+            wh_parts.append("NOT (e.callee_declaring_role IN $exclude_callee_declaring_roles)")
+            params["exclude_callee_declaring_roles"] = exclude_callee_declaring_roles
+        where = " AND ".join(wh_parts)
+        if direction == "out":
+            match = "MATCH (origin:Symbol)-[e:CALLS]->(other:Symbol)"
+        else:
+            match = "MATCH (origin:Symbol)<-[e:CALLS]-(other:Symbol)"
+        q = (
+            f"{match} WHERE {where} "
+            "RETURN other.id AS other_id, 'CALLS' AS edge_type, "
+            "e.confidence AS confidence, e.strategy AS strategy, e.source AS source, "
+            "e.call_site_line AS call_site_line, e.call_site_byte AS call_site_byte, "
+            "e.arg_count AS arg_count, e.resolved AS resolved, "
+            "e.callee_declaring_role AS callee_declaring_role "
+            "ORDER BY e.call_site_line, e.call_site_byte"
+        )
+        if sql_pagination and limit is not None:
+            q += " SKIP $offset LIMIT $limit"
+            params["offset"] = offset
+            params["limit"] = limit
+        return self._rows(q, params)
+
     def _edge_row_count_from_method_ids(self, method_ids: list[str], rel: str) -> int:
         """Count outgoing ``rel`` edges from method symbols (describe rollup helper)."""
         total = 0

mcp_hints.py

@@ -21,7 +21,10 @@
     "Maximum 5 hints per output. Describe-time type rollup hints may recommend "
     "DECLARES.* dot-keys for neighbors(); empty neighbors structural hints never use "
     "dot-key edge labels. For neighbors with multiple origin ids, empty-result "
-    "structural hints describe the first origin only."
+    "structural hints describe the first origin only. On neighbors with "
+    "edge_types=['CALLS'], optional edge_filter projects the ordered CALLS stream "
+    "(min_confidence, strategies, callee_declaring_role axes); include_unresolved and "
+    "dedup_calls are separate knobs (mutually exclusive with edge_filter where noted)."
 )
 
 # --- Appendix A verbatim templates (substitute {id}, {kind}, {limit}) ---
@@ -109,6 +112,18 @@
     "some edges resolved via brownfield/fallback strategy — check attrs.strategy on each row"
 )
 
+TPL_NEIGHBORS_CALLS_ROLE_FILTER_OTHER_FALLBACK = (
+    "0 CALLS matched callee_declaring_role filter but method has many callees — "
+    "targets may be OTHER (interface/JDK); try "
+    "edge_filter={{exclude_callee_declaring_roles: ['ENTITY','DTO']}} instead of role exact match"
+)
+
+TPL_NEIGHBORS_CALLS_NODEFILTER_ROLE_COLLISION = (
+    "NodeFilter.role filters the neighbor method's role (usually OTHER), not the callee's "
+    "declaring type — use edge_filter={{callee_declaring_role: 'SERVICE'}} (or REPOSITORY) "
+    "for CALLS stereotype projection"
+)
+
 # v4 neighbors success-path (propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md); N1a/N1b alias describe templates.
 TPL_NEIGHBORS_SUCCESS_HTTP_TARGETS = "HTTP targets: neighbors(client_ids,'out',['HTTP_CALLS'])"
 TPL_NEIGHBORS_SUCCESS_ASYNC_TARGETS = "async targets: neighbors(producer_ids,'out',['ASYNC_CALLS'])"
@@ -329,6 +344,45 @@ def _append_neighbors_success_hint(pairs: list[tuple[int, str]], text: str) -> N
         pairs.append((PRIORITY_LEAF_FOLLOWUP, text))
 
 
+def neighbors_calls_meta_hints(payload: dict[str, Any]) -> list[tuple[int, str]]:
+    """CALLS-specific hints: role-filter OTHER fallback (Decision 20) and NodeFilter.role trap (30)."""
+    pairs: list[tuple[int, str]] = []
+    req_types = payload.get("requested_edge_types")
+    if not isinstance(req_types, list) or req_types != ["CALLS"]:
+        return pairs
+    results = list(payload.get("results") or [])
+    edge_flt = payload.get("edge_filter") if isinstance(payload.get("edge_filter"), dict) else {}
+    node_flt = payload.get("node_filter") if isinstance(payload.get("node_filter"), dict) else {}
+    role_exact = edge_flt.get("callee_declaring_role")
+    if (
+        role_exact in ("SERVICE", "REPOSITORY")
+        and not results
+        and int(payload.get("unfiltered_calls_count") or 0) >= 5
+    ):
+        pairs.append((PRIORITY_META, TPL_NEIGHBORS_CALLS_ROLE_FILTER_OTHER_FALLBACK))
+    node_role = node_flt.get("role")
+    if node_role and results:
+        method_rows = [
+            r
+            for r in results
+            if str(((r.get("other") or {}) if isinstance(r.get("other"), dict) else {}).get("symbol_kind") or "")
+            == "method"
+        ]
+        if method_rows:
+            other_roles = [
+                str(
+                    ((r.get("other") or {}) if isinstance(r.get("other"), dict) else {}).get("role")
+                    or ""
+                )
+                for r in method_rows
+            ]
+            if other_roles and sum(1 for role in other_roles if role == "OTHER") >= max(
+                1, (len(other_roles) * 3) // 4
+            ):
+                pairs.append((PRIORITY_META, TPL_NEIGHBORS_CALLS_NODEFILTER_ROLE_COLLISION))
+    return pairs
+
+
 def neighbors_success_hints(payload: dict[str, Any]) -> list[tuple[int, str]]:
     """v4 non-empty neighbors follow-ups (N1a–N7); no graph I/O."""
     if not payload.get("success"):
@@ -573,11 +627,11 @@ def generate_hints(
                         requested_direction=requested_direction,
                     )
                 )
-        else:
-            if results and offset == 0:
-                success_pairs = neighbors_success_hints(payload)
-            if _any_fuzzy_strategy(results):
-                meta_pairs.append((PRIORITY_META, TPL_NEIGHBORS_FUZZY_STRATEGY))
+        elif results and offset == 0:
+            success_pairs = neighbors_success_hints(payload)
+        meta_pairs.extend(neighbors_calls_meta_hints(payload))
+        if results and _any_fuzzy_strategy(results):
+            meta_pairs.append((PRIORITY_META, TPL_NEIGHBORS_FUZZY_STRATEGY))
         return finalize_hint_list(
             _filter_neighbors_dotkey_hints(empty_pairs) + success_pairs + meta_pairs,
         )