swsd

swsd-mcp

适用于 SolarWinds Service Desk（SWSD / Samanage）的 MCP 服务。 可与任何 Model Context Protocol 客户端配合使用，通过每位用户自己的 SWSD API 令牌处理工单、服务请求、知识库工作、变更/发布工作流、资产/CMDB 上下文、采购记录、风险、工时记录和附件。请参阅客户端兼容性矩阵查看经过测试的列表。

📖 完整文档： mcp-swsd.pages.dev

此服务不会在静态存储中保留任何凭据。令牌会随每个请求转发，从不持久化、从不记录日志，且只会发送到配置的 SWSD API 主机。

---

升级到 3.0.0

MCP SDK v2 保留全部 66 个工具、五种配置文件、七个小组件和四种旧版 HTTP/STDIO 协议版本。现在，未知工具名称会引发 JSON-RPC -32602 错误；SDK 调用方应捕获这些被拒绝的调用。已知工具的验证错误仍会返回 isError: true，但错误文本已更新。严格的架构验证器和工具列表快照应接受新的 JSON Schema 2020-12 序列化格式。Node 24 要求和启动配置保持不变。详情请参阅变更日志。

快速开始

你需要：

• 已安装 MCP 客户端：任何兼容 MCP 的客户端均可使用（兼容性矩阵）
• SolarWinds Service Desk 管理员令牌（JWT）：在 SWSD 界面中生成：Setup → Users & Groups → Users → 点击你的用户 → Actions → Generate JSON Web Token（需要 Service Desk 管理员权限）

VS Code

1. 打开命令面板：Windows/Linux 上按 Ctrl+Shift+P，macOS 上按 Shift+Command+P。
2. 运行 MCP: Add Server...。

3. 使用以下任一受支持的本地选项进行安装：

   • 命令（stdio）：输入 npx -y swsd-mcp。
   • NPM Package：输入 swsd-mcp，确认发布者为 mikimatsub，然后选择 Allow。

4. 将服务命名为 swsd，然后为 VS Code 配置文件选择 Global，或为当前项目选择 Workspace。
5. 安全添加 SWSD 令牌并验证连接。

其他 stdio 客户端

1. 添加配置

下方列出的非 VS Code 客户端使用此通用 JSON 格式。将其添加到客户端配置文件的 mcpServers 下：

{
  "mcpServers": {
    "swsd": {
      "command": "npx",
      "args": ["-y", "swsd-mcp"],
      "env": {
        "SWSD_TOKEN": "your-jwt-here",
        "SWSD_BASE_URL": "https://api.samanage.com"
      }
    }
  }
}

将 your-jwt-here 替换为你的令牌。欧盟租户请改用 https://apieu.samanage.com。如需自定义行为，可在同一 env 块中添加任意配置变量（最常用的是用于选择工具集的 SWSD_PROFILE）。

2. 放入正确的文件

客户端	配置文件路径
Claude Desktop（macOS）	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop（Windows）	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop（Linux）	~/.config/Claude/claude_desktop_config.json
Claude Code	~/.claude.json（或使用下方的快捷方式）
Cursor	~/.cursor/mcp.json
Continue、Cline 和其他客户端	查看客户端文档：JSON 结构相同

如果文件不存在，请创建该文件。然后重启客户端。

Claude Code 快捷方式：无需手动编辑文件。将这单行原样粘贴到任何 shell（bash、zsh、PowerShell、cmd）中：

claude mcp add swsd --env SWSD_TOKEN="your-jwt-here" --env SWSD_BASE_URL="https://api.samanage.com" -- npx -y swsd-mcp

Microsoft Copilot Studio：路径不同。Copilot Studio 无法启动本地进程，因此需要使用 HTTP 传输的服务。请参阅 copilot-studio/README.md 和 Azure Container Apps 配置方案。

3. 验证是否正常工作

在 MCP 客户端中询问：

“使用 swsd 检查是否能够连接。”

Agent 应调用 swsd_health_check 并报告成功。如果成功，就表示已完成设置。还可以试试以下问题：

• “显示事件 60310”：按 ID 查询的工具既接受内部 ID（≥7 位数字），也接受 SWSD 界面中显示的用户可见编号（≤6 位数字）。
• “列出过去 7 天内更新的事件”：updated_within: "7d"（也支持 "24h"、"1w"、"30d"）。
• “分配给我的工单有哪些？”：swsd_list_my_incidents 会在内部调用 swsd_get_me，因此无需明确提供电子邮件地址。

---

工具（15 个类别，共 66 个）

