spring-runtime-mcp 0.2.0__py3-none-any.whl

spring_runtime_mcp/tools/search_openapi.py

@@ -0,0 +1,79 @@
+"""Read-only local OpenAPI search. Remote $ref values are not resolved."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+from uuid import uuid4
+
+from ..adapters.openapi import normalize_openapi
+from ..contracts.definitions import validate_arguments
+from ..models.common import NormalizationError
+from ..models.queries import OpenApiQuery
+from ..transport.response_gate import EndpointReadError
+from ..services import Services
+from ..diagnostics import failed, partial
+from .support import tool_handler, finalize, read_checked, resume, shell, stamp
+
+
+@tool_handler
+async def search_openapi(
+    arguments: Mapping[str, Any], services: Services
+) -> dict[str, Any]:
+    request_target = "local"
+    try:
+        query = validate_arguments(arguments, "springboot_search_openapi")
+        request_target = query.target_id
+        assert isinstance(query, OpenApiQuery)
+        if query.cursor:
+            return resume(services, query)
+        snapshot = uuid4().hex
+        observation = await read_checked(services, query.target_id, "openapi", snapshot)
+        version, candidate, items, gaps, blocked = normalize_openapi(
+            observation.body, query
+        )
+        result = shell(query.target_id, "registered target openapi", "openapi-1")
+        stamp(result, observation, "openapi", snapshot)
+        for item in items:
+            item["endpointId"] = "openapi"
+            item["observationId"] = observation.observation_id
+        result["data"] = {
+            "openapiVersion": version,
+            "candidateId": candidate,
+            "items": items,
+        }
+        enumeration_gaps = {
+            "OPENAPI_PATH_UNREADABLE",
+            "OPENAPI_PATH_FIELD_CONFLICT",
+            "OPENAPI_OPERATION_UNREADABLE",
+        }
+        result["totalMatched"] = (
+            None if enumeration_gaps.intersection(gaps) else len(items)
+        )
+        partial(result, gaps)
+        limit_codes = ("REF_DEPTH_LIMIT", "REF_CYCLE", "REF_EXPANSION_LIMIT")
+        if any(code in gaps for code in limit_codes):
+            reason = next(code for code in limit_codes if code in gaps)
+            result["truncated"] = True
+            result["truncationReasons"] = [code for code in limit_codes if code in gaps]
+            result["nextAction"] = {
+                "kind": "refine",
+                "reasonCode": reason,
+                "filterSuggestions": (
+                    [{"parameter": "schemaName", "value": blocked}] if blocked else []
+                ),
+            }
+        return finalize(result, services, query)
+    except NormalizationError as exc:
+        return failed(
+            exc.code,
+            request_target,
+            endpoint=exc.endpoint_id if isinstance(exc, EndpointReadError) else None,
+            http_status=exc.http_status if isinstance(exc, EndpointReadError) else None,
+        )
+    except TimeoutError:
+        return failed("TARGET_TIMEOUT", request_target)
+    except (ValueError, TypeError, KeyError, RecursionError, UnicodeError):
+        return failed("MALFORMED_EVIDENCE", request_target)
+    except Exception:
+        return failed("INTERNAL_ERROR", request_target)

spring_runtime_mcp/tools/support.py

@@ -0,0 +1,166 @@
+"""Shared envelope, observation check, and byte-budget paging for diagnostic tools."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from datetime import UTC, datetime
+from functools import wraps
+from typing import Any
+
+from ..models.common import CALL_BUDGET, CallBudget, NormalizationError
+from ..snapshots import SnapshotStore, page_envelope
+from ..transport.responses import serialize_response
+from ..services import Services
+from ..diagnostics import _check, failed, partial
+
+TOOL_TIMEOUT_SECONDS = 15.0
+ToolHandler = Callable[[Mapping[str, Any], Services], Awaitable[dict[str, Any]]]
+
+
+def tool_handler(handler: ToolHandler) -> ToolHandler:
+    """Bound reads, queued work and cooperative analysis under a single scope."""
+
+    @wraps(handler)
+    async def bounded(
+        arguments: Mapping[str, Any], services: Services
+    ) -> dict[str, Any]:
+        parent = CALL_BUDGET.get()
+        scope = parent or CallBudget(time.monotonic() + TOOL_TIMEOUT_SECONDS)
+        token = CALL_BUDGET.set(scope)
+        target = (
+            arguments.get("targetId", "local")
+            if isinstance(arguments, Mapping)
+            else "local"
+        )
+        try:
+            async with asyncio.timeout(scope.check()):
+                result = await handler(arguments, services)
+                scope.check()
+                return result
+        except TimeoutError:
+            return failed("TARGET_TIMEOUT", target)
+        except NormalizationError as exc:
+            return failed(exc.code, target)
+        finally:
+            CALL_BUDGET.reset(token)
+
+    return bounded
+
+
+def shell(target: str, scope: str, adapter: str) -> dict[str, Any]:
+    return {
+        "schemaVersion": "2",
+        "status": "ok",
+        "source": {
+            "targetId": target,
+            "snapshotId": None,
+            "observedAt": datetime.now(UTC).isoformat().replace("+00:00", "Z"),
+            "endpointIds": [],
+            "bootVersion": None,
+            "adapterVersion": adapter,
+            "policyVersion": adapter,
+        },
+        "data": {"items": []},
+        "totalMatched": 0,
+        "truncated": False,
+        "truncationReasons": [],
+        "coverage": {"state": "complete", "scope": scope, "gaps": []},
+        "warnings": [],
+        "redactions": [],
+        "nextCursor": None,
+        "nextAction": {
+            "kind": "done",
+            "reasonCode": "COMPLETE",
+            "filterSuggestions": [],
+        },
+        "errors": [],
+    }
+
+
+def stamp(
+    result: dict[str, Any], observation: Any, endpoint: str, snapshot: str
+) -> None:
+    result["source"].update(
+        snapshotId=snapshot,
+        endpointIds=sorted({*result["source"]["endpointIds"], endpoint}),
+        observedAt=datetime.fromisoformat(
+            observation.observed_at.replace("Z", "+00:00")
+        )
+        .astimezone(UTC)
+        .isoformat()
+        .replace("+00:00", "Z"),
+    )
+
+
+async def read_checked(
+    services: Services, target: str, endpoint: str, snapshot: str
+) -> Any:
+    if target not in services.targets or services.catalog.target_id != target:
+        raise NormalizationError("TARGET_NOT_REGISTERED")
+    if endpoint in {"env", "configprops"} and services.config_policy is None:
+        from ..transport.response_gate import EndpointReadError
+
+        raise EndpointReadError("CAPABILITY_DISABLED", endpoint)
+    observation = await services.read(target, endpoint, snapshot_id=snapshot)
+    _check(observation, target, snapshot, endpoint)
+    return observation
+
+
+def finalize(
+    result: dict[str, Any], services: Services, query: Any, *, more: bool = False
+) -> dict[str, Any]:
+    """Slice items to the query limit and the serialized response budget."""
+    result = services.sanitizer.sanitize(result)
+    if not isinstance(result.get("data"), dict):
+        return result
+    items = list(result["data"].get("items") or [])
+    count = min(len(items), query.max_results)
+    while True:
+        page = page_envelope(result, items[:count])
+        remaining = more or count < len(items)
+        if remaining:
+            page["truncated"] = True
+            page["truncationReasons"] = sorted(
+                set(page["truncationReasons"] + ["MAX_RESULTS"])
+            )[:8]
+            partial(page, ["MAX_RESULTS"])
+            page["nextAction"] = {
+                "kind": "page",
+                "reasonCode": "MORE_RESULTS",
+                "filterSuggestions": [],
+            }
+            page["nextCursor"] = "x" * 64
+        try:
+            serialize_response(page, "\0" * 128, sanitizer=services.sanitizer)
+            break
+        except NormalizationError as exc:
+            if exc.code != "RESPONSE_TOO_LARGE":
+                raise
+            if count <= 1:
+                return failed("RESPONSE_TOO_LARGE", query.target_id)
+            count //= 2
+    if remaining:
+        page["nextCursor"] = (
+            services.snapshots.advance(
+                query.cursor, query, count, sanitizer=services.sanitizer
+            )
+            if query.cursor
+            else services.snapshots.put_paged(
+                result, query, offset=count, sanitizer=services.sanitizer
+            )
+        )
+        serialize_response(page, "\0" * 128, sanitizer=services.sanitizer)
+    return page
+
+
+def resume(services: Services, query: Any) -> dict[str, Any]:
+    stored, more = services.snapshots.get_page(
+        query.cursor, query, sanitizer=services.sanitizer
+    )
+    return finalize(stored, services, query, more=more)
+
+
+# Re-export for handlers that only need the store type in annotations.
+__all__ = ["SnapshotStore", "finalize", "read_checked", "resume", "shell", "stamp"]

