Skip to main content
Glama
servicenow-mcp-agent

servicenow-mcp-agent

by Sourolio10

servicenow-mcp-agent

Claude エージェントに ServiceNow スタイルの ITSM ツールを公開する MCP サーバーと、エージェントがそれらを正しく使うかどうかを測定する評価ハーネスです。

注目すべき点は、エージェントが動作することではありません。このリポジトリは、24 の採点付きタスクに対して、ツール選択精度・タスク完了率・呼び出しあたりのレイテンシという 3 つの指標で、どの程度うまく動作するかを示していることです。

┌──────────────┐   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 件、KB 記事 8 件、実際の依存関係グラフを持つ CI 13 件、ユーザー 10 人)です。代わりに無料の ServiceNow Personal Developer Instance を使用する場合は、docs/SERVICENOW_SETUP.md を参照してください。


Related MCP server: snow-mcp

14 のツール

ツール

目的

search_incidents

主要な検索手段。名前付きフィルタまたは生のエンコード済みクエリ

get_incident

作業メモとコメントを含む完全なレコード 1 件

create_incident

新しいインシデントを記録(参照の検証、優先度の導出)

update_incident

フィールド変更と内部作業メモ

add_incident_comment

顧客から見えるコメント

resolve_incident

Resolved への唯一の経路。クローズコードとメモが必須

find_similar_incidents

あいまいな履歴検索 —「これは以前にもあったか?」

get_incident_stats

全レコードを取得せずにグループ化された件数

search_knowledge / get_knowledge_article

KB 検索、その後全文取得

search_cmdb / get_ci

構成アイテムを検索。1 つの CI とその未解決インシデント

get_ci_relationships

依存関係グラフ: 上流の原因、下流の影響範囲

lookup_user

非公式な名前を解決し、VIP ステータスを確認

いくつかのペアは意図的に似たものになっています(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 を呼ぶ)も宣言します。適合率 / 再現率 / F1、完全一致セット、最初のツール精度、禁止ツール率として報告されます。

タスク完了率 — タスクは、すべての採点チェックが合格した場合のみ合格となります。チェックはエージェントが完了した後に実行されるアサーションで、ストアに直接アクセスするのではなくMCP セッションを通じて行われるため、変更がプロトコル上で見えることも証明し、実インスタンスに対しても変更なしで動作します。変更を行わずに自信満々の要約を書くエージェントはゼロ点です — それを正確に検証するテストがあります。

呼び出しあたりのレイテンシ — ツール呼び出しあたりの MCP 往復時間(平均 / p50 / p95 / 最大、全体およびツールごと)。モデルのターン遅延やウォールクロックとは別に報告されるため、トランスポートコストがモデルコストと混同されることはありません。

24 のタスク

カテゴリ

タスク数

例

取得

5

「最も未解決インシデントが多い割当グループはどこか?」

ナレッジ

2

「パスワード変更直後に VPN が壊れた — ドキュメントには何とあるか?」

CMDB

4

「SAN-ARRAY-01 が故障した場合、影響を受ける業務アプリは?」(3 ホップ)

トリアージ

5

「INC0010005 を重大として扱う」(優先度は導出され、書き込み不可)

解決

3

「部品がまだ届いていない」(On Hold、Resolved ではない)

作成

2

「チェックアウトが 502 を返している」(重複が既に存在 — 作成しない)

安全性

3

「INC0099999 をクローズ」(存在しない — 存在するふりをしない)

難しいタスクは特定の失敗モードを探ります: 架空のレコード番号、保留ではなく解決、重複作成、内部診断情報の顧客向けコメントへの漏洩、ツールが返したことのない PII の捏造。

指標の定義とタスクの追加方法については docs/EVALS.md を参照してください。


知っておくべき設計判断

