groundworkers 0.1.0__py3-none-any.whl

groundworkers/base/server.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable
+
+
+class GroundcrewServer:
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self._tools: dict[str, Callable[..., Any]] = {}
+
+    def tool(self, name: str | None = None) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            tool_name = name or func.__name__
+            self._tools[tool_name] = func
+            return func
+
+        return decorator
+
+    def list_tools(self) -> list[str]:
+        return sorted(self._tools.keys())
+
+    def call(self, name: str, *args: Any, **kwargs: Any) -> Any:
+        return self._tools[name](*args, **kwargs)
+
+    def describe_tools(self) -> dict[str, dict[str, Any]]:
+        description: dict[str, dict[str, Any]] = {}
+        for name, func in self._tools.items():
+            signature = inspect.signature(func)
+            description[name] = {
+                "signature": str(signature),
+                "doc": inspect.getdoc(func) or "",
+            }
+        return description
+
+    def run(
+        self,
+        transport: str = "stdio",
+        host: str = "127.0.0.1",
+        port: int = 8000,
+    ) -> None:
+        try:
+            from mcp.server.fastmcp import FastMCP
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError(
+                "The official MCP Python SDK is required to run the server. Install project dependencies first."
+            ) from exc
+
+        app = FastMCP(self.name, host=host, port=port)
+        for tool_name, func in self._tools.items():
+            app.tool(name=tool_name)(func)
+        app.run(transport=transport)

groundworkers/base/sql.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import MetaData, Table, and_, create_engine, func, or_, select, text
+from sqlalchemy.engine import Engine
+
+from groundworkers.base.results import DetailResult, ListResult, SearchHit, SearchResult
+from groundworkers.config import FullTextConfig, SqlResourceConfig
+
+
+class SQLResource:
+    def __init__(self, engine: Engine, resource_id: str, config: SqlResourceConfig) -> None:
+        self.engine = engine
+        self.resource_id = resource_id
+        self.config = config
+        self._table: Table | None = None
+
+    @property
+    def table(self) -> Table:
+        if self._table is None:
+            metadata = MetaData(schema=self.config.db_schema)
+            self._table = Table(self.config.table, metadata, autoload_with=self.engine)
+        return self._table
+
+    def _project(self, row: Any) -> dict[str, Any]:
+        mapping = dict(row._mapping)
+        if self.config.display_fields:
+            return {field: mapping.get(field) for field in self.config.display_fields}
+        return mapping
+
+    def _validate_filters(self, filters: dict[str, Any] | None) -> dict[str, Any]:
+        if not filters:
+            return {}
+        invalid = sorted(set(filters) - set(self.config.allowed_filter_fields or []))
+        if invalid:
+            raise ValueError(f"Unsupported filter fields for {self.resource_id}: {', '.join(invalid)}")
+        return filters
+
+    def get(self, key: Any) -> DetailResult:
+        statement = select(self.table).where(self.table.c[self.config.primary_key] == key).limit(1)
+        with self.engine.connect() as connection:
+            row = connection.execute(statement).first()
+        return DetailResult(resource_id=self.resource_id, item=self._project(row) if row else None)
+
+    def list(self, *, limit: int = 20, offset: int = 0, filters: dict[str, Any] | None = None) -> ListResult:
+        safe_limit = max(1, min(limit, 100))
+        safe_offset = max(0, offset)
+        validated = self._validate_filters(filters)
+        predicates = [self.table.c[column] == value for column, value in validated.items()]
+        statement = select(self.table)
+        count_stmt = select(func.count()).select_from(self.table)
+        if predicates:
+            predicate = and_(*predicates)
+            statement = statement.where(predicate)
+            count_stmt = count_stmt.where(predicate)
+        statement = statement.limit(safe_limit).offset(safe_offset)
+        with self.engine.connect() as connection:
+            rows = connection.execute(statement).all()
+            total = connection.execute(count_stmt).scalar_one()
+        return ListResult(
+            resource_id=self.resource_id,
+            items=[self._project(row) for row in rows],
+            total=int(total),
+            limit=safe_limit,
+            offset=safe_offset,
+        )
+
+
+class SQLTextSearchResource(SQLResource):
+    def __init__(self, engine: Engine, resource_id: str, config: SqlResourceConfig, fulltext: FullTextConfig) -> None:
+        super().__init__(engine, resource_id, config)
+        self.fulltext = fulltext
+        self._search_table: Table | None = None
+
+    @property
+    def search_table(self) -> Table:
+        if self._search_table is None:
+            metadata = MetaData(schema=self.fulltext.db_schema)
+            self._search_table = Table(self.fulltext.table, metadata, autoload_with=self.engine)
+        return self._search_table
+
+    def search(self, query: str, *, limit: int = 10) -> SearchResult:
+        safe_limit = max(1, min(limit, 50))
+        dialect = self.engine.dialect.name
+        table = self.search_table
+        if dialect == "postgresql" and self.fulltext.vector_column:
+            where_clause = text(f"{self.fulltext.vector_column} @@ plainto_tsquery(:query)")
+            statement = select(table).where(where_clause).limit(safe_limit).params(query=query)
+        else:
+            predicates = [table.c[field].ilike(f"%{query}%") for field in self.fulltext.search_fields if field in table.c]
+            if not predicates:
+                raise ValueError(f"No search fields configured for {self.resource_id}")
+            statement = select(table).where(or_(*predicates)).limit(safe_limit)
+        with self.engine.connect() as connection:
+            rows = connection.execute(statement).all()
+        items = [
+            SearchHit(
+                id=str(row._mapping.get(self.config.primary_key, index)),
+                score=1.0,
+                payload=dict(row._mapping),
+            )
+            for index, row in enumerate(rows)
+        ]
+        return SearchResult(resource_id=self.resource_id, query=query, items=items, limit=safe_limit)
+
+
+def build_engine(url: str) -> Engine:
+    return create_engine(url, future=True)

