workbench-mcp

Ein lokaler Python-MCP-Server für interaktive PostgreSQL-Datenexploration, API-Integration und Automatisierung auf Fedora/Linux-Systemen.

Übersicht

Version 1 enthält:

• Einrichtung einer Python-virtuellen Umgebung für Fedora/Linux-Systeme

• PostgreSQL 18-Konnektivität, konfiguriert über eine .env-Datei

• MCP-Tools für:

  • Erkennung von Tabellen, Spalten und Schemastrukturen

  • Ausführung von schreibgeschützten Abfrage-Vorschauen

  • Ausführung von geschützten SQL-Batches mit Unterstützung für temporäre Tabellen

  • Aufruf von gespeicherten PostgreSQL-Funktionen und -Prozeduren

  • Zugriff auf externe APIs über vollständige URL-Anfragen

  • Ausführung von Bash-Skripten, die im PATH verfügbar sind

• Durchgesetzte Sicherheit: Dauerhafte Schema- und Datenänderungen sind blockiert

• Sitzungsbezogene Workflows für temporäre Tabellen innerhalb von SQL-Batches werden unterstützt

Fedora / Linux-Einrichtung

Beginnen Sie mit der Installation der erforderlichen Systempakete:

sudo dnf install -y python3 python3-pip nodejs npm

Python 3.12 oder neuer ist erforderlich. Verwenden Sie pyenv oder Ähnliches, wenn Sie mehrere Versionen verwalten.

Einrichtung der virtuellen Umgebung

Erstellen und aktivieren Sie im Projektstammverzeichnis eine virtuelle Python-Umgebung:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .

Umgebungsvariablen

Kopieren Sie die Beispielkonfiguration und tragen Sie die PostgreSQL-Verbindungsdetails ein:

cp .env.example .env

Erforderlich:

• DB_HOST — Hostname des PostgreSQL-Servers

• DB_NAME — Datenbankname

• DB_USER — Datenbank-Benutzername

• DB_PASSWORD — Datenbank-Passwort

Optional (Optimierung):

• DB_PORT — Verbindungsport (Standard: 5432)

• DB_SSLMODE — SSL-Modus (Standard: prefer)

• DB_APPLICATION_NAME — Anwendungsbezeichner

• DB_QUERY_TIMEOUT_SECONDS — Abfrage-Timeout (Standard: 30)

• DB_MAX_ROWS — Maximale Zeilenanzahl pro Ergebnismenge (Standard: 100)

• DB_MAX_RESULT_SETS — Maximale Ergebnismengen pro Batch (Standard: 5)

• DB_OBJECT_PREVIEW_CHARS — Maximale Länge der Definitionsvorschau (Standard: 4000)

Beispiel für die lokale Entwicklung:

DB_HOST=localhost
DB_PORT=5432
DB_NAME=app_dev
DB_USER=app_user
DB_PASSWORD=your-secure-password
DB_SSLMODE=prefer

Optional: HTTP-Anfrage-Optimierung

Das HTTP-Tool verwendet pro Aufruf eine vollständige URL und erfordert keine API-Profilkonfiguration.

Unterstützte Umgebungseinstellungen:

Beispiel für einen Aufruf:

url: https://localhost:44331/api/breakouts/filter/1871161/dd-table?ParameterSetId=231022
method: GET

Für authentifizierte Aufrufe setzen Sie API_BEARER_TOKEN in der .env (oder Prozess-Umgebung). HTTP-Tools verwenden es automatisch, sofern der Aufrufer kein eigenes jwt_token übergibt.

Umgang mit Autorisierung

HTTP-Tools unterstützen zwei Autorisierungsquellen:

1. jwt_token, das im Tool-Aufruf übergeben wird

2. API_BEARER_TOKEN aus der .env oder der Prozessumgebung

Priorität

• Wenn ein jwt_token bereitgestellt wird, wird dieses Token als Authorization: Bearer <jwt_token> weitergeleitet.

• Wenn jwt_token weggelassen oder leer ist, greift der Server auf API_BEARER_TOKEN zurück.

• Wenn kein Wert vorhanden ist, wird die Anfrage ohne Authorization-Header gesendet.

Wichtige Regel für Agenten

