Integrate Claude with ServiceNow

ServiceNow MCP Server

A Model Completion Protocol (MCP) server implementation for ServiceNow, allowing Claude to interact with ServiceNow instances.

Overview

This project implements an MCP server that enables Claude to connect to ServiceNow instances, retrieve data, and perform actions through the ServiceNow API. It serves as a bridge between Claude and ServiceNow, allowing for seamless integration.

Features

• Connect to ServiceNow instances using various authentication methods (Basic, OAuth, API Key)
• Query ServiceNow records and tables
• Create, update, and delete ServiceNow records
• Execute ServiceNow scripts and workflows
• Access and query the ServiceNow Service Catalog
• Analyze and optimize the ServiceNow Service Catalog
• Debug mode for troubleshooting
• Support for both stdio and Server-Sent Events (SSE) communication

Installation

Prerequisites

• Python 3.11 or higher
• A ServiceNow instance with appropriate access credentials

Setup

1. Clone this repository:

   git clone https://github.com/echelon-ai-labs/servicenow-mcp.git
   cd servicenow-mcp
   

2. Create a virtual environment and install the package:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -e .
   

3. Create a .env file with your ServiceNow credentials:

   SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com
   SERVICENOW_USERNAME=your-username
   SERVICENOW_PASSWORD=your-password
   SERVICENOW_AUTH_TYPE=basic  # or oauth, api_key
   

Usage

Standard (stdio) Mode

To start the MCP server:

python -m servicenow_mcp.cli

Or with environment variables:

SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com SERVICENOW_USERNAME=your-username SERVICENOW_PASSWORD=your-password SERVICENOW_AUTH_TYPE=basic python -m servicenow_mcp.cli

Server-Sent Events (SSE) Mode

The ServiceNow MCP server can also run as a web server using Server-Sent Events (SSE) for communication, which allows for more flexible integration options.

Starting the SSE Server

You can start the SSE server using the provided CLI:

servicenow-mcp-sse --instance-url=https://your-instance.service-now.com --username=your-username --password=your-password

By default, the server will listen on 0.0.0.0:8080. You can customize the host and port:

servicenow-mcp-sse --host=127.0.0.1 --port=8000

Connecting to the SSE Server

The SSE server exposes two main endpoints:

• /sse - The SSE connection endpoint
• /messages/ - The endpoint for sending messages to the server

Example

See the examples/sse_server_example.py file for a complete example of setting up and running the SSE server.

from servicenow_mcp.server import ServiceNowMCP
from servicenow_mcp.server_sse import create_starlette_app
from servicenow_mcp.utils.config import ServerConfig, AuthConfig, AuthType, BasicAuthConfig
import uvicorn

# Create server configuration
config = ServerConfig(
    instance_url="https://your-instance.service-now.com",
    auth=AuthConfig(
        type=AuthType.BASIC,
        config=BasicAuthConfig(
            username="your-username",
            password="your-password"
        )
    ),
    debug=True,
)

# Create ServiceNow MCP server
servicenow_mcp = ServiceNowMCP(config)

# Create Starlette app with SSE transport
app = create_starlette_app(servicenow_mcp, debug=True)

# Start the web server
uvicorn.run(app, host="0.0.0.0", port=8080)

Tool Packaging (Optional)

To manage the number of tools exposed to the language model (especially in environments with limits), the ServiceNow MCP server supports loading subsets of tools called "packages". This is controlled via the MCP_TOOL_PACKAGE environment variable.

Configuration

1. Environment Variable: Set the MCP_TOOL_PACKAGE environment variable to the name of the desired package.

   export MCP_TOOL_PACKAGE=catalog_builder
   

2. Package Definitions: The available packages and the tools they include are defined in config/tool_packages.yaml. You can customize this file to create your own packages.

Behavior

• If MCP_TOOL_PACKAGE is set to a valid package name defined in config/tool_packages.yaml, only the tools listed in that package will be loaded.
• If MCP_TOOL_PACKAGE is not set or is empty, the full package (containing all tools) is loaded by default.
• If MCP_TOOL_PACKAGE is set to an invalid package name, the none package is loaded (no tools except list_tool_packages), and a warning is logged.
• Setting MCP_TOOL_PACKAGE=none explicitly loads no tools (except list_tool_packages).

