adf-mcp-server

Read-only MCP (Model Context Protocol) Server für Azure Data Factory Monitoring und Root-Cause-Analyse, entwickelt für die Verwendung aus VS Code / Claude Code.

Status: Schritt 1 (Grundgerüst + Health Check). Noch keine Azure-Konnektivität – diese wird in Schritt 2 (Authentifizierung) und Schritt 3 (ADF-Tools) hinzugefügt.

Anforderungen

• Python 3.11+

• Eine Azure AD App-Registrierung (Service Principal) mit Reader-Rolle auf der/den Data Factory-Ressource(n), die Sie überprüfen möchten (Reader ist ausreichend – dieser Server ist durchgängig schreibgeschützt, benötigt also niemals Contributor)

Related MCP server: mcp-azure-landing-zone

Lokale Einrichtung

cd adf-mcp-server
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env

Erstellen des Service Principal (einmalig, über az-cli)

az ad sp create-for-rbac \
  --name "adf-mcp-server-reader" \
  --role "Reader" \
  --scopes "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.DataFactory/factories/<FACTORY_NAME>"

Dies gibt appId, password und tenant aus – ordnen Sie diese in .env als AZURE_CLIENT_ID, AZURE_CLIENT_SECRET bzw. AZURE_TENANT_ID zu. Begrenzen Sie die Rollenzuweisung auf die spezifische Factory (oder höchstens die Ressourcengruppe) statt auf das gesamte Abonnement – geringstmögliche Berechtigungen, und dieser SPN muss niemals etwas außerhalb von ADF berühren.

Server ausführen

python -m adf_mcp.server
# or, after `pip install -e .`:
adf-mcp-server

Der Server kommuniziert über stdio – wenn Sie ihn direkt in einem Terminal ausführen, sieht es so aus, als würde er hängen; das ist erwartet, er wartet darauf, dass ein MCP-Client (VS Code-Erweiterung, Claude Code, mcp dev usw.) über stdin/stdout eine Verbindung herstellt.

Konfiguration in VS Code

Weisen Sie die Serverkonfiguration Ihrer MCP-fähigen Erweiterung auf:

{
  "command": "python",
  "args": ["-m", "adf_mcp.server"],
  "cwd": "/absolute/path/to/adf-mcp-server"
}

Sobald verbunden:

1. Rufen Sie health_check auf – sollte {"status": "ok", ...} zurückgeben, ohne Azure überhaupt zu berühren.

2. Rufen Sie check_auth auf – dies führt einen echten Aufruf an Azure AD durch, um ein ARM-Token zu erhalten. Erfolg sieht so aus:

   {"authenticated": true, "auth_mode": "service_principal", "token_expires_on": 1735000000}

   Bei Fehlern wird eine strukturierte (keine Stack-Trace-)Erklärung zurückgegeben, z. B. fehlende Umgebungsvariablen oder ein ungültiges Geheimnis – siehe Fehlerbehebung unten.

3. Rufen Sie list_factories auf – dies führt einen echten Aufruf an Azure Data Factory durch. Gibt die resource_group jeder Factory zurück, die jedes andere Tool unten als Eingabe benötigt:

   {"factories": [{"name": "shell-prod-adf", "resource_group": "rg-shell-prod", "location": "eastus"}]}

Verfügbare Tools (Schritt 3)

Alle Tools sind schreibgeschützt – keines davon kann etwas in Azure Data Factory erstellen, ändern, auslösen oder löschen.

Beispiel-RCA-Ablauf für einen Agenten: list_factories → list_pipeline_runs(status="Failed") → get_failed_activity_details(run_id=...) für die Fehleraufschlüsselung direkt.

Verfügbare Tools (Schritt 4-Erweiterungen)

Vollständiger RCA-Ablauf für eine fehlgeschlagene Pipeline: list_pipeline_runs(status="Failed") → get_failed_activity_details(run_id=...) für den Fehler, und separat get_trigger_status(trigger_name=...) um auszuschließen, dass „sie nie ausgelöst wurde“.

Tests ausführen

pip install -e ".[dev]" pytest-asyncio
pytest -v

Projektstruktur

Siehe src/adf_mcp/ – server.py (MCP-Transport), config.py (Einstellungen), logging_config.py (strukturierte Protokollierung). Domänenlogik und Azure-Konnektivität werden ab Schritt 3 unter src/adf_mcp/domain/ hinzugefügt.

Fehlerbehebung

• Client zeigt sofort „Server disconnected“: Überprüfen Sie zuerst, ob python -m adf_mcp.server eigenständig sauber läuft – eine Startausnahme beendet den Prozess, bevor der Client überhaupt eine Verbindung herstellt.

• Client kann Antworten nicht parsen / verstümmelte Ausgabe: Etwas hat auf stdout geschrieben, das nicht das MCP-Protokoll selbst ist (z. B. ein versehentliches print()). Die gesamte Protokollierung in diesem Projekt geht aus genau diesem Grund an stderr.

• check_auth gibt „Missing required Service Principal setting(s)“ zurück: Eine der Variablen AZURE_TENANT_ID / AZURE_CLIENT_ID / AZURE_CLIENT_SECRET ist in .env leer. Beachten Sie, dass diese drei NICHT das Präfix ADF_MCP_ verwenden.

• check_auth gibt „Azure authentication failed“ zurück: Meist ein abgelaufenes/ rotiertes Client-Geheimnis, eine deaktivierte App-Registrierung oder ein Tippfehler bei der Mandanten-ID. Überprüfen Sie erneut mit az ad sp show --id <AZURE_CLIENT_ID>.

• ClientAuthenticationError: AADSTS7000215: Ungültiges Client-Geheimnis – generieren Sie es in der App-Registrierung neu und aktualisieren Sie .env.

• Ein Tool gibt {"error": "AZURE_SUBSCRIPTION_ID is not set..."} zurück: Fügen Sie AZURE_SUBSCRIPTION_ID zu .env hinzu – erforderlich für jedes ADF-Tool (nicht für check_auth, das nur Mandant/Client/Geheimnis benötigt).

• Ein Tool gibt {"error": "Azure API error (403): ..."} zurück: Dem Service Principal fehlt die Reader-Berechtigung für diese Factory/Ressourcengruppe – überprüfen Sie die Zuweisung az ad sp create-for-rbac --role Reader --scopes ... aus der Einrichtung.

• Ein Tool gibt {"error": "Azure API error (404): ..."} zurück: Überprüfen Sie die Schreibweise von resource_group/factory_name/pipeline_name – diese sind case-sensitiv und müssen exakt mit dem übereinstimmen, was list_factories/ list_pipelines zurückgegeben hat.

• get_failed_activity_details gibt eine leere Liste zurück, aber Sie wissen, dass die Pipeline fehlgeschlagen ist: Der Fehler kann auf Pipeline-Ebene liegen (z. B. ein ungültiger Parameter) und nicht bei einer einzelnen Aktivität – prüfen Sie stattdessen die eigene message der übergeordneten Ausführung über get_pipeline_run.

• Eine Pipeline „wurde einfach nicht ausgeführt“ ohne fehlgeschlagene Ausführungen: Überprüfen Sie get_trigger_status für ihren Trigger – runtime_state: "Stopped" bedeutet, dass der Trigger deaktiviert war und nie ausgelöst wurde, was nicht als fehlgeschlagene Ausführung erscheint, da nie eine Ausführung erstellt wurde.