<div align="center">

```text
         />_________________________________
[########[]_________________________________>
         \>
```

# ⛩️ servicenow-mcp ⛩️
### ⚔️ 武士道 (BUSHIDO) エディション ⚔️

<br/>

[![AI-Powered](https://img.shields.io/badge/AI--Powered-Claude%20%7C%20ChatGPT%20%7C%20Gemini%20%7C%20Cursor%20%7C%20Copilot-00D4AA?style=flat-square)](https://github.com/tedorigawa001/ServiceNow-MCP)
[![Tools](https://img.shields.io/badge/496%20Tools-45%20Modules-0F4C81?style=flat-square)](docs/TOOLS.md)
[![npm](https://img.shields.io/npm/v/%40tedorigawa001%2Fservicenow-mcp?style=flat-square&logo=npm&color=CB3837)](https://www.npmjs.com/package/@tedorigawa001/servicenow-mcp)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-f59e0b?style=flat-square)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-20.19%2B-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-0F4C81?style=flat-square)](https://modelcontextprotocol.io)

<br/>

## AI から ServiceNow を自然言語で操作する MCP サーバー

> **ローカル PC で動作 · 496 ツール · 5 分セットアップ · MIT ライセンス**

Claude・Cursor・VS Code などの AI ツールから、ServiceNow のインシデント・変更・CMDB・スクリプトなどをすべて自然言語で操作できます。

### v1.11.1 ハイライト

- Update Set 内のスクリプト系 Customer Update から、固定バージョンの npm コンポーネントを検出し、OSV の advisory と照合する読み取り専用 SCA ツール `scan_update_set_sca` を追加
- SCA は本文・payload・一致箇所を返さず、メタデータ・ハッシュ・PURL・証跡のみを返却。未解決参照や照会失敗を「脆弱性なし」と誤認しない JSON 契約を提供
- 依存関係を更新して既知の到達可能な脆弱性を解消。最新の検証では 496 ツール、59 テストファイル、1,553 テストを確認

</div>

---

## このツールが何をするか（初心者向け）

```mermaid
flowchart TD
    subgraph PC["💻 あなたの PC"]
        direction TB
        AI["🤖 AI クライアント<br/>(Claude Desktop / Cursor / VS Code)"]
        MCP["⚙️ servicenow-mcp サーバー<br/>(ここがこのツール)"]
        AI <-->|"MCP プロトコル (stdio)"| MCP
    end
    
    SN["☁️ ServiceNow インスタンス<br/>(開発 PDI または 社内環境)"]
    
    MCP <-->|"HTTPS / REST API<br/>(インターネット経由)"| SN

    style PC fill:#f0f7ff,stroke:#00509E,stroke-width:2px,color:#333,stroke-dasharray: 5 5
    style AI fill:#ffffff,stroke:#333,stroke-width:2px,color:#000
    style MCP fill:#e6ffe6,stroke:#008000,stroke-width:2px,color:#000
    style SN fill:#fff0f0,stroke:#cc0000,stroke-width:2px,color:#000
```

**ポイント:**
- サーバーは **あなたの PC 上で動く** Node.js プロセスです。通常のツールは ServiceNow とだけ通信します。SCA の OSV 脆弱性照会など、外部連携を行うツールは個別に明示します
- AI クライアントと stdio（標準入出力）で通信するため、ポート開放やネットワーク設定は不要
- ServiceNow へは HTTPS で接続します。既存のブラウザアクセスと同じ経路です

---

## 推奨環境

> **まずは開発インスタンス (PDI) でお試しください。**  
> 本番環境への接続は技術的には可能ですが、AI の誤操作・意図しないレコード更新を防ぐため、  
> **はじめは読み取り専用モード (`WRITE_ENABLED=false`) で動作を確認してから本番適用してください。**

| 環境 | 推奨度 | 注意 |
|------|--------|------|
| **PDI (無料開発インスタンス)** | ★★★ 推奨 | 無料。操作の影響なし。初めて使う方はここから |
| **社内開発・検証インスタンス** | ★★☆ 可 | チームと共有している場合は読み取り専用で開始 |
| **本番インスタンス** | ★☆☆ 要注意 | `WRITE_ENABLED=false` + 専用サービスアカウント必須 |

無料 PDI → [developer.servicenow.com](https://developer.servicenow.com)

---

## 動作の仕組み

```mermaid
sequenceDiagram
    participant U as あなた
    participant AI as AI クライアント<br/>(Claude / Cursor)
    participant MCP as servicenow-mcp<br/>(ローカル PC)
    participant SN as ServiceNow<br/>(クラウド)

    U->>AI: 「P1 インシデントを一覧表示して」
    AI->>MCP: list_incidents(priority=1) を呼び出す
    MCP->>MCP: 権限チェック (読み取りは常に許可)
    MCP->>SN: GET /api/now/table/incident?sysparm_query=priority=1
    SN-->>MCP: JSON でインシデント一覧を返す
    MCP-->>AI: ツール結果を返す
    AI-->>U: 「現在 3 件の P1 インシデントがあります...」
```

---

## はじめての方向け — 5 分セットアップ

```mermaid
flowchart TD
    A([はじめる]) --> B{ServiceNow\nインスタンスはある?}
    B -->|ない| C[developer.servicenow.com\nで無料 PDI を取得\n約 10 分]
    B -->|ある| D
    C --> D{Node.js 20.19+\nインストール済み?}
    D -->|ない| E[nodejs.org から\nLTS 版をインストール]
    E --> F
    D -->|あり| F[ターミナルでコマンド実行]

    F --> G["npm install -g @tedorigawa001/servicenow-mcp"]
    G --> H["servicenow-mcp setup"]
    H --> I{セットアップ\nウィザード}
    I --> J[インスタンス URL を入力\n例: https://dev12345.service-now.com]
    J --> K[OAuth グラントタイプを選択\nclient_credentials または password]
    K --> L[OAuth 認証情報を入力]
    L --> M[接続テスト]
    M -->|失敗| N[URL・認証情報を確認]
    N --> L
    M -->|成功| O[AI クライアントを自動検出]
    O --> P[設定ファイルを自動書き込み]
    P --> Q([完了！\nAI から ServiceNow に繋がります])
```

### ステップ 1 — インストール

**方法 A: npm からインストール（推奨・最速）**

```bash
# Node.js のバージョン確認 (20.19 以上が必要)
node --version

# グローバルインストール
npm install -g @tedorigawa001/servicenow-mcp

# セットアップウィザードを起動
servicenow-mcp setup
```

**方法 B: ソースからビルド（開発・カスタマイズしたい方向け）**

```bash
# リポジトリをクローン
git clone https://github.com/tedorigawa001/ServiceNow-MCP.git
cd ServiceNow-MCP

# 依存パッケージのインストール & コンパイル
npm install
npm run build

# セットアップウィザードを起動
npm run setup
```

どちらの方法でも、ウィザードが Claude Desktop・Cursor・VS Code などを自動検出し、設定ファイルを自動で書き込みます(VS Code は `npx ... server` 起動 + シークレットは `inputs` 化、それ以外は `dist/server.js` の絶対パス)。

### ステップ 2 — AI クライアントを再起動

設定ファイルを書き込んだあと、Claude Desktop や Cursor を **一度完全に終了して再起動** してください。

### ステップ 3 — 動作確認

AI に話しかけてみましょう:
```
「ServiceNow に接続して、直近のインシデントを 5 件表示してください」
```

---

## Docker での起動

![Docker 構成図](docs/images/docker-architecture.svg)

### ソースビルド vs Docker — どちらを選ぶか

| 比較項目 | ソースビルド（`node dist/server.js`） | Docker（`docker run`） |
|---------|--------------------------------------|----------------------|
| **起動速度** | ✅ 即時 | ⚠️ コンテナ起動分のオーバーヘッドあり |
| **設定のシンプルさ** | ⚠️ 絶対パスが必要 | ✅ `docker` コマンドのみ |
| **環境依存** | Node.js 20.19+ が必要 | Docker が必要 |
| **環境の統一** | ⚠️ ホスト環境に依存 | ✅ どの PC でも同一環境 |
| **チーム配布・CI/CD** | ⚠️ 各自でビルドが必要 | ✅ イメージを共有するだけ |
| **推奨シーン** | 個人利用・開発 | チーム配布・本番運用 |

### イメージのビルドと起動

```bash
# イメージをビルド
docker build -t servicenow-mcp .

# 起動
docker run --rm -i \
  -e SERVICENOW_INSTANCE_URL=https://yourinstance.service-now.com \
  -e SERVICENOW_OAUTH_CLIENT_ID=your_client_id \
  -e SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret \
  servicenow-mcp
```

Password Grant を使う場合は、さらに以下を追加します:

```bash
  -e SERVICENOW_OAUTH_USERNAME=service_account_user \
  -e SERVICENOW_OAUTH_PASSWORD=service_account_password \
```

### AI クライアントから接続する（Claude Desktop）

`claude_desktop_config.json` の `command` / `args` を以下のように変更します。
Client Credentials を使う場合は `SERVICENOW_OAUTH_USERNAME` と `SERVICENOW_OAUTH_PASSWORD` の 2 行を省略してください。

```json
{
  "mcpServers": {
    "servicenow": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "SERVICENOW_INSTANCE_URL=https://yourinstance.service-now.com",
        "-e", "SERVICENOW_OAUTH_CLIENT_ID=your_client_id",
        "-e", "SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret",
        "-e", "SERVICENOW_OAUTH_USERNAME=service_account_user",
        "-e", "SERVICENOW_OAUTH_PASSWORD=service_account_password",
        "servicenow-mcp"
      ]
    }
  }
}
```

> **注意**: `-i` フラグは必須です。MCP は stdio（標準入出力）で通信するため、インタラクティブモードが必要です。

> **HTTP モードで起動する場合**: コンテナ内の既定バインドは `127.0.0.1` のため公開ポートからは到達できません。
> `-e MCP_TRANSPORT=http -e MCP_HTTP_HOST=0.0.0.0 -p 3000:3000` を付与してください。
> イメージは非 root(`node` ユーザー)で動作し、`EXPOSE 3000` 済みです。

---

## 認証方式（OAuth 2.0 のみ）

このサーバーは **OAuth 2.0 のみ** をサポートします。Basic Auth はセキュリティリスク（資格情報が平文で設定ファイルに残る）があるため廃止しました。

OAuth 2.0 には 2 種類のグラントタイプがあり、用途に応じて自動選択されます。

```mermaid
flowchart TD
    START([OAuth 設定]) --> Q1{ユーザー名/パスワードを\n設定する?}
    Q1 -->|しない| CC["Client Credentials Grant\ngrant_type=client_credentials\n\nclient_id + client_secret のみ\n推奨: サービス間連携・自動化"]
    Q1 -->|する| PW["Password Grant\ngrant_type=password\n\nclient_id + client_secret\n+ username + password\n既存ユーザー権限を引き継ぎたい場合"]
    CC --> CC_NOTE["ServiceNow が Application Registry 上の\nスコープで API を実行する"]
    PW --> PW_NOTE["指定ユーザーの権限でAPIを実行する\n(ACL・ロールがそのまま適用)"]
```

### Client Credentials（推奨）

`client_id` と `client_secret` だけで動作します。ユーザー資格情報が不要なため、サービス間連携に最適です。

```bash
SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com
SERVICENOW_OAUTH_CLIENT_ID=your_client_id
SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret
```

### Password Grant（ユーザー権限を引き継ぐ場合）

特定ユーザーの ACL・ロールで API を実行したい場合に使います。

```bash
SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com
SERVICENOW_OAUTH_CLIENT_ID=your_client_id
SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret
SERVICENOW_OAUTH_USERNAME=svc_mcp
SERVICENOW_OAUTH_PASSWORD=your_password
```

---

## OAuth セットアップ手順

> OAuth は ServiceNow の管理者権限が必要です。PDI では自分で設定できます。

### ServiceNow 側の設定

**Step 1 — OAuth アプリケーションレジストリを作成**

1. ServiceNow にログイン
2. 左メニューで「Application Registry」を検索
3. 「New」→ **「New Inbound Integration Experience」** を選択

> ⚠️ 「[Deprecated UI] Create an OAuth API endpoint for external clients」は**旧 UI** です。  
> 現行バージョンでは **New Inbound Integration Experience** を使用してください。

グラントタイプによって設定が異なります。

#### Client Credentials Grant（推奨）

> **重要**: Client Credentials Grant では ServiceNow 側でユーザーを指定する必要があります。  
> これは標準 OAuth の仕様とは異なる ServiceNow 固有の要件です。  
> アクセストークンは「どのユーザーとして API を実行するか」を ServiceNow が決定するために使用します。

```
Name:              servicenow-mcp
Token Format:      JWT                ← 必須
Client ID:         (自動生成)
Client Secret:     (自動生成 → コピーして保存)
Redirect URL:      http://localhost
Access Token Lifespan: 1800 (秒)
Default Grant user: svc_mcp          ← 必須: API を実行するサービスアカウントを指定
```

`Default Grant user` に指定したユーザーの **ロール・ACL** が API 実行時に適用されます。  
このユーザーには必要最小限の ServiceNow ロール（例: `itil`, `admin` 等）を付与してください。

#### Password Grant

```
Name:              servicenow-mcp
Token Format:      JWT                ← 必須
Client ID:         (自動生成)
Client Secret:     (自動生成 → コピーして保存)
Redirect URL:      http://localhost
Access Token Lifespan: 1800 (秒)
Default Grant user: (不要 — username/password で指定したユーザーが使われます)
```

「Submit」で保存。

**Step 2 — 生成された Client ID / Secret を確認**

作成したレジストリを開き、`Client ID` と `Client Secret` をメモします。

```mermaid
flowchart LR
    A[Application Registry を開く] --> B[Client ID をコピー]
    A --> C[Client Secret をコピー\nShow をクリック]
    B & C --> D[環境変数に設定]
```

### MCP サーバー側の設定

#### Client Credentials Grant

```bash
SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com
SERVICENOW_OAUTH_CLIENT_ID=your_client_id
SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret
# SERVICENOW_OAUTH_USERNAME / PASSWORD は不要
```

#### Password Grant

```bash
SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com
SERVICENOW_OAUTH_CLIENT_ID=your_client_id
SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret
SERVICENOW_OAUTH_USERNAME=svc_mcp
SERVICENOW_OAUTH_PASSWORD=your_password
```

接続確認:
```bash
node dist/cli/index.js auth test
```

---

## AI クライアント別セットアップ

### Claude Desktop

設定ファイル: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/path/to/servicenow-mcp/dist/server.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://dev12345.service-now.com",
        "SERVICENOW_OAUTH_CLIENT_ID": "your_client_id",
        "SERVICENOW_OAUTH_CLIENT_SECRET": "your_client_secret",
        "WRITE_ENABLED": "false"
      }
    }
  }
}
```

> `WRITE_ENABLED: "false"` にしておくと読み取り専用になります。動作確認が終わったら `"true"` に変更できます。  
> ユーザー権限を引き継ぐ場合は `SERVICENOW_OAUTH_USERNAME` と `SERVICENOW_OAUTH_PASSWORD` も追加してください。

### Claude Code CLI

```bash
claude mcp add servicenow node /path/to/servicenow-mcp/dist/server.js \
  --env SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com \
  --env SERVICENOW_OAUTH_CLIENT_ID=your_client_id \
  --env SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret \
  --env WRITE_ENABLED=false
```

### Cursor

設定ファイル: `.cursor/mcp.json`

```json
{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/path/to/servicenow-mcp/dist/server.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://dev12345.service-now.com",
        "SERVICENOW_OAUTH_CLIENT_ID": "your_client_id",
        "SERVICENOW_OAUTH_CLIENT_SECRET": "your_client_secret",
        "WRITE_ENABLED": "true",
        "SCRIPTING_ENABLED": "true"
      }
    }
  }
}
```

### VS Code (1.99+)

設定ファイル: `.vscode/mcp.json`(ワークスペースルート)

`.vscode/` はコミットされがちなので、シークレットは平文で書かず VS Code の `inputs`(初回起動時にプロンプト表示・暗号化保存)に逃がします。セットアップウィザードもこの形式で書き込みます。

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "servicenow-client-secret",
      "description": "ServiceNow OAuth client secret",
      "password": true
    }
  ],
  "servers": {
    "servicenow-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@tedorigawa001/servicenow-mcp", "server"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://dev12345.service-now.com",
        "SERVICENOW_OAUTH_CLIENT_ID": "your_client_id",
        "SERVICENOW_OAUTH_CLIENT_SECRET": "${input:servicenow-client-secret}"
      }
    }
  }
}
```

### 対応クライアント一覧

| クライアント | 種別 | ガイド |
|------------|------|--------|
| Claude Desktop | デスクトップ | [Setup](clients/claude-desktop/SETUP.md) |
| Claude Code CLI | ターミナル | [Setup](clients/claude-code/SETUP.md) |
| Cursor | AI エディタ | [Setup](clients/cursor/SETUP.md) |
| Windsurf | AI エディタ | [Setup](docs/CLIENT_SETUP.md) |
| VS Code (Native MCP 1.99+) | IDE | [Setup](clients/vscode/SETUP.md) |
| VS Code + GitHub Copilot | IDE | [Setup](clients/vscode/SETUP.md) |
| VS Code + Continue.dev | IDE | [Setup](docs/CLIENT_SETUP.md) |
| VS Code + Cline | IDE | [Setup](docs/CLIENT_SETUP.md) |
| JetBrains AI | IDE | [Setup](docs/CLIENT_SETUP.md) |
| Amazon Q Developer | IDE / CLI | [Setup](docs/CLIENT_SETUP.md) |
| ChatGPT / OpenAI API | API | [Setup](clients/codex/SETUP.md) |
| Google Gemini API | API | [Setup](clients/gemini/SETUP.md) |
| Ollama (ローカル LLM) | ローカル | [Setup](docs/CLIENT_SETUP.md) |

