# ServiceNow Incident MCP Server

A production-ready **Model Context Protocol (MCP)** server that turns any MCP-compatible
AI assistant (Claude, Cursor, etc.) into an **AI-powered ServiceNow Incident Management
Assistant**. It exposes ServiceNow incidents, users, CMDB records, and knowledge articles
through clean, validated MCP tools.

```
AI Assistant  ──►  MCP Server (Node.js + TypeScript)  ──►  ServiceNow REST API  ──►  ServiceNow Instance
```

## Features

- **12 MCP tools** across three phases (read, actions, AI-powered helpers).
- **Reusable ServiceNow REST client** (Axios) with Basic auth, request timeout,
  and **exponential-backoff retry** on transient failures.
- **Zod-validated** inputs for every tool.
- **Structured logging to stderr** with automatic **secret redaction** — passwords
  and auth headers are never logged.
- **Self-contained, deterministic AI tools** — no external LLM or API key required.
- **Modular, enterprise-grade architecture** with a full unit-test suite (Vitest).

## Project Structure

```
src/
├── clients/
│   └── servicenowClient.ts   # Axios wrapper: GET/POST/PATCH, auth, retry, timeout, Table API helpers
├── config/
│   └── env.ts                # Zod-validated environment configuration
├── schemas/
│   └── index.ts              # Zod input schemas for every tool
├── services/
│   ├── incidentService.ts    # incident reads/writes + journal (comments/work notes)
│   ├── userService.ts        # sys_user lookups
│   ├── cmdbService.ts        # cmdb_ci search
│   ├── knowledgeService.ts   # kb_knowledge search
│   ├── aiService.ts          # rule-based classification, routing, summaries
│   └── index.ts              # service container
├── tools/
│   ├── phase1.read.ts        # get_incident, search_incidents, get_user, search_cmdb, get_knowledge_article
│   ├── phase2.actions.ts     # create_incident, update_incident, assign_incident, close_incident
│   ├── phase3.ai.ts          # classify_incident, incident_summary, suggest_assignment_group
│   ├── helpers.ts            # response builders + central error handling
│   └── index.ts              # registers all tools
├── types/
│   └── servicenow.ts         # shared TypeScript interfaces
├── utils/
│   ├── logger.ts             # structured logger + redaction
│   ├── errors.ts             # ServiceNowError + safe message mapping
│   └── format.ts             # raw ServiceNow record → clean object mappers
├── server.ts                 # builds the MCP server (config → client → services → tools)
└── index.ts                  # entrypoint (stdio transport)
tests/                        # Vitest unit tests
```

## Setup

### Prerequisites
- Node.js **18+**
- A ServiceNow instance and an account with Table API access.

### Install & build

```bash
npm install
cp .env.example .env      # then edit .env with your instance + credentials
npm run build
```

### Configure environment

| Variable             | Required | Default | Description                                   |
| -------------------- | :------: | ------- | --------------------------------------------- |
| `SNOW_INSTANCE`      |   yes    | —       | Instance base URL, e.g. `https://dev123.service-now.com` |
| `SNOW_USERNAME`      |   yes    | —       | Basic auth username                           |
| `SNOW_PASSWORD`      |   yes    | —       | Basic auth password                           |
| `SNOW_TIMEOUT_MS`    |    no    | `30000` | Per-request timeout (ms)                      |
| `SNOW_MAX_RETRIES`   |    no    | `3`     | Retry attempts on network/429/5xx errors      |
| `SNOW_DEFAULT_LIMIT` |    no    | `10`    | Default result count for search tools         |
| `LOG_LEVEL`          |    no    | `info`  | `debug` \| `info` \| `warn` \| `error`        |

### Run

```bash
npm start          # run the built server (dist/index.js)
npm run dev        # run from TypeScript with hot reload
```

The server speaks MCP over **stdio**.

## Tool Reference

### Phase 1 — Read

| Tool | Input | Returns |
| ---- | ----- | ------- |
| `get_incident` | `{ incidentNumber }` | Number, state, priority, assignment group, assignee, descriptions, timestamps |
| `search_incidents` | `{ assignedTo?, caller?, priority?, state?, limit? }` | Matching incidents (newest first) |
| `get_user` | `{ userName }` | User name, email, phone, title, department |
| `search_cmdb` | `{ name, limit? }` | Matching CMDB CIs |
| `get_knowledge_article` | `{ keyword, limit? }` | Matching published KB articles |

