Tickiti

tickiti-mcp

一个 MCP（Model Context Protocol）服务，用于向 Claude 等 AI 助手提供 Tickiti 服务台 API。它是 Tickiti Public API v1（/api/v1/...）的轻量封装：每个 MCP 工具都会转发到一个 v1 端点，并添加你的 bearer token；对于写操作，还会添加幂等键。Token 的权限就是安全边界：服务只转发调用，不会扩大权限，因此只读 token 会让助手保持只读。

📖 完整文档：https://www.tickiti.com/docs/topic/mcp_server/

工具

工单工具提供完整且经过验证的输入；API 的其余部分可通过两个通用工具访问，因此无需为每个端点单独提供工具，即可使用全部功能。

工单

工具	权限	用途
create_ticket	tickets:write	创建工单（主题+内容、模板或干预），可设置负责人、优先级、状态和参与者；必须提供 is_public
respond_to_ticket	tickets:write	发布回复；更改状态、暂缓状态、负责人、优先级、队列、主题和参与者；通过电子邮件发送完整回复时使用 send_full_email
close_ticket	tickets:write	关闭工单，可选添加最终回复和解决方案
edit_response	tickets:write	原位修改回复（完整正文、查找/替换、可见性），不发送通知；也可发布内部备注并发送通知
delete_response	tickets:write	软删除回复
add_participants / remove_participants	tickets:write	更改参与者
delete_tickets / restore_ticket	tickets:write	删除工单（按编号，或删除来自同一发件人的所有工单）并撤销删除
merge_tickets	tickets:write	合并两个工单（较早的工单会保留）
link_tickets / unlink_tickets / list_linked_tickets	tickets:write / read	Linked 面板
move_responses / copy_responses / split_ticket	tickets:write	修复对话线程：移动或复制回复，或将其拆分到新的关联工单中
change_originator	tickets:write	更改工单的提出者
delete_attachment	tickets:write	删除一个附件（例如恶意文件），同时保留记录
get_ticket / list_responses	tickets:read	工单的对话线程、参与者和关联项；使用 fields / max_body_chars 可精简较长的电子邮件对话线程
get_response	tickets:read	按 ID 获取单条回复
query_tickets	tickets:read	搜索工单
query_responses / export_responses	tickets:read	跨工单查询回复；统计数量和分组汇总；将 NDJSON 导出到磁盘
get_attachment / download_attachment	tickets:read	获取附件字节数据（下载会将任意大小的内容流式写入文件）
list_queues / list_teams / list_staff / list_resolutions / get_search_modes	tickets:read	队列名称和设置、团队键、员工地址、解决方案类别、搜索词汇

设置、模板、邮件、管理

工具	能力	用途
list_perspectives / get_perspective	settings:read	已保存的视图，包含条件和排序方式
list_watchlists	settings:read	关注列表
list_stock_responses / get_stock_response	settings:read	标准回复（搜索、正文）
create_stock_response / update_stock_response / delete_stock_response	settings:write	编辑标准回复
get_template / search_templates / render_template	templates:read	模板和常见问题；使用数据渲染模板，但不发送
create_template / update_template	templates:write	编辑模板（更新时只会更改提供的字段）
upload_template_image	templates:write / settings:write	为模板或标准回复上传图片
send_email / search_sent_mail	mail:write / mail:read	发送邮件；搜索已发送的邮件
list_api_tokens / create_api_token / update_api_token / revoke_api_token	administration:*	API 密钥（令牌只能授予其自身具备的能力）
list_workflow	workflow:read	解决类别、干预措施、升级处理
run_report	reports:read	分析报告
get_token_info	任意	此令牌可以执行的操作：能力、所有者角色、套餐
list_instances	—	已配置的 Tickiti 实例（见下文）
list_endpoints	—	所有 API 端点，包含能力、路径和正文参数
tickiti_call	按端点而定	按类别和操作调用任意 /api/v1 端点

对于命名工具（邮件、模板、工作流写入、管理、主管）之外的任何操作，助手会使用 list_endpoints 查找操作，然后使用 tickiti_call 执行——覆盖整个 v1 API。

要求

• Node.js 20 或更高版本
• Tickiti API 令牌，从 管理 → API 密钥创建，并限定为你希望助手具备的能力
• 支持 MCP 的客户端，例如 Claude Code 或 Claude 桌面应用

安装

git clone https://github.com/tickiti/tickiti-mcp.git
cd tickiti-mcp
npm install
npm run build

