SDP MCP

服务台+MCP服务器

与Service Desk Plus Cloud API集成的模型上下文协议（MCP）服务器，使人工智能助手能够在所有Service Desk+实体上执行CRUD操作。

🚀 现状（2025年1月）

🎉 生产就绪 -完整的服务台+MCP服务器\ ✅ 所有16个工具工作正常 （100%成功率）\ ✅ 企业级 -与全面的OAuth作用域完全集成ITSM\ ✅ 电子邮件通信 -通过票证对话集成回复请求者\ ✅ 零OAuth问题 -具有速率限制保护的防弹令牌管理\ ✅ 完成测试 -所有工具都经过全面的客户端测试验证\ ✅ 生产就绪 -强大的错误处理和业务规则合规性

最近的改进

• 🔧 修复了从Bearer到Zoho oauthtoken的授权头格式
• 🔧 添加子类别作为创建请求的必填字段
• 🔧 使用search_criteria实现了正确的list_info结构
• 🔧 添加了具有复杂条件的高级搜索功能
• 🔧 创建了全面的OAuth和搜索文档
• 🔧 Mock API现在完美地复制了真实的API行为
• 🔧 新：用于请求者回复的电子邮件通信工具
• 🔧 新：私人笔记和第一响应功能
• 🔧 新：完整对话历史检索

工具状态

• ✅ list_requests -使用正确的搜索标准
• ✅ 获取请求 -工作
• ✅ 搜索请求 -通过高级标准支持增强
• ✅ 获取元数据 -工作
• ✅ add_note -工作
• ✅ 回复请求者 - 新 -电子邮件回复功能正常工作
• ✅ add_private_note - 新 -私人笔记工作
• ✅ send_first_response - 新 -第一次回复电子邮件工作
• ✅ get_request_conversation - 新 -对话历史记录工作
• ✅ 列表_技术人员 -使用回退到/users端点
• ✅ get技术员 -工作
• ✅ 查找技术员 -工作
• ✅ 创建请求 -已修复子类别支持问题
• ✅ update_request -正在工作（优先级更新被API设计阻止）
• ✅ close_request -正确处理封盖
• ✅ claude_code命令 -工作

工作实施

• 建筑：服务器发送事件（SSE）上的直接MCP协议
• 位置: sdp-mcp-server/src/working-sse-server.cjs
• 状态：所有Service Desk Plus工具均可使用
• 客户端：已成功使用Claude Code进行测试

📋 可用工具

请求管理

1. list_requests -使用可选过滤器列出服务台请求
2. 获取请求 -获取特定请求的详细信息
3. 搜索请求 -使用各种条件搜索请求
4. 创建请求 -创建新的服务台请求
5. update_request -更新现有请求
6. close_request -使用关闭信息关闭请求
7. add_note -为现有请求添加注释

电子邮件通信（新）

1. 回复请求者 -向请求者发送电子邮件回复（出现在工单对话中）
2. add_private_note -添加请求者不可见的私人笔记
3. send_first_response -发送第一个回复并发送电子邮件通知
4. get_request_conversation -获取完整的对话历史记录

技术人员管理

1. 列表_技术人员 -列出可供分配的技术人员
2. get技术员 -获取详细的技术人员信息
3. 查找技术员 -通过姓名或电子邮件查找技术人员

公用事业

1. 获取元数据 -获取下拉菜单的有效字段值
2. claude_code命令 -执行Claude代码命令

🔧 最近的修复和改进

OAuth身份验证

• 固定授权头格式： Zoho-oauthtoken 而不是 Bearer
• 实现了单例OAuth客户端以防止速率限制
• 添加全局刷新锁以防止并发令牌刷新
• 代币现在可以正确重复使用，直到到期

API现场处理

• 新增强制性 subcategory 请求创建字段
• 修复了使用适当的状态过滤 search_criteria 格式
• 实现了API，每个请求最多100行
• 添加了对使用逻辑运算符的复杂搜索查询的支持

模拟API服务器

• 完全复制真实的API行为
• 包括所有错误响应和业务规则
• 测试数据包括Clay Meuth技术人员（ID:2168260000000006907）
• 支持两者 /technicians 和 /users 端点

🔧 快速开始

先决条件

• Node.js 18+
• 具有OAuth凭据的Service Desk Plus Cloud帐户
• 永久刷新令牌（永不过期！）

设置

1. 克隆存储库

git clone https://github.com/PTTG-IT/SDP-MCP.git
cd SDP-MCP/sdp-mcp-server

1. 安装依赖项

