Metadata-Version: 2.4
Name: servicenow-mcp-agent
Version: 0.5.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

**Option 1: AWS App Runner (recommended, simplest)**

App Runner builds and deploys directly from this GitHub repo -- no Docker or container registry needed. You get an HTTPS URL out of the box, which is required by remote MCP clients like Agentforce.

1. Open the [AWS App Runner console](https://console.aws.amazon.com/apprunner/)
2. Click **Create service** > **Source: Source code repository** > connect your GitHub account
3. Select the `servicenow-mcp-agent` repo and `main` branch
4. Deployment settings: **Automatic** (redeploy on every push to main)
5. Configuration file: **Use a configuration file** (App Runner will read `apprunner.yaml` from the repo)
6. In the service settings, add environment variables:
   - `SERVICENOW_INSTANCE_URL`
   - `SERVICENOW_USERNAME`
   - `SERVICENOW_PASSWORD`
   - `MCP_API_KEY` (any strong random string)
7. Click **Create & deploy**

After a few minutes you'll get a public HTTPS URL like `https://xyz.us-east-2.awsapprunner.com`. Share that URL with Agentforce along with the API key.

**Option 2: AWS ECS Fargate**

A Dockerfile and ECS task definition are included under `deploy/` for users who want a containerized deployment with VPC/ALB control. Requires a local container build tool (Docker, Podman, or Rancher Desktop).

```bash
cd deploy
./deploy.sh
```

## 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