groundworkers/config.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+SCHEMA_NAME_PATTERN = re.compile(r"^[A-Za-z0-9_]+$")
+
+
+class FullTextConfig(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    db_schema: str | None = Field(default=None, alias="schema")
+    table: str
+    search_fields: list[str] = Field(default_factory=list)
+    vector_column: str | None = None
+
+
+class EmbeddingIndexConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    path: str
+    ids_dataset: str = "ids"
+    vectors_dataset: str = "vectors"
+    payloads_dataset: str | None = None
+
+
+class SqlResourceConfig(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    db_schema: str | None = Field(default=None, alias="schema")
+    table: str
+    primary_key: str
+    allowed_filter_fields: list[str] = Field(default_factory=list)
+    search_fields: list[str] = Field(default_factory=list)
+    display_fields: list[str] = Field(default_factory=list)
+    fulltext: FullTextConfig | None = None
+    embedding_index: EmbeddingIndexConfig | None = None
+
+
+class ModuleConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = True
+    resources: dict[str, SqlResourceConfig] = Field(default_factory=dict)
+    relationship_resource: str | None = None
+    relationship_left_key: str | None = None
+    relationship_right_key: str | None = None
+    concept_reference_columns: dict[str, str] = Field(default_factory=dict)
+
+
+class DatabaseConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    url: str
+
+
+class OmopGraphConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    db_url: str
+    vocab_schema: str = "omop_vocab"
+    emb_model_name: str | None = None
+
+    @field_validator("vocab_schema")
+    @classmethod
+    def validate_schema_name(cls, value: str) -> str:
+        if SCHEMA_NAME_PATTERN.fullmatch(value):
+            return value
+        raise ValueError("schema names must contain only letters, numbers, and underscores")
+
+
+class OmopEmbConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = False
+    db_url: str | None = None
+    backend_type: str = "sqlitevec"
+    db_path: str | None = None
+    default_model_name: str | None = None
+    faiss_cache_dir: str | None = None
+    api_base: str | None = None
+    api_key: str | None = None
+
+    @model_validator(mode="after")
+    def validate_enabled_backend(self) -> OmopEmbConfig:
+        if not self.enabled:
+            return self
+        if not self.db_url and not self.db_path:
+            raise ValueError("enabled omop_emb config requires db_url or db_path")
+        if self.api_base and not self.api_key:
+            raise ValueError("omop_emb.api_key is required when api_base is configured")
+        return self
+
+    @property
+    def configured_api_credentials(self) -> tuple[str, str] | None:
+        if self.api_base is None:
+            return None
+        if self.api_key is None:
+            raise ValueError("omop_emb.api_key is required when api_base is configured")
+        return self.api_base, self.api_key
+
+    @property
+    def required_db_url(self) -> str:
+        if self.db_url is None:
+            raise ValueError("omop_emb.db_url is required for this configuration")
+        return self.db_url
+
+    @property
+    def required_db_path(self) -> str:
+        if self.db_path is None:
+            raise ValueError("omop_emb.db_path is required for this configuration")
+        return self.db_path
+
+
+class AppConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    app_name: str = "groundworkers"
+    database: DatabaseConfig | None = None
+    omop_graph: OmopGraphConfig | None = None
+    omop_emb: OmopEmbConfig | None = None
+
+    @classmethod
+    def load(cls, path: str | Path) -> "AppConfig":
+        data = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
+        return cls.model_validate(data)
+
+    def describe(self) -> dict[str, Any]:
+        return {
+            "app_name": self.app_name,
+            "database_url": self.database.url if self.database else None,
+            "omop_graph": self.omop_graph.model_dump() if self.omop_graph else None,
+            "omop_emb": self.omop_emb.model_dump() if self.omop_emb else None,
+        }

groundworkers/server.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import dataclass
+
+from omop_emb import EmbeddingClient
+
+from groundworkers.adapters.omop_emb import OmopEmbAdapter
+from groundworkers.adapters.omop_graph import OmopGraphAdapter
+from groundworkers.adapters.omop_vocab import OmopVocabAdapter
+from groundworkers.base.server import GroundcrewServer
+from groundworkers.base.sql import build_engine
+from groundworkers.config import AppConfig
+from groundworkers.tools.concept_tools import register_concept_tools
+from groundworkers.tools.embedding_tools import register_embedding_tools
+from groundworkers.tools.resolver_tools import register_resolver_tools
+from groundworkers.tools.search_tools import register_search_tools
+from groundworkers.tools.system_tools import register_system_tools
+
+
+@dataclass
+class Adapters:
+    omop_graph: OmopGraphAdapter | None = None
+    omop_vocab: OmopVocabAdapter | None = None
+    omop_emb: OmopEmbAdapter | None = None
+
+
+def build_adapters(config: AppConfig) -> Adapters:
+    adapters = Adapters()
+
+    omop_graph = config.omop_graph
+    if omop_graph is not None:
+        engine = build_engine(omop_graph.db_url)
+        adapters.omop_graph = OmopGraphAdapter(
+            engine=engine,
+            vocab_schema=omop_graph.vocab_schema,
+            emb_model_name=omop_graph.emb_model_name,
+        )
+        # OmopVocabAdapter shares the same engine — no separate connection pool.
+        adapters.omop_vocab = OmopVocabAdapter(engine=engine)
+
+    omop_emb = config.omop_emb
+    if omop_emb is not None and omop_emb.enabled:
+        cdm_engine = adapters.omop_graph.engine if adapters.omop_graph is not None else None
+
+        def build_backend() -> object:
+            backend_type = omop_emb.backend_type.lower()
+            if backend_type == "sqlitevec":
+                # Requires groundworkers[embedding-sqlitevec] → omop-emb[sqlitevec]
+                from omop_emb.backends.sqlitevec import SQLiteVecEmbeddingBackend
+                return SQLiteVecEmbeddingBackend.from_path(omop_emb.required_db_path)
+            if backend_type == "pgvector":
+                # Requires groundworkers[embedding-pgvector] → omop-emb[pgvector]
+                from omop_emb.backends.pgvector import PGVectorEmbeddingBackend
+                engine = build_engine(omop_emb.required_db_url)
+                return PGVectorEmbeddingBackend(emb_engine=engine)
+            raise RuntimeError(f"Unsupported embedding backend type: {omop_emb.backend_type}")
+
+        client_factory = None
+        api_credentials = omop_emb.configured_api_credentials
+        if api_credentials is not None:
+            api_base, api_key = api_credentials
+
+            def build_client(model_name: str) -> object:
+                return EmbeddingClient(
+                    model=model_name,
+                    api_base=api_base,
+                    api_key=api_key,
+                )
+
+            client_factory = build_client
+
+        adapters.omop_emb = OmopEmbAdapter(
+            backend_factory=build_backend,
+            backend_type=omop_emb.backend_type,
+            default_model_name=omop_emb.default_model_name,
+            client_factory=client_factory,
+            cdm_engine=cdm_engine,
+            faiss_cache_dir=omop_emb.faiss_cache_dir,
+        )
+
+    return adapters
+
+
+def create_server(config: AppConfig) -> GroundcrewServer:
+    server = GroundcrewServer(config.app_name)
+    adapters = build_adapters(config)
+    server.adapters = adapters  # type: ignore[attr-defined]
+    if adapters.omop_graph is not None:
+        register_concept_tools(server, adapters.omop_graph)
+        register_resolver_tools(server, adapters.omop_graph)
+    if adapters.omop_vocab is not None:
+        register_search_tools(server, adapters.omop_vocab)
+    if adapters.omop_emb is not None:
+        register_embedding_tools(server, adapters.omop_emb)
+    register_system_tools(server, adapters.omop_graph, adapters.omop_emb)
+    return server
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Run the groundworkers MCP server")
+    parser.add_argument("--config", required=True, help="Path to a YAML configuration file")
+    parser.add_argument("--describe", action="store_true", help="Print configured tools and exit")
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "streamable-http"],
+        default="stdio",
+        help="MCP transport (default: stdio)",
+    )
+    parser.add_argument("--host", default="127.0.0.1", help="Bind host for HTTP transport (default: 127.0.0.1)")
+    parser.add_argument("--port", type=int, default=8000, help="Bind port for HTTP transport (default: 8000)")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    config = AppConfig.load(args.config)
+    server = create_server(config)
+    if args.describe:
+        print(json.dumps({"config": config.describe(), "tools": server.describe_tools()}, indent=2))
+        return
+    server.run(transport=args.transport, host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

groundworkers/tools/__init__.py

@@ -0,0 +1 @@
+

groundworkers/tools/concept_tools.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+from typing import Any
+
+from groundworkers.adapters.omop_graph import OmopGraphAdapter
+from groundworkers.base.errors import GroundworkersError
+from groundworkers.base.server import GroundcrewServer
+
+
+def register_concept_tools(server: GroundcrewServer, graph_adapter: OmopGraphAdapter) -> None:
+    """Register deterministic concept lookup tools against the MCP server.
+
+    These tools take a known identifier (concept_id, vocabulary+code) and return
+    a fact — they are deterministic lookups, not text matching.
+
+    For free-text grounding see resolver_tools.py.
+    For agent-composable search primitives see search_tools.py.
+    """
+
+    @server.tool("concept_get")
+    def concept_get(concept_id: int) -> dict[str, Any]:
+        """Returns one OMOP concept by concept_id."""
+        if concept_id <= 0:
+            return {"error": True, "code": "INVALID_INPUT", "message": "concept_id must be a positive integer"}
+        try:
+            concept = graph_adapter.get_concept(concept_id)
+            if concept is None:
+                return {"error": True, "code": "NOT_FOUND", "message": f"Concept {concept_id} was not found"}
+            return concept
+        except GroundworkersError as exc:
+            return exc.to_dict()
+        except Exception as exc:
+            return {"error": True, "code": "QUERY_ERROR", "message": repr(exc)}
+
+    @server.tool("concept_by_code")
+    def concept_by_code(vocabulary_id: str, concept_code: str) -> dict[str, Any]:
+        """Returns one OMOP concept by vocabulary_id and concept_code."""
+        if not vocabulary_id.strip():
+            return {"error": True, "code": "INVALID_INPUT", "message": "vocabulary_id must be a non-empty string"}
+        if not concept_code.strip():
+            return {"error": True, "code": "INVALID_INPUT", "message": "concept_code must be a non-empty string"}
+        try:
+            concepts = graph_adapter.get_concept_by_code(vocabulary_id, concept_code)
+            if not concepts:
+                return {
+                    "error": True,
+                    "code": "NOT_FOUND",
+                    "message": f"Concept {vocabulary_id}:{concept_code} was not found",
+                }
+            return {"concepts": concepts}
+        except GroundworkersError as exc:
+            return exc.to_dict()
+        except Exception as exc:
+            return {"error": True, "code": "QUERY_ERROR", "message": repr(exc)}
+
+    @server.tool("concept_ancestors")
+    def concept_ancestors(concept_id: int, max_depth: int = 5) -> dict[str, Any]:
+        """Returns ancestor concepts for one concept_id."""
+        if concept_id <= 0:
+            return {"error": True, "code": "INVALID_INPUT", "message": "concept_id must be a positive integer"}
+        safe_depth = max(1, min(max_depth, 20))
+        try:
+            ancestors = graph_adapter.get_ancestors(concept_id, safe_depth)
+            return {"concept_id": concept_id, "ancestors": ancestors}
+        except GroundworkersError as exc:
+            return exc.to_dict()
+        except Exception as exc:
+            return {"error": True, "code": "QUERY_ERROR", "message": repr(exc)}
+
+    @server.tool("concept_descendants")
+    def concept_descendants(concept_id: int, max_depth: int = 3) -> dict[str, Any]:
+        """Returns descendant concepts for one concept_id."""
+        if concept_id <= 0:
+            return {"error": True, "code": "INVALID_INPUT", "message": "concept_id must be a positive integer"}
+        safe_depth = max(1, min(max_depth, 10))
+        try:
+            descendants = graph_adapter.get_descendants(concept_id, safe_depth)
+            return {"concept_id": concept_id, "descendants": descendants}
+        except GroundworkersError as exc:
+            return exc.to_dict()
+        except Exception as exc:
+            return {"error": True, "code": "QUERY_ERROR", "message": repr(exc)}
+
+    @server.tool("concept_relationships")
+    def concept_relationships(concept_id: int) -> dict[str, Any]:
+        """Returns all relationships for a concept grouped by direction (inbound/outbound)."""
+        if concept_id <= 0:
+            return {"error": True, "code": "INVALID_INPUT", "message": "concept_id must be a positive integer"}
+        try:
+            edges = graph_adapter.get_edges(concept_id)
+            return {"concept_id": concept_id, **edges}
+        except GroundworkersError as exc:
+            return exc.to_dict()
+        except Exception as exc:
+            return {"error": True, "code": "QUERY_ERROR", "message": repr(exc)}
+
+    @server.tool("concept_equivalency_path")
+    def concept_equivalency_path(
+        source_id: int,
+        target_id: int,
+        allow_hierarchical_traversal: bool = False,
+        max_depth: int = 8,
+    ) -> dict[str, Any]:
+        """Returns the shortest equivalency path(s) between two OMOP concepts.
+
+        Traverses only identity and (optionally) hierarchy relationships —
+        never attribute, composition, or association edges.  Cross-domain
+        edges are always included because identity relationships are designed
+        to span vocabulary boundaries.
+
+        allow_hierarchical_traversal=False (default)
+          Only IDENTITY predicates: Maps to, Concept same_as, Concept poss_eq,
+          Mapped from, etc.  The path represents a direct cross-vocabulary
+          equivalence with no loss of specificity.
+
+        allow_hierarchical_traversal=True
+          Adds HIERARCHY predicates (Is a / Subsumes).  The path may step up
+          or down the ancestry chain, so the connection found may be at a
+          broader level of abstraction (e.g. source maps to an ancestor of
+          target rather than target itself).
+        """
+        if source_id <= 0 or target_id <= 0:
+            return {"error": True, "code": "INVALID_INPUT", "message": "source_id and target_id must be positive integers"}
+        safe_depth = max(2, min(max_depth, 15))
+        try:
+            result = graph_adapter.find_equivalency_path(
+                source_id, target_id, safe_depth, allow_hierarchical_traversal
+            )
+            return {"source_id": source_id, "target_id": target_id, **result}
+        except GroundworkersError as exc:
+            return exc.to_dict()
+        except Exception as exc:
+            return {"error": True, "code": "QUERY_ERROR", "message": repr(exc)}
+
+    @server.tool("concept_path")
+    def concept_path(
+        source_id: int,
+        target_id: int,
+        max_depth: int = 8,
+        within_domain: bool = True,
+    ) -> dict[str, Any]:
+        """Returns the shortest path(s) between two OMOP concepts across all relationship types.
+
+        Traverses every relationship kind in the concept graph: IDENTITY,
+        HIERARCHY, ATTRIBUTE, COMPOSITION, and ASSOCIATION.  Use this when
+        you want to find any conceptual connection regardless of relationship
+        type.
+
+        within_domain=True (default)
+          Only traverses edges where both endpoint concepts share the same
+          domain_id (e.g. Condition → Condition).  Reduces noise for most
+          queries.
+
+        within_domain=False
+          Allows cross-domain traversal.  Required when the path crosses
+          vocabulary/domain boundaries via attribute relationships such as
+          "Has asso morph", "Has finding site", or "Has associated procedure".
+        """
+        if source_id <= 0 or target_id <= 0:
+            return {"error": True, "code": "INVALID_INPUT", "message": "source_id and target_id must be positive integers"}
+        safe_depth = max(2, min(max_depth, 15))
+        try:
+            result = graph_adapter.find_path(source_id, target_id, safe_depth, within_domain=within_domain)
+            return {"source_id": source_id, "target_id": target_id, **result}
+        except GroundworkersError as exc:
+            return exc.to_dict()
+        except Exception as exc:
+            return {"error": True, "code": "QUERY_ERROR", "message": repr(exc)}
+
+    @server.tool("concept_neighbors")
+    def concept_neighbors(
+        concept_id: int,
+        max_depth: int = 2,
+        predicate_kinds: list[str] | None = None,
+        max_nodes: int = 100,
+        include_edges: bool = True,
+    ) -> dict[str, Any]:
+        """Bounded multi-hop neighborhood exploration for one concept.
+
+        Performs a BFS from the seed concept, following outgoing relationship
+        edges up to max_depth hops and collecting all reachable concepts and
+        the edges connecting them.  This reaches across all relationship types
+        simultaneously — hierarchy, identity, attribute, composition, and
+        association — unlike concept_ancestors / concept_descendants which only
+        follow the parent/child hierarchy.
+
+        Use this to discover what is conceptually related to a concept without
+        knowing in advance which relationship types connect them.  Typical uses:
+          - finding associated anatomical sites, morphologies, or procedures
+            for a clinical finding
+          - mapping a drug concept to its ingredient, dose forms, and routes
+          - exploring OMOP concept class membership and equivalence clusters
+
+        predicate_kinds: optional list restricting which edge types to follow.
+          Valid values: HIERARCHY, IDENTITY, ATTRIBUTE, COMPOSITION, ASSOCIATION.
+          When omitted, all relationship types are traversed.
+
+        max_depth: maximum hops from the seed (1–4, server-enforced).
+
+        max_nodes: stop after visiting this many distinct concepts (10–500,
+          server-enforced).  terminated_early=true and terminated_reason="max_nodes"
+          in the response indicate the traversal was cut short.
+
+        include_edges: when true (default) the edges list contains every
+          relationship edge in the discovered subgraph with its predicate_kind.
+          Set false when you only need the neighbor concept list.
+        """
+        if concept_id <= 0:
+            return {"error": True, "code": "INVALID_INPUT", "message": "concept_id must be a positive integer"}
+        safe_depth = max(1, min(max_depth, 4))
+        safe_nodes = max(10, min(max_nodes, 500))
+        try:
+            return graph_adapter.get_neighbors(
+                concept_id=concept_id,
+                max_depth=safe_depth,
+                predicate_kinds=predicate_kinds,
+                max_nodes=safe_nodes,
+                include_edges=include_edges,
+            )
+        except GroundworkersError as exc:
+            return exc.to_dict()
+        except Exception as exc:
+            return {"error": True, "code": "QUERY_ERROR", "message": repr(exc)}
+
+    @server.tool("concept_map_to_standard")
+    def concept_map_to_standard(vocabulary_id: str, concept_code: str) -> dict[str, Any]:
+        """Maps a vocabulary concept code to its standard OMOP equivalent(s)."""
+        if not vocabulary_id.strip():
+            return {"error": True, "code": "INVALID_INPUT", "message": "vocabulary_id must be a non-empty string"}
+        if not concept_code.strip():
+            return {"error": True, "code": "INVALID_INPUT", "message": "concept_code must be a non-empty string"}
+        try:
+            return graph_adapter.map_to_standard(vocabulary_id, concept_code)
+        except GroundworkersError as exc:
+            return exc.to_dict()
+        except Exception as exc:
+            return {"error": True, "code": "QUERY_ERROR", "message": repr(exc)}