java-codebase-rag 0.6.0__py3-none-any.whl → 0.6.2__py3-none-any.whl

ast_java.py

@@ -13,6 +13,7 @@ Python with no tree-sitter dependency.
 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)

build_ast_graph.py

@@ -3668,10 +3668,17 @@ def incremental_rebuild(
 
 
 def _init_hash_tracker(source_root: Path, ladybug_path: Path) -> int:
-    """Initialize hash tracker for all Java files. Returns number of files hashed."""
+    """Initialize hash tracker for all Java files. Returns number of files hashed.
+
+    Called right after a full graph rebuild (``write_ladybug``), so the store must
+    mirror exactly the files that were just indexed. We deliberately do NOT
+    ``load()`` the existing store: ``update`` re-hashes every current file anyway,
+    and preserving old entries would leave stale hashes for files that no longer
+    exist (deleted or now-ignored). Those ghosts would be re-detected as "removed"
+    on every subsequent ``increment``, sustaining an endless full-rebuild loop.
+    """
     index_dir = ladybug_path.parent
     tracker = FileHashTracker(index_dir)
-    tracker.load()
     ignore = LayeredIgnore(source_root)
     all_files: set[str] = set()
     source_root_resolved = source_root.resolve()
@@ -3742,7 +3749,7 @@ def _write_clients_producers_and_calls(conn: ladybug.Connection, tables: GraphTa
 
     # Write declares_client edges
     for row in tables.declares_client_rows:
-        source_file = member_by_id.get(row.symbol_id, MemberEntry(kind="", decl=None, parent_id="", parent_fqn="", file_path="", module="", microservice="")).file_path
+        source_file = member_by_id.get(row.symbol_id, MemberEntry(kind="", decl=None, parent_id="", parent_fqn="", file_path="", module="", microservice="", node_id="")).file_path
         conn.execute(_CREATE_DECLARES_CLIENT, {
             "sid": row.symbol_id,
             "cid": row.client_id,
@@ -3753,7 +3760,7 @@ def _write_clients_producers_and_calls(conn: ladybug.Connection, tables: GraphTa
 
     # Write declares_producer edges
     for row in tables.declares_producer_rows:
-        source_file = member_by_id.get(row.symbol_id, MemberEntry(kind="", decl=None, parent_id="", parent_fqn="", file_path="", module="", microservice="")).file_path
+        source_file = member_by_id.get(row.symbol_id, MemberEntry(kind="", decl=None, parent_id="", parent_fqn="", file_path="", module="", microservice="", node_id="")).file_path
         conn.execute(_CREATE_DECLARES_PRODUCER, {
             "sid": row.symbol_id,
             "pid": row.producer_id,

java_codebase_rag/cli.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 import argparse
 import asyncio
 import json
+import os
 import pprint
 import shutil
 import sys
@@ -930,5 +931,21 @@ def main(argv: list[str] | None = None) -> int:
         return 2
 
 
+def _console_script_main() -> None:
+    """Real CLI entry: terminate without interpreter finalization.
+
+    A pyarrow/lance worker thread (loaded via lancedb in lifecycle commands) can
+    outlive CPython finalization in a one-shot CLI subprocess and trip
+    ``PyGILState_Release`` (SIGABRT, exit -6). Flushing + ``os._exit`` skips that
+    racy teardown — the command has already done its work and emitted its result.
+    ``main()`` stays return-based so in-process test callers (``cli.main(...)``)
+    keep working.
+    """
+    rc = main()
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os._exit(rc)
+
+
 if __name__ == "__main__":
-    raise SystemExit(main())
+    _console_script_main()

java_codebase_rag/config.py

@@ -52,14 +52,36 @@ _DEFAULT_EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
 _UNRESOLVED_VAR_RE = re.compile(r"\$(\w+|\{[^}]+\})")
 
 
-def maybe_expand_embedding_model_path(value: str) -> str:
-    """Expand ``~`` and ``$VAR`` when *value* is path-shaped.
+def maybe_expand_embedding_model_path(
+    value: str,
+    *,
+    config_dir: Path | None = None,
+    source_root: Path | None = None,
+    source: SettingSource | None = None,
+) -> str:
+    """Expand ``~`` / ``$VAR`` for path-shaped values and resolve relatives to absolute.
 
     Path-shape: starts with ``/``, ``./``, ``../``, ``~``, or contains ``$``.
     Plain ``org/name`` (hub id) does not match and is passed through unchanged.
 
-    Used for ``embedding.model`` after precedence resolution and for runtime
-    ``SBERT_MODEL`` reads (e.g. MCP) so the string matches ``ResolvedOperatorConfig``.
+    Relative resolution mirrors :func:`_resolve_index_dir_path` so a committed
+    config is portable regardless of process CWD:
+
+    * YAML values (``source == "yaml"``) resolve against ``config_dir`` (the
+      directory holding ``.java-codebase-rag.yml``).
+    * CLI / env values resolve against ``source_root``.
+
+    Only a result that still starts with ``./`` or ``../`` *after* ``~`` /
+    ``$VAR`` expansion is re-based — so hub ids (``org/name``), absolute paths,
+    ``~/``-expanded paths, and an env var that already yielded an absolute path
+    are all left untouched.
+
+    When no base is supplied (the runtime ``SBERT_MODEL`` read via
+    :func:`resolved_sbert_model_for_process_env`), relative resolution is
+    skipped: the value is returned ``expandvars`` / ``expanduser``-expanded but
+    not re-based, matching the prior best-effort behavior. The main resolution
+    path (:func:`resolve_operator_config`) supplies a base, so the absolute path
+    it stores is what downstream loaders receive.
     """
     needs_expand = value.startswith(("/", "./", "../", "~")) or "$" in value
     if not needs_expand:
@@ -70,9 +92,31 @@ def maybe_expand_embedding_model_path(value: str) -> str:
             f"java-codebase-rag: path-shaped model string contains unresolved variable: {expanded}",
             file=sys.stderr,
         )
+    if expanded.startswith(("./", "../")):
+        base = _embedding_model_base(
+            source=source, config_dir=config_dir, source_root=source_root
+        )
+        if base is not None:
+            return str((base / expanded).resolve())
     return expanded
 
 
+def _embedding_model_base(
+    *,
+    source: SettingSource | None,
+    config_dir: Path | None,
+    source_root: Path | None,
+) -> Path | None:
+    """Base directory for a relative ``embedding.model``.
+
+    Mirrors :func:`_resolve_index_dir_path`: YAML values anchor on the config
+    file's directory; CLI / env values anchor on the resolved ``source_root``.
+    """
+    if source == "yaml":
+        return config_dir
+    return source_root
+
+
 def resolved_sbert_model_for_process_env(import_time_default: str) -> str:
     """``SBERT_MODEL`` from the process environment, with the same expansion as YAML/CLI resolution.
 
@@ -306,9 +350,19 @@ def _pick_bool(
 def _resolve_index_dir_path(
     *,
     source_root: Path,
+    config_dir: Path,
     cli_index_dir: str | None,
     yaml_dict: dict[str, Any],
 ) -> tuple[Path, SettingSource]:
+    # Bases for relative paths:
+    #   - YAML ``index_dir``  -> the config file's directory (``config_dir``),
+    #     the SAME base used for YAML ``source_root``. Paths written in the
+    #     config file are relative to the file, so both keys stay consistent.
+    #   - CLI / env ``index_dir`` -> ``source_root`` (unchanged). These are not
+    #     "in the config file"; preserving the existing base avoids a semantics
+    #     change for operators who pass ``--index-dir`` on the command line.
+    #   - Default ``./.java-codebase-rag`` -> ``source_root`` so the index sits
+    #     beside the Java tree (the layout ``discover_project_root`` anchors on).
     raw_cli = cli_index_dir.strip() if isinstance(cli_index_dir, str) else None
     if raw_cli:
         p = Path(raw_cli).expanduser()
@@ -324,7 +378,7 @@ def _resolve_index_dir_path(
     idx = yaml_dict.get("index_dir")
     if isinstance(idx, str) and idx.strip():
         p = Path(idx.strip()).expanduser()
-        out = p.resolve() if p.is_absolute() else (source_root / p).resolve()
+        out = p.resolve() if p.is_absolute() else (config_dir / p).resolve()
         return out, "yaml"
 
     return (source_root / ".java-codebase-rag").resolve(), "default"
@@ -368,7 +422,7 @@ def resolve_operator_config(
                 root = config_dir
 
     index_dir, index_src = _resolve_index_dir_path(
-        source_root=root, cli_index_dir=cli_index_dir, yaml_dict=yaml_dict
+        source_root=root, config_dir=config_dir, cli_index_dir=cli_index_dir, yaml_dict=yaml_dict
     )
     model, model_src = _pick_str(
         cli_val=cli_embedding_model,
@@ -377,7 +431,12 @@ def resolve_operator_config(
         yaml_path=("embedding", "model"),
         default=_DEFAULT_EMBEDDING_MODEL,
     )
-    model = maybe_expand_embedding_model_path(model)
+    model = maybe_expand_embedding_model_path(
+        model,
+        config_dir=config_dir,
+        source_root=root,
+        source=model_src,
+    )
     device, device_src = _pick_optional_device(
         cli_val=cli_embedding_device,
         env_key="SBERT_DEVICE",

java_codebase_rag/installer.py

@@ -759,6 +759,11 @@ def generate_yaml_config(
         else:
             config["embedding"].pop("model", None)
 
+    # Seed cross-service resolution safe-by-default: only evidence-backed cross-service
+    # edges survive (see _is_brownfield_sourced in build_ast_graph). setdefault preserves
+    # an explicit user choice (e.g. `auto`) on re-run update.
+    config.setdefault("cross_service_resolution", "brownfield_only")
+
     # Keys NOT written by installer (preserved if present):
     # - source_root (config.py resolves from walk-up discovery)
     # - index_dir (config.py defaults to <source_root>/.java-codebase-rag)
@@ -1250,9 +1255,14 @@ def run_update(
         print("Skipping index update.")
         return EXIT_PARTIAL if has_artifact_failures else EXIT_SUCCESS
 
-    # Resolve configuration
+    # Resolve configuration. Pass source_root=None so the YAML ``source_root``
+    # field is honored exactly like increment/init/reprocess — passing the
+    # discovered config dir here routes resolve_operator_config into the
+    # explicit-override branch that SKIPS the YAML field, which made `update`
+    # point cocoindex at the config dir (no Java) against the real index and
+    # mass-delete it. Discovery still runs against the CLI's cwd.
     try:
-        cfg = resolve_operator_config(source_root=project_root, cli_index_dir=None)
+        cfg = resolve_operator_config(source_root=None, cli_index_dir=None)
         index_dir = cfg.index_dir
     except Exception as e:
         print(f"\nWarning: Failed to resolve configuration: {e}")

{java_codebase_rag-0.6.0.dist-info → java_codebase_rag-0.6.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.6.0
+Version: 0.6.2
 Summary: MCP server for semantic + structural search over Java codebases
 Author: HumanBean17
 License-Expression: MIT
@@ -35,6 +35,7 @@ Requires-Dist: unidiff<1,>=0.7.3
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-xdist>=3; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
 Dynamic: license-file
 

{java_codebase_rag-0.6.0.dist-info → java_codebase_rag-0.6.2.dist-info}/RECORD

@@ -1,33 +1,33 @@
-ast_java.py,sha256=TMesuv4SYqzkwfKxf_Pps0KaPLZNZOrhU8mL20bwqeQ,98882
+ast_java.py,sha256=NQgZzstbsMq-PdowoD6r_ixJKxEEFzTP9xUzqDpiXeU,99661
 brownfield_events.py,sha256=yxXkKDgMb3VPtaiakGzncHM_EGnda8xIue6w90yYp8s,2055
-build_ast_graph.py,sha256=GNbjiIAwsXaJQ9Je6gbR-dB9SbnaLThya2pEw3tggQs,152396
+build_ast_graph.py,sha256=OKigswkUmWwUAKXXRNH4zplw2VonIdWUWzVjC-t5roo,152893
 chunk_heuristics.py,sha256=aQk2NOKxzUdqoUAJUO3G3LE0MN_bYZWNLQ0tkmj5uts,1813
 graph_enrich.py,sha256=POT4LwSkTsrjUmP67bsm2UezUam70cunuPDYDh-v1Bs,63332
 index_common.py,sha256=HT6FKHFJ084eFvd3fR1j8z8gf4eWoPHVW8GXLpw464I,285
 java_index_flow_lancedb.py,sha256=MH9iTNF6HDHDTt5Jn7TOVE5hQ4WUPNt7PlQoh1tuh9o,13212
 java_index_v1_common.py,sha256=nF1KrSqboF_RRvWerG9knRRFmWwsrG_CvhgnsoZ8KqA,1154
-java_ontology.py,sha256=FcnOq1XWhUP03OfnTkRStslqrNyukzUKH7VNuK6Bme4,16425
+java_ontology.py,sha256=71bCLDNvMy0SpZPzSR5apJ0qJXNd6y5ggkLdBEw_PFo,16682
 ladybug_queries.py,sha256=912j9VAYDjcU4ReVorWQ6R4DZl0tteKic-Pqu0jyBS0,90837
 mcp_hints.py,sha256=3swh05LSiWur3tm3-yssndBsLxIxFhy501kBtJI8jJ0,42509
-mcp_v2.py,sha256=64UDrQ27hAQtlz3pFp9A3Xlk95bUjYZ4VBscsyAPCIY,79116
+mcp_v2.py,sha256=o94GJI7j6dLJDIA3R_1ZiQhjzQfMAEW3etdeZYnHOUc,80637
 path_filtering.py,sha256=-oX16SYLWYwX9pcV1fu3vbVTIhY1GzFflT7J1E2tqPY,17122
 pr_analysis.py,sha256=3-5L8_G5XupdJsl9RN73Lq-ejPoK11B3m_VzAx2fGG8,18413
 search_lancedb.py,sha256=scG6HBUrsgIeSWFrGcLcGdhWv1qODOx4JOBMAlLDY_E,36793
-server.py,sha256=uGKT0PdM-bVrzIsfbxF6ZuHGcuRMSSlvkJk0e7Ff43Y,30556
+server.py,sha256=Js3XDpV7ThAtj352StH6QdhHutf1D5qUkbR-8k3jO8g,31303
 java_codebase_rag/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 java_codebase_rag/_fdlimit.py,sha256=WroFdfSNbcriKok6q8znTf74dqlznxea_1Fd5bHl_3o,1930
-java_codebase_rag/cli.py,sha256=a5IFLWAsh77mfLv1Z9OdpvLaYvj4i0KR3_kLtL-ans8,34156
+java_codebase_rag/cli.py,sha256=HkzCP8-G3WlCzoXcVCI2K3forDOMpTmUSoxgx3jbKk4,34774
 java_codebase_rag/cli_format.py,sha256=arU7P9W6Fvm7X_wzR1wJ8EfyxK1rDP_ESEhdA0ub4Mo,2579
 java_codebase_rag/cli_progress.py,sha256=9jCqEagYOXs32SYVA31_sOCrONvYy7cl1CrdBD2Pg44,3168
-java_codebase_rag/config.py,sha256=u4OomvglTWHUmMpcxN8wPRnRGfXVp3qK_GJ5pY96O98,16267
-java_codebase_rag/installer.py,sha256=DlBuVVWbHXgcjaQkuXUeT9fNdmk7XZefVT3zzw47k18,45965
+java_codebase_rag/config.py,sha256=bfwYI4R8PU9YV_M4r8-03iaUZ_0TW-qN_NuhIsDXy2M,18769
+java_codebase_rag/installer.py,sha256=sE0l85K_o291PdpF1vpesefR9VgdvvVeARXrpTxa30A,46689
 java_codebase_rag/lance_optimize.py,sha256=MzACYlgwxmkJCK64qQLyIAdizSq5BARqaMYSZONlc1I,6069
 java_codebase_rag/pipeline.py,sha256=UcgluFAW9Ghnas8u40x45bVic0mQv6rjzcliDKsnYJI,11936
 java_codebase_rag/install_data/agents/explorer-rag-enhanced.md,sha256=APl9d-No12qZNZLjU7mwNRwxHIgnT3ZtQZiD4clWlyU,14413
 java_codebase_rag/install_data/skills/explore-codebase/SKILL.md,sha256=pIM-Xdwq_fXkhhBJCdb-fA2nes5c_mMPcdUXb7Adyxo,12040
-java_codebase_rag-0.6.0.dist-info/licenses/LICENSE,sha256=gxvtiHtuviR_q8ZAjWw-QTcF3DyPzg6ZY-lQrr8OPpw,1068
-java_codebase_rag-0.6.0.dist-info/METADATA,sha256=GoMO3zFTb98w4rVV5SMXpcLK-irlDs7aUH0wBGlv5cQ,16887
-java_codebase_rag-0.6.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-java_codebase_rag-0.6.0.dist-info/entry_points.txt,sha256=mVVQJa0n73OWfhHXYCDoPRrWin_LJhH2Rn0CkJ2iax4,101
-java_codebase_rag-0.6.0.dist-info/top_level.txt,sha256=syQgi8XPBwY2ws_NZ1uRCxTf_s41NpshwEHNdcdnk3A,245
-java_codebase_rag-0.6.0.dist-info/RECORD,,
+java_codebase_rag-0.6.2.dist-info/licenses/LICENSE,sha256=gxvtiHtuviR_q8ZAjWw-QTcF3DyPzg6ZY-lQrr8OPpw,1068
+java_codebase_rag-0.6.2.dist-info/METADATA,sha256=X92kaZ5TbEacz0sznWtUtpYEJvBdWIXX0s8MlqOeRyg,16934
+java_codebase_rag-0.6.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+java_codebase_rag-0.6.2.dist-info/entry_points.txt,sha256=wsPZwot0Ui4JI3TIgW8LcbN8bNtKFbwQAlHAAJXfYgQ,117
+java_codebase_rag-0.6.2.dist-info/top_level.txt,sha256=syQgi8XPBwY2ws_NZ1uRCxTf_s41NpshwEHNdcdnk3A,245
+java_codebase_rag-0.6.2.dist-info/RECORD,,

java_codebase_rag-0.6.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+java-codebase-rag = java_codebase_rag.cli:_console_script_main
+java-codebase-rag-mcp = server:main

java_ontology.py

@@ -15,7 +15,10 @@ from ast_java import (
     _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:

server.py

@@ -7,7 +7,7 @@ import os
 import sys
 import time
 from pathlib import Path
-from typing import Any, Literal
+from typing import Literal
 
 import mcp_v2
 from index_common import SBERT_MODEL
@@ -31,14 +31,14 @@ from search_lancedb import TABLES
 
 _COCOINDEX_TARGET = "java_index_flow_lancedb.py:JavaCodeIndexLance"
 _INSTRUCTIONS = (
-    "Java codebase graph navigator (LanceDB + Ladybug). "
+    "Java codebase graph navigator over an indexed Java codebase. "
     "Tools: search (NL/code locate), find (structured NodeFilter), describe (one node + edge_summary: stored edge-label counts and optional composed keys for type Symbols and override-axis virtual keys for method Symbols), "
     "neighbors (one hop; you MUST pass direction in|out AND edge_types list — no defaults), "
-    "resolve (identifier-shaped lookup for symbol/route/client/producer — three statuses one|many/none). "
-    "NodeFilter `filter` is a JSON object (preferred); a JSON-encoded string is also accepted as a fallback. "
+    "resolve (identifier-shaped lookup for symbol/route/client/producer — three statuses: one | many | none). "
     "Unknown filter keys and populated fields not applicable to the effective node kind fail with success=false and message. "
+    "Successful responses from any tool may include `hints_structured` (tool call suggestions with a `reason` field) and `advisories` (pure informational text) when hints are enabled. "
     "Edge labels: EXTENDS, IMPLEMENTS, INJECTS, OVERRIDES, DECLARES, DECLARES_CLIENT, DECLARES_PRODUCER, CALLS, EXPOSES, HTTP_CALLS, ASYNC_CALLS; "
-    "type Symbols may also use composed neighbors edge_types DECLARES.DECLARES_CLIENT, DECLARES.DECLARES_PRODUCER, DECLARES.EXPOSES (out only). "
+    "type Symbols may also use composed neighbors edge_types DECLARES.DECLARES_CLIENT, DECLARES.DECLARES_PRODUCER, DECLARES.EXPOSES (out only, type Symbol origin). "
     "Reprocess/init, meta, tables, diagnose-ignore, analyze-pr: use java-codebase-rag CLI — not MCP."
 )
 
@@ -123,19 +123,15 @@ class ScopeManager:
             print("[scope] No microservice detected (at project root)", file=sys.stderr)
             print("[scope] Queries will span all microservices", file=sys.stderr)
 
-    def apply_auto_scope(self, node_filter: dict[str, Any] | None) -> dict[str, Any] | None:
+    def apply_auto_scope(self, node_filter: mcp_v2.NodeFilter | None) -> mcp_v2.NodeFilter | None:
         """Apply auto-detected scope to filter if no explicit microservice is set."""
         if self.default_scope is None:
             return node_filter
-        # Convert to dict for manipulation
         if node_filter is None:
-            filter_dict = {}
-        else:
-            filter_dict = dict(node_filter)
-        # Only inject if user didn't specify microservice
-        if "microservice" not in filter_dict:
-            filter_dict["microservice"] = self.default_scope
-        return filter_dict
+            return mcp_v2.NodeFilter(microservice=self.default_scope)
+        if node_filter.microservice is None:
+            return node_filter.model_copy(update={"microservice": self.default_scope})
+        return node_filter
 
 
 def _resolve_lancedb_uri() -> str:
@@ -159,6 +155,27 @@ def _project_root() -> Path:
     return discovered if discovered is not None else Path.cwd().resolve()
 
 
+def _source_root_for_operator_config() -> Path | None:
+    """``source_root`` arg to hand ``resolve_operator_config`` from the MCP server.
+
+    Returns ``JAVA_CODEBASE_RAG_SOURCE_ROOT`` when set (an explicit operator
+    override that wins and suppresses the YAML ``source_root`` field, exactly
+    like CLI ``--source-root``), otherwise ``None`` — so
+    ``resolve_operator_config`` runs its OWN walk-up discovery and HONORS the
+    YAML ``source_root`` field, matching the CLI (``init`` / ``increment`` /
+    ``reprocess``) path.
+
+    Do NOT pass ``_project_root()`` (the walk-up-discovered dir) here: a
+    non-``None`` value routes into the "explicit source root" branch that
+    skips the YAML ``source_root`` field, which made the MCP server and the
+    CLI resolve different ``source_root`` / ``index_dir`` from the same config
+    file (the init-vs-MCP index_dir divergence). ``_project_root()`` is kept
+    only for the ``_resolve_lancedb_uri()`` fallback below.
+    """
+    env = os.environ.get("JAVA_CODEBASE_RAG_SOURCE_ROOT", "").strip()
+    return Path(env).expanduser().resolve() if env else None
+
+
 def _cocoindex_subprocess_env(project_root: Path) -> dict[str, str]:
     sub_env = os.environ.copy()
     sub_env["JAVA_CODEBASE_RAG_SOURCE_ROOT"] = str(project_root)
@@ -413,14 +430,15 @@ def create_mcp_server() -> FastMCP:
     @mcp.tool(
         name="search",
         description=(
-            "Ranked chunk retrieval: `query` is opaque text (natural language or code fragments); "
-            "results are score-ranked, not boolean-matched. Optional `filter` uses the same NodeFilter "
-            "schema as `find` but only **symbol-applicable** fields apply (strict frame). Wildcards "
+            "Ranked chunk retrieval over content tables (java/sql/yaml); `query` is opaque text (natural language or code "
+            "fragments) and results are score-ranked, not boolean-matched. For graph-structured listing "
+            "(symbols/routes/clients/producers) use `find`, not `search`. Optional `filter` uses the same NodeFilter "
+            "schema as `find` but only **symbol-applicable** fields apply — others return success=false. Wildcards "
             "(`*`, `?`) in prefix fields are rejected—use ranked `query` text instead. There is **no** "
             "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_structured` (tool call suggestions with `reason` field) and `advisories` (pure informational text)."
+            "Successful responses echo `limit`/`offset`."
         ),
     )
     async def search(
@@ -431,7 +449,7 @@ def create_mcp_server() -> FastMCP:
         ),
         hybrid: bool = Field(
             default=False,
-            description="If true, fuse FTS + vector (single-table java/sql/yaml only)",
+            description="If true, fuse FTS + vector. Requires a single table (java/sql/yaml); hybrid with table='all' returns success=false.",
         ),
         limit: int = Field(default=5, ge=1, le=50, description="Max hits to return"),
         offset: int = Field(default=0, ge=0, le=500, description="Skip this many hits (pagination)"),
@@ -439,11 +457,11 @@ def create_mcp_server() -> FastMCP:
             default=None,
             description="Substring match on file path (pre-filter from index)",
         ),
-        filter: dict[str, Any] | str | None = Field(
+        filter: mcp_v2.NodeFilter | None = Field(
             default=None,
             description=(
-                "Optional NodeFilter post-filter on symbol-oriented hit rows. Unknown keys or populated fields not "
-                "applicable to symbols return success=false. Prefer a JSON object; a JSON-encoded string is accepted."
+                "Optional NodeFilter post-filter on symbol-oriented hit rows. An empty object or omitted means no "
+                "predicate. Unknown keys or populated fields not applicable to symbols return success=false."
             ),
         ),
     ) -> mcp_v2.SearchOutput:
@@ -468,9 +486,11 @@ def create_mcp_server() -> FastMCP:
             "**route** — microservice, module, http_method, path_prefix, framework; **client** — microservice, module, "
             "source_layer, client_kind, target_service, target_path_prefix, http_method; **producer** — microservice, "
             "module, source_layer, producer_kind, topic_prefix. "
+            "`role` is singular and `exclude_roles` plural; `capability` is a functional tag assigned during indexing. "
+            "`fqn_prefix` is a prefix predicate — for exact FQN or id lookup use `resolve`/`describe`. "
             "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_structured` (tool call suggestions with `reason` field) and `advisories` (pure informational text)."
+            "Successful responses echo `limit`/`offset`."
         ),
     )
     async def find(
@@ -481,11 +501,10 @@ def create_mcp_server() -> FastMCP:
                 "'producer' = outbound async producers."
             )
         ),
-        filter: dict[str, Any] | str = Field(
+        filter: mcp_v2.NodeFilter = Field(
             ...,
             description=(
-                "Required NodeFilter dict (extra keys forbidden). Fields must be applicable to `kind`. "
-                "Prefer a JSON object; a JSON-encoded string is accepted."
+                "Required NodeFilter object (extra keys forbidden). Fields must be applicable to `kind`."
             ),
         ),
         limit: int = Field(default=25, ge=1, le=500, description="Max nodes to return"),
@@ -497,17 +516,14 @@ def create_mcp_server() -> FastMCP:
     @mcp.tool(
         name="describe",
         description=(
-            "Full node record plus `edge_summary` (in/out counts per stored edge label, plus optional describe-time keys). Type Symbols may add "
-            "composed keys DECLARES.DECLARES_CLIENT, DECLARES.DECLARES_PRODUCER, and DECLARES.EXPOSES (navigable on type Symbols via neighbors, out only); "
-            "method Symbols may add override-axis virtual keys (OVERRIDDEN_BY, OVERRIDDEN_BY.DECLARES_CLIENT, OVERRIDDEN_BY.DECLARES_PRODUCER, "
-            "OVERRIDDEN_BY.EXPOSES, plus an `OVERRIDES` map entry that merges stored `[:OVERRIDES]` counts with the dispatch-up rollup per direction). "
-            "Override-axis virtual keys are navigable via neighbors on non-static method Symbol origins "
-            "(out only; composed keys include via_id in attrs). The stored `OVERRIDES` relationship "
-            "is also a normal edge label (e.g. direction in from declaration toward overriders). "
+            "Full node record plus `edge_summary` (in/out counts per stored edge label). For type Symbols, `edge_summary` "
+            "also exposes composed keys (DECLARES.DECLARES_CLIENT, DECLARES.DECLARES_PRODUCER, DECLARES.EXPOSES); for "
+            "non-static method Symbols it adds override-axis virtual keys (OVERRIDDEN_BY and its composed forms, plus an "
+            "`OVERRIDES` map merging stored `[:OVERRIDES]` counts with the dispatch-up rollup). These composed/override keys "
+            "are out-only and navigable via `neighbors`; the stored `OVERRIDES` is also a normal edge label (in toward declaration). "
             "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_structured` (tool call suggestions with `reason` field) and `advisories` (pure informational text)."
+            "prefer `resolve(identifier=…, hint_kind='symbol')` first, then `describe(id=…)` on the chosen node."
         ),
     )
     async def describe(
@@ -531,18 +547,19 @@ def create_mcp_server() -> FastMCP:
     @mcp.tool(
         name="neighbors",
         description=(
-            "Graph walk: **direction** (`in` | `out`) and non-empty **edge_types** are required (stored labels for one hop; "
-            "type Symbol origins may also pass composed DECLARES.DECLARES_CLIENT, DECLARES.DECLARES_PRODUCER, or DECLARES.EXPOSES "
-            "for 2-hop member rollups; method Symbol origins may pass OVERRIDDEN_BY, OVERRIDDEN_BY.DECLARES_CLIENT, "
-            "OVERRIDDEN_BY.DECLARES_PRODUCER, OVERRIDDEN_BY.EXPOSES for override-axis rollups — out only, via_id in "
-            "attrs on composed keys). "
+            "Graph walk: **direction** (`in` | `out`) and non-empty **edge_types** are required (one hop over stored edge "
+            "labels; type/method Symbol origins may also pass composed or override-axis keys — see `edge_types`). From a "
+            "type Symbol, `direction='out'` with EXPOSES yields route nodes and HTTP_CALLS/ASYNC_CALLS yield client/producer "
+            "nodes; `direction='in'` reverses each relationship. "
+            "`direction` and `edge_types` have no defaults; an empty `edge_types` fails. The CALLS-only features — "
+            "`edge_filter`, `include_unresolved`, `dedup_calls` — each require `edge_types=['CALLS']`; `edge_filter` and "
+            "`include_unresolved` are mutually exclusive. Violating a precondition (wrong CALLS context, composed/override "
+            "keys on an ineligible origin or with `direction='in'`, wildcards in prefix fields, unknown filter keys) returns "
+            "success=false with a message; `dedup_calls` with other edge_types is a silent no-op. "
             "Optional `filter` applies to each neighbor endpoint row; populated fields must be applicable to that "
-            "neighbor's kind—mixed-kind result sets fail on the first inapplicable neighbor (strict frame). "
-            "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_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)."
+            "neighbor's kind—mixed-kind result sets fail on the first inapplicable neighbor (per-neighbor strict frame). "
+            "Each edge's `attrs.strategy` indicates resolution quality (brownfield/fallback vs primary paths). "
+            "Successful responses echo `requested_edge_types`."
         ),
     )
     async def neighbors(
@@ -573,19 +590,19 @@ def create_mcp_server() -> FastMCP:
             le=1000,
             description="Skip this many edges after merge (pagination)",
         ),
-        filter: dict[str, Any] | str | None = Field(
+        filter: mcp_v2.NodeFilter | None = Field(
             default=None,
             description=(
-                "Optional NodeFilter on the neighbor node. Same applicability rules as `find` for that node's kind. "
-                "Prefer a JSON object; a JSON-encoded string is accepted."
+                "Optional NodeFilter on the neighbor node. An empty object or omitted means no predicate. "
+                "Same applicability rules as `find` for that node's kind."
             ),
         ),
-        edge_filter: dict[str, Any] | str | None = Field(
+        edge_filter: mcp_v2.EdgeFilter | None = Field(
             default=None,
             description=(
                 "Optional EdgeFilter on CALLS edge attributes (edge_types=['CALLS'] only). Use "
                 "callee_declaring_role for callee stereotype projection — not NodeFilter.role on method neighbors. "
-                "Mutually exclusive with include_unresolved. Prefer a JSON object; a JSON-encoded string is accepted."
+                "Mutually exclusive with include_unresolved."
             ),
         ),
         include_unresolved: bool = Field(
@@ -627,10 +644,11 @@ 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 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'); "
+            "resolve('PaymentClient', hint_kind='client'); "
+            "resolve('order.created', hint_kind='producer'); "
             "resolve('the client that handles assignments') → none (use search instead)."
         ),
     )
@@ -657,7 +675,7 @@ def main() -> None:
     # Load YAML config and apply embedding settings to environment
     # This ensures SBERT_MODEL and SBERT_DEVICE from .java-codebase-rag.yml are available
     # before any tool handler runs (same behavior as CLI path)
-    cfg = resolve_operator_config(source_root=_project_root())
+    cfg = resolve_operator_config(source_root=_source_root_for_operator_config())
     cfg.apply_to_os_environ()
     mcp_v2.set_hints_enabled(cfg.hints_enabled)
 

java_codebase_rag-0.6.0.dist-info/entry_points.txt

@@ -1,3 +0,0 @@
-[console_scripts]
-java-codebase-rag = java_codebase_rag.cli:main
-java-codebase-rag-mcp = server:main