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

spring_runtime_mcp/models/bean_graph.py

@@ -0,0 +1,77 @@
+"""Immutable, target-scoped identities and dependency graph facts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal
+
+from .common import Fact
+
+
+@dataclass(frozen=True, order=True)
+class ContextKey:
+    target_id: str
+    snapshot_id: str
+    context_id: str
+
+
+@dataclass(frozen=True, order=True)
+class BeanKey:
+    context: ContextKey
+    canonical_name: str
+    bean_kind: Literal["bean", "factory", "product", "unknown"] = "unknown"
+
+
+@dataclass(frozen=True)
+class Context:
+    key: ContextKey
+    parent: Fact[ContextKey | None]
+    complete: bool
+
+
+@dataclass(frozen=True)
+class Bean:
+    key: BeanKey
+    id: str
+    aliases: tuple[str, ...]
+    reported_type: Fact[str]
+    scope: Fact[str]
+    resource: Fact[str]
+    requested_dependencies: tuple[str, ...]
+    evidence_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class Resolution:
+    state: Literal["resolved", "ambiguous", "unresolved"]
+    candidates: tuple[BeanKey, ...]
+    reason_code: str | None
+
+
+@dataclass(frozen=True)
+class DependencyEdge:
+    from_key: BeanKey
+    requested_name: str
+    resolution: Resolution
+    evidence_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class BeanGraph:
+    contexts: Mapping[ContextKey, Context]
+    beans: Mapping[BeanKey, Bean]
+    names: Mapping[ContextKey, Mapping[str, tuple[BeanKey, ...]]]
+    canonical_to_names: Mapping[BeanKey, tuple[str, ...]]
+    forward: Mapping[BeanKey, tuple[DependencyEdge, ...]]
+    reverse: Mapping[BeanKey, tuple[DependencyEdge, ...]]
+    coverage: Literal["complete", "partial", "unavailable"]
+    gaps: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class GraphSlice:
+    roots: tuple[BeanKey, ...]
+    edges: tuple[tuple[DependencyEdge, int], ...]
+    truncated: bool
+    gaps: tuple[str, ...]

spring_runtime_mcp/models/common.py

@@ -0,0 +1,99 @@
+"""Shared observation, uncertainty and request budget models."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from contextvars import ContextVar
+from dataclasses import dataclass
+import time
+from typing import Any, Generic, Literal, TypeVar
+
+T = TypeVar("T")
+
+
+class NormalizationError(ValueError):
+    """An expected, safe diagnostic failure; never attach upstream text."""
+
+    def __init__(self, code: str) -> None:
+        self.code = code
+        super().__init__(code)
+
+
+class AnalysisLimit(NormalizationError):
+    """The shared request analysis budget has been exhausted."""
+
+    def __init__(self, code: str = "GRAPH_LIMIT_REACHED") -> None:
+        super().__init__(code)
+
+
+@dataclass
+class CallBudget:
+    """One absolute deadline and visit allowance shared by an entire tool call."""
+
+    deadline: float
+    visits: int = 0
+
+    def check(self) -> float:
+        remaining = self.deadline - time.monotonic()
+        if remaining <= 0:
+            raise AnalysisLimit("TARGET_TIMEOUT")
+        return remaining
+
+    def consume(self, visits: int) -> None:
+        self.check()
+        self.visits += visits
+        if self.visits > 20_000:
+            raise AnalysisLimit()
+
+
+CALL_BUDGET: ContextVar[CallBudget | None] = ContextVar("call_budget", default=None)
+
+
+def remaining_seconds(limit: float = 15.0) -> float:
+    scope = CALL_BUDGET.get()
+    return min(limit, scope.check()) if scope is not None else limit
+
+
+@dataclass(frozen=True)
+class Fact(Generic[T]):
+    state: Literal["known", "unknown", "notReported", "redacted"]
+    value: T | None
+    reason_code: str | None = None
+
+
+@dataclass
+class AnalysisBudget:
+    max_visits: int = 20_000
+    max_depth: int = 16
+    deadline_monotonic: float | None = None
+    monotonic: Callable[[], float] | None = None
+    consumed_visits: int = 0
+
+    def consume(self, visits: int = 1) -> None:
+        if visits < 0:
+            raise ValueError("INVALID_BUDGET_INCREMENT")
+        self.consumed_visits += visits
+        scope = CALL_BUDGET.get()
+        if scope is not None:
+            scope.consume(visits)
+        if self.consumed_visits > self.max_visits:
+            raise AnalysisLimit()
+        if (
+            self.deadline_monotonic is not None
+            and self.monotonic is not None
+            and self.monotonic() >= self.deadline_monotonic
+        ):
+            raise AnalysisLimit("TARGET_TIMEOUT")
+
+
+@dataclass(frozen=True)
+class ParsedObservation:
+    target_id: str
+    snapshot_id: str
+    observation_id: str
+    observed_at: str
+    endpoint_id: str
+    body: Mapping[str, Any] | None
+    http_status: int | None = 200
+    error_code: str | None = None
+    representation: str = "actuatorV3"

