Metadata-Version: 2.4
Name: servicenow-mcp-agent
Version: 0.4.0
Summary: Claude-powered agent that manages ServiceNow incidents using MCP and AWS Bedrock
Project-URL: Homepage, https://github.com/Slalom-Consulting/servicenow-mcp-agent
Project-URL: Repository, https://github.com/Slalom-Consulting/servicenow-mcp-agent
Project-URL: Issues, https://github.com/Slalom-Consulting/servicenow-mcp-agent/issues
Author-email: Animesh Das <animesh.das@slalom.com>
License-Expression: MIT
Keywords: bedrock,claude,incident-management,mcp,servicenow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: anthropic[bedrock]
Requires-Dist: httpx
Requires-Dist: mcp
Requires-Dist: python-dotenv
Requires-Dist: starlette
Requires-Dist: uvicorn
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: respx; extra == 'test'
Description-Content-Type: text/markdown

# ServiceNow MCP Agent

Claude-powered ITSM agent that manages ServiceNow from natural language using MCP and AWS Bedrock.

Manage incidents, search the Knowledge Base for existing solutions, and handle Change Requests -- all through a conversational interface powered by Claude.

## Architecture

```text
User Input (natural language)
       |
       v
  agent.py (agentic loop)
       |
       v
  Claude via AWS Bedrock
       |  (tool calls)
       v
  MCP Protocol (stdio)
       |
       v
  server.py (12 tools)
       |  (HTTP GET / POST / PATCH)
       v
  ServiceNow REST API
       |
       v
  Incidents / KB Articles / Change Requests
```

**agent.py** -- Orchestrates the conversation loop. Sends user messages to Claude, executes tool calls via MCP, and returns results back to Claude until the task is complete.

**server.py** -- An MCP server that exposes twelve ITSM tools. Handles authentication and communication with the ServiceNow Table API.

## Tools

### Incident Management

| Tool | Description |
|------|-------------|
| `create_incident` | Create a new incident from a natural language description |
| `get_incident` | Look up a single incident by number (e.g. INC0010054) |
| `search_incidents` | Search incidents by state, impact, category, assignment group, etc. |
| `update_incident` | Update fields on an existing incident (impact, urgency, assignment, etc.) |
| `add_comment` | Add a customer-visible comment or internal work note |
| `resolve_incident` | Resolve an incident with a close code and resolution notes |

### Knowledge Base

| Tool | Description |
|------|-------------|
| `search_knowledge_base` | Search KB articles by keyword to find existing solutions |
| `get_kb_article` | Retrieve a full KB article by number (e.g. KB0000001) |

### Change Management

| Tool | Description |
|------|-------------|
| `create_change_request` | Create a Standard, Normal, or Emergency change request |
| `get_change_request` | Look up a change request by number (e.g. CHG0000001) |
| `search_change_requests` | Search change requests by state, type, risk, etc. |
| `update_change_request` | Update fields on an existing change request |

## Prerequisites