Platzieren Sie das Bearer-Token nicht innerhalb von headers.Authorization. Der MCP-Server entfernt Authorization aus den headers und akzeptiert Autorisierung nur über das dedizierte jwt_token-Feld.

Dies verhindert versehentliche Header-Kollisionen und macht die Token-Priorität explizit.

Beispiel: Verwendung des Standard-Server-Tokens

{
  "url": "https://localhost:5001/api/v1/sales/my-sales"
}

Beispiel: Weiterleitung des eigenen Tokens des Aufrufers

{
  "url": "https://localhost:5001/api/v1/sales/my-sales",
  "jwt_token": "eyJhbGciOi..."
}

Beispiel: Weiterleitung des Aufrufer-Tokens mit zusätzlichen Headern

{
  "url": "https://localhost:5001/api/v1/sales/my-sales",
  "jwt_token": "eyJhbGciOi...",
  "headers": {
    "Accept": "application/json"
  }
}

Das gleiche jwt_token-Feld ist für http_get, http_head, http_post, http_put, http_patch und http_delete verfügbar.

Sitzungs-Auth

Anstatt pro Aufruf ein jwt_token zu übergeben, können Agenten einmalig ein sitzungsbezogenes JWT erwerben, das automatisch für jeden HTTP-Tool-Aufruf während der restlichen Sitzung verwendet wird.

Funktionsweise

1. Ein Agent ruft auth_start_session mit der E-Mail-Adresse des Zielbenutzers auf.

2. Der MCP-Server tauscht das gemeinsame Geheimnis (Shared Secret) + E-Mail gegen ein sitzungsbezogenes JWT vom Backend-Broker aus (POST /api/v1/mcp/exchange).

3. Das Token wird im Prozessspeicher zwischengespeichert.

4. Jeder nachfolgende HTTP-Tool-Aufruf, der jwt_token weglässt, verwendet automatisch das Sitzungstoken.

5. Der Agent kann die Sitzung mit auth_status überprüfen, mit auth_switch_user den Benutzer wechseln oder sie mit auth_clear_session löschen.

Token-Priorität (höchste → niedrigste)

Erforderliche Umgebungsvariablen

Sitzungs-Auth-Tools

Siehe docs/SESSION_AUTH.md für die vollständige Referenz für Agenten.

Lokal ausführen

Nachdem die virtuelle Umgebung aktiviert und die Abhängigkeiten installiert wurden, starten Sie den MCP-Server mit einem der folgenden Befehle:

workbench-mcp

python -m workbench_mcp.server

MCP Inspector

Für die lokale MCP-Entwicklung und das Debugging bietet der MCP Inspector eine schnelle manuelle Testschleife:

npx @modelcontextprotocol/inspector .venv/bin/python -m workbench_mcp.server

Um den MCP-Server unter debugpy für Breakpoint-Debugging im Inspector zu starten:

npx @modelcontextprotocol/inspector .venv/bin/python -m debugpy --listen 127.0.0.1:5678 -m workbench_mcp.server

Öffnen Sie nach dem Start die Inspector-Benutzeroberfläche, verbinden Sie sich über STDIO und testen Sie Tools wie health, describe_object und exec_proc_preview.

Breakpoints (debugpy): Verwenden Sie Port 5678 für den Debugger, nicht 6274 (6274 ist nur die Inspector-Web-UI). Der schrittweise Workflow und "was vorher falsch war" finden Sie in docs/DEBUG_MCP.md.

VS Code-Einrichtung

Um den lokalen MCP-Server in VS Code zu registrieren, fügen Sie einen Eintrag zur MCP-Konfigurationsdatei des Arbeitsbereichs hinzu:

• Arbeitsbereichsdatei: .vscode/mcp.json

Beispielkonfiguration:

{
  "servers": {
    "workbench-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/workbench-mcp/.venv/bin/python",
      "args": ["-m", "workbench_mcp.server"]
    }
  }
}

Ersetzen Sie den Befehlspfad durch den lokalen Repository-Pfad zu Ihrer virtuellen Python-Umgebung.

Geheimnisse und Umgebungswerte

Sie können Umgebungswerte an zwei Stellen angeben:

1. workbench-mcp/.env

2. env in .vscode/mcp.json — VS Code injiziert diese in den MCP-Serverprozess.