spring_runtime_mcp/models/conditions.py

@@ -0,0 +1,56 @@
+"""Condition facts exclude the untrusted diagnostic message."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal
+
+from .bean_graph import ContextKey
+from .common import Fact
+
+Outcome = Literal["matched", "notMatched", "unknown"]
+Search = Literal["CURRENT", "PARENTS", "ALL", "unknown"]
+
+
+@dataclass(frozen=True)
+class Condition:
+    id: str
+    context: ContextKey
+    source: str
+    condition_type: str | None
+    operator: Literal["leaf", "any", "all", "none", "unknown"]
+    reported_outcome: Outcome
+    derived_outcome: Outcome
+    search: Search
+    required_types: tuple[str, ...]
+    required_names: tuple[str, ...]
+    property_key: Fact[str]
+    child_ids: tuple[str, ...]
+    children_complete: bool
+    reason_code: str
+    evidence_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ConditionReport:
+    nodes: Mapping[str, Condition]
+    roots_by_source: Mapping[tuple[ContextKey, str], tuple[str, ...]]
+    coverage: Literal["complete", "partial", "unavailable"]
+    gaps: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class BlockingEdge:
+    from_id: str
+    to_id: str
+    reason_code: str
+    evidence_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class FailureAnalysis:
+    state: Literal["notNeeded", "explained", "partial", "unknown"]
+    conditions: tuple[Condition, ...]
+    blocking_edges: tuple[BlockingEdge, ...]
+    blocking_paths: tuple[tuple[str, ...], ...]
+    truncated: bool
+    gaps: tuple[str, ...]

spring_runtime_mcp/models/queries.py

@@ -0,0 +1,140 @@
+"""Validated immutable tool arguments."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class InspectBeansQuery:
+    target_id: str = "local"
+    max_results: int = 50
+    cursor: str | None = None
+    bean_name_pattern: str | None = None
+    type_pattern: str | None = None
+    package_prefix: str | None = None
+    context_id: str | None = None
+    direction: Literal["dependencies", "dependents", "both"] = "both"
+    max_depth: int = 2
+    condition_depth: int = 4
+
+
+@dataclass(frozen=True)
+class HealthQuery:
+    target_id: str = "local"
+    max_results: int = 50
+    cursor: str | None = None
+    component_path: tuple[str, ...] = ()
+    group: Literal["application", "liveness", "readiness"] = "application"
+    include_details: bool = False
+    include_healthy: bool = False
+    max_depth: int = 4
+
+
+@dataclass(frozen=True)
+class MappingQuery:
+    target_id: str = "local"
+    max_results: int = 50
+    cursor: str | None = None
+    path_pattern: str | None = None
+    http_method: str | None = None
+    controller_class_pattern: str | None = None
+    context_id: str | None = None
+
+
+@dataclass(frozen=True)
+class ExpectedMigration:
+    engine: str
+    context_id: str
+    migration_bean: str
+    identity: str
+    version: str | None = None
+    checksum: str | None = None
+
+
+@dataclass(frozen=True)
+class StartupQuery:
+    target_id: str = "local"
+    max_results: int = 50
+    cursor: str | None = None
+    step_name_pattern: str | None = None
+    bean_name_pattern: str | None = None
+    min_duration_ms: float = 0
+    max_depth: int = 4
+
+
+@dataclass(frozen=True)
+class ConfigQuery:
+    target_id: str = "local"
+    max_results: int = 50
+    cursor: str | None = None
+    prefix: str | None = None
+    property_key_pattern: str | None = None
+    context_id: str | None = None
+    include_values: bool = False
+
+
+@dataclass(frozen=True)
+class OpenApiQuery:
+    target_id: str = "local"
+    max_results: int = 50
+    cursor: str | None = None
+    path_pattern: str | None = None
+    http_method: str | None = None
+    operation_id: str | None = None
+    schema_name: str | None = None
+    max_ref_depth: int = 2
+
+
+@dataclass(frozen=True)
+class MigrationQuery:
+    target_id: str = "local"
+    max_results: int = 50
+    cursor: str | None = None
+    engine: Literal["auto", "flyway", "liquibase"] = "auto"
+    context_id: str | None = None
+    migration_bean: str | None = None
+    states: tuple[str, ...] = ()
+    version: str | None = None
+    expected: tuple[ExpectedMigration, ...] = ()
+    expected_set_complete: bool = False
+
+
+@dataclass(frozen=True)
+class ExpectedBean:
+    name: str | None = None
+    type_name: str | None = None
+    context_id: str | None = None
+    aliases: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ExpectedRoute:
+    path: str
+    http_method: str
+    controller_class: str | None = None
+    context_id: str | None = None
+
+
+@dataclass(frozen=True)
+class ExpectedMigrationVersion:
+    engine: Literal["flyway", "liquibase"]
+    version: str
+    context_id: str | None = None
+    migration_bean: str | None = None
+
+
+@dataclass(frozen=True)
+class DriftQuery:
+    """Omitted expectation fields stay None; empty tuples are explicit scopes."""
+
+    target_id: str = "local"
+    max_results: int = 50
+    cursor: str | None = None
+    expected_beans: tuple[ExpectedBean, ...] | None = None
+    expected_routes: tuple[ExpectedRoute, ...] | None = None
+    expected_migration: ExpectedMigrationVersion | None = None
+    expected_profiles: tuple[str, ...] | None = None
+    expected_scope_complete: bool = False
+    source_revision: str | None = None
+    source_modified_at: str | None = None
+    max_depth: int = 2