- Python 3.10+
- AWS CLI configured with a profile that has access to Amazon Bedrock
- A ServiceNow instance with REST API access (a [developer instance](https://developer.servicenow.com/) works)

## Installation

### Option A: Install with pip

```bash
pip install servicenow-mcp-agent
```

### Option B: Install from source

```bash
git clone https://github.com/Slalom-Consulting/servicenow-mcp-agent.git
cd servicenow-mcp-agent
pip install .
```

For development (editable install):

```bash
pip install -e .
```

### Configure environment variables

Copy the example file and fill in your credentials:

```bash
cp .env.example .env
```

Edit `.env`:

```env
SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com
SERVICENOW_USERNAME=your-username
SERVICENOW_PASSWORD=your-password
AWS_REGION=us-east-1
AWS_PROFILE=default
```

### Seed sample data (optional)

To populate your ServiceNow instance with sample KB articles and Change Requests for testing:

```bash
python scripts/seed_sample_data.py
```

This creates 5 Knowledge Base articles (VPN, password reset, software requests, Outlook sync, printer troubleshooting) and 5 Change Requests (database upgrade, SSO deployment, security patching, email migration, firewall rules).

## Usage

```bash
servicenow-mcp-agent
```

Or run directly with Python:

```bash
python -m servicenow_mcp_agent.agent
```

### Search the Knowledge Base

    You: My VPN isn't connecting

    Assistant: I found a KB article that may help:
      [KB0000001] How to reset your VPN connection
      Steps: Close the VPN client, run ipconfig /flushdns, restart the client...

      Would you like to try these steps, or should I create an incident?

### Create an incident

    You: Salesforce is having issues with Authentication. Can someone look into it

    Assistant: Your incident has been created successfully!
      Incident Number:   INC0010054
      Short Description: Authentication issues with Salesforce
      Category:          Software
      Impact:            2 - Medium
      Urgency:           2 - Medium
      Priority:          3 - Moderate
      State:             New

### Look up an incident

    You: What's the status of INC0010054?

    Assistant: INC0010054 is currently in New state, Priority 3 - Moderate...

### Search incidents

    You: Show me all open high-priority software incidents

    Assistant: Found 4 incident(s):
      [INC0000015] I can't launch my VPN client since the last software update
        State: 2 | Priority: 1 | Category: Software
      ...

### Add a work note

    You: Add a work note to INC0010054: Root cause identified - SSO certificate expired

    Assistant: Work note added to incident INC0010054 successfully!

### Update an incident

    You: Escalate INC0010054 to high urgency

    Assistant: Incident INC0010054 updated successfully!
      Urgency: 1 - High

### Resolve an incident

    You: Resolve INC0010054. The fix was renewing the SSO certificate.

    Assistant: Incident INC0010054 resolved successfully!
      State:        Resolved (6)
      Close Code:   Solution provided
      Close Notes:  Resolved by renewing the SSO certificate.

### Create a Change Request

    You: We need to upgrade the production database from Postgres 14 to 16

    Assistant: Change Request created successfully!
      Number:  CHG0000001
      Type:    Normal
      Risk:    High
      Impact:  1 - High
      State:   New

### Search Change Requests

    You: Show me all high-risk change requests

    Assistant: Found 2 change request(s):
      [CHG0000001] Upgrade production database from PostgreSQL 14 to 16
        Type: Normal | State: New | Risk: High | Approval: Not Yet Requested

Type `quit` or `exit` to end the session.

## HTTP/SSE Server (for remote MCP clients)

The MCP server can also run as an HTTP service so remote clients (Salesforce Agentforce, Slack bots, etc.) can connect over the network:

```bash
servicenow-mcp-server-http
```

This starts an HTTP/SSE server on port 8000 with three endpoints:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check for load balancers |
| `/sse` | GET | SSE stream for MCP client connections |
| `/messages/` | POST | MCP message endpoint (session-based) |

### Authentication

Set `MCP_API_KEY` in your `.env` file. Clients must send it as a Bearer token:

```
Authorization: Bearer your-secret-api-key
```

### Deploy to AWS

A Dockerfile and ECS Fargate deployment script are included:

```bash
# Build and deploy to AWS ECS
cd deploy
./deploy.sh
```

Secrets (ServiceNow credentials, MCP API key) are stored in AWS Secrets Manager. See `deploy/task-definition.json` for the full configuration.

## Project Structure

```text
servicenow-mcp-agent/
├── pyproject.toml                          # Package metadata, dependencies, entry points
├── Dockerfile                              # Container image for HTTP server
├── src/
│   └── servicenow_mcp_agent/
│       ├── __init__.py                     # Package version
│       ├── agent.py                        # Main entry point - agentic loop
│       ├── server.py                       # MCP server with ITSM tools (stdio transport)
│       └── server_http.py                  # MCP server with HTTP/SSE transport
├── deploy/
│   ├── deploy.sh                           # AWS ECS Fargate deployment script
│   └── task-definition.json                # ECS task definition template
├── scripts/
│   └── seed_sample_data.py                 # Seed ServiceNow with sample KB + Change data
├── .env.example                            # Environment variable template
├── .env                                    # Your credentials (git-ignored)
└── .gitignore
```

## License

MIT
