servicenow-mcp-agent

Ein MCP-Server, der ServiceNow-ähnliche ITSM-Tools für einen Claude-Agenten bereitstellt, plus eine Evaluierungsumgebung, die misst, ob der Agent sie tatsächlich korrekt verwendet.

Das Interessante ist nicht, dass der Agent funktioniert. Sondern dass das Repository Ihnen sagt, wie gut es funktioniert, anhand von 24 bewerteten Aufgaben, mit drei Metriken: Tool-Auswahlgenauigkeit, Aufgabenabschlussrate und Latenz pro Aufruf.

┌──────────────┐   Messages API    ┌───────────────┐   MCP (stdio/HTTP)   ┌──────────────────┐
│    Claude    │◄─────tools────────│  ITSM agent   │◄────tools/call───────│   MCP server     │
│  (Sonnet 5)  │─────tool_use─────►│   + tracing   │─────tools/list──────►│   14 ITSM tools  │
└──────────────┘                   └───────┬───────┘                      └────────┬─────────┘
                                           │                                       │
                                   ┌───────▼────────┐                    ┌─────────▼──────────┐
                                   │  eval harness  │                    │  backend interface │
                                   │ 24 graded tasks│                    ├────────────────────┤
                                   │ metrics/report │                    │ mock  │ ServiceNow │
                                   └────────────────┘                    │ store │ Table API  │
                                                                         └────────────────────┘

Schnellstart

git clone https://github.com/your-username/servicenow-mcp-agent
cd servicenow-mcp-agent
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest                                   # 105 tests, no API key needed

export ANTHROPIC_API_KEY=sk-ant-...
snow-agent --list-tools
snow-agent -v "The payment service is down. What's the likely root cause?"
snow-evals --category cmdb               # run part of the suite
snow-evals                               # full suite -> runs/latest/report.{md,html,json}

Es ist keine ServiceNow-Instanz erforderlich. Das Standard-Backend ist eine deterministische In-Memory-Fixture (16 Vorfälle, 8 KB-Artikel, 13 CIs mit einem echten Abhängigkeitsgraphen, 10 Benutzer). Um stattdessen auf eine kostenlose ServiceNow Personal Developer Instance zu verweisen, siehe docs/SERVICENOW_SETUP.md.

Related MCP server: snow-mcp

Die 14 Tools

Mehrere Paare sind bewusste Nachbarn (update_incident vs add_incident_comment, search_incidents vs find_similar_incidents, get_ci vs get_ci_relationships). Sie zu unterscheiden ist genau das, was die Tool-Auswahlgenauigkeit misst, und genau dort scheitert eine naive Tool-Oberfläche.

Evaluierungen

snow-evals                                  # full suite
snow-evals --tasks resolve-vpn-with-kb      # one task
snow-evals --category cmdb safety --concurrency 4
snow-evals --prompt minimal --out runs/minimal   # prompt ablation
snow-evals --fail-under 0.8                 # CI gate

Erzeugt report.md, report.html, report.json und eine traces.jsonl, die jeden Tool-Aufruf, jedes Argument, jede Latenz und eine Ergebnisvorschau enthält.

Was gemessen wird

Tool-Auswahlgenauigkeit — Pro Aufgabe wird die Menge der aufgerufenen Tools mit der erwarteten Menge verglichen, makro-gemittelt, sodass jede Aufgabe gleich gewichtet wird. Aufgaben deklarieren auch optional_tools (ein vertretbarer alternativer Weg, der aus dem Präzisionsnenner ausgeschlossen wird) und forbidden_tools (ein echter Fehler, z. B. create_incident aufzurufen, wenn der Vorfall bereits existiert). Berichtet als Präzision / Recall / F1, exakte Mengenübereinstimmung, Genauigkeit des ersten Tools und Rate der verbotenen Tools.

Aufgabenabschlussrate — Eine Aufgabe besteht nur, wenn alle bewerteten Prüfungen bestehen. Prüfungen sind Assertions, die nach Abschluss des Agenten ausgeführt werden, über die MCP-Sitzung und nicht durch direkten Zugriff auf den Speicher, sodass sie auch beweisen, dass die Änderung über das Protokoll sichtbar ist und unverändert gegen eine echte Instanz funktionieren. Ein Agent, der eine selbstbewusste Zusammenfassung schreibt, ohne die Änderung vorzunehmen, erhält null Punkte – es gibt einen Test, der genau das bestätigt.