全クライアントのセットアップ詳細 → [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md)

---

## トランスポート（stdio / HTTP）

デフォルトは **stdio**（標準入出力）で、ポート開放やネットワーク設定は不要です。
ブラウザ経由の接続（Claude.ai Web UI）、Docker コンテナ公開、複数クライアントでのサーバー共有、
CI/CD からの呼び出しが必要な場合は **Streamable HTTP** トランスポートに切り替えられます。

```bash
# HTTP トランスポートで起動（トークンはランダムな十分長い値を使用）
MCP_TRANSPORT=http MCP_HTTP_AUTH_TOKEN=replace-with-a-random-secret node dist/server.js
# → http://127.0.0.1:3000/mcp で待ち受け、GET /health でヘルスチェック
```

| 環境変数 | デフォルト | 説明 |
|---|---|---|
| `MCP_TRANSPORT` | `stdio` | `http` で Streamable HTTP に切り替え |
| `MCP_HTTP_PORT` | `3000` | 待ち受けポート |
| `MCP_HTTP_HOST` | `127.0.0.1` | バインドアドレス（外部公開時は `0.0.0.0`）|
| `MCP_HTTP_PATH` | `/mcp` | MCP エンドポイントのパス |
| `MCP_HTTP_AUTH_TOKEN` | (必須) | MCP エンドポイント用 Bearer トークン。未設定時は `/mcp` への要求をすべて401で拒否 |
| `MCP_HTTP_CORS_ORIGIN` | `*` | CORS 許可オリジン |
| `MCP_HTTP_ALLOWED_HOSTS` | (なし) | カンマ区切り。指定すると DNS リバインディング保護を有効化 |
| `MCP_HTTP_ALLOWED_ORIGINS` | (なし) | カンマ区切り。Origin ヘッダの許可リスト |
| `MCP_HTTP_MAX_BODY_BYTES` | `1048576` | JSON-RPC 要求本文の最大バイト数 |
| `MCP_HTTP_MAX_SESSIONS` | `100` | 同時 HTTP MCP セッションの上限 |
| `MCP_HTTP_SESSION_IDLE_TIMEOUT_MS` | `1800000` | 未使用セッションを閉じるまでのミリ秒 |