spring_runtime_mcp/models/source_catalog.py

@@ -0,0 +1,35 @@
+"""Explicit, target-bound workspace facts; never inferred from Bean names."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TypeFact:
+    name: str
+    direct_supertypes: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class SourceProducer:
+    id: str
+    context_id: str
+    bean_name: str
+    aliases: tuple[str, ...]
+    declared_type: str
+    implementation_type: str | None
+    configuration_class: str
+    factory_method: str | None
+    condition_sources: tuple[str, ...]
+    source_file: str
+    source_line: int
+    evidence_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class SourceCatalog:
+    target_id: str
+    source_revision: str | None
+    types: Mapping[str, TypeFact]
+    producers: tuple[SourceProducer, ...]
+    gaps: tuple[str, ...]

spring_runtime_mcp/models/timestamps.py

@@ -0,0 +1,71 @@
+"""Bounded RFC3339 parsing shared by contracts and runtime evidence.
+
+Keep fractional precision and a leap-second ordering slot. Duration arithmetic
+involving an explicit leap second remains unknown without a trusted history.
+"""
+
+from __future__ import annotations
+
+import calendar
+import re
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta, timezone
+from decimal import Decimal
+
+_TIMESTAMP = re.compile(
+    r"([0-9]{4})-([0-9]{2})-([0-9]{2})[Tt]"
+    r"([0-9]{2}):([0-9]{2}):([0-9]{2})(\.[0-9]+)?"
+    r"([Zz]|[+-][0-9]{2}:[0-9]{2})"
+)
+
+
+@dataclass(frozen=True, order=True)
+class Timestamp:
+    second: datetime
+    leap: bool
+    fraction: Decimal
+
+    def milliseconds_since(self, earlier: Timestamp) -> float | None:
+        if self.leap or earlier.leap:
+            return None
+        delta = self.second - earlier.second
+        seconds = Decimal(delta.days * 86400 + delta.seconds)
+        return float((seconds + self.fraction - earlier.fraction) * 1000)
+
+
+def parse_rfc3339(value: object) -> Timestamp | None:
+    if not isinstance(value, str) or len(value) > 64:
+        return None
+    match = _TIMESTAMP.fullmatch(value)
+    if match is None:
+        return None
+    year, month, day, hour, minute, second = map(int, match.groups()[:6])
+    offset = match[8]
+    try:
+        zone = UTC
+        if offset not in ("Z", "z"):
+            hours, minutes = int(offset[1:3]), int(offset[4:6])
+            if hours > 23 or minutes > 59:
+                return None
+            zone = timezone(
+                timedelta(
+                    minutes=(hours * 60 + minutes) * (1 if offset[0] == "+" else -1)
+                )
+            )
+        if second > 60:
+            return None
+        instant = datetime(
+            year, month, day, hour, minute, min(second, 59), tzinfo=zone
+        ).astimezone(UTC)
+    except (ValueError, OverflowError):
+        return None
+    leap = second == 60
+    # RFC3339 permits insertions at UTC month ends. Validate the placement;
+    # do not claim knowledge of a historical or future insertion schedule.
+    if leap and (
+        instant.hour != 23
+        or instant.minute != 59
+        or instant.day != calendar.monthrange(instant.year, instant.month)[1]
+    ):
+        return None
+    return Timestamp(instant, leap, Decimal("0" + (match[7] or "")))

spring_runtime_mcp/policy/__init__.py

@@ -0,0 +1 @@
+"""Mandatory output safety controls."""

spring_runtime_mcp/policy/configuration.py

@@ -0,0 +1,32 @@
+"""Immutable operator registration for config reads, never tool arguments."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ConfigReadPolicy:
+    properties: frozenset[str] = frozenset()
+    prefixes: frozenset[str] = frozenset()
+    allow_values: bool = False
+    profiles: bool = False
+
+    def __post_init__(self) -> None:
+        for name in ("properties", "prefixes"):
+            values = frozenset(getattr(self, name))
+            if len(values) > 100 or any(
+                not isinstance(value, str)
+                or re.fullmatch(r"[A-Za-z_][A-Za-z0-9_.-]{0,255}", value) is None
+                for value in values
+            ):
+                raise ValueError("INVALID_CONFIG_REGISTRATION")
+            object.__setattr__(self, name, values)
+        if type(self.allow_values) is not bool or type(self.profiles) is not bool:
+            raise ValueError("INVALID_CONFIG_REGISTRATION")
+
+    def allows(self, key: str) -> bool:
+        return key in self.properties or any(
+            key == prefix or key.startswith(prefix + ".") for prefix in self.prefixes
+        )

