delinea-mcp Server

offiziell

Offizieller Delinea MCP-Server für die Delinea Secret Server und Platform APIs

GitHub
46

Dokumentation

DelineaMCP

MCP-Server für die Delinea Secret Server- und Plattform-APIs

License

Funktionen

  • Automatische Authentifizierung gegenüber Secret Server
  • Umfangreicher Secret-Server-Werkzeugsatz zur Verwaltung von Ordnern, Secrets, Benutzern, Gruppen und Rollen. Enthält Posteingangs- und Zugriffsanforderungs-Helfer sowie Dienstprogramme für Coding-Agenten.
  • ChatGPT-Kompatibilitätswerkzeuge (search und fetch) für kontrollierte KI-Interaktionen.
  • Optionale Delinea-Plattform-Benutzerverwaltungswerkzeuge
  • Unterstützt sowohl Server-Sent-Events- als auch STDIO-Transportmodi
  • OAuth 2.0 mit dynamischer Client-Registrierung gemäß der MCP-Spezifikation
  • TLS-Unterstützung für sichere Verbindungen
  • Einsatzbereites Docker-Image und Entwicklungsserver-Einstiegspunkt
  • Getestet mit ChatGPT, Claude Desktop, Remote-Claude-Connector, VSCode Copilot und openwebui

Installation

[!NOTE]

