hydris-mcp-integration

Hydris Pulse Bridge Track, Arbeitspaket 1: das Diagnose-MCP-Server-Skelett, das sich im Lite-Monorepo unter lite/diagnostic_mcp/ befinden wird. Es erfüllt BRIDGE-2 (pro-aufruf-Factory-Autorisierung), BRIDGE-5 (pro-aufruf-Audit-Protokollierung) und NFR-4 (Sicherheit) und erzwingt strukturell BRIDGE-1 (schreibgeschütztes Toolset).

Siehe docs/scope.md für eine genaue Beschreibung dessen, was hier gebaut wird und was nicht, und docs/decisions.md für die offenen Entscheidungen (Widerrufslatenz, Verhalten bei Audit-Sink-Fehlern, die nicht preisgebende Fehlerform, das Toolset-Versionsschema), zu denen dieses Skelett eine Position bezogen hat, in Erwartung der Ratifizierung durch Nematullah.

Architektur

• Zwei Identitäten, getrennt gehalten (diagnostic_mcp/auth/): ein Dienstprinzipal-JWT (schreibgeschützte Bereiche, unabhängig verifiziert) und ein pro-aufruf Benutzerkontext-JWT. Das Diensttoken erweitert niemals den Zugriff.

• Eine Pipeline für jeden Aufruf (diagnostic_mcp/registry/pipeline.py): Authentifiziere beide Identitäten, validiere Argumente, prüfe die Live-Factory-Berechtigung des Benutzers (kein Caching), leite weiter, protokolliere das Ergebnis – Erfolg, Ablehnung oder Fehler – jedes Mal.

• Schreibgeschütztes Tor zur Registrierungszeit (diagnostic_mcp/registry/tool_registry.py): Ein Tool ohne classification="read_only" oder ohne ein erforderliches factory_id-Argument wird bei der Registrierung abgelehnt, nicht beim Aufruf.

• FastMCP für Schema-Ankündigung, eine Überschreibung für Dispatch (diagnostic_mcp/server.py): tools/list kommt wie gewohnt von FastMCP; tools/call wird einmal auf dem Low-Level-Server abgefangen, sodass jedes Tool – gegenwärtig oder zukünftig – dieselbe Pipeline durchläuft, ohne pro-Tool-Boilerplate.

• Ein Demonstrations-Tool, get_plant_overview (diagnostic_mcp/tools/plant_overview.py), gestützt durch einen In-Memory-Stub der Lese-Service-Schicht von Lite, befüllt mit den genauen Fixtures, die die Quelldokumente nennen (u-ops-alpha gewährt fx-mbr-01; u-ops-beta gewährt fx-beta-01).

Related MCP server: system-monitor

Quickstart

python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"      # .venv/bin/pip on macOS/Linux
cp .env.example .env                        # then edit the two secrets

Server ausführen:

set -a; source .env; set +a                 # or export the vars another way
python -m diagnostic_mcp.server

Er hört standardmäßig auf streamable-http unter http://127.0.0.1:8765/mcp.

End-to-End-Überprüfung

pytest -v            # includes a real streamable-HTTP client/server round trip
ruff check .
mypy diagnostic_mcp tests
python scripts/check_no_write_imports.py

Um den laufenden Server manuell mit dem offiziellen MCP-Client aufzurufen, erstelle ein Diensttoken und ein Benutzerkontext-Token mit denselben Geheimnissen, mit denen der Server läuft:

from diagnostic_mcp.auth.service_principal import issue_service_token
from diagnostic_mcp.auth.user_context import issue_user_context_token

service_token = issue_service_token("<LITE_MCP_SERVICE_TOKEN_SECRET>")
user_token = issue_user_context_token("<LITE_MCP_USER_CONTEXT_SECRET>", "u-ops-alpha", "org-alpha")
print(f"Authorization: Bearer {service_token}")
print(f"X-Pulse-User-Context: {user_token}")

Rufe dann get_plant_overview mit factory_id=fx-mbr-01 auf (gewährt – erfolgreich) oder factory_id=fx-beta-01 (nicht gewährt – abgelehnt, und beide Versuche landen in audit.jsonl).

Definition of Done für Arbeitspaket 1