spring_runtime_mcp/policy/output_guard.py

@@ -0,0 +1,117 @@
+"""Independent rejection gate for cache and wire sinks; never repair raw JSON."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..models.common import NormalizationError
+from ..transport.bounded_json import loads_bounded, validate_tree
+from .sanitization import (
+    MARKER,
+    OMITTED_TEXT_FIELDS,
+    SanitizerPipeline,
+    sensitive_key,
+    untrusted_text_descriptor,
+)
+
+DIAGNOSTIC_MESSAGE = "Diagnostic evidence is unavailable; review the registered target and access policy."
+REVIEW_TARGET = (
+    "Review target registration, endpoint exposure and authorization locally."
+)
+REVIEW_AUTHORIZATION = "Review the existing Spring Security rule and diagnostic credentials; do not disable security or follow login redirects."
+REVIEW_STARTUP = "Review startup endpoint exposure; if collection is absent, configure SpringApplication.setApplicationStartup(new BufferingApplicationStartup(2048)) before run; restart requires approval."
+LOCAL_PROSE = frozenset(
+    {
+        DIAGNOSTIC_MESSAGE,
+        REVIEW_TARGET,
+        REVIEW_AUTHORIZATION,
+        REVIEW_STARTUP,
+        "registered target Bean contexts",
+        "registered target health",
+        "registered target mappings",
+        "registered target migrations",
+        "registered target startup",
+        "registered target config",
+        "registered target openapi",
+    }
+)
+
+
+def ensure_safe_output(
+    value: Any, *, sanitizer: SanitizerPipeline | None = None
+) -> None:
+    """Reject recognizable secrets, raw prose and unsafe secondary JSON at sinks.
+
+    This complements typed projection. Opaque unknown secrets have no universal
+    recognizer; producers must still allowlist facts and register credentials.
+    """
+    validate_tree(value, max_bytes=32 * 1024 * 1024)
+    pipeline = sanitizer or SanitizerPipeline()
+    pending = [(value, "", 0)]
+    while pending:
+        item, field, depth = pending.pop()
+        if depth > 64:
+            raise NormalizationError("UNSAFE_OUTPUT")
+        if isinstance(item, dict):
+            descriptor_tainted = untrusted_text_descriptor(item)
+            unsafe_descriptor = False
+            for key in ("name", "key", "propertyName", "propertyKey"):
+                name = item.get(key)
+                if isinstance(name, str) and pipeline.identifier(name) == MARKER:
+                    descriptor_tainted = True
+                    unsafe_descriptor |= sensitive_key(name) or pipeline.high_risk(name)
+            if descriptor_tainted and any(
+                item.get(key) not in (None, MARKER)
+                for key in ("value", "bindingValue", "effectiveValue", "inputs")
+            ):
+                raise NormalizationError(
+                    "UNSAFE_OUTPUT" if unsafe_descriptor else "UNTRUSTED_OUTPUT"
+                )
+            if (
+                descriptor_tainted
+                and isinstance(item.get("origin"), str)
+                and item["origin"] != MARKER
+            ):
+                raise NormalizationError("UNTRUSTED_OUTPUT")
+            for key, child in item.items():
+                if pipeline.high_risk(key) or (
+                    sensitive_key(key) and child not in (MARKER, None)
+                ):
+                    raise NormalizationError("UNSAFE_OUTPUT")
+                if field == "properties":
+                    # Property names may coincide with omitted prose fields;
+                    # only Schema objects are allowed, and their contents still
+                    # pass every ordinary output check.
+                    if not isinstance(child, dict):
+                        raise NormalizationError("UNTRUSTED_OUTPUT")
+                    pending.append((child, "", depth + 1))
+                    continue
+                if key in OMITTED_TEXT_FIELDS and child not in (MARKER, None, [], {}):
+                    raise NormalizationError("UNTRUSTED_OUTPUT")
+                pending.append((child, key, depth + 1))
+        elif isinstance(item, list):
+            pending.extend((child, field, depth + 1) for child in item)
+        elif isinstance(item, str) and item != MARKER:
+            if pipeline.high_risk(item):
+                raise NormalizationError("UNSAFE_OUTPUT")
+            if (
+                any(c.isspace() for c in item)
+                and item not in LOCAL_PROSE
+                and not item.lstrip().startswith(("{", "["))
+            ):
+                raise NormalizationError("UNTRUSTED_OUTPUT")
+            if field in ("message", "steps") and item not in LOCAL_PROSE:
+                raise NormalizationError("UNTRUSTED_OUTPUT")
+            if field == "nextAction":
+                raise NormalizationError("UNTRUSTED_OUTPUT")
+            if item.lstrip().startswith(("{", "[")):
+                try:
+                    nested = loads_bounded(
+                        ('{"value":' + item.strip() + "}").encode(),
+                        max_bytes=65_550,
+                        max_depth=32,
+                        max_nodes=10_000,
+                    )["value"]
+                except NormalizationError:
+                    raise NormalizationError("UNSAFE_OUTPUT") from None
+                pending.append((nested, field, depth + 1))