Dieses Projekt verwendet uv (https://github.com/astral-sh/uv), aber wenn Sie Befehle lieber ohne dies ausführen möchten, können Sie pip und venv-Befehle wie gewohnt verwenden.

  • Uv installieren
  • Projekt initialisieren: uv pip sync requirements.txt
  • uv run server.py --config config.json verwenden

Konfiguration

Geheimnisse wie Passwörter stammen weiterhin aus Umgebungsvariablen. Stellen Sie DELINEA_PASSWORD in Ihrer Shell-Umgebung bereit. Optionale Funktionen benötigen zusätzliche Variablen wie AZURE_OPENAI_KEY oder PLATFORM_SERVICE_PASSWORD.

Nicht geheime Parameter gehören in config.json:

{
  "delinea_username": "<username>",
  "delinea_base_url": "https://your-secret-server/SecretServer",
  "platform_hostname": "<tenant>.secureplatform.io",
  "platform_service_account": "<service_account>",
  "platform_tenant_id": "<tenant_id>",
  "azure_openai_endpoint": "https://example.openai.azure.com/",
  "azure_openai_deployment": "<deployment_name>",
  "auth_mode": "none",
  "transport_mode": "stdio",
  "chatgpt_disable_scope_checks": false,
  "port": 8000,
  "debug": false,
  "external_hostname": null,
  "ssl_keyfile": null,
  "ssl_certfile": null,
  "registration_psk": null,
  "jwt_key_path": ".cache/jwt.json",
  "oauth_db_path": ".cache/oauth.db",
  "enabled_tools": []
}

Für Secret Server Cloud verwenden Sie einfach die Cloud-URL ohne /SecretServer. Geben Sie ssl_keyfile und ssl_certfile an, um HTTPS zu aktivieren. Für Let's Encrypt verwenden Sie die Dateien privkey.pem und fullchain.pem.

Die Konfigurationsdatei unterstützt die folgenden Schlüssel:

  • delinea_username – Secret-Server-Benutzername. Muss ein programmatischer Benutzer mit Berechtigung für die gewünschten Aufgaben sein.
  • delinea_base_url – Basis-URL Ihrer Secret-Server-Instanz.
  • platform_hostname – Plattform-Mandanten-Hostname (aktiviert Plattform-Werkzeuge).
  • platform_service_account – Dienstkonto, das mit der Plattform-API verwendet wird.
  • platform_tenant_id – Mandanten-ID für Plattform-API-Anfragen.
  • azure_openai_endpoint – Azure OpenAI-Endpunkt. Nur erforderlich, wenn Sie die automatische Berichterstellung wünschen (die meisten Agenten können ihr eigenes Berichts-SQL generieren, daher nur aktivieren, wenn nötig).
  • azure_openai_deployment – Bereitstellungsname für Azure OpenAI.
  • auth_mode – Authentifizierungsmodus (none oder oauth). OAuth funktioniert offensichtlich nicht mit stdio-Transport.
  • transport_mode – stdio für Befehlszeile oder sse für HTTP/SSE.
  • chatgpt_disable_scope_checks – Bereichsvalidierung bei ChatGPT-Anfragen überspringen. Nur aktivieren, wenn Probleme bei der Verbindung mit ChatGPT auftreten.
  • port – Port für den HTTP-Server im sse-Modus.
  • debug – Ausführliche Protokollierung aktivieren.
  • external_hostname – Hostname, der bei der Erstellung von OAuth-Token-Zielgruppen verwendet wird. Kein HTTP(S)-Präfix oder Port hinzufügen.
  • ssl_keyfile – Pfad zum SSL-Schlüssel für HTTPS. (z. B. privkey.pem)
  • ssl_certfile – Pfad zum SSL-Zertifikat für HTTPS. (z. B. fullchain.pem)
  • registration_psk – Vorab vereinbarter Schlüssel, der zur Registrierung von OAuth-Clients erforderlich ist. Sie müssen dieses Geheimnis in Ihrem Browser eingeben, um OAuth-Verbindungen zu genehmigen.
  • jwt_key_path – Speicherort des RSA-Schlüsselpaars, das für OAuth-Token verwendet wird. Standard: .cache/jwt.json. Wird automatisch generiert, falls nicht vorhanden.
  • oauth_db_path – Pfad zur OAuth-Datenbankdatei. Standard: .cache/oauth.db. Wird automatisch generiert, falls nicht vorhanden.
  • enabled_tools – Liste der zu registrierenden Werkzeugnamen. Eine leere Liste aktiviert alle Werkzeuge. Es wird dringend empfohlen, Werkzeuge selektiv pro Anwendungsfall oder Aufgabe zu aktivieren. Siehe Ordner docs/ für einige Beispiele.
  • search_objects – Erlaubte Objekttypen für das Werkzeug search. Standard: ["secret"], kann aber user, folder, group und role enthalten.
  • fetch_objects – Erlaubte Objekttypen für das Werkzeug fetch. Standard: ["secret"], kann aber dieselben Werte wie search_objects enthalten.

Server ausführen

Starten Sie den Server lokal im Entwicklungsmodus:

python server.py

Beim Start fordert der Server ein Bearer-Token an und speichert es für nachfolgende API-Anfragen. Dieses Projekt wird erweitert, um die Integration mit der Secret-Server-API zu vertiefen.

MCP-Werkzeuge

Der Server stellt mehrere MCP-Werkzeuge für die Interaktion mit Secret Server bereit:

  • run_report(sql_query, report_name=None) – einen temporären Bericht erstellen und ausführen.
  • ai_generate_and_run_report(description) – SQL mit Azure OpenAI generieren und ausführen. Erfordert die Azure OpenAI-Variablen.
  • list_example_reports() – Beispielabfragen und Tabelleninformationen auflisten.
  • get_secret(id, summary=False) – ein Secret oder Zusammenfassungsdetails abrufen.
  • get_folder(id) – Ordnermetadaten und untergeordnete Elemente abrufen.
  • search_users(query) – aktive Benutzer suchen.
  • search_secrets(query, lookup=False) – Secrets suchen oder nachschlagen.
  • search_folders(query, lookup=False) – Ordner suchen oder nachschlagen.
  • get_secret_environment_variable(secret_id, environment) – ein Skript zum Abrufen von Secret-Anmeldeinformationen in der angegebenen Shell ausgeben.
  • check_secret_template(template_id) – Details zur Secret-Vorlage abrufen.
  • check_secret_template_field(template_id, field_id) – prüfen, ob eine Vorlage ein Feld enthält.
  • get_secret_template_field(field_id) – Details zu einem bestimmten Secret-Vorlagenfeld anhand der ID abrufen.
  • handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) – eine Zugriffsanforderung genehmigen oder ablehnen.
  • get_pending_access_requests() – ausstehende Zugriffsanforderungen auflisten.
  • get_inbox_messages(read_status_filter=None, take=20, skip=0) – Posteingangsnachrichten abrufen.
  • mark_inbox_messages_read(message_ids, read=True) – Nachrichten als gelesen oder ungelesen markieren.
  • user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) – einheitliche Benutzeroperationen. action akzeptiert get, create, update, delete, list_sessions, reset_2fa, reset_password oder lock_out. Geben Sie user_id an, wenn erforderlich, und übergeben Sie den Anforderungstext über data für Erstellungs-, Aktualisierungs- und Passwort-Zurücksetzungsaktionen. Beispiel: user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
  • role_management(action, role_id=None, data=None, params=None) – Rollen verwalten. action kann list, get, create oder update sein. Übergeben Sie optionale Abfrageparameter mit params beim Auflisten von Rollen. Beispiel: role_management("update", role_id=3, data={"name": "New Role"}).
  • user_role_management(action, user_id, role_ids=None) – Rollen einem Benutzer zuweisen oder entziehen. action ist get, add oder remove und role_ids ist eine Liste von Rollen-IDs für Hinzufügen-/Entfernen-Operationen.
  • group_management(action, group_id=None, data=None, params=None) – Gruppen verwalten. action kann get, list, create oder delete sein. Geben Sie group_id für Abrufen/Löschen und data beim Erstellen einer Gruppe an.
  • folder_management(action, folder_id=None, data=None, params=None) – Ordner verwalten. action kann get, list, create, update oder delete sein. Geben Sie folder_id für Abrufen, Aktualisieren oder Löschen an und übergeben Sie data beim Erstellen oder Aktualisieren eines Ordners.
  • user_group_management(action, user_id, group_ids=None) – Gruppenmitgliedschaft für einen Benutzer verwalten. action ist get, add oder remove. Übergeben Sie eine Liste von group_ids beim Hinzufügen oder Entfernen der Mitgliedschaft.
  • group_role_management(action, group_id, role_ids=None) – Rollen für eine Gruppe steuern. Verwenden Sie die Aktionen list, add oder remove. Geben Sie role_ids beim Hinzufügen oder Entfernen an.
  • health_check() – den Secret-Server-Health-Check-Endpunkt abfragen und den aktuellen Dienststatus zurückgeben.

