freshservice-automation

通过 Rube MCP 实现 Freshservice 自动化

通过 Rube MCP 使用 Composio 的 Freshservice 工具包，自动化 Freshservice IT 服务管理操作。

工具包文档：composio.dev/toolkits/freshservice

前提条件

• 必须已连接 Rube MCP（可使用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Freshservice 连接，工具包为 freshservice
• 始终先调用 RUBE_SEARCH_TOOLS 以获取当前工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。无需 API 密钥——只需添加此端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 可以正常响应，以验证 Rube MCP 是否可用
2. 使用工具包 freshservice 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请按照返回的身份验证链接完成 Freshservice 身份验证
4. 在运行任何工作流之前，确认连接状态显示为 ACTIVE

核心工作流

1. 列出和搜索工单

适用场景：用户想查找、列出或搜索工单

工具调用顺序：

1. FRESHSERVICE_LIST_TICKETS - 使用可选筛选条件和分页列出工单［必需］
2. FRESHSERVICE_GET_TICKET - 获取特定工单的详细信息［可选］

列出工单的关键参数：

• filter：预定义筛选条件（'all_tickets'、'deleted'、'spam'、'watching'）
• updated_since：ISO 8601 时间戳，用于获取此时间之后更新的工单
• order_by：排序字段（'created_at'、'updated_at'、'status'、'priority'）
• order_type：排序方向（'asc' 或 'desc'）
• page：页码（从 1 开始）
• per_page：每页结果数（1-100，默认值为 30）
• include：要包含的其他字段（'requester'、'stats'、'description'、'conversations'、'assets'）

获取工单的关键参数：

• ticket_id：唯一工单 ID 或 display_id
• include：要包含的其他字段

注意事项：

• 默认仅返回过去 30 天内创建的工单
• 使用 updated_since 获取较早的工单
• 每个 include 值都会消耗额外的 API 额度
• page 从 1 开始；最小值为 1
• per_page 最大值为 100；默认值为 30
• 工单 ID 可以是内部 ID，也可以是界面中显示的 display_id

2. 创建工单

适用场景：用户想要记录新的事件或请求

工具调用顺序：

1. FRESHSERVICE_CREATE_TICKET - 创建新工单［必需］

关键参数：

• subject：工单主题（必填）
• description：工单的 HTML 描述（必填）
• status：工单状态——2（Open）、3（Pending）、4（Resolved）、5（Closed）（必填）
• priority：工单优先级——1（Low）、2（Medium）、3（High）、4（Urgent）（必填）
• email：请求者的电子邮件地址（提供 email 或 requester_id 其中之一）
• requester_id：请求者的用户 ID
• type：工单类型（'Incident' 或 'Service Request'）
• source：渠道——1（Email）、2（Portal）、3（Phone）、4（Chat）、5（Twitter）、6（Facebook）
• impact：影响级别——1（Low）、2（Medium）、3（High）
• urgency：紧急程度——1（Low）、2（Medium）、3（High）、4（Critical）

注意事项：

• subject、description、status 和 priority 均为必填项
• 必须提供 email 或 requester_id 以识别请求者
• 状态和优先级使用数字代码，而不是字符串名称
• 描述支持 HTML 格式
• 如果电子邮件地址与现有联系人不匹配，系统会创建新联系人

3. 批量更新工单

适用场景：用户希望一次更新多个工单

工具调用顺序：

1. FRESHSERVICE_LIST_TICKETS - 查找要更新的工单 [前置条件]
2. FRESHSERVICE_BULK_UPDATE_TICKETS - 更新多个工单 [必需]

关键参数：

• ids：要更新的工单 ID 数组（必需）
• update_fields：要更新的字段字典（必需）
  • 允许的键：'subject'、'description'、'status'、'priority'、'responder_id'、'group_id'、'type'、'tags'、'custom_fields'

注意事项：