类别	工具
实用工具	swsd_get_server_info、swsd_health_check、swsd_get_me
事件	swsd_list_incidents、swsd_list_my_incidents、swsd_get_incident、swsd_create_incident、swsd_update_incident、swsd_assign_incident、swsd_update_incident_state、swsd_link_solution_to_incident
评论	swsd_list_incident_comments、swsd_add_incident_comment、swsd_update_comment
任务	swsd_list_incident_tasks、swsd_create_incident_task、swsd_update_task_state
问题	swsd_list_problems、swsd_get_problem、swsd_create_problem
变更与发布	swsd_list_changes、swsd_get_change、swsd_create_change、swsd_update_change、swsd_list_releases、swsd_get_release、swsd_create_release、swsd_update_release
资产与 CMDB	swsd_list_hardware_assets、swsd_get_hardware_asset、swsd_list_mobile_devices、swsd_get_mobile_device、swsd_list_printers、swsd_get_printer、swsd_list_software_assets、swsd_get_software_asset、swsd_list_other_assets、swsd_get_other_asset、swsd_list_configuration_items、swsd_get_configuration_item
采购与风险	swsd_list_contracts、swsd_get_contract、swsd_list_purchase_orders、swsd_get_purchase_order、swsd_list_vendors、swsd_get_vendor、swsd_list_risks
时间跟踪	swsd_list_time_tracks、swsd_log_time、swsd_update_time_track
附件	swsd_upload_attachment
解决方案 / 知识库	swsd_search_solutions、swsd_get_solution、swsd_create_solution、swsd_update_solution
服务目录	swsd_list_catalog_items、swsd_get_catalog_item、swsd_create_service_request
查询	swsd_list_categories、swsd_list_sites、swsd_list_departments、swsd_list_users、swsd_list_groups、swsd_list_roles
自定义字段	swsd_describe_custom_fields
审计	swsd_get_record_audits

MCP 客户端会在运行时自动发现每个工具的输入架构、说明和输出结构。完整的工具文档请参阅工具参考。

---

MCP Apps 微件（富 UI）

七个读取工具通过 MCP Apps 能力提供交互式 UI 套件。在支持该能力的主机（Claude Desktop、Claude Web、VS Code Copilot Chat、ChatGPT、Goose、Postman）上，工具会在结构化响应旁返回渲染后的微件。在仅支持文本的主机（Claude Code、LM Studio）上，这些工具会返回常规结构化负载。

示例：swsd_list_incidents 渲染 incident-list 微件。数据为合成数据；不含真实租户信息。所有七个微件的截图请参阅完整图库。

工具	微件	渲染内容
swsd_get_incident	incident-detail	单条记录卡片（描述、到期日期、SLA、解决方案、自定义字段）
swsd_get_solution	solution-detail	正文经过清理的知识库文章
swsd_list_incidents、swsd_list_my_incidents	incident-list	可筛选、可排序的表格
swsd_list_incident_comments	comment-thread	按垂直方向排列的对话，带作者标签和公开／私密徽标
swsd_get_record_audits	audit-timeline	按日分组的时间线，带操作标签和字段差异
swsd_get_catalog_item	catalog-item-form	通过 swsd_create_service_request 提交的表单
swsd_describe_custom_fields	custom-fields	可搜索的浏览器，支持范围／模块筛选

截图和各微件的详细信息请参阅 Widgets 参考。

---

配置

大多数用户只需设置 SWSD_TOKEN 和 SWSD_BASE_URL：

变量	默认值	备注
SWSD_TOKEN	None	必需。你的 SWSD 管理员令牌（JWT）。
SWSD_BASE_URL	https://api.samanage.com	EU 租户：https://apieu.samanage.com
SWSD_PROFILE	agent	triage、agent、knowledge、operations 或 full：参阅 Profiles
SWSD_WRITE_MODE	live	live、dry-run 或 disabled：预览或禁用写入工具，但不更改配置档案
SWSD_ATTACHMENT_ROOT	None	可选，为 stdio 模式下本地 file_path 上传设置真实路径边界

完整的环境变量参考（HTTP 传输、重试、速率限制、允许列表）请参阅配置。

---

配置档案

配置档案控制启动时注册哪些工具。会话期间无法更改。

配置档案	用途	工具数量
triage	以读取为主的一线支持和评论	14
agent	完整的工单处理工作流（默认）	37
knowledge	知识库编写工作流和事件读取	15
operations	Agent 工作流，以及变更／发布、ITAM、CMDB、采购和风险相关信息	64
full	所有工具	66

使用 SWSD_ENABLE_EXTRAS=swsd_foo,swsd_bar 可在配置档案基础上添加指定工具。

---

托管 HTTP 服务（高级）

上方的快速开始会在你自己的机器上运行 swsd-mcp：MCP 客户端按需通过 npx 启动它。大多数用户到此即可。

仅在以下情况需要设置 HTTP 模式服务：

• 集成 Microsoft Copilot Studio：Copilot Studio 无法启动本地进程
• 团队共用一个实例：部署一次，供多人使用，每个人在每次请求中提供自己的令牌
• 更严格的网络控制：私有 VNet、IP 允许列表、自定义域名

Docker 镜像可在任何环境运行：Azure、AWS、GCP、Render、Fly.io 或你自己的 VM。完整指南请参阅部署，以及 Azure Container Apps 配置教程（建议用于 Copilot Studio；支持缩容至零，按使用量计费）。

---

文档

• SECURITY.md：通过 GitHub Security Advisories 报告漏洞
• docs/SECURITY-POSTURE.md：安全控制、供应链加固、验证方法
• CONTRIBUTING.md：错误报告、PR 审查标准、本地开发环境设置
• CHANGELOG.md：版本历史
• copilot-studio/：Microsoft Copilot Studio Swagger 连接器规范和导入指南
• docs/deployment/：云部署方案

---

许可证

MIT：参见 LICENSE。按“原样”提供，不作任何保证。

商标

SolarWinds、Samanage 和 Service Desk 是 SolarWinds Worldwide, LLC 的商标。本项目与 SolarWinds 无关，也未获得其认可或赞助。本项目封装了公开文档中记载的 SWSD REST API。