Verwenden Sie die oben beschriebenen Serverkonfigurationsvariablen zur Authentifizierung. Das KI-Werkzeug wird automatisch deaktiviert, wenn die Azure OpenAI-Variablen fehlen. Nur die in config.json aufgeführten Werkzeugnamen werden registriert. Eine leere Liste aktiviert jedes Werkzeug.

Anwendungsfälle

Die Dokumentation behandelt mehrere Workflows zum Verbinden von Werkzeugen mit dem Server:

Docker-Schnellstart

Eine Dockerfile wird bereitgestellt, um den MCP-Server ohne lokale Installation von Python-Abhängigkeiten auszuführen.

  1. Image erstellen:
docker build -t dev.local/delinea-mcp:latest .
  1. Server ausführen (übergeben Sie Ihre Anmeldeinformationen über Umgebungsvariablen):
docker run --rm -p 8000:8000 \
  -e DELINEA_PASSWORD=<password> \
  -e PLATFORM_SERVICE_PASSWORD=<password> \
  -e DELINEA_DEBUG=1 \
  -e AZURE_OPENAI_KEY=<your-key-or-appropriate-token> \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v mcp-data:/app/data \
  dev.local/delinea-mcp:latest

Füllen Sie config.json mit Ihren Benutzernamen und URLs wie oben gezeigt.

Der Container speichert oauth.db und jwt.json in /app/data. Binden Sie ein Volume ein (oben als mcp-data dargestellt), damit diese Dateien und etwaige HTTPS-Zertifikate zwischen den Ausführungen erhalten bleiben.

Ersetzen Sie <https://your-secret-server/SecretServer> durch die Basis-URL Ihrer Secret-Server-Instanz, um Verbindungsfehler zu vermeiden.

