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

spring_runtime_mcp/tools/__init__.py

@@ -0,0 +1 @@
+"""Tool orchestration independent of a specific MCP host."""

spring_runtime_mcp/tools/analyze_startup.py

@@ -0,0 +1,79 @@
+"""Read-only startup timeline handler."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+from uuid import uuid4
+
+from ..adapters.startup import normalize_startup
+from ..contracts.definitions import validate_arguments
+from ..models.common import NormalizationError
+from ..models.queries import StartupQuery
+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 analyze_startup(
+    arguments: Mapping[str, Any], services: Services
+) -> dict[str, Any]:
+    request_target = "local"
+    try:
+        query = validate_arguments(arguments, "springboot_analyze_startup")
+        request_target = query.target_id
+        assert isinstance(query, StartupQuery)
+        if query.cursor:
+            return resume(services, query)
+        snapshot = uuid4().hex
+        observation = await read_checked(services, query.target_id, "startup", snapshot)
+        version, total, basis, complete, items, gaps = normalize_startup(
+            observation.body,
+            step_name_pattern=query.step_name_pattern,
+            bean_name_pattern=query.bean_name_pattern,
+            min_duration_ms=query.min_duration_ms,
+            max_depth=query.max_depth,
+        )
+        result = shell(query.target_id, "registered target startup", "startup-1")
+        stamp(result, observation, "startup", snapshot)
+        for index, item in enumerate(items, start=1):
+            item["id"] = f"startup_{index:06d}"
+            item["endpointId"] = "startup"
+            item["observationId"] = observation.observation_id
+        result["data"] = {
+            "springBootVersion": version,
+            "totalDurationMs": total,
+            "durationBasis": basis,
+            "timelineComplete": complete,
+            "items": items,
+        }
+        limited = {
+            "STARTUP_NODE_LIMIT",
+            "STARTUP_TAG_LIMIT",
+            "STARTUP_DEPTH_LIMIT",
+        } & set(gaps)
+        result["totalMatched"] = None if limited else len(items)
+        if limited:
+            result["truncated"] = True
+            result["truncationReasons"] = sorted(
+                set(result["truncationReasons"] + list(limited))
+            )[:8]
+        if not complete:
+            gaps = [*gaps, "STARTUP_TIMELINE_INCOMPLETE"]
+        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/tools/check_migrations.py

@@ -0,0 +1,99 @@
+"""Read-only Flyway and Liquibase handler. It never executes migrations."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+from uuid import uuid4
+
+from ..adapters.migrations import normalize_migrations
+from ..contracts.definitions import validate_arguments
+from ..models.common import NormalizationError
+from ..models.queries import MigrationQuery
+from ..transport.response_gate import EndpointReadError
+from ..services import Services
+from ..diagnostics import error, failed, partial, safe_code
+from .support import tool_handler, finalize, read_checked, resume, shell, stamp
+
+
+@tool_handler
+async def check_migrations(
+    arguments: Mapping[str, Any], services: Services
+) -> dict[str, Any]:
+    request_target = "local"
+    try:
+        query = validate_arguments(arguments, "springboot_check_migrations")
+        request_target = query.target_id
+        assert isinstance(query, MigrationQuery)
+        if query.cursor:
+            return resume(services, query)
+        snapshot = uuid4().hex
+        if (
+            query.target_id not in services.targets
+            or services.catalog.target_id != query.target_id
+        ):
+            raise NormalizationError("TARGET_NOT_REGISTERED")
+        engines = ("flyway", "liquibase") if query.engine == "auto" else (query.engine,)
+        bodies: dict[str, Any] = {}
+        observation_ids: dict[str, str] = {}
+        result = shell(query.target_id, "registered target migrations", "migrations-1")
+        gaps: list[str] = []
+        for endpoint in engines:
+            try:
+                observation = await read_checked(
+                    services, query.target_id, endpoint, snapshot
+                )
+            except NormalizationError as exc:
+                gaps.append(safe_code(exc.code))
+                result["errors"].append(
+                    error(
+                        exc.code,
+                        endpoint,
+                        exc.http_status if isinstance(exc, EndpointReadError) else None,
+                    )
+                )
+                continue
+            bodies[endpoint] = observation.body
+            observation_ids[endpoint] = observation.observation_id
+            stamp(result, observation, endpoint, snapshot)
+        if not bodies and result["errors"]:
+            return failed(
+                result["errors"][0]["code"],
+                query.target_id,
+                endpoint=result["errors"][0]["endpointId"],
+                http_status=result["errors"][0]["httpStatus"],
+            )
+        items, parsed_gaps, visibility = normalize_migrations(
+            bodies.get("flyway"), bodies.get("liquibase"), query
+        )
+        gaps.extend(parsed_gaps)
+        invalid = [
+            engine
+            for engine in bodies
+            if engine.upper() + "_EVIDENCE_INVALID" in parsed_gaps
+        ]
+        if invalid and len(invalid) == len(bodies):
+            return failed("MALFORMED_EVIDENCE", query.target_id, endpoint=invalid[0])
+        for engine in invalid:
+            result["errors"].append(error("MALFORMED_EVIDENCE", engine))
+        for item in items:
+            item["observationId"] = observation_ids.get(
+                item["endpointId"], "observation_baseline"
+            )
+        result["data"] = {"pendingVisibility": visibility, "items": items}
+        result["totalMatched"] = None if result["errors"] or 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/tools/detect_drift.py