Available Packages (Default)

The default config/tool_packages.yaml includes the following role-based packages:

• service_desk: Tools for incident handling and basic user/knowledge lookup.
• catalog_builder: Tools for creating and managing service catalog items, categories, variables, and related scripting (UI Policies, User Criteria).
• change_coordinator: Tools for managing the change request lifecycle, including tasks and approvals.
• knowledge_author: Tools for creating and managing knowledge bases, categories, and articles.
• platform_developer: Tools for server-side scripting (Script Includes), workflow development, and deployment (Changesets).
• system_administrator: Tools for user/group management and viewing system logs.
• agile_management: Tools for managing user stories, epics, scrum tasks, and projects.
• full: Includes all available tools (default).
• none: Includes no tools (except list_tool_packages).

Introspection Tool

• list_tool_packages: Lists all available tool package names defined in the configuration and shows the currently loaded package. This tool is available in all packages except none.

Available Tools

Note: The availability of the following tools depends on the loaded tool package (see Tool Packaging section above). By default (full package), all tools are available.

Incident Management Tools

1. create_incident - Create a new incident in ServiceNow
2. update_incident - Update an existing incident in ServiceNow
3. add_comment - Add a comment to an incident in ServiceNow
4. resolve_incident - Resolve an incident in ServiceNow
5. list_incidents - List incidents from ServiceNow

Service Catalog Tools

1. list_catalog_items - List service catalog items from ServiceNow
2. get_catalog_item - Get a specific service catalog item from ServiceNow
3. list_catalog_categories - List service catalog categories from ServiceNow
4. create_catalog_category - Create a new service catalog category in ServiceNow
5. update_catalog_category - Update an existing service catalog category in ServiceNow
6. move_catalog_items - Move catalog items between categories in ServiceNow
7. create_catalog_item_variable - Create a new variable (form field) for a catalog item
8. list_catalog_item_variables - List all variables for a catalog item
9. update_catalog_item_variable - Update an existing variable for a catalog item
10. list_catalogs - List service catalogs from ServiceNow

Catalog Optimization Tools

1. get_optimization_recommendations - Get recommendations for optimizing the service catalog
2. update_catalog_item - Update a service catalog item

Change Management Tools

1. create_change_request - Create a new change request in ServiceNow
2. update_change_request - Update an existing change request
3. list_change_requests - List change requests with filtering options
4. get_change_request_details - Get detailed information about a specific change request
5. add_change_task - Add a task to a change request
6. submit_change_for_approval - Submit a change request for approval
7. approve_change - Approve a change request
8. reject_change - Reject a change request

Agile Management Tools

Story Management

1. create_story - Create a new user story in ServiceNow
2. update_story - Update an existing user story in ServiceNow
3. list_stories - List user stories with filtering options
4. create_story_dependency - Create a dependency between two stories
5. delete_story_dependency - Delete a dependency between stories

Epic Management

1. create_epic - Create a new epic in ServiceNow
2. update_epic - Update an existing epic in ServiceNow
3. list_epics - List epics from ServiceNow with filtering options

Scrum Task Management

1. create_scrum_task - Create a new scrum task in ServiceNow
2. update_scrum_task - Update an existing scrum task in ServiceNow
3. list_scrum_tasks - List scrum tasks from ServiceNow with filtering options

Project Management

1. create_project - Create a new project in ServiceNow
2. update_project - Update an existing project in ServiceNow
3. list_projects - List projects from ServiceNow with filtering options

Workflow Management Tools

1. list_workflows - List workflows from ServiceNow
2. get_workflow - Get a specific workflow from ServiceNow
3. create_workflow - Create a new workflow in ServiceNow
4. update_workflow - Update an existing workflow in ServiceNow
5. delete_workflow - Delete a workflow from ServiceNow

Script Include Management Tools

1. list_script_includes - List script includes from ServiceNow
2. get_script_include - Get a specific script include from ServiceNow
3. create_script_include - Create a new script include in ServiceNow
4. update_script_include - Update an existing script include in ServiceNow
5. delete_script_include - Delete a script include from ServiceNow