セッションは MCP 仕様に従い、`initialize` 応答の `Mcp-Session-Id` ヘッダで払い出され、
以降のリクエストで再利用します（`DELETE /mcp` でセッション終了）。HTTP 接続するクライアント設定例:

```json
{
  "mcpServers": {
    "servicenow": {
    "url": "http://localhost:3000/mcp",
    "headers": { "Authorization": "Bearer replace-with-a-random-secret" }
    }
  }
}
```

> **セキュリティ注意**: HTTP MCP は `MCP_HTTP_AUTH_TOKEN` を必須とします。デフォルトは loopback（`127.0.0.1`）バインドです。`MCP_HTTP_HOST=0.0.0.0`
> で外部公開する場合は、リバースプロキシでの TLS 終端・認証、および `MCP_HTTP_ALLOWED_HOSTS` /
> `MCP_HTTP_ALLOWED_ORIGINS` による保護を推奨します。

---

## 権限設定（何ができるかを制御する）

デフォルトは**読み取り専用**です。操作範囲を広げたい場合は環境変数で段階的に有効化します。

```mermaid
graph TD
    T0["🛡️ Tier 0: 常時有効 (デフォルト)<br/>インシデント表示 / KB 検索 / レコード参照..."]
    T1["✏️ Tier 1: WRITE_ENABLED=true<br/>インシデント作成・更新 / 変更リクエスト管理..."]
    T2["🧩 Tier 2: CMDB_WRITE_ENABLED=true (Tier 1も必要)<br/>CI の作成・更新 / 関連付け管理..."]
    T3["⚙️ Tier 3: SCRIPTING_ENABLED=true (Tier 1も必要)<br/>ビジネスルール / スクリプト / Update Set..."]
    TAI["🤖 Tier AI: NOW_ASSIST_ENABLED=true<br/>NLQ / AI サマリー / Agentic Playbook..."]
    
    T0 --> T1
    T1 --> T2
    T1 --> T3
    T0 -.->|"独立オプション"| TAI

    style T0 fill:#f5f5f5,stroke:#999,stroke-width:2px,color:#333
    style T1 fill:#e3f2fd,stroke:#2196f3,stroke-width:2px,color:#000
    style T2 fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#000
    style T3 fill:#ffebee,stroke:#f44336,stroke-width:2px,color:#000
    style TAI fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000
```