### Phase 2 — Actions

| Tool | Input | Effect |
| ---- | ----- | ------ |
| `create_incident` | `{ shortDescription, description?, callerId?, assignmentGroup?, impact?, urgency? }` | Creates an incident → `{ incidentNumber, sysId }` |
| `update_incident` | `{ incidentNumber, workNote?, comment? }` | Appends work note / comment |
| `assign_incident` | `{ incidentNumber, assignmentGroup?, assignedTo? }` | Updates assignment |
| `close_incident` | `{ incidentNumber, closeNotes, closeCode? }` | Resolves & closes the incident |

### Phase 3 — AI-powered (deterministic, rule-based)

| Tool | Input | Returns |
| ---- | ----- | ------- |
| `classify_incident` | `{ issue }` | `{ impact, urgency, priority, reason }` |
| `incident_summary` | `{ incidentNumber }` | Executive summary built from the incident + journal |
| `suggest_assignment_group` | `{ issue }` | `{ assignmentGroup, reason }` |

## Classification Logic

`classify_incident` mirrors ServiceNow's **Impact × Urgency → Priority** matrix. It infers
**impact** from the *scope* of the issue and **urgency** from time-critical language, both via
documented keyword rules (case-insensitive, first match wins).

| Scope detected in the issue text | Impact | Urgency | Priority |
| -------------------------------- | :----: | :-----: | :------: |
| Entire office / company / site / everyone | 1 | 1 | **P1** |
| Entire team / department / group / floor  | 2 | 2 | **P2** |
| Single employee / one user / "my…"        | 3 | 2 | **P3** |
| Minor / cosmetic / typo / question / slow | 3 | 3 | **P4** |
| *Unrecognized (default)*                  | 3 | 3 | **P3** |

Time-critical words (`urgent`, `critical`, `outage`, `down`, `blocked`, `cannot work`,
`production`, `emergency`, …) escalate **urgency → 1**, and priority is recomputed from the matrix:

```
 Impact \ Urgency   1    2    3
        1          P1   P2   P3
        2          P2   P3   P4
        3          P3   P4   P4
```

`suggest_assignment_group` uses a keyword→group routing table (VPN/network → *Network
Operations*, email/Outlook → *Messaging & Collaboration*, password/login → *Identity & Access
Management*, database/SQL → *Database Team*, laptop/printer → *Desktop Support*, phone/call
forwarding → *Telephony*, application/crash → *Application Support*), defaulting to *Service Desk*.

> These rules live in `src/services/aiService.ts` and are easy to tune for your org's groups.

## Sample MCP Client Configuration

Add the server to your MCP client config. Use **absolute paths** and supply credentials via `env`.

**Claude Desktop** (`claude_desktop_config.json`) / **Cursor** (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/servicenow-mcp/dist/index.js"],
      "env": {
        "SNOW_INSTANCE": "https://dev12345.service-now.com",
        "SNOW_USERNAME": "admin",
        "SNOW_PASSWORD": "your-password",
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

Run `npm run build` first so `dist/index.js` exists.

## Testing & Quality

```bash
npm test            # run the unit test suite (Vitest)
npm run test:coverage
npm run typecheck   # tsc --noEmit
npm run lint        # eslint
```

Tests are fully offline — the ServiceNow client is mocked, and the AI tools are deterministic.

### Manual smoke test with MCP Inspector

```bash
npm run build
npx @modelcontextprotocol/inspector node dist/index.js
```

Then list tools and try `classify_incident` / `suggest_assignment_group` (work offline) or a
read tool against your instance.

## Security

- Credentials are read only from environment variables; `.env` is git-ignored.
- The logger redacts any `password` / `authorization` / `token` / `secret` field, and logs
  go to **stderr** only (keeping the MCP stdout channel clean).
- All HTTP requests use a configurable timeout and retry transient failures with
  exponential backoff; 4xx errors (other than 429) fail fast with safe messages.

## License

MIT