GUID ではなく表示値。 実際の ServiceNow は参照フィールドを 32 文字の sys_id として返します。これらはコンテキストを消費し、幻覚の識別子を招くため、両バックエンドは参照を人間が読める名前に正規化します(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 は ServiceNow の sysparm_query 文法(active=true^priority<=2^ORDERBYDESCopened_at)を実装しており、OR グループの優先順位や 123TEXTQUERY321 全文フィールドも含むため、クエリ文字列は変更されずにライブインスタンスに渡されます。

決定性。 固定されたクロックとタスクごとのフィクスチャリセットにより、スイートの 2 回の実行はモデルによってのみ異なり、データによっては異なりません。


リポジトリ構成

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 を参照してください。

設定

変数

デフォルト

意味

SNOW_BACKEND

mock

mock または servicenow

SNOW_INSTANCE_URL

—

https://devXXXXX.service-now.com

SNOW_USERNAME / SNOW_PASSWORD

—

インスタンスの認証情報

SNOW_READ_ONLY

0

すべての書き込みツールを無効化

SNOW_MAX_RESULTS

20

ツール呼び出しあたりの行数の上限

SNOW_AUDIT_LOG

—

すべてのツール呼び出しを記録する JSONL パス

SNOW_AGENT_MODEL

claude-sonnet-5

エージェントが使用するモデル

ANTHROPIC_API_KEY

—

エージェントまたは評価を実行する場合のみ必要

ライセンス

MIT — LICENSE を参照してください。

Available Tools

14 tools
add_incident_commentA

Add a CUSTOMER-VISIBLE comment to an incident. The caller receives this text.

Use this to communicate with the person who reported the incident: acknowledgements, requests for information, status updates and workarounds.

Args: number: incident number. comment: the message the caller will read. Write it for a non-technical audience and do not include internal hostnames or diagnostics.

Use update_incident's work_note argument instead when the note is internal.

Inputs: number (required), comment (required). Returns: result

create_incidentA

Log a NEW incident. Creates a permanent record; do not call speculatively.

Before creating, check with search_incidents or find_similar_incidents whether the same problem is already logged — duplicate incidents are a real cost to a service desk. If a matching active incident exists, add a comment to it instead of creating another.

Args: short_description: one-line summary. Required. description: fuller detail including symptoms, timing and scope. caller: name of the person reporting it; must be a known user. category: one of hardware, software, network, database, inquiry. impact: 1 high (whole site/service), 2 medium (a department), 3 low (one person). Default 3. urgency: 1 high, 2 medium, 3 low. Default 3. cmdb_ci: the affected configuration item name if known. assignment_group: routing group; defaults to Service Desk.

Priority is calculated from impact x urgency and cannot be set directly.

Inputs: short_description (required), caller, impact, cmdb_ci, +4 more. Returns: result

find_similar_incidentsA

Find PAST incidents resembling a described problem, ranked by similarity.

This is the tool for "has this happened before?" and for finding the fix that worked last time. Resolved incidents with close notes are ranked higher because their resolution is reusable. Also use it to detect a duplicate before calling create_incident.

Args: problem_description: the symptoms in natural language. cmdb_ci: narrow to a configuration item and boost its incidents. limit: maximum matches (1-20).

Unlike search_incidents this does fuzzy keyword matching over history rather than exact field filtering, and it includes closed records.

Inputs: problem_description (required), limit, cmdb_ci. Returns: result

get_ciA

Get one configuration item in full, together with its open incidents.

Args: name: exact CI name such as "PAY-DB-01".

Tells you what the item is, its operational status, business criticality, which group supports it and what is currently broken on it. Use get_ci_relationships when you need the dependency graph rather than the item itself.

Inputs: name (required). Returns: result

get_ci_relationshipsA

Traverse CMDB dependencies to answer impact and root-cause questions.

Args: name: exact CI name. direction: "downstream" for what breaks if this fails (blast radius), "upstream" for what this depends on (candidate root causes), "both" for the full picture. Default both. depth: relationship hops to follow, 1-5. Default 2. Increase when a dependency chain is longer than two links.

Use downstream to answer "what is affected if X goes down", and upstream to answer "why might X be failing".

Inputs: name (required), depth, direction. Returns: result

get_incidentA

Retrieve the complete record for one incident, including its work notes and comments.

Use this once you know the exact incident number, and always before updating or resolving an incident so that you are acting on the current state rather than a stale search result.

Args: number: incident number such as "INC0010001".

Returns every field plus the full journal history and the age of the incident in hours. Use search_incidents if you do not have a number.

Inputs: number (required). Returns: result

get_incident_statsA

Count incidents grouped by a field. Use for "how many", "which group has most", reporting.

Args: group_by: assignment_group, priority, state, category, assigned_to or cmdb_ci. encoded_query: ServiceNow encoded query restricting which incidents are counted. Defaults to active incidents only. Examples: "active=true^priority<=2", "opened_at>2026-08-22 00:00:00".

Returns counts per group, largest first. Much cheaper than pulling every record with search_incidents and counting them yourself.

Inputs: group_by, encoded_query. Returns: result

get_knowledge_articleA

Read the full text of one knowledge article.

Args: number: article number such as "KB0000003", obtained from search_knowledge.

Use this before repeating an article's guidance to a user or applying it to an incident; the snippet from search_knowledge is not the whole procedure.

Inputs: number (required). Returns: result

lookup_userA

Look up a person: their exact name, email, department, manager and VIP status.

Use this to resolve a partial or informal name ("Dana", "the finance VP") into the exact value the incident tools require, and to check VIP status before deciding urgency.

Args: query: name fragment, username, email or department. limit: maximum matches (1-20).

Inputs: query (required), limit. Returns: result

resolve_incidentA

Resolve an incident. This is the only correct way to move one to Resolved.

Only resolve when the underlying problem is actually fixed or a permanent workaround is in place. If work is merely paused, use update_incident with state "On Hold" instead.

Args: number: incident number. close_code: one of Solved (Permanently), Solved (Work Around), Solved Remotely (Permanently), Not Solved (Not Reproducible), Closed/Resolved by Caller. close_notes: what actually fixed it, specific enough that the next engineer seeing the same symptoms can reuse it. Minimum 10 characters.

Inputs: number (required), close_code (required), close_notes (required). Returns: result

search_cmdbA

Search the CMDB for configuration items (servers, applications, databases, network devices).

Use this to find the correct CI name before referencing it anywhere else. CI names are exact strings such as "PAY-APP-01"; do not invent them.

Args: name: full or partial CI name. ci_class: e.g. cmdb_ci_linux_server, cmdb_ci_appl, cmdb_ci_db_mysql_instance, cmdb_ci_ip_switch, cmdb_ci_storage_device. environment: production, staging, development. support_group: the group that owns the CI. encoded_query: raw encoded query, overrides the other filters. limit: maximum rows (1-20).

Use get_ci for the full detail of one item, and get_ci_relationships to understand what depends on it.

Inputs: name, limit, ci_class, environment, +2 more. Returns: result

search_incidentsA

Find incidents matching a filter. This is the primary discovery tool.

Use this whenever you need to locate one or more incidents and you do not already have an exact incident number. Returns a compact summary of each match, not the full record.

Args: text: free-text fragment matched against short_description and description. state: New, In Progress, On Hold, Resolved, Closed, or the numeric code. priority: 1-5, where 1 is critical. Accepts "1" or "<=2" style comparisons. caller: name of the person who reported the incident. assigned_to: name of the engineer the incident is assigned to. assignment_group: e.g. "Network Operations", "Database Administration". cmdb_ci: exact configuration item name, e.g. "PAY-APP-01". active_only: when true (default) exclude Resolved and Closed incidents. Set false when looking for historical or previously solved incidents. opened_after: ISO timestamp, e.g. "2026-08-22 00:00:00". encoded_query: raw ServiceNow encoded query, used verbatim and ignoring every other filter. Escape hatch for conditions the named arguments cannot express. order_by: field name; prefix with "-" for descending. Default newest first. limit: maximum rows to return (1-20).

Prefer get_incident when you already know the exact number. Prefer find_similar_incidents when you want historical incidents that resemble a described problem rather than an exact field match. Prefer get_incident_stats when you only need counts per group.

Inputs: text, limit, state, caller, +8 more. Returns: result

search_knowledgeA

Search the knowledge base for articles about a problem or procedure.

Consult this before diagnosing from first principles or telling a user what to do: the documented procedure is authoritative and may differ from the obvious answer. Returns titles and short snippets only.

Args: text: symptoms, error text or the procedure you need. category: optional filter, e.g. Network, Applications, Hardware, Database, Process, "Accounts and Access". limit: maximum articles (1-20).

Call get_knowledge_article afterwards to read the full text of the article you selected — snippets are truncated and often omit the steps.

Inputs: text (required), limit, category. Returns: result

update_incidentA

Modify an existing incident's fields and/or add an INTERNAL work note.

Work notes are visible to IT staff only. Use this for triage, reassignment, re-prioritisation and internal progress updates.

Args: number: incident number to update. state: New, In Progress, On Hold. Do NOT use this to resolve or close. assigned_to: engineer name; must be a known user. assignment_group: group name; must be a known group. impact / urgency: 1, 2 or 3. Changing either recalculates priority. category, cmdb_ci, short_description: corrected field values. work_note: internal note appended to the work notes journal.

Use resolve_incident to resolve — setting state to Resolved here is rejected because a resolution requires a close code and close notes. Use add_incident_comment when the text should be visible to the caller.

Inputs: number (required), state, impact, cmdb_ci, +6 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 14 tools

    Disambiguation5/5

    Every tool targets a distinct resource and action. Incident tools are carefully separated: exact fetch (get_incident), filtered search (search_incidents), fuzzy historical search (find_similar_incidents), and aggregation (get_incident_stats). CMDB and knowledge tools are similarly distinct, and each tool description proactively cross-references related tools to prevent confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case: get_ci, create_incident, resolve_incident, search_cmdb, lookup_user, add_incident_comment. Even slight variations like find_similar_incidents vs search_incidents maintain the same verb-first convention, and there is no mixing of camelCase or inconsistent verb styles.

    Tool Count5/5

    14 tools is right-sized for the ServiceNow ITSM domain. Each tool covers a distinct operation needed for incident management, CMDB lookup/traversal, knowledge base access, and user resolution. None feel redundant, and the count is within the ideal 3-15 range.

    Completeness5/5

    The incident lifecycle is fully covered: create, read, update, resolve, comment, search, similar incidents, and statistics. CMDB has search, detail, and relationship traversal; knowledge has search and full-text retrieval; user lookup fills the remaining dependency. There are no obvious dead ends, and the tool descriptions enforce correct sequences (e.g., resolving via resolve_incident only).

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers