simple-support-system-mcp

simple-support-system-mcp

面向 Concrete CMS 的 Simple Support System 插件 REST API 的本地 MCP 服务（stdio）。它让助手像人工客服一样处理支持队列：查找工单、连同历史记录一起阅读、撰写回复，并将工单推进到下一个状态。项目、附件和审核也都涵盖在内。

该服务可与运行此软件包的任何站点通信。所有内容都不是硬编码的，站点 URL 和 API 密钥通过环境变量提供。它仅使用 stdio 通信，绝不会打开端口。

安装

npm install
npm run build

在 Claude Code 中注册此服务：

claude mcp add simple-support-system \
  -e SIMPLE_SUPPORT_SYSTEM_BASE_URL=https://support.example.com \
  -e SIMPLE_SUPPORT_SYSTEM_API_KEY=your-api-key \
  -- node "/absolute/path/to/simple-support-system-mcp/dist/src/index.js"

或者在 ~/.claude.json / claude_desktop_config.json 中注册：

{
  "mcpServers": {
    "simple-support-system": {
      "command": "node",
      "args": ["/absolute/path/to/simple-support-system-mcp/dist/src/index.js"],
      "env": {
        "SIMPLE_SUPPORT_SYSTEM_BASE_URL": "https://support.example.com",
        "SIMPLE_SUPPORT_SYSTEM_API_KEY": "your-api-key"
      }
    }
  }
}

环境变量

变量	用途
SIMPLE_SUPPORT_SYSTEM_BASE_URL	必填。Concrete CMS 站点的基础 URL，例如 https://support.example.com。系统会自动附加 API 路径 /index.php/api/v1；如果 URL 已以 /api/v1 结尾，则按原样使用。
SIMPLE_SUPPORT_SYSTEM_API_KEY	此安装实例的 API 密钥，通过 X-Api-Key 标头发送。没有此密钥时，只能访问 API 的公开部分。
SIMPLE_SUPPORT_SYSTEM_API_PATH	可选。覆盖默认 API 路径，适用于不使用 index.php 调度程序的站点，例如 /api/v1。
SIMPLE_SUPPORT_SYSTEM_PROJECT_TOKEN	可选。私有项目的默认访问令牌；工具调用未提供自己的令牌时使用此令牌。
SIMPLE_SUPPORT_SYSTEM_PROJECT_ID	可选。将服务限制为此项目，参见将服务限制为一个项目。
SIMPLE_SUPPORT_SYSTEM_TIMEOUT_MS	可选。请求超时时间，单位为毫秒，默认值为 30000。

安装此软件包时会生成 API 密钥，并将其保存在站点配置的 simple_support_system.api_key 中。不提供密钥的调用会以匿名访客身份运行：仍可读取公开项目及其中已审核通过的工单、创建工单和撰写评论，但无法执行任何管理操作（更改状态、删除、审核、管理项目）。

工具

日常使用的三个工具是 list_tickets、get_ticket 和 reply_to_ticket，此外还有用于推进工单状态的 set_ticket_state。

工具	用途
list_tickets	按项目、状态、类型、优先级、负责人、文本搜索和变更日期筛选工单，并支持排序和分页。默认返回精简摘要。
get_ticket	读取单个工单及其附件；除非关闭此选项，否则还会读取所有评论。
reply_to_ticket	在工单上发布评论形式的回复，并触发通知邮件。
set_ticket_state	将工单推进到另一个工作流状态，并通知所有相关人员。
create_ticket	在项目中创建工单，可通过项目 ID 或项目标识符指定项目，并可选择上传文件。
update_ticket	修改标题、内容、类型、优先级或负责人。只会更改指定的字段。
approve_ticket	批准经过审核的工单。
delete_ticket	删除工单及其所有评论和附件链接。此操作不可逆，需设置 confirm: true。
list_ticket_comments	列出工单的评论。
update_comment	替换评论文本。
approve_comment	批准经过审核的评论。
delete_comment	删除评论。此操作不可逆，需设置 confirm: true。
list_projects	列出支持项目；配置 API 密钥后会一并返回访问令牌。
get_project	按 ID 读取单个项目。
create_project	创建项目；私有项目会生成访问令牌。
update_project	修改项目名称、标识符或可见性。
delete_project	删除项目及其中的所有工单和评论。此操作不可逆，需设置 confirm: true。
list_ticket_attachments	列出工单的附件。
upload_attachment	将本地文件上传到文件管理器，并返回其文件 ID。
add_ticket_attachments	将已上传的文件 ID 链接到工单。
download_attachment	获取附件的下载 URL，并可将其保存到本地路径。
delete_attachment	从工单中移除文件。此操作不可逆，需设置 confirm: true。
get_server_info	显示已配置的 API URL、是否存在密钥，以及可接受的状态、类型和优先级。不会返回密钥本身。

读取工具会标记为只读，四个 delete_ 工具会标记为破坏性操作。所有这些工具还都需要 confirm: true，因此不会因含糊的指令而意外触发删除。API 端没有回收站，也无法恢复；工单、评论或项目一旦删除便会彻底消失。

处理工单

list_tickets   { "state": "open", "sortBy": "updatedAt" }
get_ticket     { "ticketId": 42 }
reply_to_ticket{ "ticketId": 42, "comment": "Thanks for the report, we are on it." }
set_ticket_state { "ticketId": 42, "state": "in_progress" }

list_tickets 还支持传入 projectHandle 替代 projectId，并会先通过项目列表解析该标识符。

API 接受的值

• 状态：new、open、in_progress、on_hold、resolved、duplicate、invalid、wont_fix、closed。set_ticket_state 接受其中除 new 之外的所有状态；new 仅在创建工单时设置。
• 类型：bug、enhancement、proposal、task
• 优先级：trivial、minor、major、critical、blocker
• 状态为 closed 或 invalid 的工单会被锁定：在状态变更之前，API 会拒绝修改工单、评论和附件。

附件

upload_attachment      { "filePath": "/tmp/screenshot.png" }      -> fileId
add_ticket_attachments { "ticketId": 42, "fileIds": [123] }

upload_attachment 会将文件放入站点的文件管理器，但不会将其链接到任何位置；第二次调用会将其添加为附件。create_ticket 也可通过 attachmentFileIds 接收相同的 ID。

私有项目

私有项目只能通过其访问令牌访问。可在每次调用时将令牌作为 token 传入，或将 SIMPLE_SUPPORT_SYSTEM_PROJECT_TOKEN 设为默认值。使用 API 密钥时无需令牌，因为该密钥已授予完全访问权限。

将服务限制为单个项目

设置 SIMPLE_SUPPORT_SYSTEM_PROJECT_ID，将服务交给只需在一个项目中工作的人员；通常还会配合该项目的访问令牌使用，且不提供 API 密钥。此时，如果未指定项目，list_tickets 和 create_ticket 会使用此项目；list_projects 只会显示此项目；所有接受工单 ID 的工具都会先检查工单是否属于此项目。其他项目 ID 或句柄都会被拒绝。不提供 API 密钥时，站点本身就会将其他私有项目设为不可访问；此设置还会将此安装中的公开项目排除在视野之外。

API 说明

该软件包会以多种形式返回结果，服务会将其统一处理，使工具返回未经包装的资源：

• 集合以普通数组的形式返回；单个工单和评论分别包含在 ticket 或 comment 键中；附件则包含在 data 中。
• 失败结果可能是 {"errors": [...]}，也可能是带有 error 标记的 Concrete EditResponse。第二种形式的状态码可能为 200，因此不能仅凭 200 状态码就认定操作成功。所有错误都会转换为工具错误，并附上 API 返回的消息。
• create_ticket 返回的是状态封装，而不是新记录，因此必须通过 list_tickets 查找新创建工单的 ID。
• download_attachment 会跟随 API 返回的重定向，并报告解析后的 URL。

验证

npm run build
npm test

测试使用桩 HTTP 层运行，不会访问真实站点，也不需要凭据。测试涵盖 PHP 控制器所需的 URL 和表单编码（包括 PHP 布尔值和数组表示法）、响应封装、错误映射、list_tickets 的筛选与排序，以及破坏性工具的防护措施。

许可证

MIT，详见 LICENSE。