Files

77 lines
5.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.