freshservice-automation

通过 Rube MCP 自动化 Freshservice

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

前提条件

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

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。完成主机的信任／身份验证设置；仅添加端点并不能建立可用的 Freshservice 连接。

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

记录与通知边界

写入数据前，确认租户／工作区、确切的工单 ID 和请求字段。工单／服务请求可能会通知相关人员、触发审批或资源配置，也可能创建联系人；读取请求并不授权这些操作。发送外部邮件需要获得对收件人和内容的明确授权。从报告中删除工单 PII／机密信息，并使用发现的架构获取当前 ID／状态代码。批量更改时，先预览 ID 列表，并核对每张工单的结果，再重试结果不确定或部分成功的操作。

核心工作流

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 为数值整数

快速参考

任务	工具 Slug	关键参数
列出工单	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

何时使用

本技能适用于执行概述中描述的工作流或操作。

限制

• 仅当任务与上述范围明确匹配时，才使用本技能。
• 请勿将输出视为特定环境验证、测试或专家评审的替代品。
• 如果缺少所需输入、权限、安全边界或成功标准，请停止并请求澄清。