lucerna-mcp 0.3.4__py3-none-any.whl

lucerna_mcp/__init__.py

@@ -0,0 +1,94 @@
+"""lucerna-mcp: OpenSearch (Iceberg REST catalog) API + MCP Server + A2A Server."""
+
+import importlib
+import inspect
+from typing import Any
+
+__all__: list[str] = []
+
+CORE_MODULES = ["lucerna_mcp.api_client"]
+OPTIONAL_MODULES = {
+    "lucerna_mcp.mcp_server": "mcp",
+}
+
+
+def _expose_members(module):
+    for name, obj in inspect.getmembers(module):
+        if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
+            "_"
+        ):
+            globals()[name] = obj
+            if name not in __all__:
+                __all__.append(name)
+
+
+for module_name in CORE_MODULES:
+    module = importlib.import_module(module_name)
+    _expose_members(module)
+
+_loaded_optional_modules: dict[str, Any] = {}
+
+
+def _import_module_safely(module_name: str):
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+_AVAILABILITY_FLAG_MARKERS = {
+    "_MCP_AVAILABLE": "mcp_server",
+}
+
+
+def _resolve_availability_flag(name: str) -> bool | None:
+    """Return the True/False availability flag for `name`, or None if `name`
+    isn't one of the recognized ``_*_AVAILABLE`` markers."""
+    marker = _AVAILABILITY_FLAG_MARKERS.get(name)
+    if marker is None:
+        return None
+    module_key = next((k for k in OPTIONAL_MODULES if marker in k), None)
+    return _import_module_safely(module_key) is not None if module_key else False
+
+
+def _ensure_optional_module_loaded(module_name: str):
+    """Import and expose `module_name`'s public members once, then return it
+    (or the cached module, or None if it isn't installed)."""
+    if module_name not in _loaded_optional_modules:
+        module = _import_module_safely(module_name)
+        if module is not None:
+            _loaded_optional_modules[module_name] = module
+            _expose_members(module)
+    return _loaded_optional_modules.get(module_name)
+
+
+def _lookup_optional_attribute(name: str) -> Any:
+    for module_name in OPTIONAL_MODULES:
+        module = _ensure_optional_module_loaded(module_name)
+        if module is not None and hasattr(module, name):
+            return getattr(module, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __getattr__(name: str) -> Any:
+    flag = _resolve_availability_flag(name)
+    if flag is not None:
+        return flag
+    return _lookup_optional_attribute(name)
+
+
+def __dir__() -> list[str]:
+    return sorted(list(globals().keys()) + __all__)
+
+
+from agent_connector_sdk.connector import Connector
+
+from lucerna_mcp.api_client import Api
+from lucerna_mcp.auth import get_client
+
+connector = Connector(
+    api=Api,
+    get_client=get_client,
+    tools="lucerna_mcp.mcp_server",
+    instructions="Lucerna MCP Server (CA-50 search tier) — index/alias/settings/rollover admin, BM25/kNN/hybrid search always run as the calling principal so document-level security applies, ingest-pipeline admin, DLS-bundle read/apply (never hand-authors a rule — only applies what CA-16/26 render), and a trigger-only reindex-from-KG tool.",
+)

lucerna_mcp/__main__.py

@@ -0,0 +1,4 @@
+from agent_connector_sdk import run
+
+if __name__ == "__main__":
+    run()

lucerna_mcp/api/__init__.py

@@ -0,0 +1 @@
+"""API client subpackage for lucerna-mcp."""

lucerna_mcp/api/api_client_base.py

@@ -0,0 +1,101 @@
+"""Shared transport primitives for the OpenSearch API wrapper.
+
+CA-43's single hardest invariant (stated three times in the lane's source
+specs, restated here so it cannot be missed by anyone editing this file):
+**every OpenSearch request this package makes carries the calling
+principal's own bearer token, attached per HTTP call — never a token baked
+in once at client-construction time, and never a service-level/admin bypass
+credential.** :class:`_PerCallBearerAuth` below is the structural mechanism
+that makes this true: it is a ``requests.auth.AuthBase`` callable that
+``opensearchpy``'s ``RequestsHttpConnection`` stores as ``session.auth`` and
+invokes fresh on every single outbound request (see ``requests``'
+``Session.send`` -> ``PreparedRequest.prepare_auth``) — so a token that
+expires mid-session, or a caller whose identity changes between two tool
+calls in the same process, is never silently reused.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from requests.auth import AuthBase
+
+
+class OpenSearchApiError(RuntimeError):
+    """An OpenSearch call failed with a typed, non-2xx response (or no usable
+    calling-principal credential was available at all).
+
+    Never silently degraded to an empty result — a caller (tool layer, KG
+    ingest, the DLS-bundle applier) must be able to distinguish "no hits"
+    from "the call failed" / "unreachable" / "no principal token available".
+    """
+
+    def __init__(
+        self, message: str, *, status_code: int | str | None = None, body: Any = None
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class _PerCallBearerAuth(AuthBase):
+    """A ``requests`` auth callable that mints the ``Authorization`` header
+    fresh on every request by invoking ``token_provider()``.
+
+    This is the structural half of the "always the calling principal, never
+    a bypass credential" invariant: ``opensearchpy.RequestsHttpConnection``
+    assigns whatever is passed as ``http_auth`` directly to
+    ``requests.Session.auth`` (verified against opensearch-py 3.2.0's own
+    source), and ``requests`` calls an ``AuthBase.__call__`` on EVERY
+    prepared request, not once at session construction. A client built from
+    this auth object cannot go stale, and cannot be handed a credential at
+    construction time that outlives the request it was minted for.
+    """
+
+    def __init__(self, token_provider: Callable[[], str]) -> None:
+        self._token_provider = token_provider
+
+    def __call__(self, r: Any) -> Any:
+        token = self._token_provider()
+        if not token:
+            raise OpenSearchApiError(
+                "no calling-principal bearer token was available at request time — "
+                "refusing to send an unauthenticated OpenSearch request rather than "
+                "silently falling back to an admin/service credential"
+            )
+        r.headers["Authorization"] = f"Bearer {token}"
+        return r
+
+
+def raise_for_transport_error(exc: Exception, *, operation: str) -> None:
+    """Translate an ``opensearchpy`` transport exception into
+    :class:`OpenSearchApiError`, fail-closed and never swallowed.
+
+    A hibernating/misrouted backend or a transport-layer failure must never
+    look like "zero hits" — the exact class of bug recorded platform-wide
+    from the ServiceNow PDI case (HTTP 200 + HTML on every path treated as
+    silent success).
+    """
+    from opensearchpy.exceptions import NotFoundError, TransportError
+
+    if isinstance(exc, OpenSearchApiError):
+        # Already typed (e.g. _PerCallBearerAuth's "no calling-principal
+        # token available") — re-raise as-is rather than double-wrapping it
+        # inside a generic transport-failure message.
+        raise exc
+    if isinstance(exc, NotFoundError):
+        raise OpenSearchApiError(
+            f"OpenSearch {operation}: not found",
+            status_code=404,
+            body=getattr(exc, "info", None),
+        ) from exc
+    if isinstance(exc, TransportError):
+        raise OpenSearchApiError(
+            f"OpenSearch {operation} failed: {exc}",
+            status_code=getattr(exc, "status_code", None),
+            body=getattr(exc, "info", None),
+        ) from exc
+    raise OpenSearchApiError(
+        f"OpenSearch {operation} failed (transport): {exc}"
+    ) from exc

lucerna_mcp/api/api_client_opensearch.py

@@ -0,0 +1,340 @@
+"""OpenSearch client wrapping ``opensearchpy.OpenSearch`` for the search tier (CA-50).
+
+Every method routes through one ``opensearchpy.OpenSearch`` instance whose
+transport auth is :class:`~lucerna_mcp.api.api_client_base._PerCallBearerAuth`
+— the calling principal's own token, re-minted on every request (see that
+module's docstring for why this is structural rather than conventional).
+
+**k-NN plugin**: disabled cluster-wide (pre-AVX2 homelab nodes — no AVX2-free
+OpenSearch k-NN build exists upstream, `services/opensearch/AGENTS.md`).
+`knn_search`/`hybrid_search` exist per this lane's scope but degrade to a
+typed :class:`OpenSearchApiError` (naming the plugin as the cause) rather
+than a bare 500 when the plugin refuses the query — verified live against
+the deployed cluster (2.19.6): indexing a `knn_vector` document and running a
+`knn` query both fail with `illegal_state_exception: "KNN plugin is
+disabled..."`.
+
+**Security-plugin admin surface** (DLS role read/apply) has no first-class
+``opensearchpy`` client namespace — both go through
+``client.transport.perform_request`` against ``/_plugins/_security/api/...``,
+the same low-level path OpenSearch's own `securityadmin.sh`/Dashboards use.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+from urllib.parse import urlparse
+
+from opensearchpy import OpenSearch, RequestsHttpConnection
+from opensearchpy.exceptions import TransportError
+
+from lucerna_mcp.api.api_client_base import (
+    OpenSearchApiError,
+    _PerCallBearerAuth,
+    raise_for_transport_error,
+)
+
+logger = logging.getLogger("lucerna_mcp.api")
+
+__all__ = ["OpenSearchApi", "OpenSearchApiError"]
+
+_MAX_SEARCH_SIZE = 100
+_KNN_DISABLED_MARKERS = ("knn plugin is disabled", "knn.plugin.enabled")
+
+
+def _is_knn_disabled_error(exc: Exception) -> bool:
+    text = str(exc).lower()
+    return any(marker in text for marker in _KNN_DISABLED_MARKERS)
+
+
+class OpenSearchApi:
+    """Authenticated OpenSearch client — always constructed with a per-call
+    token provider, never a static baked-in credential.
+
+    ``base_url`` is the bare OpenSearch origin (e.g. ``http://localhost:9200``).
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token_provider: Any = None,
+        verify_certs: bool | str = True,
+        timeout: float = 30.0,
+        _test_basic_auth: tuple[str, str] | None = None,
+    ) -> None:
+        """Construct the client. ``token_provider`` (a zero-arg callable
+        returning a bearer token) is the ONLY production credential path —
+        ``lucerna_mcp.auth.get_client()`` is the sole caller that should
+        ever populate it, sourced from the calling principal's own delegated
+        token, never a fixed/service credential.
+
+        ``_test_basic_auth`` exists ONLY for this package's own live-proof
+        scripts/tests exercising this exact client class against OpenSearch's
+        pre-bundle internal-user DLS demonstration accounts
+        (``services/opensearch/AGENTS.md``'s W07 fixture — CA-16/26's real
+        policy bundle has not landed yet). It is never referenced by
+        ``auth.py`` or by any ``mcp/*.py`` tool — passing it from either would
+        be exactly the admin/service-bypass this package's own contract
+        forbids.
+        """
+        if token_provider is None and _test_basic_auth is None:
+            raise OpenSearchApiError(
+                "OpenSearchApi requires a token_provider callable — a static token "
+                "or no credential at all would violate the 'always the calling "
+                "principal, per-call' invariant this package exists to hold"
+            )
+        parsed = urlparse(base_url)
+        host = parsed.hostname or base_url
+        port = parsed.port or (443 if parsed.scheme != "http" else 9200)
+        use_ssl = parsed.scheme != "http"
+        self.base_url = base_url.rstrip("/")
+        if token_provider is not None:
+            http_auth: Any = _PerCallBearerAuth(token_provider)
+        else:
+            logger.warning(
+                "OpenSearchApi constructed with _test_basic_auth — this is the "
+                "package's TEST-ONLY escape hatch and must never be reachable "
+                "from auth.get_client() or any mcp/*.py tool"
+            )
+            http_auth = _test_basic_auth
+        self._client = OpenSearch(
+            hosts=[{"host": host, "port": port}],
+            http_auth=http_auth,
+            use_ssl=use_ssl,
+            verify_certs=verify_certs,
+            connection_class=RequestsHttpConnection,
+            timeout=timeout,
+        )
+
+    # ── low-level escape hatch (security-plugin admin API) ───────────────
+    def _perform(self, method: str, url: str, body: Any = None) -> Any:
+        try:
+            return self._client.transport.perform_request(method, url, body=body)
+        except Exception as exc:  # noqa: BLE001 - normalized below
+            raise_for_transport_error(exc, operation=f"{method} {url}")
+
+    # ── cluster / plugin introspection ────────────────────────────────────
+    def cluster_health(self) -> dict[str, Any]:
+        try:
+            return self._client.cluster.health()
+        except Exception as exc:  # noqa: BLE001
+            raise_for_transport_error(exc, operation="cluster_health")
+
+    def knn_plugin_enabled(self) -> bool:
+        """Live check of the k-NN plugin's runtime-enabled flag (never assumed)."""
+        # `include_defaults` isn't expressible via the high-level client's
+        # settings helper params without extra plumbing; ask the flat path
+        # directly, matching services/opensearch/AGENTS.md's own verification.
+        flat = self._perform(
+            "GET",
+            "/_cluster/settings?include_defaults=true&filter_path=**.knn.plugin.enabled",
+        )
+        try:
+            return str(flat["defaults"]["knn"]["plugin"]["enabled"]).lower() == "true"
+        except (KeyError, TypeError):
+            return False
+
+    # ── index admin (typed OntologyActions per DEC-CA-07) ─────────────────
+    def create_index(
+        self, index: str, body: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        try:
+            return self._client.indices.create(index=index, body=body or {})
+        except Exception as exc:  # noqa: BLE001
+            if (
+                isinstance(exc, TransportError)
+                and getattr(exc, "status_code", None) == 400
+            ):
+                info = getattr(exc, "info", {}) or {}
+                err = (info.get("error") or {}) if isinstance(info, dict) else {}
+                if err.get("type") == "resource_already_exists_exception":
+                    # Idempotent per this lane's contract: creating an index
+                    # that already exists is not an error.
+                    return {
+                        "index": index,
+                        "acknowledged": True,
+                        "already_exists": True,
+                    }
+            raise_for_transport_error(exc, operation=f"create_index({index})")
+
+    def update_mapping(self, index: str, properties: dict[str, Any]) -> dict[str, Any]:
+        try:
+            return self._client.indices.put_mapping(
+                index=index, body={"properties": properties}
+            )
+        except Exception as exc:  # noqa: BLE001
+            raise_for_transport_error(exc, operation=f"update_mapping({index})")
+
+    def manage_alias(self, actions: list[dict[str, Any]]) -> dict[str, Any]:
+        """Apply one or more alias actions (``{"add": {...}}``/``{"remove": {...}}``).
+
+        The Alias Swap idiom (remove old + add new in one call) is OpenSearch's
+        own idempotent primitive — this method is a thin pass-through to it.
+        """
+        try:
+            return self._client.indices.update_aliases(body={"actions": actions})
+        except Exception as exc:  # noqa: BLE001
+            raise_for_transport_error(exc, operation="manage_alias")
+
+    def get_aliases(self, index: str = "*") -> dict[str, Any]:
+        try:
+            return self._client.indices.get_alias(index=index)
+        except Exception as exc:  # noqa: BLE001
+            raise_for_transport_error(exc, operation=f"get_aliases({index})")
+
+    def update_settings(self, index: str, settings: dict[str, Any]) -> dict[str, Any]:
+        try:
+            return self._client.indices.put_settings(
+                index=index, body={"index": settings}
+            )
+        except Exception as exc:  # noqa: BLE001
+            raise_for_transport_error(exc, operation=f"update_settings({index})")
+
+    def rollover(
+        self,
+        alias: str,
+        conditions: dict[str, Any] | None = None,
+        new_index: str | None = None,
+    ) -> dict[str, Any]:
+        try:
+            target = f"{alias}/{new_index}" if new_index else alias
+            return self._client.indices.rollover(
+                alias=target, body={"conditions": conditions or {}}
+            )
+        except Exception as exc:  # noqa: BLE001
+            raise_for_transport_error(exc, operation=f"rollover({alias})")
+
+    def delete_index(self, index: str) -> dict[str, Any]:
+        try:
+            return self._client.indices.delete(index=index)
+        except Exception as exc:  # noqa: BLE001
+            raise_for_transport_error(exc, operation=f"delete_index({index})")
+
+    # ── search (always the calling principal — DLS applies per-request) ──
+    def search(
+        self,
+        index: str,
+        query: dict[str, Any],
+        size: int = 10,
+        _source: list[str] | None = None,
+    ) -> dict[str, Any]:
+        capped = min(max(int(size), 0), _MAX_SEARCH_SIZE)
+        body: dict[str, Any] = {"query": query, "size": capped}
+        if _source is not None:
+            body["_source"] = _source
+        try:
+            return self._client.search(index=index, body=body)
+        except Exception as exc:  # noqa: BLE001
+            raise_for_transport_error(exc, operation=f"search({index})")
+
+    def knn_search(
+        self,
+        index: str,
+        field: str,
+        vector: list[float],
+        k: int = 10,
+        size: int = 10,
+    ) -> dict[str, Any]:
+        capped = min(max(int(size), 0), _MAX_SEARCH_SIZE)
+        body = {
+            "size": capped,
+            "query": {"knn": {field: {"vector": vector, "k": k}}},
+        }
+        try:
+            return self._client.search(index=index, body=body)
+        except Exception as exc:  # noqa: BLE001
+            if _is_knn_disabled_error(exc):
+                raise OpenSearchApiError(
+                    "k-NN plugin is disabled on this cluster (pre-AVX2 homelab "
+                    "nodes — no AVX2-free k-NN build exists upstream, "
+                    "services/opensearch/AGENTS.md). opensearch_knn_search cannot "
+                    "run here; use opensearch_search (BM25) or eg-vector/vector-mcp "
+                    "for vector search instead.",
+                    status_code=getattr(exc, "status_code", None),
+                ) from exc
+            raise_for_transport_error(exc, operation=f"knn_search({index})")
+
+    def hybrid_search(
+        self,
+        index: str,
+        queries: list[dict[str, Any]],
+        size: int = 10,
+    ) -> dict[str, Any]:
+        """OpenSearch's native hybrid (lexical + vector) query compound clause.
+
+        Degrades the same way as :meth:`knn_search` when any sub-query is a
+        ``knn`` clause and the plugin is disabled — never a bare 500.
+        """
+        capped = min(max(int(size), 0), _MAX_SEARCH_SIZE)
+        body = {"size": capped, "query": {"hybrid": {"queries": queries}}}
+        try:
+            return self._client.search(
+                index=index,
+                body=body,
+                params={"search_pipeline": "hybrid-search-pipeline"},
+            )
+        except Exception as exc:  # noqa: BLE001
+            if _is_knn_disabled_error(exc):
+                raise OpenSearchApiError(
+                    "hybrid search includes a k-NN clause and the k-NN plugin is "
+                    "disabled on this cluster (pre-AVX2 homelab nodes). Run a "
+                    "lexical-only opensearch_search instead, or drop the vector "
+                    "sub-query.",
+                    status_code=getattr(exc, "status_code", None),
+                ) from exc
+            raise_for_transport_error(exc, operation=f"hybrid_search({index})")
+
+    # ── ingest pipelines ───────────────────────────────────────────────────
+    def put_ingest_pipeline(
+        self, pipeline_id: str, body: dict[str, Any]
+    ) -> dict[str, Any]:
+        try:
+            return self._client.ingest.put_pipeline(id=pipeline_id, body=body)
+        except Exception as exc:  # noqa: BLE001
+            raise_for_transport_error(
+                exc, operation=f"put_ingest_pipeline({pipeline_id})"
+            )
+
+    def get_ingest_pipeline(self, pipeline_id: str) -> dict[str, Any]:
+        try:
+            return self._client.ingest.get_pipeline(id=pipeline_id)
+        except Exception as exc:  # noqa: BLE001
+            raise_for_transport_error(
+                exc, operation=f"get_ingest_pipeline({pipeline_id})"
+            )
+
+    # ── security / DLS (never hand-authored — applies a CA-16/26 bundle) ──
+    def read_dls_rules(self, role: str) -> dict[str, Any]:
+        """Read one OpenSearch security-plugin role's index permissions/DLS query.
+
+        Read-only — this is the *only* security-group method the ``search``
+        invariant does not apply to as strictly (it reads config, it does not
+        search data), but it still runs as the calling principal's own token
+        (a principal with no ``security_rest_api_access`` simply gets a 403
+        from OpenSearch itself, which is surfaced, not swallowed).
+        """
+        return self._perform("GET", f"/_plugins/_security/api/roles/{role}")
+
+    def apply_dls_bundle_rendering(
+        self, role: str, index_pattern: str, dls_query: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Apply ONE already-validated ``renderings.opensearch`` entry.
+
+        Callers (``mcp/mcp_opensearch.py``) are responsible for validating the
+        bundle's shape and provenance BEFORE calling this — this method never
+        constructs a DLS predicate itself, it only PUTs the one already given
+        to it, matching this package's "never hand-author a DLS rule" invariant.
+        """
+        body = {
+            "cluster_permissions": [],
+            "index_permissions": [
+                {
+                    "index_patterns": [index_pattern],
+                    "dls": json.dumps(dls_query),
+                    "allowed_actions": ["read"],
+                }
+            ],
+        }
+        return self._perform("PUT", f"/_plugins/_security/api/roles/{role}", body=body)

lucerna_mcp/api_client.py

@@ -0,0 +1,11 @@
+"""Public client facade for lucerna_mcp."""
+
+from lucerna_mcp.api.api_client_opensearch import OpenSearchApi, OpenSearchApiError
+
+__all__ = ["Api", "OpenSearchApiError"]
+
+
+class Api(OpenSearchApi):
+    """Authenticated OpenSearch client — always the calling principal's token."""
+
+    pass