# ServiceNow Story MCP – Python-Client Ein Kommandozeilen-Client für die vier ServiceNow-Story-Tools. Voraussetzung: Python 3.10 oder neuer und Microsoft Edge für den ersten OAuth-Login. Die OAuth-Registrierung muss als Redirect `http://127.0.0.1:8765/oauth/callback` enthalten; Browser und Client müssen auf demselben Rechner laufen. ## Installation ```bash python3 -m venv .venv source .venv/bin/activate python -m pip install -r requirements.txt ``` Unter Windows: `py -m venv .venv` und `.venv\Scripts\activate`. Unter Debian/Ubuntu kann für `venv` das entsprechende Paket `python3-venv` fehlen. Alternativ lässt sich ohne virtuelle Umgebung lokal installieren: ```bash python3 -m pip install --target .python-deps -r requirements.txt PYTHONPATH=.python-deps python3 story_client.py tools ``` ## Anmelden und verwenden Die Datei `clientsecret` im Arbeitsverzeichnis enthält das Client-Secret. Alternativ `OAUTH_CLIENT_SECRET_FILE` auf die Datei oder `OAUTH_CLIENT_SECRET` auf den Wert setzen. `chmod 600 clientsecret` schränkt unter Linux den Zugriff ein. Geheimnisse und Tokens nicht einchecken. ```bash python story_client.py tools python story_client.py list '{"limit":"5"}' python story_client.py list '{"query":"active=true^priority=1"}' python story_client.py get SYS_ID python story_client.py create '{"short_description":"MCP Test Story","type":"Development","product":"PRODUCT_SYS_ID"}' python story_client.py update SYS_ID '{"story_points":"3"}' ``` Bei Bedarf öffnet der Client Microsoft Edge für die Anmeldung und empfängt den OAuth-Code lokal. Er sucht Edge in den üblichen Installationspfaden bzw. im PATH. Mit `EDGE_PATH` kann der vollständige Programmpfad angegeben werden. Ein anderer Browser wird nicht automatisch verwendet. Port 8765 muss frei sein. Der Client speichert Tokens in `.tokens.json` mit Dateirechten 0600 auf Unix und erneuert sie automatisch; die vorhandene Token-Datei des JavaScript-Clients kann weiterverwendet werden. Ein widerrufener oder abgelaufener Refresh-Token führt zu einer erneuten Edge-Anmeldung. Um ein anderes Konto zu verwenden, eine andere Datei mit `OAUTH_TOKEN_FILE` wählen. `create` und `update` verpacken die Felder automatisch in `request_body`, entsprechend dem vom Server gemeldeten Schema. Für direkte MCP-Aufrufe wird das vollständige Tool-Argument übergeben, zum Beispiel: ```bash python story_client.py call rm_story_create '{"request_body":{"short_description":"MCP Test Story","type":"Development","product":"PRODUCT_SYS_ID"}}' ``` Die Ausgabe ist die MCP-Antwort als JSON. Ein Toolfehler setzt einen Exit-Code ungleich null. `tools` prüft die vier erwarteten Tool-Namen. Create und Update ändern echte ServiceNow-Daten; für Referenzfelder sys_id verwenden. Es gibt keinen Delete-Befehl. Optionen: `--transport sse` für einen SSE-Server (ggf. `MCP_URL` ändern), `MCP_URL`, `OAUTH_CLIENT_ID`, `OAUTH_REDIRECT_URI` und `OAUTH_TOKEN_FILE`. Eine geänderte Callback-URL muss exakt auf dem Server registriert sein und HTTP auf `127.0.0.1` mit festem Port verwenden. OAuth-Endpunkte werden per Discovery ermittelt; falls das fehlschlägt, werden die bekannten ServiceNow-Endpunkte verwendet. Tests: `python -m unittest discover -s tests -v`. ## Echter Integrationstest ```bash python scripts/integration_test.py --product PRODUCT_SYS_ID ``` Der Test verwendet die echte ServiceNow-Instanz, erneuert das gespeicherte Token und prüft Tool-Liste, Lesen, Filter, Einzelabruf und Negativfälle. Danach versucht er, eine mit `MCP Integrationstest` und Zeitstempel gekennzeichnete Story zu erstellen, zu lesen, `story_points` zu ändern und die Änderung erneut zu lesen. Eine erfolgreich angelegte Test-Story bleibt bestehen, da kein Delete-Tool angeboten wird. Der Test gibt ihre sys_id aus. Bei einem Fehler endet er mit Exit-Code 1 und überspringt abhängige Schritte. Auf dieser Instanz verlangt eine Data Policy beim Anlegen zusätzlich `product`: Die Produkt-sys_id muss ausdrücklich angegeben werden. Der Integrationstest wurde inklusive Create, Lesen, Update und erneutem Lesen erfolgreich ausgeführt. Die benutzte Produkt-sys_id muss zur vorgesehenen Test-Story passen. ## Lokaler MCP-Proxy für Codex Den Proxy im Projektverzeichnis starten und während der Nutzung laufen lassen: ```bash PYTHONPATH=.python-deps python3 mcp_proxy.py # oder mit aktivierter virtueller Umgebung: python mcp_proxy.py ``` Er verwendet dieselben OAuth-Einstellungen, das Secret und die Token-Datei wie der Kommandozeilen-Client. Falls ein Login nötig ist, muss Microsoft Edge auf dem Rechner verfügbar sein; `EDGE_PATH` kann seinen Pfad angeben. Den Proxy mit `Strg+C` beenden. Ein anderer lokaler Port ist über `--port` wählbar. In der MCP-Konfiguration von Codex: - Name: `ServiceNow Stories Proxy` - Typ: `Streamable HTTP` - URL: `http://127.0.0.1:8766/mcp` - Bearer-Token-Umgebungsvariable und Header: leer lassen. Die vier Tool-Schemas, Argumente und Ergebnisse inklusive Fehler werden an den ServiceNow-Server durchgereicht. Der Proxy bindet ausschließlich an `127.0.0.1` und benötigt lokal selbst kein Token. **Andere Prozesse auf demselben Rechner können den Proxy ebenfalls verwenden und damit unter deiner ServiceNow-Identität Stories lesen und ändern, solange er läuft.** Deshalb nur auf einem vertrauenswürdigen Rechner ausführen und nach Gebrauch beenden. Der Proxy ist für lokale Codex-Prozesse gedacht; eine in der Cloud laufende ChatGPT-Sitzung erreicht `127.0.0.1` auf deinem Rechner nicht direkt.