MCP FreeScout

FreeScout MCP 服务

用于 FreeScout 帮助台工单管理的 MCP（Model Context Protocol）服务。此服务提供用于处理 FreeScout 工单、分析问题和管理客户回复的工具。

功能

• 🎫 工单管理：获取、分析和更新 FreeScout 工单
• 🔍 智能分析：自动分析工单，确定问题类型、根本原因和解决方案
• 💬 回复草稿：根据工单分析生成客户回复
• 📊 高级搜索：提供一流的筛选参数，支持相对时间（“7d”“24h”）
• 🔒 类型安全：使用 Zod 进行完整的架构验证，并提供结构化输出
• 🔁 可靠性：针对瞬时故障，使用指数退避机制自动重试
• ⚡ 协议就绪的 stdio：全新的 buildServer 工厂可同时为 2025 年和 2026 年的 MCP stdio 客户端提供服务

v3 运行时

• 需要 Node.js 24 或更高版本。
• 使用 @modelcontextprotocol/server 2.x 和 Zod 4 输入架构。
• 通过同一个服务工厂同时提供 2025 年旧版握手协议和 2026 年 stdio 协议。
• 为稳定的分析结果和写入操作结果提供 structuredContent，无需声明输出架构。
• 接受 FreeScout 成功的 204 No Content 更新响应，并记录发起工单更新的用户 ID。

安装

前提条件

• Node.js 24 或更高版本
• 已启用 API 访问权限的 FreeScout 实例

快速开始（推荐）

使用此 MCP 服务最简单的方式是使用 npx：

使用 Claude Desktop

将以下内容添加到 Claude Desktop 设置中（macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "freescout": {
      "command": "npx",
      "args": ["@verygoodplugins/mcp-freescout@latest"],
      "env": {
        "FREESCOUT_URL": "https://your-freescout-domain.com",
        "FREESCOUT_API_KEY": "your-api-key-here"
      }
    }
  }
}

使用 Cursor IDE

将以下内容添加到 Cursor MCP 设置中：

方法 1：通过 Cursor 设置界面

1. 打开 Cursor 设置（Cmd/Ctrl + ,）
2. 搜索“MCP”
3. 点击“在 settings.json 中编辑”
4. 添加 MCP 服务配置

方法 2：手动配置 将以下内容添加到 Cursor 的 settings.json，或创建 ~/.cursor/mcp.json：

