Structured MCP filter schemas, hardened value enums, tool-description rewrite (#315)

* expose structured filter schemas and rewrite mcp tool descriptions

search/find/neighbors `filter`/`edge_filter` params are now typed
NodeFilter/EdgeFilter (structured, extra-forbidden) instead of opaque
dict|str, so MCP clients see field-level enums and descriptions. Value
taxonomies role/framework/source_layer/client_kind/producer_kind are Literal
enums. Rewrite the five tool descriptions and _INSTRUCTIONS to drop
internal-implementation leaks, cross-reference sibling tools, and document
strict-frame failure modes. apply_auto_scope operates on NodeFilter.

Co-Authored-By: Claude <noreply@anthropic.com>

* validate client/producer kind at index time; document OTHER role split

The in-source @CodebaseHttpClient(clientKind=) / @CodebaseProducer(producerKind=)
enum paths did str(val) with no validation, unlike the YAML path. Validate
against VALID_CLIENT_KINDS/VALID_PRODUCER_KINDS (deferred import to avoid the
java_ontology->ast_java cycle) and warn-and-ignore on unknown — this closes the
last open producers, making client_kind/producer_kind a closed set safe to
surface as enums. Also document in java_ontology.py that VALID_ROLES deliberately
excludes OTHER (inference-only fallback; the read-side Role enum includes it).

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: align consumer docs with closed filter enums (#315)

The structured filter schemas PR makes role/framework/source_layer/
client_kind/producer_kind closed Literal enums with extra="forbid", so
stale or omitted values are now hard schema errors instead of silent
no-ops. Align the three consumer-facing operating manuals with the
now-closed sets:

- Framework glossary: drop the non-existent `codebase_async_route` (only
  ever a function name, never a stored value), add the missing `feign`,
  drop the misleading `...` (the set is now closed/exhaustive).
- NodeFilter applicability tables: add `source_layer` to the client and
  producer rows (applicable per _NODEFILTER_APPLICABLE_FIELDS, previously
  undocumented).
- Strict-frame note: invalid enum values (e.g. wrong case) are rejected
  earlier at the schema layer with the valid set listed - distinct from
  the success=false applicability path.
- Glossary: add Source layers (client/producer) closed value set.

Doc-only; no code or test impact.

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: HumanBean17

agents/explorer-rag-enhanced.md

@@ -151,15 +151,15 @@ Simple types in parentheses; generics erased. No spaces after commas. No-arg: `(
 
 ### Shared NodeFilter
 
-For `find`, `filter` is required — `{}` means no predicates. **Strict frame:** unknown keys or inapplicable populated fields → `success=false`.
+For `find`, `filter` is required — `{}` means no predicates. **Strict frame:** unknown keys or inapplicable populated fields → `success=false`; invalid enum values (e.g. wrong case) are rejected earlier at the schema layer with the valid set listed.
 
 | Keys | Applies to |
 | ---- | ---------- |
 | `microservice`, `module` | All kinds |
 | `role`, `exclude_roles`, `annotation`, `capability`, `fqn_prefix`, `symbol_kind`, `symbol_kinds` | **symbol** |
 | `http_method`, `path_prefix`, `framework` | **route** |
-| `client_kind`, `target_service`, `target_path_prefix`, `http_method` | **client** |
-| `producer_kind`, `topic_prefix` | **producer** |
+| `source_layer`, `client_kind`, `target_service`, `target_path_prefix`, `http_method` | **client** |
+| `source_layer`, `producer_kind`, `topic_prefix` | **producer** |
 
 No wildcards in prefix fields — use `search(query=…)` for fuzzy text.
 

ast_java.py

@@ -13,6 +13,7 @@
 from __future__ import annotations
 
 import posixpath
+import sys
 from dataclasses import dataclass, field
 from functools import lru_cache
 from typing import Iterable
@@ -1642,9 +1643,17 @@ def _parse_codebase_http_client_annotation(
     pairs, _ = _annotation_kv_nodes(ann, src)
     client_kind = ""
     if "clientKind" in pairs:
-        val, _kind = _annotation_value(pairs["clientKind"], src)
-        if val and _kind == "enum":
-            client_kind = str(val)
+        val, vkind = _annotation_value(pairs["clientKind"], src)
+        if val and vkind == "enum":
+            kind_val = str(val)
+            from java_ontology import VALID_CLIENT_KINDS  # deferred: java_ontology imports ast_java
+            if kind_val in VALID_CLIENT_KINDS:
+                client_kind = kind_val
+            else:
+                print(
+                    f"[lancedb-mcp] CodebaseHttpClient: invalid clientKind {kind_val!r} — ignored",
+                    file=sys.stderr,
+                )
     target_service = ""
     if "targetService" in pairs:
         atoms = _string_value_atoms(pairs["targetService"], src, ctx)
@@ -1714,9 +1723,17 @@ def _parse_codebase_producer_annotation(
     client_kind = "kafka_send"
     kind_node = pairs.get("producerKind") or pairs.get("clientKind")
     if kind_node is not None:
-        val, _kind = _annotation_value(kind_node, src)
-        if val and _kind == "enum":
-            client_kind = str(val)
+        val, vkind = _annotation_value(kind_node, src)
+        if val and vkind == "enum":
+            kind_val = str(val)
+            from java_ontology import VALID_PRODUCER_KINDS  # deferred: java_ontology imports ast_java
+            if kind_val in VALID_PRODUCER_KINDS:
+                client_kind = kind_val
+            else:
+                print(
+                    f"[lancedb-mcp] CodebaseProducer: invalid producerKind {kind_val!r} — ignored",
+                    file=sys.stderr,
+                )
     topic = ""
     if "topic" in pairs:
         atoms = _string_value_atoms(pairs["topic"], src, ctx)

docs/AGENT-GUIDE.md

@@ -138,12 +138,12 @@ For **`find`**, `filter` is required — `{}` means no predicates (all nodes of
 | `microservice`, `module` | All kinds |
 | `role`, `exclude_roles`, `annotation`, `capability`, `fqn_prefix`, `symbol_kind`, `symbol_kinds` | **symbol** |
 | `http_method`, `path_prefix`, `framework` | **route** |
-| `client_kind`, `target_service`, `target_path_prefix`, `http_method` | **client** |
-| `producer_kind`, `topic_prefix` | **producer** |
+| `source_layer`, `client_kind`, `target_service`, `target_path_prefix`, `http_method` | **client** |
+| `source_layer`, `producer_kind`, `topic_prefix` | **producer** |
 
 `http_method` filters HTTP verbs on **routes** (declared method) and on **clients** (outbound call method). Not applicable to **symbol** rows.
 
-**Strict frame:** one populated field → one stored attribute for that kind. Unknown keys or inapplicable populated fields → `success=false` with a teaching `message`. No wildcards in `fqn_prefix`, `path_prefix`, or `target_path_prefix` (`*` / `?` rejected) — use `search(query=…)` for ranked text instead. `search.query` is opaque text, not a DSL.
+**Strict frame:** one populated field → one stored attribute for that kind. Unknown keys or inapplicable populated fields → `success=false` with a teaching `message`. Invalid enum values (e.g. wrong case) are rejected earlier at the schema layer with the valid set listed. No wildcards in `fqn_prefix`, `path_prefix`, or `target_path_prefix` (`*` / `?` rejected) — use `search(query=…)` for ranked text instead. `search.query` is opaque text, not a DSL.
 
 ### Identifier resolution (`resolve`)
 
@@ -245,12 +245,14 @@ Returns **edges** with `attrs` (`confidence`, `strategy`, `match`, … on cross-
 
 **Symbol kinds (`symbol_kind` / `symbol_kinds`):** `class`, `interface`, `enum`, `record`, `annotation`, `method`, `constructor`.
 
-**Route `framework` (examples on stored routes):** `spring_mvc`, `webflux`, `kafka`, `rabbitmq`, `jms`, `stream`, `codebase_async_route`, …
+**Route `framework` (closed set on stored routes):** `spring_mvc`, `webflux`, `kafka`, `rabbitmq`, `jms`, `stream`, `feign`.
 
 **Client kinds:** `feign_method`, `rest_template`, `web_client`.
 
 **Producer kinds:** `kafka_send`, `stream_bridge_send`.
 
+**Source layers (client/producer):** `builtin`, `layer_a_meta`, `layer_b_ann`, `layer_b_fqn`, `layer_c_source`.
+
 **HTTP call `attrs.match` / async `attrs.match`:** `cross_service`, `intra_service`, `ambiguous`, `phantom`, `unresolved`.
 
 ### Recovery playbook

java_ontology.py

@@ -15,7 +15,10 @@
     _TYPE_ANN_TO_CAPABILITY,
 )
 
-# Roles: Spring stereotype values plus DTO from `infer_role_for_type`.
+# Roles assignable by indexing: Spring stereotype values plus DTO. ``OTHER`` is the
+# built-in inference fallback (ast_java.infer_role when nothing matches) and is
+# deliberately excluded here — it is a read-side value (the mcp_v2 ``Role`` enum
+# includes it) but not a role a user may set via @CodebaseRole / role_overrides.
 VALID_ROLES: frozenset[str] = frozenset((*ROLE_ANNOTATIONS.values(), "DTO"))
 
 VALID_CAPABILITIES: frozenset[str] = frozenset(

mcp_v2.py

@@ -48,6 +48,22 @@ def _hints_or_skip(tool: str, payload: dict) -> tuple[list, list]:
 
 DeclarationSymbolKind = Literal["class", "interface", "enum", "record", "annotation", "method", "constructor"]
 
+# Closed value taxonomies surfaced to MCP consumers as enums. Sources of truth:
+#   Role         — VALID_ROLES in java_ontology.py + the "OTHER" inference fallback (ast_java.infer_role)
+#   Framework    — hardcoded literals across ast_java.py / build_ast_graph.py
+#   SourceLayer  — exhaustive classifier build_ast_graph._client_source_layer / _producer_source_layer
+#   ClientKind   — VALID_CLIENT_KINDS in java_ontology.py (every producer validated at index time)
+#   ProducerKind — VALID_PRODUCER_KINDS in java_ontology.py (every producer validated at index time)
+# Keep these in sync with the indexing-side taxonomies if they change.
+Role = Literal[
+    "CONTROLLER", "SERVICE", "REPOSITORY", "COMPONENT", "CONFIG",
+    "ENTITY", "CLIENT", "MAPPER", "DTO", "OTHER",
+]
+Framework = Literal["spring_mvc", "webflux", "kafka", "rabbitmq", "jms", "stream", "feign", ""]
+SourceLayer = Literal["builtin", "layer_a_meta", "layer_b_ann", "layer_b_fqn", "layer_c_source"]
+ClientKind = Literal["feign_method", "rest_template", "web_client"]
+ProducerKind = Literal["kafka_send", "stream_bridge_send"]
+
 # Stored graph edge labels for one-hop neighbors. Composed DECLARES.* and OVERRIDDEN_BY.*
 # dot-keys are separate ComposedEdgeType literals (2-hop traversal). Stored OVERRIDES is an EdgeType.
 EdgeType = Literal[
@@ -133,21 +149,30 @@ class NodeFilter(BaseModel):
 
     microservice: str | None = None
     module: str | None = None
-    source_layer: str | None = None
-    role: str | None = None
-    exclude_roles: list[str] | None = None
+    source_layer: SourceLayer | None = None
+    role: Role | None = None
+    exclude_roles: list[Role] | None = None
     annotation: str | None = None
     capability: str | None = None
     fqn_prefix: str | None = None
     symbol_kind: DeclarationSymbolKind | None = None
     symbol_kinds: list[DeclarationSymbolKind] | None = None
-    http_method: str | None = None
+    http_method: str | None = Field(
+        default=None,
+        description="HTTP verb (commonly GET/POST/PUT/DELETE/PATCH; user route annotations may yield others).",
+    )
     path_prefix: str | None = None
-    framework: str | None = None
-    client_kind: str | None = None
+    framework: Framework | None = None
+    client_kind: ClientKind | None = Field(
+        default=None,
+        description="Outbound HTTP client kind: feign_method, rest_template, or web_client.",
+    )
     target_service: str | None = None
     target_path_prefix: str | None = None
-    producer_kind: str | None = None
+    producer_kind: ProducerKind | None = Field(
+        default=None,
+        description="Outbound async producer kind: kafka_send or stream_bridge_send.",
+    )
     topic_prefix: str | None = None
 
 
@@ -157,9 +182,9 @@ class EdgeFilter(BaseModel):
     min_confidence: float | None = None
     exclude_strategies: list[str] | None = None
     include_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
+    callee_declaring_role: Role | None = None
+    callee_declaring_roles: list[Role] | None = None
+    exclude_callee_declaring_roles: list[Role] | None = None
 
     @model_validator(mode="after")
     def _strategy_axes_mutually_exclusive(self) -> EdgeFilter: