CloudOps MCP

CloudOps MCP ist ein schreibgeschützter Model Context Protocol-Server, der normalisierten Betriebsinfrastrukturkontext (Logs, Metriken, Bereitstellungen, Zustand) für KI-Agenten über eine kleine Menge typisierter, begrenzter Werkzeuge bereitstellt.

Warum es existiert

Ein Agent, der einen Vorfall untersucht, benötigt Betriebskontext: was sich kürzlich geändert hat, wie die Fehlerrate aussieht, was die Logs sagen. Er benötigt keinen uneingeschränkten Zugriff auf Cloud-APIs, und er sollte nicht das sein, was entscheidet, was als Grundursache gilt.

CloudOps MCP sitzt zwischen beiden:

Cloud APIs / observability systems
        |
Provider adapters
        |
Normalized operational domain
        |
Deterministic services
        |
MCP tools
        |
AI agent

Jede Schicht normalisiert weiter und schränkt ein, was der Agent anfragen kann. Provider-Adapter übersetzen Anbieter-APIs in ein gemeinsames Domänenmodell. Dienste wenden Begrenzungen, Sortierung und Aggregation deterministisch an, auf die gleiche Weise für jeden Anbieter. MCP-Werkzeuge legen dies als eine kleine, typisierte Oberfläche dar.

CloudOps MCP liefert Betriebsfakten, keine Schlussfolgerungen zur Grundursache. Ein Werkzeug kann sagen „Fehlerrate von 0,4 % auf 8 % um 14:06 gestiegen“; es wird nicht sagen „die Bereitstellung hat den Ausfall verursacht.“ Dieses Urteil obliegt dem Agenten, mit den Fakten, die CloudOps MCP ihm als Beweismittel übergibt.

Related MCP server: cloud-chat-assistant

Fähigkeiten

Sechs Werkzeuge, alle schreibgeschützt und begrenzt:

get_operational_snapshot setzt sich aus denselben primitiven Diensten zusammen, die auch die anderen fünf Werkzeuge verwenden, und führt alle vier unabhängigen Abfragen gleichzeitig aus. Es kommuniziert nie direkt mit einem Anbieter, und es schlägt nie als Ganzes fehl, weil ein Abschnitt nicht verfügbar ist; jeder Abschnitt meldet seinen eigenen Status.

Entwurfsprinzipien

• Von Grund auf schreibgeschützt. Anbieterschnittstellen legen keine Mutationsmethoden offen. Es gibt keinen Codepfad zu einer Schreib-API.

• Anbieterneutrale Dienstidentität. Ein Dienst wird durch (service, environment) identifiziert. Anbieterspezifische Bezeichner (eine CloudWatch-Loggruppe, ein Kubernetes-Objektname) bleiben intern in den Anbieterbindungen und sind nie Teil des öffentlichen Vertrags.

• Kanonische, erweiterbare Metriken. error_rate, latency_p99 und ähnliche Namen sind unsere, nicht die des Anbieters. Die Abbildung eines kanonischen Namens auf eine echte Metrik lebt in der Konfiguration, pro Dienst. Das Vokabular ist offen, kein festgelegtes Enum.

• Begrenzte Abfragen. Jede Telemetrieabfrage hat eine Zeitbereichsobergrenze und eine Anzahlsobergrenze. Ein Aufrufer kann nach weniger fragen; er kann nicht nach unbegrenzten Daten fragen.

• Explizite Datenverfügbarkeit. Jede Sammlung meldet einen von SUCCESS, EMPTY, PARTIAL oder FAILED. Fehlende Daten werden nie stillschweigend als „gesund“ oder „nichts passiert“ behandelt.

• Verfügbarkeit getrennt vom Ergebnis. NOT_CONFIGURED (kein Anbieter angeschlossen) und EMPTY (erfolgreich abgefragt, null Treffer) sind unterschiedliche Zustände und werden nie vermischt.

• Herkunft ohne Offenlegung von Interna. Einzelergebnisse tragen provider und source, wenn ein Anbieteradapter sie liefert. Die interne Referenz, die zum Aufrufen eines Anbieters verwendet wird, wird nie in die öffentliche Ausgabe kopiert.

• Überall UTC. Alle Zeitstempel sind zeitzonenbewusst und auf UTC normalisiert; naive Datums-/Zeitangaben werden an der Modellgrenze zurückgewiesen.

• Kein LLM im MCP-Server. Keine Zusammenfassung, keine Klassifizierung, keine Schlussfolgerung über Log-Inhalte. Log-Nachrichten werden als undurchsichtiger, nicht vertrauenswürdiger Text behandelt.

• Keine kausale Argumentation. Werkzeuge berichten, was sich wann geändert hat. Die Interpretation des Warums bleibt dem Agenten überlassen.

Kurzstart: Fake-Modus

Der Fake-Modus ist der Standard und der primäre Weg, CloudOps MCP auszuprobieren. Er benötigt kein Cloud-Konto.

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Den Server ausführen (stdio-Transport):

python -m cloudops_mcp.server

Oder, wenn das Paket mit seinem Konsolenskript installiert ist:

cloudops-mcp

Der Server spricht MCP über stdio und erwartet einen Client auf der anderen Seite. Um es direkt von Python aus mit dem Client des offiziellen SDKs zu testen:

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(command="python", args=["-m", "cloudops_mcp.server"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            result = await session.call_tool(
                "get_operational_snapshot",
                {"service": "checkout-api", "environment": "production"},
            )
            print(result.structured_content)

asyncio.run(main())

Fake-Szenarien

Wählen Sie ein Szenario mit CLOUDOPS_MCP_SCENARIO (Standard healthy):

CLOUDOPS_MCP_SCENARIO=bad_deploy python -m cloudops_mcp.server

bad_deploy säht drei korrelierte Fakten zu festen Zeitstempeln: eine Bereitstellung, dann eine Metrikverschiebung einige Minuten später, dann Timeout-Logzeilen kurz danach. CloudOps MCP meldet diese drei Fakten und sonst nichts. Es behauptet nicht, dass die Bereitstellung die Fehler verursacht hat; diese Schlussfolgerung wird vollständig dem verbrauchenden Agenten überlassen.

AWS CloudWatch-Modus

pip install -e ".[aws]"        # runtime only
pip install -e ".[dev,aws]"    # development

CLOUDOPS_MCP_MODE=aws CLOUDOPS_MCP_CONFIG=/path/to/cloudops.toml cloudops-mcp

Siehe examples/aws-cloudwatch.toml für eine vollständige Beispielkonfiguration. Sie verwendet nur Platzhalterwerte, keine echte Konto-ID, ARN oder Anmeldeinformation gehört in diese Datei.

Anmeldeinformationen stammen vollständig aus boto3s Standard-Provider-Kette: AWS_PROFILE, AWS_REGION / AWS_DEFAULT_REGION, Umgebungsanmeldeinformationen oder eine IAM-Rolle. CloudOps MCP liest, speichert oder protokolliert niemals einen Zugriffsschlüssel oder ein Secret.

Im AWS-Modus implementiert:

• Logs: CloudWatch Logs FilterLogEvents.

• Metrics: CloudWatch GetMetricData (MetricStat queries only).

Noch nicht implementiert: AWS-gestützte Bereitstellungen und Zustand. Ein Dienst, der ohne diese Abschnitte konfiguriert ist, meldet einfach NOT_CONFIGURED für sie, wie jede andere nicht konfigurierte Fähigkeit. Siehe docs/aws.md für Konfigurationsschema, Paginierungsverhalten und Einschränkungen.

AWS IAM

Mindestrichtlinie für schreibgeschützten Zugriff für diese Integration (fiktives Konto und Loggruppe):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "logs:FilterLogEvents",
      "Resource": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/checkout-api"
    },
    {
      "Effect": "Allow",
      "Action": "cloudwatch:GetMetricData",
      "Resource": "*"
    }
  ]
}

FilterLogEvents kann auf die spezifische Loggruppen-ARN eingegrenzt werden. Für die MetricStat-Abfragen, die diese Integration ausgibt, hat GetMetricData keine ressourcenbezogene Eingrenzung im IAM-Autorisierungsmodell von AWS, daher verwendet diese Anweisung Resource: "*". Das ist eine Eigenschaft der API, keine hier getroffene Wahl.

Begrenzte Abfragen

Jedes begrenzte Ergebnis meldet sowohl requested_bounds als auch applied_bounds, sodass ein Aufrufer genau sehen kann, was begrenzt wurde. Eine Begrenzung einer Anfrage auf die harte Obergrenze ist nicht dasselbe wie PARTIAL: Eine begrenzte, aber vollständig erfüllte Abfrage ist immer noch SUCCESS. PARTIAL bedeutet, dass die Extraktion selbst bekanntermaßen unvollständig ist, zum Beispiel wenn ein Anbieter paginiert und aufgehört hat, bevor alle Treffer innerhalb des angewendeten Fensters ausgeschöpft wurden.

Datenverfügbarkeitssemantik

Zwei orthogonale Fragen, die nie zu einer zusammengefasst werden:

1. Ist eine Fähigkeit für diesen Dienst überhaupt konfiguriert? (CONFIGURED / NOT_CONFIGURED)

2. Wenn sie abgefragt wurde, was ist passiert? (SUCCESS / EMPTY / PARTIAL / FAILED)

Eine Zustandsprüfung für einen Dienst ohne konfigurierten Zustandsanbieter ist NOT_CONFIGURED, nicht EMPTY und nicht FAILED. Eine Log-Abfrage, die im Zeitfenster berechtigterweise nichts gefunden hat, ist EMPTY, nicht FAILED. Ein Metrikaufruf, der auf eine Ratenbegrenzung stößt, bevor er etwas Verwertbares zurückgibt, ist FAILED mit einem Grund, nicht stillschweigend leere Daten.

