servicenow-mcp-agent

Un servidor MCP que expone herramientas ITSM de estilo ServiceNow a un agente Claude, además de un harness de evaluación que mide si el agente realmente las usa correctamente.

Lo interesante no es que el agente funcione. Es que el repositorio te dice qué tan bien funciona, en 24 tareas calificadas, con tres métricas: precisión de selección de herramientas, tasa de finalización de tareas y latencia por llamada.

┌──────────────┐   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  │
                                                                         └────────────────────┘

Inicio rápido

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}

No se requiere una instancia de ServiceNow. El backend predeterminado es un fixture determinista en memoria (16 incidentes, 8 artículos de KB, 13 CIs con un grafo de dependencias real, 10 usuarios). Para apuntar a una instancia gratuita de ServiceNow Personal Developer en su lugar, consulte docs/SERVICENOW_SETUP.md.

Related MCP server: snow-mcp

Las 14 herramientas

Varios pares son vecinos deliberadamente cercanos (update_incident vs add_incident_comment, search_incidents vs find_similar_incidents, get_ci vs get_ci_relationships). Distinguirlos es exactamente lo que mide la precisión de selección de herramientas, y es donde falla una superficie de herramientas ingenua.

Evaluaciones

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

Genera report.md, report.html, report.json y un traces.jsonl que contiene cada llamada de herramienta, argumento, latencia y vista previa del resultado.

Qué se mide

Precisión de selección de herramientas — por tarea, el conjunto de herramientas distintas llamadas frente al conjunto esperado, promediado macro para que cada tarea pese lo mismo. Las tareas también declaran optional_tools (una ruta alternativa defendible, excluida del denominador de precisión) y forbidden_tools (un error real, p. ej., llamar a create_incident cuando el incidente ya existe). Se informa como precisión / recall / F1, coincidencia exacta de conjuntos, precisión de la primera herramienta y tasa de herramientas prohibidas.

Tasa de finalización de tareas — una tarea pasa solo cuando todas las comprobaciones calificadas pasan. Las comprobaciones son aserciones que se ejecutan después de que el agente termina, hechas a través de la sesión MCP en lugar de acceder al almacenamiento, por lo que también demuestran que el cambio es visible a través del protocolo y funcionan sin cambios contra una instancia real. Un agente que escribe un resumen seguro sin hacer el cambio obtiene cero — hay una prueba que afirma exactamente eso.

Latencia por llamada — tiempo de ida y vuelta MCP por llamada de herramienta (media / p50 / p95 / máx, general y por herramienta), informado por separado de la latencia de turno del modelo y del tiempo de pared, para que el costo de transporte nunca se confunda con el costo del modelo.

Las 24 tareas

Las difíciles exploran modos de fallo específicos: números de registro fabricados, resolver en lugar de poner en espera, crear duplicados, filtrar diagnósticos internos en comentarios visibles para el cliente e inventar PII que las herramientas nunca devolvieron.

Consulte docs/EVALS.md para las definiciones de métricas y cómo agregar una tarea.

Decisiones de diseño que vale la pena conocer

Valores mostrados, no GUIDs. El ServiceNow real devuelve campos de referencia como sys_ids de 32 caracteres. Esos consumen contexto e invitan a identificadores alucinados, por lo que ambos backends normalizan las referencias a nombres legibles (assigned_to: "Priya Nair"). Las escrituras aceptan un nombre y se validan contra la plataforma — un valor desconocido se rechaza con la lista de los válidos, que el modelo puede usar.

Los errores de dominio son datos, no fallos. Un mensaje de validación como "la prioridad se deriva de impacto y urgencia" se devuelve como JSON recuperable. El agente se adapta y continúa; test_agent_recovers_from_a_rejected_tool_call fija este comportamiento.

Protecciones en el servidor, no en el prompt. update_incident no puede establecer el estado a Resuelto. Los registros cerrados son inmutables. resolve_incident requiere un código de cierre y notas significativas. SNOW_READ_ONLY=1 desactiva todas las herramientas de escritura. Un prompt se puede discutir; un servidor no.

Las descripciones de herramientas son prompts. Cada una dice qué hace, cuándo usarla y cuándo usar una herramienta vecina en su lugar. La precisión de selección de herramientas se mueve más editando esas cadenas que por cualquier otra cosa en el repositorio — que es por lo que existe la evaluación.

Consultas codificadas reales. src/snow_mcp/query.py implementa la gramática sysparm_query de ServiceNow (active=true^priority<=2^ORDERBYDESCopened_at), incluida la precedencia de grupos OR y el campo de texto completo 123TEXTQUERY321, para que las cadenas de consulta pasen sin cambios a una instancia en vivo.

Determinismo. Un reloj congelado y un restablecimiento de fixture por tarea significan que dos ejecuciones de la suite difieren solo por el modelo, no por los datos.

Estructura del repositorio

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

Conexión desde Claude Desktop / Claude Code

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

.mcp.json y examples/claude_desktop_config.json están listos para copiar — consulte docs/CONNECTING.md.

Configuración

Licencia

MIT — consulte LICENSE.