Changeset Management Tools

1. list_changesets - List changesets from ServiceNow with filtering options
2. get_changeset_details - Get detailed information about a specific changeset
3. create_changeset - Create a new changeset in ServiceNow
4. update_changeset - Update an existing changeset
5. commit_changeset - Commit a changeset
6. publish_changeset - Publish a changeset
7. add_file_to_changeset - Add a file to a changeset

Knowledge Base Management Tools

1. create_knowledge_base - Create a new knowledge base in ServiceNow
2. list_knowledge_bases - List knowledge bases with filtering options
3. create_category - Create a new category in a knowledge base
4. create_article - Create a new knowledge article in ServiceNow
5. update_article - Update an existing knowledge article in ServiceNow
6. publish_article - Publish a knowledge article in ServiceNow
7. list_articles - List knowledge articles with filtering options
8. get_article - Get a specific knowledge article by ID

User Management Tools

1. create_user - Create a new user in ServiceNow
2. update_user - Update an existing user in ServiceNow
3. get_user - Get a specific user by ID, username, or email
4. list_users - List users with filtering options
5. create_group - Create a new group in ServiceNow
6. update_group - Update an existing group in ServiceNow
7. add_group_members - Add members to a group in ServiceNow
8. remove_group_members - Remove members from a group in ServiceNow
9. list_groups - List groups with filtering options

UI Policy Tools

1. create_ui_policy - Creates a ServiceNow UI Policy, typically for a Catalog Item.
2. create_ui_policy_action - Creates an action associated with a UI Policy to control variable states (visibility, mandatory, etc.).

Using the MCP CLI

The ServiceNow MCP server can be installed with the MCP CLI, which provides a convenient way to register the server with Claude.

# Install the ServiceNow MCP server with environment variables from .env file
mcp install src/servicenow_mcp/server.py -f .env

This command will register the ServiceNow MCP server with Claude and configure it to use the environment variables from the .env file.

Integration with Claude Desktop

To configure the ServiceNow MCP server in Claude Desktop:

1. Edit the Claude Desktop configuration file at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the appropriate path for your OS:

{
  "mcpServers": {
    "ServiceNow": {
      "command": "/Users/yourusername/dev/servicenow-mcp/.venv/bin/python",
      "args": [
        "-m",
        "servicenow_mcp.cli"
      ],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_USERNAME": "your-username",
        "SERVICENOW_PASSWORD": "your-password",
        "SERVICENOW_AUTH_TYPE": "basic"
      }
    }
  }
}

2. Restart Claude Desktop to apply the changes

Example Usage with Claude

Below are some example natural language queries you can use with Claude to interact with ServiceNow via the MCP server:

Incident Management Examples

• "Create a new incident for a network outage in the east region"
• "Update the priority of incident INC0010001 to high"
• "Add a comment to incident INC0010001 saying the issue is being investigated"
• "Resolve incident INC0010001 with a note that the server was restarted"
• "List all high priority incidents assigned to the Network team"
• "List all active P1 incidents assigned to the Network team."

Service Catalog Examples

• "Show me all items in the service catalog"
• "List all service catalog categories"
• "Get details about the laptop request catalog item"
• "Show me all catalog items in the Hardware category"
• "Search for 'software' in the service catalog"
• "Create a new category called 'Cloud Services' in the service catalog"
• "Update the 'Hardware' category to rename it to 'IT Equipment'"
• "Move the 'Virtual Machine' catalog item to the 'Cloud Services' category"
• "Create a subcategory called 'Monitors' under the 'IT Equipment' category"
• "Reorganize our catalog by moving all software items to the 'Software' category"
• "Create a description field for the laptop request catalog item"
• "Add a dropdown field for selecting laptop models to catalog item"
• "List all form fields for the VPN access request catalog item"
• "Make the department field mandatory in the software request form"
• "Update the help text for the cost center field"
• "Show me all service catalogs in the system"
• "List all hardware catalog items."
• "Find the catalog item for 'New Laptop Request'."
• "Show me the variables for the 'New Laptop Request' item."
• "Create a new variable named 'department_code' for the 'New Hire Setup' catalog item. Make it a mandatory string field."

