Py MCP Snow

ServiceNow MCP服务器

一种模型上下文协议（MCP）服务器，为AI助手提供管理ServiceNow服务请求的标准化工具。建于 FastMCP 2.0 和Python，该服务器实现了与ServiceNow的REST API的自然语言交互。

特性

• 🔐 安全认证 -支持基本身份验证和API密钥身份验证
• 📝 服务请求管理 -创建、读取、更新和搜索服务请求
• 🛒 服务目录集成 -使用服务目录API浏览和订购目录项
• 🔍 高级搜索 -按状态、用户、日期范围等筛选请求
• ⚡ FastMCP 2.0 -使用装饰器简化MCP服务器开发
• 🛡️ 全面的错误处理 -详细的错误消息和重试逻辑
• ✅ 经过全面测试 -52+个单元测试，涵盖所有核心操作
• 🔄 自动重试 -瞬态故障的可配置重试逻辑
• 📊 结构化日志记录 -调试和监控的详细日志记录
• 🌐 多个传输 -支持stdio和流式HTTP

安装

先决条件

• Python 3.10或更高版本
• 紫外线 -快速Python包管理器
• 具有API访问权限的ServiceNow实例
• ServiceNow凭据（用户名/密码或API密钥）

或

• Docker和Docker Compose（用于容器化部署）

Docker部署（推荐用于生产环境）

1. 克隆存储库：

git clone 
cd servicenow-mcp-server

1. 配置环境变量：

cp .env.example .env
# Edit .env with your ServiceNow credentials

1. 使用Docker Compose构建和运行：

docker-compose up -d

服务器将在以下时间可用 http://localhost:8000/mcp

1. 查看日志：

docker-compose logs -f

1. 停止服务器：

docker-compose down

快速设置（建议用于开发）

要快速自动设置，请运行开发设置脚本：

./scripts/dev-setup.sh

此脚本将：

• 如果尚未安装，请安装uv
• 安装所有依赖项
• 从模板创建.env文件
• 运行测试以验证设置

手动设置

1. 克隆存储库：

git clone 
cd servicenow-mcp-server

1. 安装uv（如果尚未安装）：

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip
pip install uv

1. 安装依赖项并创建虚拟环境：

uv sync

1. 激活虚拟环境：

source .venv/bin/activate  # On Windows: .venv\Scripts\activate

1. 配置环境变量：

cp .env.example .env
# Edit .env with your ServiceNow credentials

配置

创建一个 .env 项目根目录中的文件，包含以下变量：

# ServiceNow Instance Configuration
SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com
SERVICENOW_USERNAME=your_username
SERVICENOW_PASSWORD=your_password
# OR use API key authentication
# SERVICENOW_API_KEY=your_api_key

# Optional Configuration
SERVICENOW_TIMEOUT=30
SERVICENOW_RETRY_COUNT=3

# Server Configuration
LOG_LEVEL=INFO
MAX_CONCURRENT_REQUESTS=10

认证方法

服务器支持两种身份验证方法：

1. 基本认证 （用户名/密码）：

- 集 SERVICENOW_USERNAME 和 SERVICENOW_PASSWORD

1. API密钥验证:

- 集 SERVICENOW_API_KEY - 如果同时配置了两种方法，则API键优先

用法

运行服务器

服务器支持两种传输模式：

1.stdio传输（默认）

对于本地MCP客户端和IDE集成：

uv run servicenow-mcp-server
# or explicitly
uv run servicenow-mcp-server --transport stdio

2.流式HTTP传输

对于远程访问和基于web的客户端：

uv run servicenow-mcp-server --transport streamable-http
# Custom host and port
uv run servicenow-mcp-server --transport streamable-http --host 0.0.0.0 --port 8080

HTTP服务器将在 http://{host}:{port}/mcp （默认值： http://127.0.0.1:8000/mcp)

命令行选项

servicenow-mcp-server --help

Options:
  --transport {stdio,streamable-http}  Transport type (default: stdio)
  --host HOST                          Host for HTTP transport (default: 127.0.0.1)
  --port PORT                          Port for HTTP transport (default: 8000)

可用操作

ServiceNow MCP服务器提供以下操作：

标准操作

创建服务请求

create_request({
    "short_description": "Request new laptop",
    "description": "Need a new laptop for development work",
    "requested_for": "user_sys_id",
    "priority": "2"
})

获取服务请求

# By sys_id
get_request("abc123", "sys_id")

# By request number
get_request("REQ0001234", "number")

更新服务请求

update_request("abc123", {
    "state": "2",
    "priority": "1",
    "work_notes": "Updated priority to high"
})

订购目录项

order_catalog_item("catalog_item_sys_id", {
    "quantity": "1",
    "requested_for": "user_sys_id",
    "custom_variable": "value"
})

获取目录项

get_catalog_items({
    "sysparm_catalog": "catalog_sys_id",
    "sysparm_category": "category_sys_id",
    "sysparm_limit": 50,
    "sysparm_text": "search_text",
    "sysparm_type": "item_type"
})