**本番環境で使う場合の推奨設定:**
```bash
WRITE_ENABLED=false          # まずは読み取りのみで確認
CMDB_WRITE_ENABLED=false
SCRIPTING_ENABLED=false      # 本番では原則 false のまま
```

---

## ロールベース ツールパッケージ

`MCP_TOOL_PACKAGE` 環境変数でツールを絞り込めます。全部入りではなく、用途に応じたセットを使うと AI が迷わずに済みます。

```mermaid
mindmap
  root((ツールパッケージ))
    full
      全496ツール
    service_desk
      インシデント管理
      タスク/承認
      KB検索
      SLA確認
    change_coordinator
      変更管理
      CABスケジュール
      CMDB参照
    platform_developer
      スクリプト管理
      ACL/UI Policy
      ATFテスト
      Update Set
    system_administrator
      ユーザー/グループ管理
      レポート/ログ
      PA ダッシュボード
    itom_engineer
      CMDB
      Discovery
      MIDサーバー
    ai_developer
      Now Assist
      NLQ
      Agentic Playbooks
    secops_analyst
      VI作成/RT横断検索
      グルーピング診断
      SLA/例外承認
```

| パッケージ名 | 対象ロール | 主なツール |
|------------|----------|-----------|
| `full` | 管理者 | 全ツール (496) |
| `service_desk` | L1/L2 エージェント | インシデント・タスク・KB・SLA |
| `change_coordinator` | 変更管理者 | 変更リクエスト・CAB・CMDB |
| `knowledge_author` | KB 著者 | KB 作成・公開 |
| `catalog_builder` | カタログ管理者 | カタログ・承認ルール |
| `system_administrator` | システム管理者 | ユーザー・グループ・レポート |
| `platform_developer` | 開発者 | スクリプト・ATF・Update Set |
| `portal_developer` | ポータル開発者 | ポータル・ウィジェット・UX |
| `integration_engineer` | 統合エンジニア | REST・Transform・イベント |
| `itom_engineer` | ITOM エンジニア | CMDB・Discovery(実行履歴/エラー調査)・MID ヘルス・ACC |
| `agile_manager` | スクラムマスター | ストーリー・エピック |
| `ai_developer` | AI 開発者 | Now Assist・NLQ・Playbook |
| `itam_analyst` | 資産管理者 | 資産・ライセンス・契約・SAM Pro(ソフトウェア資産管理) |
| `secops_analyst` | SecOps アナリスト | 脆弱性(VI/RT)・RT横断検索・グルーピング診断・USEM・SLA・例外承認 |
| `devops_engineer` | DevOps | パイプライン・デプロイ |

