Structured MCP filter schemas, hardened value enums, tool-description rewrite

[HumanBean17]

Scope

Make the MCP filter surface structured and visible to clients, harden the
value taxonomies to enums, rewrite the tool descriptions, and close the
indexer-side validation holes that made two of those enums trustworthy.

Accumulated across a multi-session effort (no separate propose — incrementally
reviewed with the user); shipped as two logical commits.

Changes

• Structured filter params (server.py, mcp_v2.py): search/find/neighbors
filter and edge_filter are typed NodeFilter/EdgeFilter instead of
  opaque dict | str, so the tool input schema now exposes field-level types,
  enums, and descriptions ($ref NodeFilter / $ref EdgeFilter).
• Hardened value enums (mcp_v2.py): role, framework, source_layer,
  client_kind, producer_kind are Literal enums (the last two newly closed).
• Index-time validation (ast_java.py): the in-source
  @CodebaseHttpClient(clientKind=) / @CodebaseProducer(producerKind=) enum
  paths now validate against VALID_CLIENT_KINDS / VALID_PRODUCER_KINDS
  (warn + ignore on unknown), mirroring the existing YAML path. Deferred import
  to avoid the java_ontology → ast_java cycle. This is what makes
  client_kind/producer_kind a closed set safe to surface as enums.
• VALID_ROLES / OTHER (java_ontology.py): added a comment documenting
  that OTHER is deliberately excluded — it is the inference-only fallback
  (read-side Role enum includes it; write-side VALID_ROLES does not). OTHER
  was not added to VALID_ROLES (would weaken @CodebaseRole/brownfield
  validation with no benefit).
• Tool descriptions / _INSTRUCTIONS (server.py): dropped
  internal-implementation leaks, added sibling-tool cross-references, documented
  strict-frame failure modes (incl. the dedup_calls-without-CALLS silent
  no-op, hybrid+table='all' → success=false).
• apply_auto_scope (server.py): operates on NodeFilter (model_copy
  injection).

Behavior changes

• BREAKING (MCP input schema): filter/edge_filter are now structured with
  extra="forbid". Unknown keys / bad enum values now fail at the FastMCP schema
  layer as a ToolError that names the bad field and lists the valid enum
  values (a net teaching improvement — the old success=false envelope never
  listed valid values for enum fields). Per-kind applicability and wildcard
  checks still return the in-function success=false envelope (with
  hints_structured). Direct v2 Python callers are unaffected (still accept
  dicts, still get the teaching envelope).
• Indexing: invalid @CodebaseHttpClient(clientKind=…) /
  @CodebaseProducer(producerKind=…) values are now dropped (warned on stderr)
  instead of stored verbatim.

Reindex / ontology / env

• No ontology_version bump — no graph schema/column change and no
  enrichment-semantic change.
• Reindex recommended for indexes that captured out-of-set client/producer
  kinds under the old hole: that data remains in the graph but is no longer
  filterable via the new enum.
• No env-var changes.

Validation

• ruff check . clean
• pytest tests — 769 passed, 11 skipped (11 skips pre-existing/env-gated;
  +2 new tests test_29a/test_29b covering the source-annotation validation)

🤖 Generated with Claude Code