搜索服务请求

search_requests({
    "status": "1",
    "requested_for": "user_sys_id",
    "date_from": "2024-01-01",
    "limit": 50
})

为什么是紫外线？

此项目使用 紫外线 作为Python包管理器，有几个好处：

• ⚡ 快10-100倍 用于依赖解析和安装的pip
• 🔒 确定性构建 具有自动锁定文件生成功能
• 🎯 统一的工具链 -替换pip、pip工具、pipx、诗歌等
• 🐍 Python版本管理 -自动安装和管理Python版本
• 📦 现代依赖群体 -更清晰地分离dev/test/prod依赖关系

发展

运行测试

运行所有测试：

uv run pytest tests/ -v

运行特定测试文件：

uv run pytest tests/test_servicenow_client.py -v

跑步覆盖：

uv run pytest tests/ --cov=src/servicenow_mcp --cov-report=html

代码质量

黑色格式代码：

uv run black src/ tests/

使用isort对导入进行排序：

uv run isort src/ tests/

使用mypy进行类型检查：

uv run mypy src/

添加依赖关系

添加新的依赖关系：

uv add package-name

添加开发依赖关系：

uv add --group dev package-name

更新依赖关系：

uv sync --upgrade

项目结构

servicenow-mcp-server/
├── src/
│   └── servicenow_mcp/
│       ├── client/           # ServiceNow HTTP client
│       │   └── servicenow_client.py
│       ├── config/           # Configuration management
│       │   └── settings.py
│       ├── tools/            # FastMCP tool definitions
│       │   └── fastmcp_tools.py
│       ├── utils/            # Utilities (logging, etc.)
│       │   └── logging.py
│       ├── exceptions.py     # Custom exceptions
│       └── server.py         # Main server entry point
├── tests/                    # Test suite
│   ├── conftest.py          # Pytest fixtures
│   ├── test_setup.py        # Setup tests
│   └── test_servicenow_client.py  # Client tests
├── scripts/                  # Development scripts
│   └── dev-setup.sh         # Automated development setup
├── .kiro/
│   └── specs/               # Feature specifications
│       └── servicenow-mcp-server/
│           ├── requirements.md
│           ├── design.md
│           └── tasks.md
├── Dockerfile               # Docker container definition
├── docker-compose.yml       # Docker Compose configuration
├── pyproject.toml           # Project configuration
├── uv.lock                  # uv lock file
├── .python-version          # Python version specification
├── .env.example             # Example environment variables
└── README.md                # This file

建筑

服务器遵循分层架构：

• FastMCP框架：处理MCP协议通信和工具发现
• 装饰工具：公开ServiceNow操作的Python函数
• ServiceNow客户端：使用ServiceNow REST API管理HTTP通信
• 认证管理器：处理凭据和身份验证生命周期
• 配置管理器：管理服务器配置和环境设置

错误处理

服务器为以下内容提供全面的错误处理：

• 身份验证错误：凭据无效，令牌过期
• 连接错误：网络故障、超时、DNS问题
• 验证错误：缺少必填字段，数据类型无效
• API错误：ServiceNow特定错误，并显示详细消息
• 速率限制：使用指数回退自动重试

测试

该项目包括全面的测试覆盖范围：

• ✅ 身份验证和连接验证
• ✅ CRUD操作（创建、读取、更新、搜索）
• ✅ 错误处理和边缘情况
• ✅ 输入验证
• ✅ 配置管理

测试统计：

• 52+单元测试
• 100%通过率
• 涵盖了ServiceNow的所有核心业务

实施状态

完成✅

• \[x\] 项目结构和依赖关系
• \[x\] 配置管理
• \[x\] 具有身份验证的ServiceNow客户端
• \[x\] 服务请求创建
• \[x\] 服务请求检索
• \[x\] 服务请求更新
• \[x\] 搜索和过滤
• \[x\] 全面的错误处理
• \[x\] 所有操作的单元测试
• \[x\] FastMCP工具装饰器
• \[x\] MCP协议集成
• \[x\] 多种传输支持（stdio、流式HTTP）
• \[x\] Docker部署

进行中🚧

• \[\]基于属性的测试

计划的📋

• \[\]OAuth 2.0身份验证
• \[\]附加ServiceNow表支持
• \[\]Webhook支持
• \[\]性能优化
• \[\]对大型结果集的分页支持

贡献

欢迎投稿！请遵循以下指南：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 为您的更改编写测试
4. 确保所有测试通过(uv run pytest tests/)
5. 格式代码(uv run black src/ tests/)
6. 提交您的更改(git commit -m 'Add amazing feature')
7. 推到分支(git push origin feature/amazing-feature)
8. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

支持

对于问题、疑问或贡献：

• 在GitHub上打开一个问题
• 检查 设计文件
• 查看 需求

致谢

• 建于 FastMCP 2.0 用于简化MCP服务器开发
• 用途 紫外线 用于快速可靠的Python包管理
• 用途 派丹蒂克 用于数据验证
• 由...驱动 ServiceNow REST API