Catalog Optimization Examples

• "Analyze our service catalog and identify opportunities for improvement"
• "Find catalog items with poor descriptions that need improvement"
• "Identify catalog items with low usage that we might want to retire"
• "Find catalog items with high abandonment rates"
• "Optimize our Hardware category to improve user experience"

Change Management Examples

• "Create a change request for server maintenance to apply security patches tomorrow night"
• "Schedule a database upgrade for next Tuesday from 2 AM to 4 AM"
• "Add a task to the server maintenance change for pre-implementation checks"
• "Submit the server maintenance change for approval"
• "Approve the database upgrade change with comment: implementation plan looks thorough"
• "Show me all emergency changes scheduled for this week"
• "List all changes assigned to the Network team"
• "Create a normal change request to upgrade the production database server."
• "Update change CHG0012345, set the state to 'Implement'."

Agile Management Examples

• "Create a new user story for implementing a new reporting dashboard"
• "Update the 'Implement a new reporting dashboard' story to set it as blocked"
• "List all user stories assigned to the Data Analytics team"
• "Create a dependency between the 'Implement a new reporting dashboard' story and the 'Develop data extraction pipeline' story"
• "Delete the dependency between the 'Implement a new reporting dashboard' story and the 'Develop data extraction pipeline' story"
• "Create a new epic called 'Data Analytics Initiatives'"
• "Update the 'Data Analytics Initiatives' epic to set it as completed"
• "List all epics in the 'Data Analytics' project"
• "Create a new scrum task for the 'Implement a new reporting dashboard' story"
• "Update the 'Develop data extraction pipeline' scrum task to set it as completed"
• "List all scrum tasks in the 'Implement a new reporting dashboard' story"
• "Create a new project called 'Data Analytics Initiatives'"
• "Update the 'Data Analytics Initiatives' project to set it as completed"
• "List all projects in the 'Data Analytics' epic"

Workflow Management Examples

• "Show me all active workflows in ServiceNow"
• "Get details about the incident approval workflow"
• "List all versions of the change request workflow"
• "Show me all activities in the service catalog request workflow"
• "Create a new workflow for handling software license requests"
• "Update the description of the incident escalation workflow"
• "Activate the new employee onboarding workflow"
• "Deactivate the old password reset workflow"
• "Add an approval activity to the software license request workflow"
• "Update the notification activity in the incident escalation workflow"
• "Delete the unnecessary activity from the change request workflow"
• "Reorder the activities in the service catalog request workflow"

Changeset Management Examples

• "List all changesets in ServiceNow"
• "Show me all changesets created by developer 'john.doe'"
• "Get details about changeset 'sys_update_set_123'"
• "Create a new changeset for the 'HR Portal' application"
• "Update the description of changeset 'sys_update_set_123'"
• "Commit changeset 'sys_update_set_123' with message 'Fixed login issue'"
• "Publish changeset 'sys_update_set_123' to production"
• "Add a file to changeset 'sys_update_set_123'"
• "Show me all changes in changeset 'sys_update_set_123'"

Knowledge Base Examples

• "Create a new knowledge base for the IT department"
• "List all knowledge bases in the organization"
• "Create a category called 'Network Troubleshooting' in the IT knowledge base"
• "Write an article about VPN setup in the Network Troubleshooting category"
• "Update the VPN setup article to include mobile device instructions"
• "Publish the VPN setup article so it's visible to all users"
• "List all articles in the Network Troubleshooting category"
• "Show me the details of the VPN setup article"
• "Find knowledge articles containing 'password reset' in the IT knowledge base"
• "Create a subcategory called 'Wireless Networks' under the Network Troubleshooting category"

User Management Examples

• "Create a new user Dr. Alice Radiology in the Radiology department"
• "Update Bob's user record to make him the manager of Alice"
• "Assign the ITIL role to Bob so he can approve change requests"
• "List all users in the Radiology department"
• "Create a new group called 'Biomedical Engineering' for managing medical devices"
• "Add an admin user to the Biomedical Engineering group as a member"
• "Update the Biomedical Engineering group to change its manager"
• "Remove a user from the Biomedical Engineering group"
• "Find all active users in the system with 'doctor' in their title"
• "Create a user that will act as an approver for the Radiology department"
• "List all IT support groups in the system"