构建后的服务为 dist/server.js。

配置

服务会读取两个环境变量（如果任一变量缺失，启动时会立即报错）：

变量	用途
TICKITI_API_BASE	Tickiti 安装的公开地址，末尾不加斜杠，例如 https://support.example.com。服务会追加 /api/v1/…。
TICKITI_API_TOKEN	Bearer 令牌。其能力决定助手可以执行的操作。

多个实例

要通过一个服务访问多个 Tickiti 安装实例（例如生产环境和预发布环境），请添加 TICKITI_INSTANCES：可以是 JSON，也可以是 JSON 文件的路径，将名称映射到 { "base", "token" }。 TICKITI_API_BASE / TICKITI_API_TOKEN 仍为默认实例，其名称由 TICKITI_INSTANCE_NAME 指定（默认为 default）。

TICKITI_INSTANCE_NAME=production
TICKITI_INSTANCES='{"staging": {"base": "https://staging.example.com", "token": "…"}}'

之后，每个工具都会接受可选的 instance 参数；list_instances 会显示实例名称。

与 Claude Code 配合使用

claude mcp add tickiti \
  --env TICKITI_API_BASE=https://support.example.com \
  --env TICKITI_API_TOKEN=YOUR_TICKITI_API_TOKEN \
  -- node /absolute/path/to/tickiti-mcp/dist/server.js

使用 claude mcp list（或在会话中使用 /mcp）确认。使用 claude mcp remove tickiti 移除。

其他 MCP 客户端会在各自的设置文件中配置服务，但格式相同： 将 node /absolute/path/to/tickiti-mcp/dist/server.js 作为 stdio 服务运行，并在其环境中设置 TICKITI_API_BASE 和 TICKITI_API_TOKEN。

权限与安全

该服务不添加任何自身权限。每次调用都以令牌所属的员工用户身份运行，并受令牌权限限制——与直接调用 API 完全相同。若要限制助手的操作能力，请创建权限范围较窄的令牌：

• 只读令牌（例如 tickets:read、reports:read）可让助手查看内容，但无法进行任何更改。
• 仅为助手需要操作的类别授予写入权限。
• 如果调用被拒绝，服务会说明原因（缺少权限、角色或套餐）。

写入工单的工具每次调用都会发送幂等键，因此重试请求不会创建重复的工单或回复。

长文本正文可通过 content_path（本地文件）提供，而非使用 content；文件和图像始终通过路径传递：服务会读取它们，因此其字节不会经过模型。

工作原理

文件	作用
src/client.ts	请求核心：基础 URL、Bearer 身份验证、幂等处理、错误规范化
src/result.ts	将 API 结果映射为 MCP 工具结果封装
src/manifest.ts	基于生成的路由清单提供辅助功能（查找、路径构建）
src/generated/manifest.ts	自动生成的路由表（请勿编辑）
src/tools/tickets.ts	工单写入——经过验证的输入架构
src/tools/ticket-reads.ts	工单、回复和附件读取
src/tools/ticket-operations.ts	删除、合并、关联、移动、发起人、删除附件、查找
src/tools/settings-writes.ts	预设回复和模板
src/tools/admin.ts	邮件、模板渲染和图像、视图、API 密钥、实例
src/tools/reads.ts	命名读取工具（设置 / 工作流 / 报告）
src/tools/generic.ts	list_endpoints + tickiti_call
src/param-hints.ts	对于没有专用工具的端点，list_endpoints 显示的正文参数
src/server.ts	入口点：注册工具，连接 stdio 传输
scripts/build-manifest.mjs	根据 Tickiti 路由表重新生成清单

维护者

src/generated/manifest.ts 根据 Tickiti 自身的路由表（php artisan route:list --json）生成，因此权限、角色、套餐限制和路径参数都无需手动维护。API 更改后，请基于 Tickiti 检出版本重新生成：

TICKITI_DIR=/path/to/tickiti npm run manifest

tests/all-paths.mjs 中提供了对每个端点进行端到端遍历的测试（npm run test:paths，需要基础 URL、针对临时实例的全权限令牌），而 tests/smoke-tools.mjs 中则提供了工具注册的离线检查（npm run build && node tests/smoke-tools.mjs）。

有几个工具会调用 2026 年 10 月添加到 Tickiti 的端点。在较旧的安装版本中，这些调用会返回 404；list_endpoints 会描述最新的 API。

许可证

MIT © Oxenic