servicenow-mcp-agent

MCP-сервер, который предоставляет инструменты ITSM в стиле ServiceNow агенту Claude, а также харнесс для оценки, который измеряет, действительно ли агент использует их правильно.

Интересно не то, что агент работает. А то, что репозиторий показывает, насколько хорошо он работает, на 24 оцениваемых задачах, с тремя метриками: точность выбора инструментов, доля выполненных задач и задержка на вызов.

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

Быстрый старт

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}

Экземпляр ServiceNow не требуется. По умолчанию используется детерминированный фикстур в памяти (16 инцидентов, 8 статей базы знаний, 13 CI с реальным графом зависимостей, 10 пользователей). Чтобы вместо этого подключиться к бесплатному персональному экземпляру разработчика ServiceNow, см. docs/SERVICENOW_SETUP.md.

Related MCP server: snow-mcp

14 инструментов

Несколько пар намеренно являются близкими соседями (update_incident против add_incident_comment, search_incidents против find_similar_incidents, get_ci против get_ci_relationships). Различие между ними — это именно то, что измеряет точность выбора инструментов, и именно здесь наивная поверхность инструментов терпит неудачу.

Оценки

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

Выводит report.md, report.html, report.json и traces.jsonl, содержащий каждый вызов инструмента, аргумент, задержку и предпросмотр результата.

Что измеряется

Точность выбора инструментов — для каждой задачи набор различных вызванных инструментов по сравнению с ожидаемым набором, усреднённый по макро-методу, так что каждая задача имеет одинаковый вес. Задачи также объявляют optional_tools (допустимый альтернативный путь, исключаемый из знаменателя точности) и forbidden_tools (реальная ошибка, например, вызов create_incident, когда инцидент уже существует). Сообщается как precision / recall / F1, точное совпадение набора, точность первого инструмента и доля запрещённых инструментов.

Доля выполненных задач — задача считается пройденной только тогда, когда все оцениваемые проверки пройдены. Проверки — это утверждения, выполняемые после завершения работы агента, сделанные через MCP-сессию, а не путём прямого доступа к хранилищу, поэтому они также доказывают, что изменение видно через протокол, и работают без изменений с реальным экземпляром. Агент, который пишет уверенное резюме без внесения изменения, получает ноль — есть тест, который проверяет именно это.

Задержка на вызов — время полного цикла MCP на вызов инструмента (среднее / p50 / p95 / максимум, в целом и по каждому инструменту), сообщается отдельно от задержки хода модели и настенных часов, чтобы стоимость транспорта никогда не путалась со стоимостью модели.

24 задачи

Сложные задачи проверяют конкретные режимы отказов: выдуманные номера записей, разрешение вместо удержания, создание дубликатов, утечка внутренней диагностики в комментарии, видимые клиенту, и выдумывание PII, которое инструменты никогда не возвращали.

См. docs/EVALS.md для определений метрик и того, как добавить задачу.

Проектные решения, о которых стоит знать

Отображаемые значения, а не GUID. Реальный ServiceNow возвращает ссылочные поля как 32-символьные sys_ids. Они сжигают контекст и провоцируют галлюцинированные идентификаторы, поэтому оба бэкенда нормализуют ссылки до человеческих имён (assigned_to: "Priya Nair"). Записи принимают имя и проверяются платформой — неизвестное значение отклоняется со списком допустимых, на который модель может опираться.

Ошибки домена — это данные, а не сбои. Сообщение проверки, например «приоритет вычисляется из влияния и срочности», возвращается как восстанавливаемый JSON. Агент адаптируется и продолжает; test_agent_recovers_from_a_rejected_tool_call закрепляет это поведение.

Ограничения на сервере, а не в промпте. update_incident не может установить статус Resolved. Закрытые записи неизменяемы. resolve_incident требует код закрытия и содержательные заметки. SNOW_READ_ONLY=1 отключает все инструменты записи. С промптом можно спорить; с сервером — нет.

Описания инструментов — это промпты. Каждое говорит, что делает инструмент, когда его использовать, а когда вместо него использовать соседний. Точность выбора инструментов больше зависит от редактирования этих строк, чем от чего-либо ещё в репозитории — именно поэтому существует оценка.

Реальные закодированные запросы. src/snow_mcp/query.py реализует грамматику sysparm_query ServiceNow (active=true^priority<=2^ORDERBYDESCopened_at), включая приоритет OR-групп и поле полнотекстового поиска 123TEXTQUERY321, поэтому строки запросов передаются в живой экземпляр без изменений.

Детерминизм. Замороженные часы и сброс фикстур для каждой задачи означают, что два запуска набора отличаются только моделью, а не данными.

Структура репозитория

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

Подключение из Claude Desktop / Claude Code

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

.mcp.json и examples/claude_desktop_config.json готовы к копированию — см. docs/CONNECTING.md.

Конфигурация

Лицензия

MIT — см. LICENSE.