UI Policy Examples

• "Create a UI policy for the 'Software Request' item (sys_id: abc...) named 'Show Justification' that applies when 'software_cost' is greater than 100."
• "For the UI policy 'Show Justification' (sys_id: def...), add an action to make the 'business_justification' variable visible and mandatory."
• "Create another action for policy 'Show Justification' to hide the 'alternative_software' variable."

Example Scripts

The repository includes example scripts that demonstrate how to use the tools:

• examples/catalog_optimization_example.py: Demonstrates how to analyze and improve the ServiceNow Service Catalog
• examples/change_management_demo.py: Shows how to create and manage change requests in ServiceNow

Authentication Methods

Basic Authentication

SERVICENOW_AUTH_TYPE=basic
SERVICENOW_USERNAME=your-username
SERVICENOW_PASSWORD=your-password

OAuth Authentication

SERVICENOW_AUTH_TYPE=oauth
SERVICENOW_CLIENT_ID=your-client-id
SERVICENOW_CLIENT_SECRET=your-client-secret
SERVICENOW_TOKEN_URL=https://your-instance.service-now.com/oauth_token.do

API Key Authentication

SERVICENOW_AUTH_TYPE=api_key
SERVICENOW_API_KEY=your-api-key

Development

Documentation

Additional documentation is available in the docs directory:

• Catalog Integration - Detailed information about the Service Catalog integration
• Catalog Optimization - Detailed plan for catalog optimization features
• Change Management - Detailed information about the Change Management tools
• Workflow Management - Detailed information about the Workflow Management tools
• Changeset Management - Detailed information about the Changeset Management tools

Troubleshooting

Common Errors with Change Management Tools

1. Error: argument after ** must be a mapping, not CreateChangeRequestParams

   • This error occurs when you pass a CreateChangeRequestParams object instead of a dictionary to the create_change_request function.
   • Solution: Make sure you're passing a dictionary with the parameters, not a Pydantic model object.
   • Note: The change management tools have been updated to handle this error automatically. The functions will now attempt to unwrap parameters if they're incorrectly wrapped or passed as a Pydantic model object.

2. Error: Missing required parameter 'type'

   • This error occurs when you don't provide all required parameters for creating a change request.
   • Solution: Make sure to include all required parameters. For create_change_request, both short_description and type are required.

3. Error: Invalid value for parameter 'type'

   • This error occurs when you provide an invalid value for the type parameter.
   • Solution: Use one of the valid values: "normal", "standard", or "emergency".

4. Error: Cannot find get_headers method in either auth_manager or server_config

   • This error occurs when the parameters are passed in the wrong order or when using objects that don't have the required methods.
   • Solution: Make sure you're passing the auth_manager and server_config parameters in the correct order. The functions have been updated to handle parameter swapping automatically.

examples/catalog_optimization_example.py

#!/usr/bin/env python3
"""
Example script demonstrating how to use the ServiceNow MCP catalog optimization tools.

This script shows how to:
1. Get optimization recommendations for a ServiceNow Service Catalog
2. Update catalog items with improved descriptions

Usage:
    python catalog_optimization_example.py [--update-descriptions]

Options:
    --update-descriptions    Automatically update items with poor descriptions
"""

import argparse
import logging
import sys
from typing import Dict

from servicenow_mcp.server import ServiceNowMCP
from servicenow_mcp.tools.catalog_optimization import (
    OptimizationRecommendationsParams,
    UpdateCatalogItemParams,
)
from servicenow_mcp.utils.config import load_config

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
)
logger = logging.getLogger(__name__)


def get_optimization_recommendations(server: ServiceNowMCP) -> Dict:
    """
    Get optimization recommendations for the ServiceNow Service Catalog.
    
    Args:
        server: The ServiceNowMCP server instance
        
    Returns:
        Dict containing the optimization recommendations
    """
    logger.info("Getting catalog optimization recommendations...")
    
    # Create parameters for all recommendation types
    params = OptimizationRecommendationsParams(
        recommendation_types=[
            "inactive_items",
            "low_usage",
            "high_abandonment",
            "slow_fulfillment",
            "description_quality",
        ]
    )
    
    # Call the tool
    result = server.tools["get_optimization_recommendations"](params)
    
    if not result["success"]:
        logger.error(f"Failed to get optimization recommendations: {result.get('message', 'Unknown error')}")
        return {}
    
    return result