{
  "mcp": {
    "servers": {
      "freescout": {
        "command": "npx",
        "args": ["@verygoodplugins/mcp-freescout@latest"],
        "env": {
          "FREESCOUT_URL": "https://your-freescout-domain.com",
          "FREESCOUT_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

此服务只会与其环境中配置的 FreeScout 实例通信。

手动安装（替代方式）

如果你希望在本地安装并运行此服务：

1. 克隆此代码库：

git clone https://github.com/verygoodplugins/mcp-freescout.git
cd mcp-freescout

2. 安装依赖：

npm install

3. 构建 TypeScript 代码：

npm run build

4. 将 MCP 客户端配置为使用本地安装：

{
  "mcpServers": {
    "freescout": {
      "command": "node",
      "args": ["/path/to/mcp-freescout/dist/index.js"],
      "env": {
        "FREESCOUT_URL": "https://your-freescout-domain.com",
        "FREESCOUT_API_KEY": "your-api-key-here"
      }
    }
  }
}

与其他 MCP 客户端搭配使用

直接运行服务：

npm start

或者在开发模式下运行并启用自动重新加载：

npm run dev

可用工具

核心工单操作

freescout_get_ticket

获取 FreeScout 工单及其全部详情和对话串。

参数：

• ticket（必填）：工单 ID、编号或 FreeScout URL
• includeThreads（可选）：是否包含对话串（默认值：true）

自然语言示例：

• “显示工单 #12345”
• “获取 FreeScout 工单 34811 的详情”
• “获取工单 https://support.example.com/conversation/12345”
• “工单 12345 的内容是什么？”
• “打开工单 #34811 的对话”

示例：

{
  "ticket": "12345",
  "includeThreads": true
}

示例：获取包含对话串的 FreeScout 工单

freescout_analyze_ticket

分析工单，以确定问题类型、根本原因和建议的解决方案。

参数：

• ticket（必填）：工单 ID、编号或 FreeScout URL

自然语言示例：

• “分析工单 #12345”
• “工单 34811 是什么类型的问题？”
• “你能分析这张工单并告诉我它是否是 Bug 吗？”
• “检查工单 #12345 并确定根本原因”
• “这张工单是 Bug 还是功能请求？”

返回内容：

• 客户信息
• 问题描述和分类
• 代码片段和错误消息
• 可复现性状态
• 根本原因分析
• 判断是 Bug、功能请求还是第三方问题

示例：智能工单分析与问题分类

freescout_add_note

向工单添加内部备注，以便团队沟通。

参数：

• ticket（必填）：工单 ID、编号或 FreeScout URL
• note（必填）：备注内容
• userId（可选）：备注的用户 ID（默认使用 env 设置）

自然语言示例：

• “向工单 #12345 添加备注：‘已在暂存环境复现’”
• “在这张工单上留一条内部备注”
• “添加团队备注：‘客户确认修复有效’”
• “工单 34811 的备注：‘正在升级至开发团队处理’”
• “向这张工单添加内部文档”

freescout_update_ticket

更新工单状态和／或指派对象。

参数：

• ticket（必填）：工单 ID、编号或 FreeScout URL
• status（可选）：新状态（'active'、'pending'、'closed'、'spam'）
• assignTo（可选）：要将工单指派给的用户 ID

自然语言示例：

• “关闭工单 #12345”
• “将工单 34811 标记为待处理”
• “将这张工单指派给用户 ID 2”
• “将工单状态设为 active”
• “将工单 #12345 的状态更新为 closed，并指派给用户 1”

freescout_create_draft_reply

在 FreeScout 中创建可在发送前编辑的回复草稿。此工具允许 LLM 生成回复内容，并将其直接保存到 FreeScout 中作为草稿。会自动将 Markdown 格式转换为 HTML，以便在 FreeScout 中正确显示。

参数：

• ticket（必填）：工单 ID、编号或 FreeScout URL
• replyText（必填）：回复草稿内容（由 LLM 生成，支持 Markdown 格式）
• userId（可选）：创建草稿的用户 ID（默认为环境变量设置）
• to（可选）：收件人列表。省略此参数可保留现有收件人；传入 [] 可清空。
• cc（可选）：抄送人列表。省略此参数可保留现有收件人；传入 [] 可清空。
• bcc（可选）：密送人列表。省略此参数可保留现有收件人；传入 [] 可清空。

自然语言示例：

• “为工单 #12345 创建回复草稿”
• “为此工单起草一份客户回复”
• “生成并保存一份说明修复方案的回复草稿”
• “为工单 34811 起草一份给客户的回复”
• “创建一份感谢客户并说明解决方案的回复草稿”

如果省略收件人字段，服务会在可能的情况下保留 FreeScout 中当前会话的收件人。如果 FreeScout 未在会话中提供现有的 to 收件人，则会保留其通常的默认客户收件人行为。

Markdown 支持：

• 粗体文本：**text** 或 __text__ → text
• 斜体文本：*text* 或 _text_ → text
• 代码：`code` → code
• 编号列表：1. item → 转换为规范的有序列表
• 项目符号列表：- item 或 * item → 转换为规范的无序列表
• 换行：两个换行符会创建段落，单个换行符会创建换行

工作流：

1. 使用 freescout_get_ticket_context 获取客户信息和工单详情
2. 让 LLM 使用 Markdown 格式撰写个性化回复
3. 使用 freescout_create_draft_reply 将草稿保存到 FreeScout（Markdown 会自动转换为 HTML）
4. 在 FreeScout 中检查并编辑草稿，然后再发送

示例：个性化客户回复的草稿工作流

freescout_get_ticket_context

获取工单上下文和客户信息，以帮助撰写个性化回复。

参数：

• ticket（必填）：工单 ID、编号或 FreeScout URL

自然语言示例：

• “获取工单 #12345 的上下文，以便撰写回复”
• “我需要客户信息和工单详情来起草回复”
• “收集此工单的上下文，以便撰写个性化回复”
• “获取工单 34811 的客户信息和问题详情”
• “获取工单上下文，帮助撰写客户回复”

返回内容：

• 客户姓名和电子邮件
• 工单主题和状态
• 问题描述和分析
• 客户和团队的近期消息
• 分析结果（错误、功能需求或第三方问题）

freescout_search_tickets

在你的 FreeScout 实例中搜索工单。

参数：

• query（必填）：搜索查询
• status（可选）：按状态筛选（'active'、'pending'、'closed'、'spam'、'all'）
• mailboxId（可选）：按指定邮箱 ID 筛选（如果未指定，则搜索所有邮箱）

自然语言示例：

• “搜索包含 'OAuth error' 的工单”
• “查找所有包含 'HighLevel' 的待处理工单”
• “搜索有关 'plugin conflicts' 的已关闭工单”
• “查找来自客户 '[email protected]' 的工单”
• “查找所有与 'authentication' 相关的活动工单”
• “搜索邮箱 1 中包含 'bug report' 的工单”
• “查找邮箱 2 中状态为待处理的工单”

搜索参数（v2.0+）：

• textSearch（可选）：在工单内容/主题中进行纯文本搜索
• assignee（可选）：'unassigned' | 'any' | 用户 ID（数字）
• status（可选）：'active' | 'pending' | 'closed' | 'spam' | 'all'
• state（可选）：'published' | 'deleted'
• mailboxId（可选）：按指定邮箱 ID 筛选
• updatedSince（可选）：ISO 日期或相对时间，例如 "7d"、"24h"、"30m"
• createdSince（可选）：ISO 日期或相对时间
• page（可选）：分页页码（最小值：1）
• pageSize（可选）：每页结果数（最小值：1，最大值：100）

AI Agent 搜索提示：

• 对于未分配的工单：使用 assignee: "unassigned" 和 status: "active"
• 对于近期工单：使用 updatedSince: "7d" 获取最近 7 天的工单
• 对于特定用户：使用 assignee: 123（用户 ID 数字）
• 状态 "active" = 开放/活动工单（不是 "open"——该值无效）
• 按邮箱筛选前，先使用 freescout_get_mailboxes
• 组合筛选条件：{ textSearch: "error", assignee: "unassigned", updatedSince: "24h" }

freescout_get_mailboxes

获取 FreeScout 实例中所有可用邮箱的列表。

参数： 无

自然语言示例：

• “显示所有可用邮箱”
• “列出 FreeScout 中的邮箱”
• “配置了哪些邮箱？”
• “获取邮箱信息”

工作流示例

基本工单分析

// Analyze a ticket to understand the issue
await mcp.callTool('freescout_analyze_ticket', {
  ticket: '12345',
});

完整工单回复工作流

// 1. Analyze the ticket to understand the issue
const analysis = await mcp.callTool('freescout_analyze_ticket', {
  ticket: '12345',
});

// 2. Get ticket context for personalized reply
const context = await mcp.callTool('freescout_get_ticket_context', {
  ticket: '12345',
});

// 3. Create a draft reply directly in FreeScout
await mcp.callTool('freescout_create_draft_reply', {
  ticket: '12345',
  replyText: `Hi ${context.customer.name},

Thank you for reaching out! Based on my analysis, I can see that ${analysis.issueDescription}.

Here's what I found:

1. **Issue Type**: ${analysis.isBug ? 'Bug' : 'Configuration/Feature Request'}
2. **Root Cause**: ${analysis.rootCause || 'Under investigation'}

I'll look into this and get back to you shortly with a solution.

Best regards,
[Your name]`,
  cc: ['[email protected]'],
});

// 4. Update ticket status and assignment
await mcp.callTool('freescout_update_ticket', {
  ticket: '12345',
  status: 'active',
  assignTo: 1,
});

// 5. Add an internal note with findings
await mcp.callTool('freescout_add_note', {
  ticket: '12345',
  note: `Analysis complete:
- Is Bug: ${analysis.isBug}
- Third-party Issue: ${analysis.isThirdPartyIssue}
- Root Cause: ${analysis.rootCause}`,
});

回复草稿工作流

// 1. Get ticket context for personalized reply
const context = await mcp.callTool('freescout_get_ticket_context', {
  ticket: '34811',
});

// 2. Create draft reply in FreeScout (LLM crafts the content)
await mcp.callTool('freescout_create_draft_reply', {
  ticket: '34811',
  replyText: `Hi ${context.customer.name},

Thank you for reporting the HighLevel OAuth authorization issue! Your experience with the EngageBay LiveChat plugin conflict has been really valuable.

Based on what we learned from your case, I've added a new plugin conflict detection system to WP Fusion. In the next update (v3.46.7), users will see:

🔍 **Plugin Conflict Detection**
- Automatic detection of known conflicting plugins  
- Warning messages before HighLevel authorization
- Clear guidance when conflicts are detected

This should prevent the confusion you experienced and help other users avoid similar issues.

The update should be available within the next few weeks. Thanks for your patience and for helping us improve the plugin!

Best regards,
Jack`,
  to: ['[email protected]'],
  cc: ['[email protected]'],
});

// The draft is now saved in FreeScout and can be reviewed/edited before sending

处理非缺陷问题

// For third-party issues or feature requests
const reply = await mcp.callTool('freescout_create_draft_reply', {
  ticket: '12345',
  replyText: 'This is a limitation of the Elementor plugin that we cannot override.',
});

架构

组件

1. FreeScout API 客户端（freescout-api.ts）

   • 处理与 FreeScout 的所有 API 通信
   • 管理身份验证和请求格式
   • 提供工单解析工具

2. 工单分析器（ticket-analyzer.ts）

   • 智能分析工单内容
   • 问题分类（缺陷、功能或配置）
   • 提取代码片段和错误信息
   • 确定根本原因

3. MCP 服务（index.ts）

   • 工具注册和请求处理
   • 为每个 stdio 连接创建全新的服务实例
   • 响应格式化和错误处理

数据流

MCP client (2025 or 2026) → stdio entry → buildServer → FreeScout API
                                                   ↓
                                            Ticket analysis
                                                   ↓
                                            Response to client

开发

在开发模式下运行

npm run dev

运行测试

npm test

代码检查

npm run lint

构建生产版本

npm run build

配置

必需的环境变量

变量	描述	示例
FREESCOUT_URL	你的 FreeScout 实例 URL	https://support.example.com
FREESCOUT_API_KEY	FreeScout API 密钥	your-api-key-here

可选的环境变量

变量	描述	默认值
FREESCOUT_DEFAULT_USER_ID	分配工单时使用的默认用户 ID	1

高级配置示例

如需更精细的控制，你可以指定其他环境变量：

{
  "mcpServers": {
    "freescout": {
      "command": "npx",
      "args": ["@verygoodplugins/mcp-freescout@latest"],
      "env": {
        "FREESCOUT_URL": "https://support.example.com",
        "FREESCOUT_API_KEY": "your-api-key",
        "FREESCOUT_DEFAULT_USER_ID": "2"
      }
    }
  }
}

FreeScout API 设置

1. 以管理员身份登录 FreeScout 实例
2. 前往 Manage → API Keys
3. 创建具有相应权限的新 API 密钥：
   • 查看会话
   • 更新会话
   • 创建主题（用于备注）

最佳实践

工单分析

• 实施修复前，务必先分析工单
• 尝试修复前，检查第三方服务的限制
• 通过团队备注确认问题可复现

客户沟通

• 生成回复草稿供审核
• 在与客户的沟通中说明修复内容
• 对于非 Bug 问题，使用解释性回复

从 v1.x 迁移到 v2.0

破坏性变更

freescout_search_tickets 工具已重新设计，改为使用明确的筛选参数。不再支持旧版查询字符串语法。

之前（v1.x）：

{
  "query": "assignee:null",
  "status": "active"
}

之后（v2.0）：

{
  "assignee": "unassigned",
  "status": "active"
}

文本搜索：

{
  "textSearch": "authentication error",
  "assignee": "unassigned",
  "updatedSince": "7d"
}

应采用的新功能

1. 相对时间筛选：使用 "7d"、"24h"、"30m"，而非计算 ISO 日期
2. 分页：为大型结果集添加 page 和 pageSize 参数
3. 结构化输出：稳定的分析结果和写入结果包含 structuredContent；工具不会声明输出架构

自动重试

现在，服务会通过指数退避自动重试失败的请求。无需配置，开箱即用，可靠性更高。

故障排除

常见问题

API 连接错误

• 确认 FreeScout URL 包含协议（https://）
• 检查 FreeScout 中的 API 密钥权限
• 确保 FreeScout 实例已启用 API 访问
• v2.0 新增：服务会自动重试暂时性的连接错误

工单解析问题

• 服务接受工单 ID、编号和完整 URL
• URL 会自动解析以提取工单 ID
• 数字输入会被视为工单 ID

速率限制（429 错误）

• v2.0 新增：服务会自动检测速率限制并进行退避
• 重试逻辑包含带抖动的指数退避
• 无需手动干预

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 编写测试并完成更改
4. 提交拉取请求

许可证

GPL-3.0 许可证——详情请参阅 LICENSE 文件

支持

如有问题、疑问或建议：

• 在 GitHub 上提交问题
• 联系 Very Good Plugins
• 查看文档

---

由 Very Good Plugins 用 🧡 打造

路线图

• 批量工单操作
• 支持通过 Webhook 实时更新
• 常用回复模板系统
• 与 CI/CD 管道集成
• 高级搜索筛选
• 工单指标和分析
• 支持以多种语言回复客户
• 附件处理
• 自定义字段支持
• 自动化测试集成