77 lines
5.4 KiB
Markdown
77 lines
5.4 KiB
Markdown
# 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.
|