Priorität: Die Prozessumgebung (einschließlich .vscode/mcp.json → env) überschreibt Werte aus .env für denselben Schlüssel.

Beispiel mit HTTP-Optimierung in VS Code:

{
  "servers": {
    "workbench-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/workbench-mcp/.venv/bin/python",
      "args": ["-m", "workbench_mcp.server"],
      "env": {
        "API_TIMEOUT_SECONDS": "30",
        "API_MAX_RESPONSE_BYTES": "2097152",
        "API_VERIFY_SSL": "false"
      }
    }
  }
}

Übertragen Sie keine echten Token in das Repository. Bevorzugen Sie eine lokale Arbeitsbereichskonfiguration oder lassen Sie env weg und verwenden Sie .env (welche nicht in Git eingecheckt werden sollte).

Wenn bereits andere MCP-Server konfiguriert sind, fügen Sie workbench-mcp innerhalb des bestehenden servers-Objekts hinzu, anstatt die gesamte Datei zu ersetzen.

Nach dem Speichern von .vscode/mcp.json laden Sie VS Code neu oder aktualisieren Sie die MCP-Server, damit der neue Server erkannt wird. Führen Sie nach dem Laden des Servers das health-Tool aus, bevor Sie Datenbankprozeduren testen.

Erste Tools

• health

• describe_object

• list_tables_and_columns

• preview_query

• execute_readonly_sql

• exec_proc_preview

• exec_function_preview

• insert_row

• insert_rows

• http_get

• http_head

• http_post

• http_put

• http_patch

• http_delete

• auth_start_session

• auth_switch_user

• auth_status

• auth_clear_session

• execute_path_bash_script (Skriptname wird über PATH aufgelöst)

Sicherheitsmodell

• Dauerhafte DDL- und DML-Befehle sind in Ad-hoc-PostgreSQL-Batches blockiert

• Nur Schreibvorgänge in temporäre Tabellen sind erlaubt, und nur für temporäre Tabellen, die im aktuellen Batch erstellt wurden

• preview_query erlaubt nur SELECT-Anweisungen und CTE-basierte Lesezugriffe

• exec_proc_preview kann PostgreSQL-Prozeduren und -Funktionen ausführen; überladene Routinen sollten mit einer Signatur wie public.my_func(integer, text) übergeben werden

• execute_path_bash_script akzeptiert nur Skriptnamen (keine Pfade), löst diese über PATH auf und führt sie über bash aus

Empfohlene erste Prüfungen

Nachdem .env konfiguriert ist, ist ein typischer Validierungsablauf:

1. Beschreiben Sie die Funktion, Prozedur, Tabelle oder Ansicht, die inspiziert werden soll.

2. Zeigen Sie die unterstützende Konfiguration oder Referenzdaten an, die zum Verständnis dieses Objekts erforderlich sind.

3. Führen Sie exec_proc_preview, preview_query oder execute_readonly_sql mit bekannten Eingaben aus.

4. Vergleichen Sie die zurückgegebene Form mit dem Szenario, das evaluiert wird (Feature, Untersuchung oder Debugging).

Beispiel für Funktionsausführung

Verwenden Sie für positionelle PostgreSQL-Funktionsaufrufe exec_function_preview. Übergeben Sie PostgreSQL-Arrays als normale JSON-Listen.

Beispiel-SQL-Ziel:

select * from sales."Fn_GetSalesChamps"(2, 2025, array[1,2,5,6,7,8,9,10,11,12,15,16,18,19], 5);

Äquivalente MCP-Tool-Eingabe:

{
  "function_name": "sales.\"Fn_GetSalesChamps\"",
  "parameters": [2, 2025, [1, 2, 5, 6, 7, 8, 9, 10, 11, 12, 15, 16, 18, 19], 5]
}

Beispiele für Einfügungen

Einfügen einer einzelnen Zeile:

{
  "table_name": "sales.orders",
  "row": {
    "customer_id": 10,
    "status": "new"
  },
  "returning_columns": ["order_id"]
}

Batch-Einfügung:

{
  "table_name": "sales.orders",
  "rows": [
    {"customer_id": 10, "status": "new"},
    {"customer_id": 11, "status": "pending"}
  ]
}