npm install

1. 配置环境

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

1. 启动服务器

./start-sse-server.sh

服务器将在端口3456上启动。

客户端配置

对于Claude Code或其他MCP客户：

{
  "mcpServers": {
    "service-desk-plus": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3456/sse", "--allow-http"]
    }
  }
}

对于远程访问：

{
  "mcpServers": {
    "service-desk-plus": {
      "command": "npx",
      "args": ["mcp-remote", "http://192.168.2.10:3456/sse", "--allow-http"]
    }
  }
}

对于Windows VS代码：

{
  "mcpServers": {
    "service-desk-plus": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://10.212.0.7:3456/sse", "--allow-http"]
    }
  }
}

🧪 使用模拟API进行测试

该项目包括一个完整的模拟API服务器，用于安全测试：

# Start mock API server (port 3457)
npm run mock:api

# Use mock API with SSE server
export SDP_USE_MOCK_API=true
./start-sse-server.sh

模拟API：

• 从真实的API复制准确的错误响应
• 执行相同的业务规则（无法更新已关闭的工单）
• 包括测试数据 is_mock: true 标识符
• 非常适合开发和测试

📚 文档

知识库

• example/knowledge/service-desk-plus-authentication.md -OAuth实现指南
• example/knowledge/service-desk-plus-oauth-complete.md -完整的OAuth参考
• example/knowledge/service-desk-plus-search-criteria.md -高级搜索指南
• example/knowledge/service-desk-plus-mandatory-fields.md -必填字段参考
• example/knowledge/service-desk-plus-sse-implementation.md -SSE服务器详细信息

API文档

• 主要文件：https://www.manageengine.com/products/service-desk/sdpod-v3-api/
• OAuth指南：https://www.manageengine.com/products/service-desk/sdpod-v3-api/getting-started/oauth-2.0.html

🔑 OAuth配置

所需的环境变量

# Service Desk Plus Configuration
SDP_BASE_URL=https://helpdesk.yourdomain.com   # Custom domain
SDP_INSTANCE_NAME=itdesk                       # Instance name
SDP_PORTAL_NAME=yourportal                     # Portal name
SDP_DATA_CENTER=US                             # Data center (US, EU, IN, AU, JP, UK, CA, CN)

# OAuth Credentials
SDP_OAUTH_CLIENT_ID=your_client_id
SDP_OAUTH_CLIENT_SECRET=your_client_secret_here
SDP_OAUTH_REFRESH_TOKEN=your_permanent_refresh_token_here

# Optional: Use mock API for testing
SDP_USE_MOCK_API=false

OAuth设置步骤

1. 在Service Desk Plus中创建自客户端OAuth应用程序
2. 生成具有所需范围的授权码
3. 永久刷新令牌的交换代码
4. 使用凭据配置.env

看 docs/OAUTH_SETUP_GUIDE.md 详细说明。

🏗️ 建筑

当前实施（单个租户）

• 在SSE上直接实现MCP协议
• 通过环境变量配置OAuth令牌
• Singleton OAuth客户端可防止速率限制问题
• 仅在401错误时刷新智能令牌
• 生产就绪并经过全面测试

未来多租户架构

当MCP协议发展到支持无状态连接时：

• 多个客户端连接到单个服务器
• 每租户OAuth令牌管理
• 完全隔离租户
• 数据库支持的令牌存储

🐛 故障排除

常见问题

1. OAuth速率限制

- 错误：“您连续发出的请求太多” - 解决方案：等待5-15分钟，服务器实现适当的令牌重用

1. 字段验证错误（4012）

- 错误：缺少必填字段 - 解决方案：检查实例配置中的必填字段

1. 优先级更新错误（403）

- 错误：“无法为优先级赋值” - 解决方案：这是API限制，优先级可能不可更新

1. 身份验证错误（401）

- 错误：“未经授权” - 解决方案：验证OAuth令牌和自定义域配置

调试模式

# Enable debug logging
export DEBUG=sdp:*
./start-sse-server.sh

🤝 贡献

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

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

🙏 致谢

• Service Desk Plus API管理引擎
• 模型上下文协议的拟人化
• Claude测试和集成代码

📞 支持

对于问题和疑问：

• GitHub问题：https://github.com/PTTG-IT/SDP-MCP/issues
• 文件：检查 example/knowledge/ 文件夹
• API参考：https://www.manageengine.com/products/service-desk/sdpod-v3-api/

______________________________________________________________________

备注：这是服务台升级版 云 （SDPOnDemand），而非现场安装。