def print_recommendations(recommendations: Dict) -> None:
    """
    Print the optimization recommendations in a readable format.
    
    Args:
        recommendations: The optimization recommendations dictionary
    """
    if not recommendations or "recommendations" not in recommendations:
        logger.warning("No recommendations available")
        return
    
    print("\n" + "=" * 80)
    print("SERVICENOW CATALOG OPTIMIZATION RECOMMENDATIONS")
    print("=" * 80)
    
    for rec in recommendations["recommendations"]:
        print(f"\n{rec['title']} ({rec['type']})")
        print("-" * len(rec['title']))
        print(f"Description: {rec['description']}")
        print(f"Impact: {rec['impact'].upper()}")
        print(f"Effort: {rec['effort'].upper()}")
        print(f"Recommended Action: {rec['action']}")
        
        if rec["items"]:
            print("\nAffected Items:")
            for i, item in enumerate(rec["items"], 1):
                print(f"  {i}. {item['name']}")
                print(f"     ID: {item['sys_id']}")
                print(f"     Description: {item['short_description'] or '(No description)'}")
                
                # Print additional details based on recommendation type
                if rec["type"] == "low_usage":
                    print(f"     Order Count: {item['order_count']}")
                elif rec["type"] == "high_abandonment":
                    print(f"     Abandonment Rate: {item['abandonment_rate']}%")
                    print(f"     Cart Adds: {item['cart_adds']}")
                    print(f"     Completed Orders: {item['orders']}")
                elif rec["type"] == "slow_fulfillment":
                    print(f"     Avg. Fulfillment Time: {item['avg_fulfillment_time']} days")
                    print(f"     Compared to Catalog Avg: {item['avg_fulfillment_time_vs_catalog']}x slower")
                elif rec["type"] == "description_quality":
                    print(f"     Description Quality Score: {item['description_quality']}/100")
                    print(f"     Issues: {', '.join(item['quality_issues'])}")
                
                print()
        else:
            print("\nNo items found in this category.")
    
    print("=" * 80)


def update_poor_descriptions(server: ServiceNowMCP, recommendations: Dict) -> None:
    """
    Update catalog items with poor descriptions.
    
    Args:
        server: The ServiceNowMCP server instance
        recommendations: The optimization recommendations dictionary
    """
    # Find the description quality recommendation
    description_rec = None
    for rec in recommendations.get("recommendations", []):
        if rec["type"] == "description_quality":
            description_rec = rec
            break
    
    if not description_rec or not description_rec.get("items"):
        logger.warning("No items with poor descriptions found")
        return
    
    logger.info(f"Found {len(description_rec['items'])} items with poor descriptions")
    
    # Update each item with a better description
    for item in description_rec["items"]:
        # Generate an improved description based on the item name and category
        improved_description = generate_improved_description(item)
        
        logger.info(f"Updating description for item: {item['name']} (ID: {item['sys_id']})")
        logger.info(f"  Original: {item['short_description'] or '(No description)'}")
        logger.info(f"  Improved: {improved_description}")
        
        # Create parameters for updating the item
        params = UpdateCatalogItemParams(
            item_id=item["sys_id"],
            short_description=improved_description,
        )
        
        # Call the tool
        result = server.tools["update_catalog_item"](params)
        
        if result["success"]:
            logger.info(f"Successfully updated description for {item['name']}")
        else:
            logger.error(f"Failed to update description: {result.get('message', 'Unknown error')}")