• 批量更新在内部按顺序逐一执行；批次较大时可能需要较长时间
• 所有指定的工单都会收到相同的字段更新
• 如果某个工单更新失败，其他工单仍可能成功；请检查响应中的各项结果
• 无法在一次调用中为不同工单选择性地更新不同字段
• 自定义字段必须使用其内部字段名，而非显示名称

4. 通过外发邮件创建工单

适用场景：用户希望通过发送外发邮件通知来创建工单

工具调用顺序：

1. FRESHSERVICE_CREATE_TICKET_OUTBOUND_EMAIL - 创建工单并发送邮件通知 [必需]

关键参数：

• email：请求者的电子邮件地址（必需）
• subject：邮件主题 / 工单主题（必需）
• description：HTML 邮件正文内容
• status：工单状态（2=开放，3=待处理，4=已解决，5=已关闭）
• priority：工单优先级（1=低，2=中，3=高，4=紧急）
• cc_emails：抄送电子邮件地址数组
• email_config_id：发件人地址的邮件配置 ID
• name：请求者姓名

注意事项：

• 此操作会在发送邮件的同时，通过 /api/v2/tickets 端点创建标准工单
• 如果该邮箱与现有联系人不匹配，则会使用提供的姓名创建新联系人
• email_config_id 决定通知显示的发件邮箱地址

5. 创建服务请求

适用场景：用户希望提交服务目录请求

工具调用顺序：

1. FRESHSERVICE_CREATE_SERVICE_REQUEST - 为目录项目创建服务请求 [必需]

关键参数：

• item_display_id：目录项目的显示 ID（必需）
• email：请求者的电子邮件地址
• quantity：请求项目的数量（默认值：1）
• custom_fields：服务项目表单的自定义字段值
• parent_ticket_id：父工单的显示 ID（用于子请求）

注意事项：

• 可在 Admin > Service Catalog > 项目 URL 中找到 item_display_id（例如 /service_catalog/items/1）
• custom_fields 的键必须与服务项目表单字段名称一致
• 如果未指定数量，默认为 1
• 服务请求遵循为目录项目定义的审批工作流

常见模式

状态代码参考

代码	状态
2	开放
3	待处理
4	已解决
5	已关闭

优先级代码参考

代码	优先级
1	低
2	中
3	高
4	紧急

分页

• 使用 page（从 1 开始）和 per_page（最大值为 100）参数
• 每次请求将 page 加 1
• 持续请求，直到返回结果数量 < per_page
• 默认每页数量为 30

按日期范围查找工单

1. Call FRESHSERVICE_LIST_TICKETS with updated_since='2024-01-01T00:00:00Z'
2. Optionally add order_by='updated_at' and order_type='desc'
3. Paginate through results

已知注意事项

数值代码：

• 状态和优先级使用数值，而非字符串
• 来源渠道使用数值代码（1-6）
• 影响和紧急程度使用数值代码（1-3 或 1-4）

日期筛选：

• 默认仅返回最近 30 天内的工单
• 对于较早的工单，请使用 updated_since 参数
• 日期格式为 ISO 8601（例如，'2024-01-01T00:00:00Z'）

速率限制：

• Freshservice API 存在账户级速率限制
• 每个 include 选项都会额外消耗 API 配额
• 收到 429 响应时实施退避策略

响应解析：

• 响应数据可能嵌套在 data 或 data.data 下
• 使用备用模式进行稳健解析
• 工单 ID 为数值整数

快速参考

任务	工具标识	关键参数
列出工单	FRESHSERVICE_LIST_TICKETS	filter, updated_since, page, per_page
获取工单	FRESHSERVICE_GET_TICKET	ticket_id, include
创建工单	FRESHSERVICE_CREATE_TICKET	subject, description, status, priority, email
批量更新	FRESHSERVICE_BULK_UPDATE_TICKETS	ids, update_fields
出站邮件工单	FRESHSERVICE_CREATE_TICKET_OUTBOUND_EMAIL	email, subject, description
服务请求	FRESHSERVICE_CREATE_SERVICE_REQUEST	item_display_id, email, quantity

---

由 Composio 提供支持