spring_runtime_mcp/tools/verify_mappings.py

@@ -0,0 +1,62 @@
+"""Read-only MVC and WebFlux mapping handler."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+from uuid import uuid4
+
+from ..adapters.mappings import normalize_mappings
+from ..contracts.definitions import validate_arguments
+from ..models.common import NormalizationError
+from ..models.queries import MappingQuery
+from ..transport.response_gate import EndpointReadError
+from ..services import Services
+from ..diagnostics import failed, partial
+from .support import tool_handler, finalize, read_checked, resume, shell, stamp
+
+
+@tool_handler
+async def verify_mappings(
+    arguments: Mapping[str, Any], services: Services
+) -> dict[str, Any]:
+    request_target = "local"
+    try:
+        query = validate_arguments(arguments, "springboot_verify_mappings")
+        request_target = query.target_id
+        assert isinstance(query, MappingQuery)
+        if query.cursor:
+            return resume(services, query)
+        snapshot = uuid4().hex
+        observation = await read_checked(
+            services, query.target_id, "mappings", snapshot
+        )
+        items, gaps = normalize_mappings(
+            observation.body,
+            path_pattern=query.path_pattern,
+            http_method=query.http_method,
+            controller_pattern=query.controller_class_pattern,
+            context_id=query.context_id,
+        )
+        result = shell(query.target_id, "registered target mappings", "mappings-1")
+        stamp(result, observation, "mappings", snapshot)
+        for item in items:
+            item["endpointId"] = "mappings"
+            item["observationId"] = observation.observation_id
+        result["data"] = {"items": items}
+        result["totalMatched"] = None if gaps else len(items)
+        partial(result, gaps)
+        return finalize(result, services, query)
+    except NormalizationError as exc:
+        return failed(
+            exc.code,
+            request_target,
+            endpoint=exc.endpoint_id if isinstance(exc, EndpointReadError) else None,
+            http_status=exc.http_status if isinstance(exc, EndpointReadError) else None,
+        )
+    except TimeoutError:
+        return failed("TARGET_TIMEOUT", request_target)
+    except (ValueError, TypeError, KeyError, RecursionError, UnicodeError):
+        return failed("MALFORMED_EVIDENCE", request_target)
+    except Exception:
+        return failed("INTERNAL_ERROR", request_target)

spring_runtime_mcp/transport/__init__.py

@@ -0,0 +1 @@
+"""Explicit reader interfaces; no live network connector is enabled."""