def generate_improved_description(item: Dict) -> str:
    """
    Generate an improved description for a catalog item.
    
    In a real implementation, this could use AI to generate better descriptions,
    but for this example we'll use a simple template-based approach.
    
    Args:
        item: The catalog item dictionary
        
    Returns:
        An improved description string
    """
    name = item["name"]
    category = item.get("category", "").lower()
    
    # Simple templates based on category
    if "hardware" in category:
        return f"Enterprise-grade {name.lower()} for professional use. Includes standard warranty and IT support."
    elif "software" in category:
        return f"Licensed {name.lower()} application with full feature set. Includes installation support."
    elif "service" in category:
        return f"Professional {name.lower()} service delivered by our expert team. Includes consultation and implementation."
    else:
        return f"High-quality {name.lower()} available through IT self-service. Contact the service desk for assistance."


def main():
    """Main function to run the example."""
    parser = argparse.ArgumentParser(description="ServiceNow Catalog Optimization Example")
    parser.add_argument(
        "--update-descriptions",
        action="store_true",
        help="Automatically update items with poor descriptions",
    )
    args = parser.parse_args()
    
    try:
        # Load configuration
        config = load_config()
        
        # Initialize the ServiceNow MCP server
        server = ServiceNowMCP(config)
        
        # Get optimization recommendations
        recommendations = get_optimization_recommendations(server)
        
        # Print the recommendations
        print_recommendations(recommendations)
        
        # Update poor descriptions if requested
        if args.update_descriptions and recommendations:
            update_poor_descriptions(server, recommendations)
    
    except Exception as e:
        logger.exception(f"Error running catalog optimization example: {e}")
        sys.exit(1)


if __name__ == "__main__":
    main() 

examples/change_management_demo.py

#!/usr/bin/env python
"""
Change Management Demo

This script demonstrates how to use the ServiceNow MCP server with Claude Desktop
to manage change requests in ServiceNow.
"""

import json
import os
from datetime import datetime, timedelta

from dotenv import load_dotenv

from servicenow_mcp.auth.auth_manager import AuthManager
from servicenow_mcp.tools.change_tools import (
    add_change_task,
    approve_change,
    create_change_request,
    get_change_request_details,
    list_change_requests,
    submit_change_for_approval,
    update_change_request,
)
from servicenow_mcp.utils.config import AuthConfig, AuthType, BasicAuthConfig, ServerConfig


