# ServiceNow MCP Demo — Incident Assistant

An end-to-end **Model Context Protocol** demo that connects Claude to **ServiceNow Incident Management**. Built to showcase MCP fundamentals (servers, clients, tools, resources, stdio transport, agent loops) applied to a real ITSM workflow.

## Architecture

```
┌─────────────────────────────┐        ┌───────────────────────────────┐        ┌────────────────┐
│  Web Client (Streamlit)     │  MCP   │  MCP Server (FastMCP)         │  REST  │  ServiceNow    │
│  - MCP host + client        │◄──────►│  - create_incident            │◄──────►│  Table API     │
│  - Claude agent loop        │ stdio  │  - get_incident               │        │  (or mock mode)│
│  - Incident cards in UI     │JSON-RPC│  - list_recent_incidents      │        │                │
│                             │        │  - update_incident_state      │        │                │
│                             │        │  - resolve_incident           │        │                │
│                             │        │  - search_knowledge_articles  │        │                │
│                             │        │  - resource: priority         │        │                │
│                             │        │    matrix reference           │        │                │
└─────────────────────────────┘        └───────────────────────────────┘        └────────────────┘
```

Flow for "my laptop won't boot, open a ticket":
1. The web client sends your message to Claude along with the tool schemas it **discovered from the MCP server** at startup (`tools/list`).
2. Claude decides to call `create_incident` with inferred urgency/impact/category.
3. The client forwards the call over MCP (`tools/call`); the server hits the ServiceNow Table API (or the in-memory mock).
4. The result flows back; Claude confirms the incident number; the UI renders an incident card.

## Quick start

```bash
# 1. Create a virtual environment
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure
cp .env.example .env             # then edit: add your ANTHROPIC_API_KEY
                                 # leave SERVICENOW_MODE=mock for a no-setup demo

# 4. Run the web client (it launches the MCP server automatically)
streamlit run client/app.py
```

Open http://localhost:8501 and try:
- *"My laptop won't boot and I have a client demo in an hour — open a ticket."*
- *"Show me the 5 most recent incidents."*
- *"Move INC0010001 to In Progress with a work note that the tech is en route."*
- *"Any KB articles on a laptop that won't power on?"*
- *"That fixed it — resolve INC0010001, solved permanently, replaced the charger."*

## Live ServiceNow mode

1. Request a free **Personal Developer Instance (PDI)** at https://developer.servicenow.com (takes ~2 minutes).
2. In `.env`, set `SERVICENOW_MODE=live` and fill in `SERVICENOW_INSTANCE`, `SERVICENOW_USER`, `SERVICENOW_PASSWORD`.
3. Restart the app. Created incidents will appear in your PDI under **Incident > All** — great for showing the ticket in the real ServiceNow UI during the demo.

> PDIs hibernate after inactivity. Wake yours up ~15 minutes before your interview, and keep `mock` mode as a fallback.

> `search_knowledge_articles` queries the PDI's `kb_knowledge` table directly — before demoing in live mode, seed 2–3 **published** KB articles there with titles matching your demo scenario (e.g. "Laptop won't power on"), or the live search will come back empty. Mock mode already ships with 3 seeded articles so it works out of the box.

## Testing the server standalone (no UI)

The MCP Inspector is the fastest way to prove the server works on its own:

```bash
npx @modelcontextprotocol/inspector python server/servicenow_server.py
```

You can also add the server to **Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "servicenow": {
      "command": "python",
      "args": ["/absolute/path/to/server/servicenow_server.py"]
    }
  }
}
```

## Project layout

```
servicenow-mcp-demo/
├── server/servicenow_server.py   # FastMCP server: 6 tools + 1 resource, mock/live backends
├── client/app.py                 # Streamlit web app: MCP client + Claude agent loop
├── requirements.txt
├── .env.example
├── PROJECT_PLAN.md               # Phase-by-phase build plan and status
└── DEMO_SCRIPT.md                # 5-minute recorded-demo script
```

## MCP concepts demonstrated

- **Server** built with FastMCP: tools with typed parameters and docstring-driven schemas
- **Resource** (`servicenow://reference/priority-matrix`) — read-only context, distinct from tools
- **stdio transport** — client launches the server subprocess and speaks JSON-RPC
- **Capability discovery** — the client never hardcodes tools; it calls `tools/list`
- **Agent loop** — multi-round tool use with Claude until a final text answer
- **Separation of concerns** — the same server works with this web client, Claude Desktop, or MCP Inspector, unchanged