Add ServiceNow MCP client and local proxy

This commit is contained in:
2026-10-30 11:44:24 +01:00
commit 5eba2ecb36
12 changed files with 1991 additions and 0 deletions
+10
View File
@@ -0,0 +1,10 @@
node_modules/
.venv/
clientsecret
.tokens.json
.tokens.json.*
.env
.python-deps/
__pycache__/
*.pyc
+76
View File
@@ -0,0 +1,76 @@
# 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.
+31
View File
@@ -0,0 +1,31 @@
import { createServer } from 'node:http';
// Bind only to loopback and validate state before returning the code.
export async function startCallback(redirectUri, expectedState, timeoutMs = 180000) {
const uri = new URL(redirectUri);
if (uri.protocol !== 'http:' || uri.hostname !== '127.0.0.1' || !uri.port || uri.search || uri.hash) {
throw new Error('Lokaler Callback muss eine HTTP-URL auf 127.0.0.1 mit festem Port ohne Query oder Fragment sein.');
}
let settle;
const result = new Promise((resolve, reject) => { settle = { resolve, reject }; });
const server = createServer((req, res) => {
const url = new URL(req.url, uri);
if (req.method !== 'GET' || url.pathname !== uri.pathname) { res.writeHead(404).end(); return; }
res.setHeader('Cache-Control', 'no-store');
res.setHeader('Content-Type', 'text/plain; charset=utf-8');
if (url.searchParams.get('state') !== expectedState) { res.writeHead(400).end('Ungueltiger OAuth-State.'); return; }
if (url.searchParams.has('error')) {
res.writeHead(400).end('Anmeldung abgelehnt. Sie koennen dieses Fenster schliessen.');
settle.reject(new Error(`Autorisierung abgelehnt: ${url.searchParams.get('error')}`));
} else if (!url.searchParams.get('code')) {
res.writeHead(400).end('Autorisierungscode fehlt.');
return;
} else {
res.writeHead(200).end('Anmeldung abgeschlossen. Sie koennen dieses Fenster schliessen.');
settle.resolve(url.searchParams.get('code'));
}
});
await new Promise((resolve, reject) => { server.once('error', reject); server.listen(Number(uri.port), '127.0.0.1', resolve); });
const timer = setTimeout(() => settle.reject(new Error('Zeitlimit fuer OAuth-Login abgelaufen.')), timeoutMs);
return { result, close: () => { clearTimeout(timer); server.close(); } };
}
+151
View File
@@ -0,0 +1,151 @@
#!/usr/bin/env node
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
import { randomBytes, createHash } from 'node:crypto';
import { readFile, writeFile, rename, chmod } from 'node:fs/promises';
import { createInterface } from 'node:readline/promises';
import { stdin, stderr } from 'node:process';
import { spawn } from 'node:child_process';
import { resolve } from 'node:path';
import { startCallback } from './callback.js';
const origin = 'https://enercondev.service-now.com';
const endpoint = process.env.MCP_URL || `${origin}/sncapps/mcp-server/mcp/x_engm3_mcp_stor_0_mcp_story_bridge`;
const clientId = process.env.OAUTH_CLIENT_ID || 'bde15764d0cb43658c41d31797c28b0e';
const redirectUri = process.env.OAUTH_REDIRECT_URI || 'http://127.0.0.1:8765/oauth/callback';
const cache = resolve(process.env.OAUTH_TOKEN_FILE || '.tokens.json');
const expected = ['rm_story_list', 'rm_story_get', 'rm_story_create', 'rm_story_update'];
const fallback = { authorization_endpoint: `${origin}/oauth_auth.do`, token_endpoint: `${origin}/oauth_token.do` };
let tokens, tokenPromise, metadata;
async function json(url) {
const response = await fetch(url, { signal: AbortSignal.timeout(8000), redirect: 'error' });
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return response.json();
}
async function discover() {
const u = new URL(endpoint);
const paths = [`${u.origin}/.well-known/oauth-protected-resource${u.pathname}`, `${u.origin}/.well-known/oauth-protected-resource`];
for (const url of paths) {
try {
const resource = await json(url);
if (resource.resource && resource.resource.replace(/\/$/, '') !== endpoint.replace(/\/$/, '')) continue;
for (const issuer of resource.authorization_servers || []) {
const i = new URL(issuer);
// Do not send a confidential client secret to a different host based on discovery alone.
if (i.origin !== origin) continue;
const as = await json(`${i.origin}/.well-known/oauth-authorization-server${i.pathname === '/' ? '' : i.pathname}`);
if (new URL(as.token_endpoint).origin !== origin || new URL(as.authorization_endpoint).origin !== origin) continue;
console.error('OAuth-Discovery erfolgreich.');
return as;
}
} catch { /* try the next route */ }
}
console.error('OAuth-Discovery nicht verfügbar; konfigurierte ServiceNow-Endpunkte werden verwendet.');
return fallback;
}
async function saveTokens(value) {
const tmp = `${cache}.${process.pid}.tmp`;
await writeFile(tmp, JSON.stringify(value), { mode: 0o600 });
await chmod(tmp, 0o600);
await rename(tmp, cache);
}
async function exchange(params) {
const secret = process.env.OAUTH_CLIENT_SECRET || (await readFile(process.env.OAUTH_CLIENT_SECRET_FILE || 'clientsecret', 'utf8')).trim();
if (!secret) throw new Error('Client-Secret ist leer.');
const response = await fetch(metadata.token_endpoint, {
method: 'POST', redirect: 'error', headers: { 'content-type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({ ...params, client_id: clientId, client_secret: secret })
});
const result = await response.json().catch(() => ({}));
if (!response.ok || !result.access_token) throw new Error(`Token-Endpunkt: HTTP ${response.status}, ${result.error || 'kein access_token'}`);
const lifetime = Number(result.expires_in);
tokens = { ...result, refresh_token: result.refresh_token || (params.grant_type === 'refresh_token' ? tokens?.refresh_token : undefined), expires_at: Date.now() + (Number.isFinite(lifetime) && lifetime > 0 ? lifetime : 1800) * 1000 };
await saveTokens(tokens);
}
async function login() {
const verifier = randomBytes(32).toString('base64url');
const state = randomBytes(32).toString('base64url');
const challenge = createHash('sha256').update(verifier).digest('base64url');
const url = new URL(metadata.authorization_endpoint);
url.search = new URLSearchParams({ response_type: 'code', client_id: clientId, redirect_uri: redirectUri, state, code_challenge: challenge, code_challenge_method: 'S256' }).toString();
const callbackUri = new URL(redirectUri);
const local = callbackUri.protocol === 'http:' && callbackUri.hostname === '127.0.0.1';
const listener = local ? await startCallback(redirectUri, state) : null;
try {
console.error(`Im Browser anmelden:\n${url}`);
if (process.env.NO_BROWSER !== '1') { const p = spawn('xdg-open', [url.toString()], { stdio: 'ignore', detached: true }); p.on('error', () => {}); p.unref(); }
let code;
if (listener) {
console.error('Warte auf den lokalen OAuth-Callback (maximal 3 Minuten).');
code = await listener.result;
} else {
console.error('Anschließend die vollständige Weiterleitungs-URL hier einfügen.');
if (!stdin.isTTY) throw new Error('Interaktiver Login benötigt ein Terminal.');
const rl = createInterface({ input: stdin, output: stderr });
let reply;
try { reply = await rl.question('Weiterleitungs-URL: '); } finally { rl.close(); }
const callback = new URL(reply.trim());
if (callback.origin !== callbackUri.origin || callback.pathname !== callbackUri.pathname) throw new Error('Weiterleitungs-URL stimmt nicht mit redirect_uri überein.');
if (callback.searchParams.get('state') !== state) throw new Error('OAuth-State stimmt nicht überein.');
if (callback.searchParams.has('error')) throw new Error(`Autorisierung abgelehnt: ${callback.searchParams.get('error')}`);
code = callback.searchParams.get('code');
if (!code) throw new Error('Kein Code in der Weiterleitungs-URL.');
}
await exchange({ grant_type: 'authorization_code', code, redirect_uri: redirectUri, code_verifier: verifier });
} finally { listener?.close(); }
}
async function ensureToken(force = false) {
if (tokenPromise) return tokenPromise;
tokenPromise = (async () => {
if (!force && tokens?.access_token && tokens.expires_at > Date.now() + 60000) return;
if (tokens?.refresh_token) {
try { await exchange({ grant_type: 'refresh_token', refresh_token: tokens.refresh_token }); return; }
catch (e) { console.error(`Refresh fehlgeschlagen: ${e.message}. Erneuter Login erforderlich.`); }
}
await login();
})();
try { await tokenPromise; } finally { tokenPromise = undefined; }
}
async function authenticatedFetch(input, init = {}) {
await ensureToken();
const send = () => { const headers = new Headers(init.headers); headers.set('Authorization', `Bearer ${tokens.access_token}`); return fetch(input, { ...init, headers, redirect: 'error' }); };
let response = await send();
if (response.status === 401) { await response.body?.cancel(); await ensureToken(true); response = await send(); }
return response;
}
async function main() {
const [command = 'tools', ...args] = process.argv.slice(2);
if (command === 'help' || command === '--help') { console.log('Aufruf: node client.js tools | list [JSON] | get SYS_ID | create JSON | update SYS_ID JSON | call TOOL JSON\nBeispiel: node client.js list \'{"limit":"5"}\''); return; }
const parse = (s) => { const o = JSON.parse(s || '{}'); if (!o || Array.isArray(o) || typeof o !== 'object') throw new Error('Argument muss ein JSON-Objekt sein.'); return o; };
let name, input;
if (command === 'list') { name = 'rm_story_list'; input = parse(args[0]); }
else if (command === 'get') { name = 'rm_story_get'; input = { sys_id: args[0] }; }
else if (command === 'create') { name = 'rm_story_create'; input = parse(args[0]); }
else if (command === 'update') { name = 'rm_story_update'; input = { ...parse(args[1]), sys_id: args[0] }; }
else if (command === 'call') { name = args[0]; input = parse(args[1]); if (!expected.includes(name)) throw new Error('Unbekanntes Tool.'); }
else if (command !== 'tools') throw new Error('Unbekannter Befehl. Siehe help.');
if ((command === 'get' || command === 'update') && !args[0]) throw new Error('sys_id fehlt.');
metadata = await discover();
try { tokens = JSON.parse(await readFile(cache, 'utf8')); } catch (e) { if (e.code !== 'ENOENT') throw new Error(`Token-Datei kann nicht gelesen werden: ${e.message}`); }
const client = new Client({ name: 'servicenow-story-client', version: '1.0.0' });
const Transport = process.env.MCP_TRANSPORT === 'sse' ? SSEClientTransport : StreamableHTTPClientTransport;
const transport = new Transport(new URL(endpoint), { fetch: authenticatedFetch });
try {
await client.connect(transport);
if (command === 'tools') {
const tools = []; let cursor;
do { const page = await client.listTools(cursor ? { cursor } : undefined); tools.push(...page.tools); cursor = page.nextCursor; } while (cursor);
console.log(JSON.stringify(tools, null, 2));
const names = tools.map(t => t.name);
if (names.length !== 4 || expected.some(n => !names.includes(n))) { console.error('Warnung: Tool-Liste entspricht nicht den vier erwarteten Tools.'); process.exitCode = 1; }
} else {
const result = await client.callTool({ name, arguments: input });
console.log(JSON.stringify(result, null, 2));
if (result.isError) process.exitCode = 1;
}
} finally { await client.close(); }
}
main().catch(error => { console.error(`Fehler: ${error.message}`); process.exitCode = 1; });
+82
View File
@@ -0,0 +1,82 @@
#!/usr/bin/env python3
"""Loopback-only MCP bridge to the OAuth-protected ServiceNow MCP server."""
import argparse
import contextlib
import logging
import sys
import httpx
import uvicorn
from mcp import ClientSession
from mcp.server.lowlevel import Server
from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
from mcp.server.transport_security import TransportSecuritySettings
from starlette.applications import Starlette
from starlette.routing import Mount
from story_client import EXPECTED, MCP_URL, OAuth
logger = logging.getLogger('servicenow-proxy')
server = Server('servicenow-story-proxy', version='1.0.0', instructions='Proxy to ServiceNow Scrum Story tools. Creating a story requires short_description, type, and a product sys_id on this instance.')
auth = None
@contextlib.asynccontextmanager
async def upstream():
from mcp.client.streamable_http import streamable_http_client
if auth is None: raise RuntimeError('Proxy wurde nicht initialisiert.')
async with httpx.AsyncClient(auth=auth, timeout=httpx.Timeout(30, read=300), follow_redirects=False) as http:
async with streamable_http_client(MCP_URL, http_client=http) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
yield session
@server.list_tools()
async def list_tools():
tools, cursor = [], None
async with upstream() as session:
while True:
page = await session.list_tools(cursor=cursor)
tools.extend(tool for tool in page.tools if tool.name in EXPECTED)
cursor = page.nextCursor
if not cursor: break
return tools
@server.call_tool(validate_input=False)
async def call_tool(name, arguments):
if name not in EXPECTED: raise ValueError('Unbekanntes oder nicht erlaubtes Tool.')
async with upstream() as session:
return await session.call_tool(name, arguments)
def make_app(port):
global auth
auth = OAuth()
manager = StreamableHTTPSessionManager(
app=server, json_response=True, stateless=True,
security_settings=TransportSecuritySettings(enable_dns_rebinding_protection=True,
allowed_hosts=[f'127.0.0.1:{port}', f'localhost:{port}'],
allowed_origins=[f'http://127.0.0.1:{port}', f'http://localhost:{port}']))
@contextlib.asynccontextmanager
async def lifespan(app):
try:
async with manager.run(): yield
finally:
await auth.close()
async def handle(scope, receive, send):
# A fixed local route; mounted ASGI app receives /mcp in the original path.
await manager.handle_request(scope, receive, send)
return Starlette(routes=[Mount('/mcp', app=handle)], lifespan=lifespan)
def main():
parser = argparse.ArgumentParser(description='Lokaler ServiceNow-MCP-Proxy (nur 127.0.0.1).')
parser.add_argument('--port', type=int, default=8766)
args = parser.parse_args()
if not 1 <= args.port <= 65535: parser.error('Port muss zwischen 1 und 65535 liegen.')
print(f'ServiceNow MCP Proxy: http://127.0.0.1:{args.port}/mcp', file=sys.stderr)
uvicorn.run(make_app(args.port), host='127.0.0.1', port=args.port, log_level='warning', access_log=False)
if __name__ == '__main__': main()
+1224
View File
File diff suppressed because it is too large Load Diff
+8
View File
@@ -0,0 +1,8 @@
{
"name": "servicenow-story-mcp-client",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": { "start": "node client.js", "test": "node --test" },
"dependencies": { "@modelcontextprotocol/sdk": "^1.32.2", "zod": "^4.6.7" }
}
+1
View File
@@ -0,0 +1 @@
mcp>=1.30,<2
+112
View File
@@ -0,0 +1,112 @@
#!/usr/bin/env python3
"""Opt-in live integration test. Creates a real story and leaves it in ServiceNow."""
import ast
import argparse
import asyncio
from datetime import datetime, timezone
import json
from pathlib import Path
import sys
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
from story_client import OAuth, MCP_URL, EXPECTED
def payload(result):
if result.structuredContent is not None: return result.structuredContent
for block in result.content:
text = getattr(block, 'text', None)
if text:
for parser in (json.loads, ast.literal_eval):
try: return parser(text)
except (ValueError, SyntaxError): pass
return text
return None
def unwrap(data):
while isinstance(data, dict) and set(data) == {'result'}:
data = data['result']
return data
def error_text(result):
return str(payload(result))
async def main(product):
failures = []
def check(label, ok, detail=''):
print(('OK' if ok else 'FEHLER') + ': ' + label + (f' – {detail}' if detail else ''), flush=True)
if not ok: failures.append(label)
auth = OAuth()
story_id = None
try:
await auth.ensure()
if auth.tokens.get('refresh_token'):
old = auth.tokens['access_token']
await auth.ensure(force=True, rejected_token=old)
check('Token-Refresh', bool(auth.tokens.get('access_token')))
else:
check('Token-Refresh', False, 'Kein Refresh-Token vorhanden')
async with httpx.AsyncClient(auth=auth, timeout=httpx.Timeout(30, read=300)) as http:
async with streamable_http_client(MCP_URL, http_client=http) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
tools, cursor = [], None
while True:
page = await session.list_tools(cursor=cursor)
tools.extend(t.name for t in page.tools)
cursor = page.nextCursor
if not cursor: break
check('tools/list: genau vier Tools, kein Delete', len(tools) == 4 and set(tools) == EXPECTED)
listed = await session.call_tool('rm_story_list', {'limit': '5'})
listing = unwrap(payload(listed))
rows = listing.get('result', []) if isinstance(listing, dict) else []
check('Stories lesen (limit=5)', not listed.isError and isinstance(rows, list) and len(rows) <= 5, f'{len(rows)} Treffer')
filtered = await session.call_tool('rm_story_list', {'query': 'active=true^priority=1', 'limit': '5'})
check('Stories filtern', not filtered.isError)
if rows and rows[0].get('sys_id'):
got = await session.call_tool('rm_story_get', {'sys_id': rows[0]['sys_id']})
check('Einzelne vorhandene Story lesen', not got.isError)
else: check('Einzelne vorhandene Story lesen', False, 'Keine sichtbare Story vorhanden')
missing = await session.call_tool('rm_story_create', {'request_body': {'short_description': 'MCP Negativtest', 'product': product}})
check('Create ohne type abgelehnt', bool(missing.isError) and ('400' in error_text(missing) or 'required' in error_text(missing).lower()))
absent = await session.call_tool('rm_story_get', {'sys_id': '00000000000000000000000000000000'})
check('Unbekannte Story abgelehnt (404)', bool(absent.isError) and '404' in error_text(absent), error_text(absent)[:200] if not absent.isError else '')
title = 'MCP Integrationstest ' + datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC')
created = await session.call_tool('rm_story_create', {'request_body': {'short_description': title, 'type': 'Development', 'product': product}})
body = unwrap(payload(created))
story_id = body.get('sys_id') if isinstance(body, dict) else None
check('Test-Story erstellen', not created.isError and bool(story_id), error_text(created)[:500] if created.isError else '')
if story_id:
print('Test-Story sys_id:', story_id, flush=True)
got = await session.call_tool('rm_story_get', {'sys_id': story_id})
read_story = unwrap(payload(got))
check('Test-Story lesen', not got.isError and isinstance(read_story, dict) and read_story.get('sys_id') == story_id)
updated = await session.call_tool('rm_story_update', {'sys_id': story_id, 'request_body': {'story_points': '3'}})
update_body = unwrap(payload(updated))
fields = update_body.get('updated_fields', []) if isinstance(update_body, dict) else []
check('Test-Story ändern', not updated.isError and 'story_points' in fields, error_text(updated)[:500] if updated.isError or 'story_points' not in fields else '')
if not updated.isError:
reread = await session.call_tool('rm_story_get', {'sys_id': story_id})
after = unwrap(payload(reread))
check('Änderung erneut lesen', not reread.isError and isinstance(after, dict) and str(after.get('story_points')) in ('3', '3.0'))
else:
print('ÜBERSPRUNGEN: Lesen und Ändern der Test-Story (Create fehlgeschlagen).', flush=True)
finally:
await auth.close()
print('\n' + ('Alle Tests bestanden.' if not failures else f'{len(failures)} Test(s) fehlgeschlagen: ' + ', '.join(failures)))
if story_id: print('Die Test-Story bleibt bestehen; der Server bietet kein Delete-Tool.')
return 1 if failures else 0
if __name__ == '__main__':
parser = argparse.ArgumentParser(description='Echter Integrationstest: legt eine Test-Story an.')
parser.add_argument('--product', required=True, help='sys_id eines gültigen Produkts')
args = parser.parse_args()
try: sys.exit(asyncio.run(main(args.product)))
except Exception as exc:
print(f'Integrationstest abgebrochen: {exc}', file=sys.stderr)
sys.exit(1)
+246
View File
@@ -0,0 +1,246 @@
#!/usr/bin/env python3
"""ServiceNow Story MCP CLI; OAuth authorization code with PKCE and Edge."""
import argparse
import asyncio
import base64
import hashlib
import json
import os
from pathlib import Path
import secrets
import shutil
import subprocess
import sys
import tempfile
import time
from urllib.parse import parse_qs, urlencode, urlparse
import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
from mcp.client.sse import sse_client
ORIGIN = 'https://enercondev.service-now.com'
MCP_URL = os.getenv('MCP_URL', ORIGIN + '/sncapps/mcp-server/mcp/x_engm3_mcp_stor_0_mcp_story_bridge')
CLIENT_ID = os.getenv('OAUTH_CLIENT_ID', 'bde15764d0cb43658c41d31797c28b0e')
REDIRECT = os.getenv('OAUTH_REDIRECT_URI', 'http://127.0.0.1:8765/oauth/callback')
TOKEN_FILE = Path(os.getenv('OAUTH_TOKEN_FILE', '.tokens.json')).expanduser()
EXPECTED = {'rm_story_list', 'rm_story_get', 'rm_story_create', 'rm_story_update'}
def edge_open(url):
"""Launch Edge specifically; never silently substitute another browser."""
configured = os.getenv('EDGE_PATH')
candidates = [configured] if configured else (['msedge', 'microsoft-edge', 'microsoft-edge-stable', 'microsoft-edge-beta'] if sys.platform != 'win32' else [
os.path.join(os.environ.get('PROGRAMFILES(X86)', r'C:\Program Files (x86)'), 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
os.path.join(os.environ.get('PROGRAMFILES', r'C:\Program Files'), 'Microsoft', 'Edge', 'Application', 'msedge.exe'), 'msedge'])
if sys.platform == 'darwin' and not configured:
candidates.insert(0, '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge')
executable = next((x for x in candidates if x and (shutil.which(x) or Path(x).is_file())), None)
if not executable:
raise RuntimeError('Microsoft Edge wurde nicht gefunden. Installiere Edge oder setze EDGE_PATH auf die Edge-Programmdatei.')
subprocess.Popen([executable, url], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, start_new_session=True)
def save_tokens(tokens):
TOKEN_FILE.parent.mkdir(parents=True, exist_ok=True)
fd, tmp = tempfile.mkstemp(prefix='.oauth-', dir=TOKEN_FILE.parent)
try:
if os.name != 'nt': os.fchmod(fd, 0o600)
with os.fdopen(fd, 'w', encoding='utf-8') as f: json.dump(tokens, f)
os.replace(tmp, TOKEN_FILE)
finally:
if os.path.exists(tmp): os.unlink(tmp)
async def wait_for_callback(state, open_browser, timeout=180):
uri = urlparse(REDIRECT)
if uri.scheme != 'http' or uri.hostname != '127.0.0.1' or not uri.port or uri.query or uri.fragment:
raise ValueError('OAUTH_REDIRECT_URI muss eine HTTP-URL auf 127.0.0.1 mit festem Port sein.')
loop = asyncio.get_running_loop()
result = loop.create_future()
async def handle(reader, writer):
try:
line = await asyncio.wait_for(reader.readline(), 5)
parts = line.decode('ascii', 'replace').split()
target = urlparse(parts[1]) if len(parts) >= 2 else None
params = parse_qs(target.query) if target else {}
if len(parts) < 2 or parts[0] != 'GET' or target.path != uri.path:
status, message = '404 Not Found', 'Nicht gefunden.'
elif params.get('state', [None])[0] != state:
status, message = '400 Bad Request', 'Ungueltiger OAuth-State.'
elif params.get('error'):
status, message = '400 Bad Request', 'Anmeldung abgelehnt.'
if not result.done(): result.set_exception(RuntimeError('OAuth-Autorisierung abgelehnt: ' + params['error'][0]))
elif not params.get('code'):
status, message = '400 Bad Request', 'Autorisierungscode fehlt.'
else:
status, message = '200 OK', 'Anmeldung abgeschlossen. Dieses Fenster kann geschlossen werden.'
if not result.done(): result.set_result(params['code'][0])
body = message.encode()
writer.write(f'HTTP/1.1 {status}\r\nContent-Type: text/plain; charset=utf-8\r\nCache-Control: no-store\r\nContent-Length: {len(body)}\r\nConnection: close\r\n\r\n'.encode() + body)
await writer.drain()
finally:
writer.close()
await writer.wait_closed()
server = await asyncio.start_server(handle, '127.0.0.1', uri.port)
try:
open_browser()
async with server:
return await asyncio.wait_for(result, timeout)
finally:
server.close()
await server.wait_closed()
class TokenError(RuntimeError):
def __init__(self, status, error):
self.status, self.error = status, error
super().__init__(f'Token-Endpunkt: HTTP {status}, {error}')
class OAuth(httpx.Auth):
def __init__(self):
self.tokens = {}
if TOKEN_FILE.exists():
self.tokens = json.loads(TOKEN_FILE.read_text(encoding='utf-8'))
self.metadata = None
self.lock = asyncio.Lock()
self.http = httpx.AsyncClient(timeout=20, follow_redirects=False)
async def close(self): await self.http.aclose()
async def discover(self):
url = urlparse(MCP_URL)
base = f'{url.scheme}://{url.netloc}'
for suffix in [url.path, '']:
try:
r = await self.http.get(base + '/.well-known/oauth-protected-resource' + suffix)
r.raise_for_status()
resource = r.json()
if resource.get('resource', MCP_URL).rstrip('/') != MCP_URL.rstrip('/'): continue
for issuer in resource.get('authorization_servers', []):
i = urlparse(issuer)
if f'{i.scheme}://{i.netloc}' != ORIGIN: continue
r = await self.http.get(ORIGIN + '/.well-known/oauth-authorization-server' + (i.path if i.path != '/' else ''))
r.raise_for_status()
meta = r.json()
if all(f'{urlparse(meta[k]).scheme}://{urlparse(meta[k]).netloc}' == ORIGIN for k in ('authorization_endpoint', 'token_endpoint')):
print('OAuth-Discovery erfolgreich.', file=sys.stderr)
return meta
except (httpx.HTTPError, ValueError, KeyError): pass
print('OAuth-Discovery fehlgeschlagen; ServiceNow-Endpunkte werden verwendet.', file=sys.stderr)
return {'authorization_endpoint': ORIGIN + '/oauth_auth.do', 'token_endpoint': ORIGIN + '/oauth_token.do'}
async def exchange(self, fields):
secret = os.getenv('OAUTH_CLIENT_SECRET')
if not secret: secret = Path(os.getenv('OAUTH_CLIENT_SECRET_FILE', 'clientsecret')).read_text(encoding='utf-8').strip()
if not secret: raise RuntimeError('Client-Secret ist leer.')
r = await self.http.post(self.metadata['token_endpoint'], data={**fields, 'client_id': CLIENT_ID, 'client_secret': secret})
try: data = r.json()
except ValueError: data = {}
if r.is_error or not data.get('access_token'):
raise TokenError(r.status_code, data.get('error', 'kein access_token'))
if fields['grant_type'] == 'refresh_token' and not data.get('refresh_token'):
data['refresh_token'] = self.tokens.get('refresh_token')
data['expires_at'] = int((time.time() + float(data.get('expires_in', 1800))) * 1000)
save_tokens(data)
self.tokens = data
async def ensure(self, force=False, rejected_token=None):
async with self.lock:
if self.metadata is None: self.metadata = await self.discover()
if force and rejected_token and self.tokens.get('access_token') != rejected_token: return
if not force and self.tokens.get('access_token') and self.tokens.get('expires_at', 0) > (time.time() + 60) * 1000: return
if self.tokens.get('refresh_token'):
try:
await self.exchange({'grant_type': 'refresh_token', 'refresh_token': self.tokens['refresh_token']})
return
except TokenError as error:
if error.error != 'invalid_grant': raise
print('Refresh-Token abgelaufen oder widerrufen; erneuter Login erforderlich.', file=sys.stderr)
self.tokens = {}
verifier = secrets.token_urlsafe(32)
state = secrets.token_urlsafe(32)
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).decode().rstrip('=')
url = self.metadata['authorization_endpoint'] + '?' + urlencode({'response_type': 'code', 'client_id': CLIENT_ID, 'redirect_uri': REDIRECT, 'state': state, 'code_challenge': challenge, 'code_challenge_method': 'S256'})
print('Microsoft Edge wird für den Login geöffnet; warte auf den lokalen Callback.', file=sys.stderr)
code = await wait_for_callback(state, lambda: edge_open(url))
await self.exchange({'grant_type': 'authorization_code', 'code': code, 'redirect_uri': REDIRECT, 'code_verifier': verifier})
async def async_auth_flow(self, request):
await self.ensure()
token = self.tokens['access_token']
request.headers['Authorization'] = 'Bearer ' + token
response = yield request
if response.status_code == 401:
await response.aread()
await self.ensure(force=True, rejected_token=token)
request.headers['Authorization'] = 'Bearer ' + self.tokens['access_token']
yield request
def object_json(value):
try: obj = json.loads(value)
except ValueError as e: raise argparse.ArgumentTypeError(str(e)) from e
if not isinstance(obj, dict): raise argparse.ArgumentTypeError('JSON-Objekt erforderlich')
return obj
def parser():
p = argparse.ArgumentParser(description='ServiceNow Story MCP Client')
p.add_argument('--transport', choices=('http', 'sse'), default='http')
sub = p.add_subparsers(dest='command', required=True)
sub.add_parser('tools')
listp = sub.add_parser('list'); listp.add_argument('data', nargs='?', type=object_json, default={})
get = sub.add_parser('get'); get.add_argument('sys_id')
create = sub.add_parser('create'); create.add_argument('data', type=object_json)
update = sub.add_parser('update'); update.add_argument('sys_id'); update.add_argument('data', type=object_json)
call = sub.add_parser('call'); call.add_argument('name', choices=sorted(EXPECTED)); call.add_argument('data', nargs='?', type=object_json, default={})
return p
def call_args(args):
if args.command == 'list': return 'rm_story_list', args.data
if args.command == 'get': return 'rm_story_get', {'sys_id': args.sys_id}
if args.command == 'create': return 'rm_story_create', {'request_body': args.data}
if args.command == 'update': return 'rm_story_update', {'sys_id': args.sys_id, 'request_body': args.data}
return args.name, args.data
async def run(args):
auth = OAuth()
try:
async with httpx.AsyncClient(auth=auth, timeout=httpx.Timeout(30, read=300), follow_redirects=False) as http:
transport = sse_client(MCP_URL, auth=auth) if args.transport == 'sse' else streamable_http_client(MCP_URL, http_client=http)
async with transport as streams:
async with ClientSession(streams[0], streams[1]) as session:
await session.initialize()
if args.command == 'tools':
tools, cursor = [], None
while True:
page = await session.list_tools(cursor=cursor)
tools.extend(page.tools)
cursor = page.nextCursor
if not cursor: break
print(json.dumps([x.model_dump(mode='json', exclude_none=True) for x in tools], ensure_ascii=False, indent=2))
names = [t.name for t in tools]
if len(names) != 4 or set(names) != EXPECTED:
print('Warnung: Tool-Liste weicht von den vier erwarteten Tools ab.', file=sys.stderr)
return 1
else:
name, data = call_args(args)
result = await session.call_tool(name, data)
print(json.dumps(result.model_dump(mode='json', exclude_none=True), ensure_ascii=False, indent=2))
if result.isError: return 1
return 0
finally: await auth.close()
def main():
try: return asyncio.run(run(parser().parse_args()))
except (Exception, KeyboardInterrupt) as e:
print(f'Fehler: {e}', file=sys.stderr)
return 1
if __name__ == '__main__': sys.exit(main())
+17
View File
@@ -0,0 +1,17 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { startCallback } from '../callback.js';
test('OAuth callback ignores invalid state and accepts matching code', async () => {
const uri = 'http://127.0.0.1:18765/oauth/callback';
const listener = await startCallback(uri, 'expected', 2000);
try {
assert.equal((await fetch(`${uri}?code=bad&state=wrong`)).status, 400);
assert.equal((await fetch(`${uri}?code=good&state=expected`)).status, 200);
assert.equal(await listener.result, 'good');
} finally { listener.close(); }
});
test('OAuth callback rejects non-loopback addresses', async () => {
await assert.rejects(startCallback('http://0.0.0.0:8765/oauth/callback', 'state'));
});
+33
View File
@@ -0,0 +1,33 @@
import asyncio
import unittest
from types import SimpleNamespace
from unittest.mock import patch
import story_client as client
class ClientTests(unittest.TestCase):
def test_create_and_update_use_request_body(self):
self.assertEqual(client.call_args(SimpleNamespace(command='create', data={'type': 'Bug'})),
('rm_story_create', {'request_body': {'type': 'Bug'}}))
self.assertEqual(client.call_args(SimpleNamespace(command='update', sys_id='abc', data={'story_points': '3'})),
('rm_story_update', {'sys_id': 'abc', 'request_body': {'story_points': '3'}}))
def test_callback_checks_state(self):
async def check():
async def request(query):
reader, writer = await asyncio.open_connection('127.0.0.1', 18766)
writer.write(('GET /oauth/callback?' + query + ' HTTP/1.1\r\nHost: 127.0.0.1\r\n\r\n').encode())
await writer.drain()
response = await reader.read()
writer.close(); await writer.wait_closed()
return response
async def send():
await asyncio.sleep(.02)
self.assertIn(b'400 Bad Request', await request('code=wrong&state=bad'))
self.assertIn(b'200 OK', await request('code=ok&state=expected'))
with patch.object(client, 'REDIRECT', 'http://127.0.0.1:18766/oauth/callback'):
task = asyncio.create_task(client.wait_for_callback('expected', lambda: None, 3))
await send()
self.assertEqual(await task, 'ok')
asyncio.run(check())
if __name__ == '__main__': unittest.main()