Der Server startet standardmäßig auf Port 8000 unter Verwendung von python server.py. Setzen Sie die Option port in config.json, um den Standard zu überschreiben. Aktivieren Sie debug: true, um alle eingehenden HTTP-Anfragen zu protokollieren.

Beispielskripte

Das Skript manual_secret_request.py zeigt, wie ein OAuth-Token für eine bestimmte Secret-ID abgerufen wird:

python scripts/manual_secret_request.py <Secret_ID>

Setzen Sie die Umgebungsvariablen SECRET_USERNAME_<id> und SECRET_PASSWORD_<id> für das Secret, bevor Sie das Skript ausführen. Setzen Sie optional DELINEA_BASE_URL, um den Standard https://localhost/SecretServer zu überschreiben.

Tests ausführen

Führen Sie die Unit-Tests mit Abdeckung aus, um 100 % Codeabdeckung sicherzustellen:

pip install -r requirements.txt
coverage run -m pytest -q
coverage report --omit "tests/*"

Live-Tests

Einige Integrationstests erfordern gültige Anmeldeinformationen. Setzen Sie die folgenden Umgebungsvariablen und das optionale LIVE_SECRET_ID, bevor Sie die Suite ausführen:

export DELINEA_PASSWORD=<password>
# Optional secret used by tests/test_live.py
export LIVE_SECRET_ID=<id>
export SECRET_USERNAME_<id>=<secret_username>
export SECRET_PASSWORD_<id>=<secret_password>

Wenn diese Variablen vorhanden sind, führen die Live-Tests echte API-Anfragen durch.

Produktionsbereitstellung

Abhängigkeiten sind in requirements.txt fixiert und Releases werden mit Semantic Versioning getaggt. Erstellen Sie das Docker-Image von einem getaggten Commit und stellen Sie es in Ihrer Produktionsumgebung bereit, wobei Sie die erforderlichen Umgebungsvariablen übergeben (DELINEA_USERNAME, DELINEA_PASSWORD, optional DELINEA_BASE_URL). Optionale Funktionen benötigen zusätzliche Variablen:

  • PLATFORM_SERVICE_PASSWORD zusammen mit PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT und PLATFORM_TENANT_ID aktiviert die Benutzerverwaltungswerkzeuge.
  • AZURE_OPENAI_KEY zusammen mit AZURE_OPENAI_ENDPOINT und AZURE_OPENAI_DEPLOYMENT aktiviert den KI-Berichterstellungshelfer.

Bei Ausführung mit OAuth- oder SSE-Transport müssen Sie möglicherweise registration_psk bereitstellen und einen external_hostname oder HTTPS-Zertifikatsdateien konfigurieren.

Repository-Struktur

  • delinea_mcp/ – Paket mit MCP-Werkzeugen.
  • server.py – schlanker Einstiegspunkt, der alles beim MCP-Server registriert.
  • docs/ – Projektdokumentation und die generierte delinea-secret-server-openapi-spec.json.
  • scripts/ – Hilfsbeispiele, einschließlich manual_secret_request.py.

Sicherheitshinweise

Die enthaltenen OAuth-Endpunkte sind für Entwicklung und Tests vorgesehen. Die Route /oauth/authorize akzeptiert jedes redirect_uri und leitet den Benutzer ohne Validierung weiter. Bereitstellungen müssen diesen Wert auf genehmigte Callback-URLs beschränken; andernfalls könnten Angreifer eine bösartige URL angeben und Autorisierungscodes abfangen. Siehe Open Redirection für Hintergrundinformationen.

Versionshinweise

Siehe docs/release_notes.md für eine Zusammenfassung der neuesten Funktionen und Roadmap-Elemente.

Roadmap

  1. Passthrough-Authentifizierung
  2. Streaming-HTTP-Transportunterstützung
  3. Werkzeugabdeckung auf der Delinea-Plattform erweitern und andere Delinea-Produkte hinzufügen

Mitwirken

Beiträge sind willkommen! Bitte eröffnen Sie Issues oder Pull Requests für Verbesserungen. Jeder neue Code sollte Unit-Tests enthalten und die bestehende Testsuite bestehen.

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.