def main():
    """Run the change management demo."""
    # Load environment variables from .env file
    load_dotenv()

    # Create auth configuration
    auth_config = AuthConfig(
        type=AuthType.BASIC,
        basic=BasicAuthConfig(
            username=os.environ.get("SERVICENOW_USERNAME"),
            password=os.environ.get("SERVICENOW_PASSWORD"),
        )
    )

    # Create server configuration with auth
    server_config = ServerConfig(
        instance_url=os.environ.get("SERVICENOW_INSTANCE_URL"),
        debug=os.environ.get("DEBUG", "false").lower() == "true",
        auth=auth_config,
    )

    # Create authentication manager with the auth_config
    auth_manager = AuthManager(auth_config)

    print("ServiceNow Change Management Demo")
    print("=================================")
    print(f"Instance URL: {server_config.instance_url}")
    print(f"Auth Type: {auth_config.type}")
    print()

    # Demo 1: Create a change request
    print("Demo 1: Creating a change request")
    print("---------------------------------")
    
    # Calculate start and end dates for the change (tomorrow)
    tomorrow = datetime.now() + timedelta(days=1)
    start_date = tomorrow.replace(hour=1, minute=0, second=0).strftime("%Y-%m-%d %H:%M:%S")
    end_date = tomorrow.replace(hour=3, minute=0, second=0).strftime("%Y-%m-%d %H:%M:%S")
    
    create_params = {
        "short_description": "Server maintenance - Apply security patches",
        "description": "Apply the latest security patches to the application servers to address recent vulnerabilities.",
        "type": "normal",
        "risk": "moderate",
        "impact": "medium",
        "category": "Hardware",
        "start_date": start_date,
        "end_date": end_date,
    }
    
    result = create_change_request(auth_manager, server_config, create_params)
    print(json.dumps(result, indent=2))
    
    if not result.get("success"):
        print("Failed to create change request. Exiting demo.")
        return
    
    # Store the change request ID for later use
    change_id = result["change_request"]["sys_id"]
    print(f"Created change request with ID: {change_id}")
    print()
    
    # Demo 2: Add tasks to the change request
    print("Demo 2: Adding tasks to the change request")
    print("-----------------------------------------")
    
    # Task 1: Pre-implementation checks
    task1_params = {
        "change_id": change_id,
        "short_description": "Pre-implementation checks",
        "description": "Verify system backups and confirm all prerequisites are met.",
        "planned_start_date": start_date,
        "planned_end_date": (datetime.strptime(start_date, "%Y-%m-%d %H:%M:%S") + timedelta(minutes=30)).strftime("%Y-%m-%d %H:%M:%S"),
    }
    
    task1_result = add_change_task(auth_manager, server_config, task1_params)
    print(json.dumps(task1_result, indent=2))
    
    # Task 2: Apply patches
    task2_params = {
        "change_id": change_id,
        "short_description": "Apply security patches",
        "description": "Apply the latest security patches to all application servers.",
        "planned_start_date": (datetime.strptime(start_date, "%Y-%m-%d %H:%M:%S") + timedelta(minutes=30)).strftime("%Y-%m-%d %H:%M:%S"),
        "planned_end_date": (datetime.strptime(start_date, "%Y-%m-%d %H:%M:%S") + timedelta(minutes=90)).strftime("%Y-%m-%d %H:%M:%S"),
    }
    
    task2_result = add_change_task(auth_manager, server_config, task2_params)
    print(json.dumps(task2_result, indent=2))
    
    # Task 3: Post-implementation verification
    task3_params = {
        "change_id": change_id,
        "short_description": "Post-implementation verification",
        "description": "Verify all systems are functioning correctly after patching.",
        "planned_start_date": (datetime.strptime(start_date, "%Y-%m-%d %H:%M:%S") + timedelta(minutes=90)).strftime("%Y-%m-%d %H:%M:%S"),
        "planned_end_date": (datetime.strptime(start_date, "%Y-%m-%d %H:%M:%S") + timedelta(minutes=120)).strftime("%Y-%m-%d %H:%M:%S"),
    }
    
    task3_result = add_change_task(auth_manager, server_config, task3_params)
    print(json.dumps(task3_result, indent=2))
    print()
    
    # Demo 3: Update the change request
    print("Demo 3: Updating the change request")
    print("----------------------------------")
    
    update_params = {
        "change_id": change_id,
        "work_notes": "Added implementation plan and tasks. Ready for review.",
        "risk": "low",  # Downgrading risk after assessment
    }
    
    update_result = update_change_request(auth_manager, server_config, update_params)
    print(json.dumps(update_result, indent=2))
    print()
    
    # Demo 4: Get change request details
    print("Demo 4: Getting change request details")
    print("-------------------------------------")
    
    details_params = {
        "change_id": change_id,
    }
    
    details_result = get_change_request_details(auth_manager, server_config, details_params)
    print(json.dumps(details_result, indent=2))
    print()
    
    # Demo 5: Submit change for approval
    print("Demo 5: Submitting change for approval")
    print("-------------------------------------")
    
    approval_params = {
        "change_id": change_id,
        "approval_comments": "Implementation plan is complete and ready for review.",
    }
    
    approval_result = submit_change_for_approval(auth_manager, server_config, approval_params)
    print(json.dumps(approval_result, indent=2))
    print()
    
    # Demo 6: List change requests
    print("Demo 6: Listing change requests")
    print("------------------------------")
    
    list_params = {
        "limit": 5,
        "timeframe": "upcoming",
    }
    
    list_result = list_change_requests(auth_manager, server_config, list_params)
    print(json.dumps(list_result, indent=2))
    print()
    
    # Demo 7: Approve the change request
    print("Demo 7: Approving the change request")
    print("-----------------------------------")
    
    approve_params = {
        "change_id": change_id,
        "approval_comments": "Implementation plan looks good. Approved.",
    }
    
    approve_result = approve_change(auth_manager, server_config, approve_params)
    print(json.dumps(approve_result, indent=2))
    print()
    
    print("Change Management Demo Complete")
    print("==============================")
    print(f"Created and managed change request: {change_id}")
    print("You can now view this change request in your ServiceNow instance.")


if __name__ == "__main__":
    main()