詳細 → [docs/TOOL_PACKAGES.md](docs/TOOL_PACKAGES.md)

---

## 使用例

### 自然言語で操作する

```
「Network Operations グループの P1 インシデントをすべて表示して」

「INC0012345 に "調査中。30 分以内に更新します" とワークノートを追加して」

「SAP 本番システムの障害でインシデントを作成して。
  優先度 Critical、Network Ops グループに割り当てて」

「先月の Priority 別インシデント件数をグラフ用データで出して」
```

### 典型的なやりとりの流れ

```mermaid
sequenceDiagram
    participant U as あなた
    participant AI as AI アシスタント
    participant MCP as servicenow-mcp
    participant SN as ServiceNow

    U->>AI: 「SAP の P1 インシデントを作って」
    AI->>MCP: create_incident を呼び出す
    MCP->>MCP: WRITE_ENABLED チェック ✅
    MCP->>SN: POST /api/now/table/incident
    SN-->>MCP: INC0099001 作成完了
    MCP-->>AI: 作成結果を返す
    AI-->>U: 「INC0099001 を作成しました」

    U->>AI: 「SAP サーバーの CMDB 依存関係も確認して」
    AI->>MCP: search_cmdb_ci + list_relationships
    MCP->>SN: CMDB API を 2 回呼び出す
    SN-->>MCP: 依存 CI 8 件
    MCP-->>AI: 依存関係リスト
    AI-->>U: 「SAP-PROD-DB01 は 8 つの CI に依存しています」
```

### Update Set の第三者コンポーネントを SCA する