Latenz pro Aufruf — MCP-Roundtrip-Zeit pro Tool-Aufruf (Mittelwert / p50 / p95 / Max, insgesamt und pro Tool), getrennt von der Modell-Turn-Latenz und der Wanduhrzeit, sodass Transportkosten nie mit Modellkosten verwechselt werden.

Die 24 Aufgaben

Die schwierigen Aufgaben testen spezifische Fehlermodi: erfundene Datensatznummern, Auflösen statt Wartestellung, Erstellen von Duplikaten, Durchsickern interner Diagnosen in kunden sichtbare Kommentare und das Erfinden von PII, die die Tools nie zurückgegeben haben.

Siehe docs/EVALS.md für die Metrikdefinitionen und wie man eine Aufgabe hinzufügt.

Designentscheidungen, die man kennen sollte

Anzeigewerte, keine GUIDs. Echtes ServiceNow gibt Referenzfelder als 32-stellige sys_ids zurück. Diese verbrauchen Kontext und laden zu halluzinierten Identifikatoren ein, daher normalisieren beide Backends Referenzen auf menschenlesbare Namen (assigned_to: "Priya Nair"). Schreibvorgänge akzeptieren einen Namen und werden gegen die Plattform validiert – ein unbekannter Wert wird mit der Liste der gültigen Werte abgelehnt, auf die das Modell reagieren kann.

Domänenfehler sind Daten, keine Fehler. Eine Validierungsmeldung wie „Priorität wird aus Auswirkung und Dringlichkeit abgeleitet“ wird als wiederherstellbares JSON zurückgegeben. Der Agent passt sich an und fährt fort; test_agent_recovers_from_a_rejected_tool_call fixiert dieses Verhalten.

Schutzmechanismen im Server, nicht im Prompt. update_incident kann den Status nicht auf Gelöst setzen. Geschlossene Datensätze sind unveränderlich. resolve_incident erfordert einen Abschlusscode und aussagekräftige Notizen. SNOW_READ_ONLY=1 deaktiviert jedes Schreibwerkzeug. Mit einem Prompt kann man argumentieren; mit einem Server nicht.

Tool-Beschreibungen sind Prompts. Jede sagt, was sie tut, wann man sie verwenden sollte und wann man stattdessen ein benachbartes Tool verwenden sollte. Die Tool-Auswahlgenauigkeit verändert sich durch die Bearbeitung dieser Zeichenketten mehr als durch alles andere im Repository – genau deshalb existiert die Evaluierung.

Echte codierte Abfragen. src/snow_mcp/query.py implementiert die sysparm_query-Grammatik von ServiceNow (active=true^priority<=2^ORDERBYDESCopened_at), einschließlich OR-Gruppen-Präzedenz und des 123TEXTQUERY321-Volltextfelds, sodass Abfragezeichenfolgen unverändert an eine Live-Instanz durchgereicht werden.

Determinismus. Eine eingefrorene Uhr und ein Fixture-Reset pro Aufgabe bedeuten, dass sich zwei Läufe der Suite nur durch das Modell unterscheiden, nicht durch die Daten.

Repository-Struktur

src/snow_mcp/
  query.py            ServiceNow encoded-query parser and evaluator
  store.py            in-memory ITSM store (derived priority, journals, CMDB graph)
  clock.py            frozen clock for reproducible runs
  data/seed.json      the ACME Corp fixture
  backends/
    base.py           the backend contract + response shaping
    mock.py           in-memory implementation with platform validation
    servicenow.py     live Table API client for a Personal Developer Instance
  mock_api/app.py     FastAPI service speaking the Table API dialect
  server.py           the MCP server: 14 tools
  agent/
    bridge.py         MCP <-> Anthropic tool translation, latency capture
    llm.py            LLM interface, Anthropic client, scripted client for CI
    agent.py          the tool-use loop and run instrumentation
    prompts.py        operator vs minimal system prompts
  evals/
    tasks.yaml        24 graded tasks
    runner.py         isolated execution
    metrics.py        metric definitions
    checks.py         assertion engine
    report.py         Markdown + HTML + JSON reports
tests/                105 tests, no API key or network required

Verbinden von Claude Desktop / Claude Code

claude mcp add servicenow-itsm -- python -m snow_mcp.server

.mcp.json und examples/claude_desktop_config.json sind bereit zum Kopieren – siehe docs/CONNECTING.md.

Konfiguration

Lizenz

MIT – siehe LICENSE.