@@ -0,0 +1,323 @@
+"""Compare caller-supplied expectations with a read-only runtime snapshot."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Any
+from uuid import uuid4
+
+from ..adapters.drift import compare_drift
+from ..contracts.definitions import validate_arguments
+from ..models.common import NormalizationError
+from ..models.queries import DriftQuery
+from ..models.timestamps import parse_rfc3339
+from ..transport.response_gate import EndpointReadError
+from ..services import Services
+from ..diagnostics import error, failed, partial, safe_code
+from .support import tool_handler, finalize, read_checked, resume, shell, stamp
+
+_VERSION = re.compile(r"[A-Za-z0-9_.-]{1,64}\Z")
+_STARTUP_UNAVAILABLE = frozenset(
+    {"CAPABILITY_DISABLED", "ENDPOINT_NOT_EXPOSED", "STARTUP_DATA_UNAVAILABLE"}
+)
+_STARTUP_EVIDENCE_GAP = "STARTUP_EVIDENCE_UNAVAILABLE"
+_DIFF_FIELDS = (
+    "id",
+    "dimension",
+    "identity",
+    "contextId",
+    "expected",
+    "actual",
+    "evidenceLevel",
+    "affectedDependencyIds",
+)
+
+
+def _profile_evidence(body: Any, services: Services) -> Any:
+    """Profiles permission does not grant unregistered property evidence."""
+    if not isinstance(body, dict) or services.config_policy is None:
+        return None
+    sources = []
+    for source in (
+        body.get("propertySources", [])
+        if isinstance(body.get("propertySources"), list)
+        else []
+    ):
+        if not isinstance(source, dict) or not isinstance(
+            source.get("properties"), dict
+        ):
+            continue
+        sources.append(
+            {
+                "name": source.get("name"),
+                "properties": {
+                    key: value
+                    for key, value in source["properties"].items()
+                    if services.config_policy.allows(key)
+                },
+            }
+        )
+    return {"activeProfiles": body.get("activeProfiles"), "propertySources": sources}
+
+
+def _project(page: dict[str, Any]) -> dict[str, Any]:
+    data = page.get("data")
+    if not isinstance(data, dict) or "items" not in data:
+        return page
+    missing: list[dict[str, Any]] = []
+    unexpected: list[dict[str, Any]] = []
+    for item in data.pop("items") or []:
+        if not isinstance(item, dict):
+            continue
+        record = {field: item.get(field) for field in _DIFF_FIELDS}
+        if not isinstance(record["affectedDependencyIds"], list):
+            record["affectedDependencyIds"] = []
+        if str(record.get("id") or "").startswith("u"):
+            unexpected.append(record)
+        else:
+            missing.append(record)
+    data["missingInRuntime"] = missing
+    data["unexpectedInRuntime"] = unexpected
+    data.setdefault("profileMismatch", None)
+    data.setdefault("rootCauseInferences", [])
+    return page
+
+
+def _startup_start(body: Any) -> str | None:
+    if not isinstance(body, dict) or not isinstance(body.get("timeline"), dict):
+        return None
+    start = body["timeline"].get("startTime")
+    return (
+        start if isinstance(start, str) and parse_rfc3339(start) is not None else None
+    )
+
+
+def _later(modified: str, started: str) -> bool:
+    left, right = parse_rfc3339(modified), parse_rfc3339(started)
+    return left is not None and right is not None and left > right
+
+
+def _inferences(
+    missing: list[dict[str, Any]],
+    unexpected: list[dict[str, Any]],
+    profile: dict[str, Any] | None,
+    *,
+    environment_override: bool,
+    not_restarted: bool,
+) -> list[dict[str, Any]]:
+    evidence = [row["id"] for row in (*missing, *unexpected)][:8]
+    drifted = bool(
+        missing or unexpected or (profile and profile.get("state") == "mismatch")
+    )
+    rows: list[dict[str, Any]] = []
+    if profile and profile.get("state") == "mismatch":
+        rows.append(
+            {"code": "PROFILE_MISMATCH", "confidence": "supported", "evidenceIds": []}
+        )
+        if environment_override:
+            rows.append(
+                {
+                    "code": "ENVIRONMENT_OVERRIDE",
+                    "confidence": "supported",
+                    "evidenceIds": [],
+                }
+            )
+    if not_restarted and drifted:
+        rows.append(
+            {
+                "code": "POSSIBLE_NOT_RESTARTED",
+                "confidence": "candidate",
+                "evidenceIds": list(evidence),
+            }
+        )
+    if missing or unexpected:
+        rows.append(
+            {
+                "code": "INSUFFICIENT_EVIDENCE",
+                "confidence": "unknown",
+                "evidenceIds": list(evidence),
+            }
+        )
+    return rows[:4]
+
+
+def _assign(rows: list[dict[str, Any]], prefix: str) -> None:
+    for index, row in enumerate(rows, start=1):
+        row["id"] = f"{prefix}{index:06d}"
+
+
+async def _optional_startup(
+    services: Services, query: DriftQuery, snapshot: str, result: dict[str, Any]
+) -> tuple[Any | None, list[dict[str, Any]], list[str]]:
+    if query.source_modified_at is None:
+        return None, [], []
+    try:
+        observation = await read_checked(services, query.target_id, "startup", snapshot)
+    except NormalizationError as exc:
+        if safe_code(exc.code) in _STARTUP_UNAVAILABLE:
+            # The caller explicitly supplied sourceModifiedAt, so startup timing
+            # is required evidence. Missing it is a gap, never a silent success.
+            return None, [], [_STARTUP_EVIDENCE_GAP]
+        return (
+            None,
+            [
+                error(
+                    exc.code,
+                    "startup",
+                    exc.http_status if isinstance(exc, EndpointReadError) else None,
+                )
+            ],
+            [],
+        )
+    stamp(result, observation, "startup", snapshot)
+    version = (
+        observation.body.get("springBootVersion")
+        if isinstance(observation.body, dict)
+        else None
+    )
+    if isinstance(version, str) and _VERSION.fullmatch(version):
+        result["source"]["bootVersion"] = version
+    return observation.body, [], []
+
+
+@tool_handler
+async def detect_drift(
+    arguments: Mapping[str, Any], services: Services
+) -> dict[str, Any]:
+    request_target = "local"
+    try:
+        query = validate_arguments(arguments, "springboot_detect_drift")
+        request_target = query.target_id
+        assert isinstance(query, DriftQuery)
+        # A caller revision is not an observed build id. Do not infer
+        # POSSIBLE_WRONG_INSTANCE unless a future authorized info read proves it.
+        if query.source_revision is not None and not isinstance(
+            query.source_revision, str
+        ):
+            raise NormalizationError("INVALID_ARGUMENT")
+        if query.cursor:
+            return _project(resume(services, query))
+        snapshot = uuid4().hex
+        if (
+            query.target_id not in services.targets
+            or services.catalog.target_id != query.target_id
+        ):
+            raise NormalizationError("TARGET_NOT_REGISTERED")
+        result = shell(query.target_id, "registered-target-drift", "drift-1")
+        plan: list[str] = []
+        if query.expected_beans is not None:
+            plan.append("beans")
+        if query.expected_routes is not None:
+            plan.append("mappings")
+        if query.expected_migration is not None:
+            plan.append(query.expected_migration.engine)
+        if query.expected_profiles is not None:
+            plan.append("env")
+        bodies: dict[str, Any] = {}
+        failures: list[dict[str, Any]] = []
+        for endpoint in plan:
+            try:
+                if endpoint == "env" and (
+                    services.config_policy is None
+                    or not services.config_policy.profiles
+                ):
+                    raise EndpointReadError("CAPABILITY_DISABLED", "env")
+                observation = await read_checked(
+                    services, query.target_id, endpoint, snapshot
+                )
+            except NormalizationError as exc:
+                failures.append(
+                    error(
+                        exc.code,
+                        endpoint,
+                        exc.http_status if isinstance(exc, EndpointReadError) else None,
+                    )
+                )
+                continue
+            bodies[endpoint] = observation
+            stamp(result, observation, endpoint, snapshot)
+        if plan and not bodies and failures:
+            first = failures[0]
+            return failed(
+                first["code"],
+                query.target_id,
+                endpoint=first["endpointId"],
+                http_status=first["httpStatus"],
+            )
+        startup_body, startup_errors, startup_gaps = await _optional_startup(
+            services, query, snapshot, result
+        )
+        failures.extend(startup_errors)
+        compared = compare_drift(
+            query,
+            beans=bodies.get("beans"),
+            mappings_body=None if "mappings" not in bodies else bodies["mappings"].body,
+            flyway_body=None if "flyway" not in bodies else bodies["flyway"].body,
+            migration_observed="liquibase" in bodies,
+            env_body=_profile_evidence(bodies["env"].body, services)
+            if "env" in bodies
+            else None,
+            catalog=services.catalog,
+        )
+        missing = list(compared["missing"])
+        unexpected = list(compared["unexpected"])
+        _assign(missing, "m")
+        _assign(unexpected, "u")
+        started = _startup_start(startup_body)
+        not_restarted = bool(
+            query.source_modified_at
+            and started
+            and _later(query.source_modified_at, started)
+        )
+        if query.source_modified_at and startup_body is not None and started is None:
+            compared["gaps"] = [*compared["gaps"], "STARTUP_TIMING_UNOBSERVED"]
+            compared["incomplete"] = True
+        profile = compared["profile"]
+        result["data"] = {
+            "items": [*missing, *unexpected],
+            "profileMismatch": profile,
+            "rootCauseInferences": _inferences(
+                missing,
+                unexpected,
+                profile,
+                environment_override=bool(compared["environment_override"]),
+                not_restarted=not_restarted,
+            ),
+        }
+        result["errors"] = failures[:8]
+        gaps = (
+            list(compared["gaps"])
+            + [safe_code(item["code"]) for item in failures]
+            + startup_gaps
+        )
+        if startup_gaps:
+            compared["incomplete"] = True
+        if compared["incomplete"] and not gaps:
+            gaps.append("EVIDENCE_INCOMPLETE")
+        result["totalMatched"] = (
+            None
+            if compared["incomplete"] or failures or startup_gaps
+            else len(missing)
+            + len(unexpected)
+            + (
+                1
+                if isinstance(profile, dict) and profile.get("state") == "mismatch"
+                else 0
+            )
+        )
+        partial(result, gaps)
+        return _project(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/diagnose_health.py

@@ -0,0 +1,88 @@
+"""Read-only health handler for Boot 2.x details and 3.x/4.x components."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+from uuid import uuid4
+
+from ..adapters.health import normalize_health
+from ..contracts.definitions import validate_arguments
+from ..models.common import NormalizationError
+from ..models.queries import HealthQuery
+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
+
+_ENDPOINTS = {
+    "application": "health",
+    "liveness": "health-liveness",
+    "readiness": "health-readiness",
+}
+
+
+@tool_handler
+async def diagnose_health(
+    arguments: Mapping[str, Any], services: Services
+) -> dict[str, Any]:
+    request_target = "local"
+    try:
+        query = validate_arguments(arguments, "springboot_diagnose_health")
+        request_target = query.target_id
+        assert isinstance(query, HealthQuery)
+        if query.cursor:
+            return resume(services, query)
+        endpoint = _ENDPOINTS[query.group]
+        snapshot = uuid4().hex
+        observation = await read_checked(services, query.target_id, endpoint, snapshot)
+        overall, items, gaps = normalize_health(
+            observation.body,
+            component_path=query.component_path,
+            include_details=query.include_details,
+            include_healthy=query.include_healthy,
+            max_depth=query.max_depth,
+        )
+        result = shell(query.target_id, "registered target health", "health-1")
+        stamp(result, observation, endpoint, snapshot)
+        for item in items:
+            item["endpointId"] = endpoint
+            item["observationId"] = observation.observation_id
+        result["data"] = {
+            "overallStatus": overall,
+            "activeGroup": query.group,
+            "items": items,
+        }
+        limited = {"HEALTH_DETAILS_LIMIT", "HEALTH_DEPTH_LIMIT"} & set(gaps)
+        if limited:
+            result["truncated"] = True
+            result["truncationReasons"] = sorted(
+                set(result["truncationReasons"] + list(limited))
+            )[:8]
+        incomplete_count = {
+            "HEALTH_DETAILS_NOT_VISIBLE",
+            "HEALTH_COMPONENT_UNREADABLE",
+            "HEALTH_STATUS_UNOBSERVED",
+        } & set(gaps)
+        result["totalMatched"] = None if limited or incomplete_count else len(items)
+        partial(result, gaps)
+        if "HEALTH_DETAILS_NOT_VISIBLE" in result["coverage"]["gaps"]:
+            result["nextAction"] = {
+                "kind": "remediate",
+                "reasonCode": "HEALTH_DETAILS_NOT_VISIBLE",
+                "filterSuggestions": [],
+            }
+        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)