`scan_update_set_sca` は **読み取り専用**で Update Set 内のスクリプト系 Customer Update を収集し、固定バージョンが確認できる npm コンポーネントを検出します。既定では [OSV](https://osv.dev) に照会して advisory を JSON で返します。コード本文・payload・一致箇所の文字列は返しません。

```
「Release 1.12 Update Set を SCA スキャンして。検出したコンポーネント、
脆弱性、照会できなかった項目、次の対応を JSON の根拠だけで報告して」
```

ローカル収集だけを先に確認したい場合は、AI に `lookup_vulnerabilities: false` を指定します。

```json
{
  "update_set": "46f0...",
  "max_records": 50,
  "lookup_vulnerabilities": false
}
```

AI への報告依頼例:

```
scan_update_set_sca の JSON だけを根拠に報告してください。
critical / high を最優先にし、各 finding は component、installed_version、
advisory_id、fixed_versions、evidence の asset_type と asset_name を示してください。
summary.assessment、lookup.status、errors、unresolved_references、truncated を必ず確認し、
対象外・未照会・失敗を「脆弱性なし」と表現しないでください。
修正は自動実行せず、Update Set の変更案と確認手順を提案してください。
```

> **制約**: `findings` が空でも安全性は証明されません。バージョン範囲、`latest` のような CDN alias、バージョンなしのモジュール参照は CVE 照合できず `unresolved_references` として返ります。CDN URL を検出しても、そのライブラリが実際にロード・実行されたことまでは示しません。また SCA は依存コンポーネントを対象にするものであり、ServiceNow のカスタムスクリプトに対する SAST、権限設計、クエリ安全性のレビューを代替しません。

### スラッシュコマンド & @メンション

```
/morning-standup  → P1/P2 オープンインシデント・当日変更・SLA 違反のサマリー
/my-tickets       → 自分に割り当てられたオープンタスク一覧
/p1-alerts        → アクティブな P1 インシデント一覧

@my-incidents     → 自分のインシデントをコンテキストに追加
@ci:web-prod-01   → CMDB CI レコードをコンテキストに追加
@kb:VPN-setup     → KB 記事をコンテキストに追加
```

120+ の実例 → [EXAMPLES.md](EXAMPLES.md)

---

## マルチインスタンス対応

```mermaid
graph LR
    User["あなたの PC\n(AI + MCP サーバー)"] -->|dev| DEV[(開発 PDI\ndev12345.service-now.com)]
    User -->|staging| STG[(検証\nstg.company.com)]
    User -->|prod| PRD[(本番\nacme.service-now.com)]
```

```json
{
  "default_instance": "dev",
  "instances": {
    "dev": {
      "url": "https://dev12345.service-now.com",
      "client_id": "dev-client-id",
      "client_secret": "dev-client-secret"
    },
    "prod": {
      "url": "https://acme.service-now.com",
      "auth": "oauth",
      "client_id": "xxx",
      "client_secret": "yyy",
      "username": "svc_account",
      "password": "zzz"
    }
  }
}
```

```bash
SN_INSTANCES_CONFIG=/path/to/instances.json
```

詳細 → [docs/MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md)

---

## モジュールカバレッジ

```mermaid
graph TB
    subgraph ITSM["ITSM & サービス管理"]
        I1[インシデント管理]
        I2[問題管理]
        I3[変更管理]
        I4[タスク管理]
        I5[ナレッジベース]
        I6[サービスカタログ]
    end

    subgraph PLATFORM["プラットフォーム & 開発"]
        P1[スクリプト/ビジネスルール]
        P2[Flow Designer]
        P3[Service Portal / UIB]
        P4[ATF テスト]
        P5[Update Set 管理]
        P6[App Studio]
    end

    subgraph OPS["運用 & 分析"]
        O1[CMDB / ITOM]
        O2[Performance Analytics]
        O3[レポート / 集計]
        O4[通知 / 添付]
        O5[システムプロパティ]
        O6[DevOps パイプライン]
        O7[インスタンス診断 / 性能履歴]
    end

    subgraph EXTENDED["拡張モジュール"]
        E1[HRSD]
        E2[CSM]
        E3[SecOps / GRC]
        E4[Agile / Scrum]
        E5[IT 資産管理]
        E6[Virtual Agent]
    end

    subgraph AI["AI & インテグレーション"]
        A1[Now Assist / AI]
        A2[Integration Hub]
        A3[Machine Learning]
        A4[モバイル]
        A5[ワークスペース]
    end
```

---

## プロジェクト構造

```
servicenow-mcp/
├── src/
│   ├── server.ts                   # MCP サーバーエントリーポイント
│   ├── servicenow/
│   │   ├── client.ts               # REST API クライアント (OAuth)
│   │   ├── instances.ts            # マルチインスタンスマネージャー
│   │   └── types.ts                # TypeScript 型定義
│   ├── tools/                      # 45 ドメインモジュール (496 ツール)
│   │   ├── index.ts                # ツールルーター & パッケージ定義
│   │   ├── incident.ts
│   │   ├── change.ts
│   │   ├── knowledge.ts
│   │   └── ...
│   ├── prompts/                    # スラッシュコマンド定義
│   ├── resources/                  # @メンション定義
│   ├── cli/                        # セットアップウィザード
│   └── utils/
│       ├── permissions.ts          # 5 段階権限ゲート
│       └── errors.ts
├── tests/                          # テスト (Vitest · 1,553 件)
├── docs/                           # ドキュメント
└── instances.example.json
```

---

## 開発

```bash
npm install          # 依存パッケージのインストール
npm run build        # TypeScript → dist/ にコンパイル
npm test             # テストを実行 (1,553 件)
npm run dev          # ウォッチモード
npm run type-check   # 型チェックのみ
npm run lint         # ESLint
```

---

## よくある質問

**ServiceNow の API 知識は必要ですか？**  
いいえ。「P1 インシデントを一覧表示して」のように日本語で話しかけるだけです。API 呼び出しはサーバーが自動で行います。

**本番環境に接続しても大丈夫ですか？**  
`WRITE_ENABLED=false`（デフォルト）で接続する分には読み取りのみで安全です。書き込みを有効にする前に、必ず開発環境で動作を確認してください。

**無料で使えますか？**  
このサーバー自体は MIT ライセンスで無料です。ServiceNow の無料 PDI（Personal Developer Instance）も [developer.servicenow.com](https://developer.servicenow.com) で取得できます。AI クライアント側（Claude Pro 等）の料金は各サービスに従います。

**MCP って何ですか？**  
Model Context Protocol の略で、AI クライアントが外部ツールを呼び出すための標準規格です。Claude・Cursor などが対応しています。このサーバーは MCP に準拠しているため、対応 AI から自動的に発見・使用されます。

**複数インスタンスに接続できますか？**  
はい。`instances.json` で dev / staging / prod を定義しておき、「本番インスタンスに切り替えて」と指示するだけで切り替わります。

---

## ドキュメント

| ガイド | 内容 |
|-------|------|
| [docs/INSTALLATION.md](docs/INSTALLATION.md) | 環境変数リファレンス |
| [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md) | 全 AI クライアントのセットアップ |
| [docs/SERVICENOW_OAUTH_SETUP.md](docs/SERVICENOW_OAUTH_SETUP.md) | ServiceNow OAuth アプリ作成手順（詳細版） |
| [docs/TOOL_PACKAGES.md](docs/TOOL_PACKAGES.md) | ロールベースパッケージの詳細 |
| [docs/TOOLS.md](docs/TOOLS.md) | 全ツールのパラメータ・権限要件 |
| [docs/MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md) | マルチインスタンス設定 |
| [docs/NOW_ASSIST.md](docs/NOW_ASSIST.md) | Now Assist / AI 統合 |
| [docs/ATF.md](docs/ATF.md) | ATF テストガイド |
| [EXAMPLES.md](EXAMPLES.md) | 120+ 実用例 |
| [SECURITY.md](SECURITY.md) | セキュリティポリシー・脆弱性報告 |
| [CHANGELOG.md](CHANGELOG.md) | 変更履歴 |

---

## コントリビュート

[CONTRIBUTING.md](CONTRIBUTING.md) をお読みの上、Pull Request をお送りください。  
バグ報告・機能要望 → [Issue を開く](../../issues)

---

## セキュリティ

脆弱性を発見した場合は **公開 Issue には投稿せず**、[SECURITY.md](SECURITY.md) の責任ある開示プロセスに従ってください。

---

## ライセンス

[MIT](LICENSE) — 個人・商用利用とも無料。

---

<div align="center">

**496 ツール · 45 モジュール · ローカル PC で動作 · 永久オープンソース**

役に立ったら ⭐ スターをお願いします — 他の人が見つけやすくなります。

[![GitHub Stars](https://img.shields.io/github/stars/tedorigawa001/ServiceNow-MCP?style=social)](https://github.com/tedorigawa001/ServiceNow-MCP/stargazers)

</div>