Strukturierte MCP-Ausgaben

Jedes Werkzeug akzeptiert typisierte Argumente und gibt ein typisiertes Pydantic-Modell zurück. Das offizielle Python MCP SDK leitet structuredContent und das Ausgabeschema des Werkzeugs direkt von diesem Rückgabetyp ab, Werkzeugantworten sind echte strukturierte Daten, kein JSON-String, der in einen Textblock eingewickelt ist.

Architektur

flowchart TD
    subgraph Providers
        Fake[Fake providers]
        AWS[AWS CloudWatch providers]
    end

    Fake --> Services
    AWS --> Services

    Registry[ServiceRegistry] --> Services

    subgraph Services[Deterministic services]
        Catalog[catalog_service]
        Health[health_service]
        Deploy[deployment_service]
        Logs[logs_service]
        Metrics[metrics_service]
        Snapshot[snapshot_service]
    end

    Snapshot --> Deploy
    Snapshot --> Logs
    Snapshot --> Metrics
    Snapshot --> Health

    Services --> Tools[MCP tools]
    Tools --> Agent[AI agent]

get_operational_snapshot setzt die primitiven Dienste zusammen, es umgeht sie nicht oder spricht selbst mit Anbietern. Siehe docs/architecture.md für die vollständige technische Aufschlüsselung.

Testen

• Deterministische Fake-Szenarien üben die gesamte Werkzeugoberfläche Ende-zu-Ende.

• Tests auf Anbieterebene verwenden absichtlich fehlverhaltende Stub-Anbieter (falsche Sortierung, ignorierte Begrenzungen), um zu beweisen, dass die Dienstschicht die Ausgabe selbst verteidigt, nicht nur wohlverhaltende Anbieter.

• AWS-Anbieter-Tests verwenden kleine Stub-CloudWatch-Clients, keine echten AWS-Aufrufe, kein moto, kein LocalStack.

• Ein Test treibt den echten MCP SDK-Client gegen einen prozessinternen Server an und bestätigt die Protokollgrenze selbst (Werkzeugerkennung, strukturierte Ausgabe) und nicht nur die interne Logik.

ruff check src tests
mypy src tests --strict
pytest -q

Aktuelle Einschränkungen

• Die Live-Validierung für AWS wurde mit typisierter Konfigurationsanalyse, gestubten Client-Tests und der echten MCP-Client/Server-Grenze durchgeführt, noch nicht gegen ein echtes AWS-Konto. Das erfordert benutzerausgewählte Ressourcen und ist absichtlich nicht automatisiert: CloudOps MCP entdeckt oder prüft kein Konto von sich aus.

• Noch keine AWS-gestützten Bereitstellungen oder Zustandsanbieter.

• Nur stdio-Transport, kein Remote-MCP.

• Das Dienstregister ist statisch und konfigurationsgestützt, es gibt keine automatische Erkennung von Diensten aus einem Cloud-Konto.

• Keine Mutation, Behebung oder Schreibpfad jeglicher Art.

Fahrplan

• Zusätzliche schreibgeschützte Fähigkeiten bei bestehenden Anbietern.

• Ein zweiter echter Anbieter, um die Normalisierungsgrenze gegen mehr als einen Anbieter zu testen.

• Ein Remote-Transport, falls ein Bereitstellungsszenario tatsächlich einen benötigt.

• Nutzung durch Incident-Response-Agenten als ein Beispiel eines generischen MCP-Clients. CloudOps MCP ist an keinen bestimmten Verbraucher gekoppelt.

Sicherheit

• Keine Mutationsmethoden irgendwo in den Provider-Schnittstellen.

• Keine Shell-Ausführung, keine Aufrufe von Cloud-CLI-Subprozessen.

• Least-Privilege-IAM: genau logs:FilterLogEvents und cloudwatch:GetMetricData, nichts wird "für den Fall der Fälle" angefordert.

• Nur die Standard-AWS-Anmeldeinformationskette, keine benutzerdefinierte Anmeldeinformationsverwaltung.

• Interne Provider-Referenzen (Log-Gruppennamen, CloudWatch-Dimensionen) erscheinen niemals in der Tool-Ausgabe.

• Log-Inhalte werden als nicht vertrauenswürdiger, undurchsichtiger Text behandelt: niemals geparst, ausgeführt oder interpretiert.

• Unerwartete Fehler werden an der Tool-Grenze bereinigt; nur eine feste, generische Nachricht überschreitet sie, niemals eine rohe Ausnahmestring.

• Jede Telemetrieabfrage ist begrenzt, um sowohl die Provider-APIs als auch das Kontextfenster des Agents zu schützen.

License

MIT, siehe LICENSE.