Help Scout MCP 服务器

帮助侦察MCP服务器

帮助侦察MCP服务器 -通过企业级安全和高级搜索功能，将Claude和其他人工智能助手连接到您的Help Scout数据。

📖 目录

• 🎉 新增功能
• ⚡ 快速开始
• 🔑 API证书
• 🛠️ 工具和功能
• ⚙️ 配置
• 🔍 故障排除
• 🤝 贡献

🎉 v1.2.1的新增功能

• 🎯 DXT扩展：一键安装Claude Desktop
• 🔧 清除环境变量: HELPSCOUT_CLIENT_ID 和 HELPSCOUT_CLIENT_SECRET
• ⚡ 连接池：通过HTTP连接重用提高了性能
• 🛡️ 增强的安全性：全面的输入验证和API约束
• 🔄 依赖注入：使用ServiceContainer实现更清洁的架构
• 🧪 综合测试：69%以上的分支覆盖率，具有可靠的测试

先决条件

• Node.js 18+ （用于命令行）
• 帮助Scout帐户 具有API访问权限
• OAuth2应用程序 或 个人访问令牌 来自Help Scout
• 克劳德桌面 （用于DXT安装）或任何MCP兼容客户端

备注：DXT扩展包括Node.js，因此Claude Desktop用户不需要本地安装。

快速开始

🎯 选项1:克劳德桌面（DXT一键安装）

使用最简单的设置 DXT（桌面扩展） -无需配置：

1. 下载最新 .dxt 文件来自发布
2. 双击以在Claude Desktop中安装
3. 出现提示时，输入您的Help Scout OAuth2客户端ID和客户端密码
4. 立即开始使用！

📋 选项2:Claude桌面（手动配置）

{
  "mcpServers": {
    "helpscout": {
      "command": "npx",
      "args": ["help-scout-mcp-server"],
      "env": {
        "HELPSCOUT_CLIENT_ID": "your-client-id",
        "HELPSCOUT_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

🐳 选项3:Docker

docker run -e HELPSCOUT_CLIENT_ID="your-client-id" \
  -e HELPSCOUT_CLIENT_SECRET="your-client-secret" \
  drewburchfield/help-scout-mcp-server

💻 选项4：命令行

HELPSCOUT_CLIENT_ID="your-client-id" \
HELPSCOUT_CLIENT_SECRET="your-client-secret" \
npx help-scout-mcp-server

获取API凭据

🎯 推荐：OAuth2客户端凭据

1. 首选 帮助童子军 → 我的应用程序 → 创建私人应用程序
2. 填写应用程序详细信息并选择所需范围
3. 复制您的 客户端ID 和 客户端密钥
4. 在配置中使用：
   • HELPSCOUT_CLIENT_ID=your-client-id
   • HELPSCOUT_CLIENT_SECRET=your-client-secret

🔐 替代方案：个人访问令牌

1. 首选 帮助童子军 → 您的个人资料 → API密钥
2. 创建新 个人访问令牌
3. 在配置中使用： HELPSCOUT_API_KEY=Bearer your-token-here

特性

• 🔍 高级搜索：多状态对话搜索、内容过滤、布尔查询
• 📊 智能分析：对话摘要、线程检索、收件箱监控
• 🔒 企业安全：PII编辑、安全令牌处理、全面的审计日志
• ⚡ 高性能：内置缓存、速率限制、自动重试逻辑
• 🎯 易于集成：适用于Claude Desktop、Cursor、Continue.dev等

工具和功能

核心搜索工具

分析和检索工具

资源

• helpscout://inboxes -列出所有可访问的收件箱
• helpscout://conversations -使用过滤器搜索对话
• helpscout://threads -获取对话的线程消息
• helpscout://clock -当前服务器时间戳

搜索示例

推荐：多状态搜索

// Best approach - automatically searches active, pending, and closed
comprehensiveConversationSearch({
  searchTerms: ["urgent", "billing"],
  timeframeDays: 60,
  inboxId: "256809"
})

内容特定搜索

// Search in message bodies and subjects
comprehensiveConversationSearch({
  searchTerms: ["refund", "cancellation"],
  searchIn: ["both"],
  timeframeDays: 30
})

// Customer organization search
advancedConversationSearch({
  emailDomain: "company.com",
  contentTerms: ["integration", "API"],
  status: "active"
})

Help Scout查询语法

// Advanced query syntax support
searchConversations({
  query: "(body:\"urgent\" OR subject:\"emergency\") AND tag:\"escalated\"",
  status: "active"
})

配置选项

兼容性

适用于任何 模型上下文协议（MCP） 兼容客户端：

• 🖥️ 桌面应用程序：Claude Desktop、AI编码助手和其他支持MCP的桌面应用程序
• 📝 代码编辑器：VS代码扩展、游标和其他支持MCP的编辑器
• 🔌 自定义集成：任何实施MCP标准的应用程序
• 🛠️ 开发工具：命令行MCP客户端和自定义自动化脚本

主平台: 克劳德桌面 具有完整的DXT和手动配置支持

由于此服务器遵循MCP标准，因此它可以自动与任何当前或未来的MCP兼容客户端一起工作。

安全与隐私

• 🔒 PII保护：默认情况下已编辑邮件内容
• 🛡️ 安全认证：OAuth2客户端凭据或自动刷新的个人访问令牌
• 📝 审计日志：全面的请求跟踪和错误记录
• ⚡ 速率限制：具有指数回退的内置重试逻辑
• 🏢 企业就绪：符合SOC2的部署选项

发展

# Quick start
git clone https://github.com/drewburchfield/help-scout-mcp-server.git
cd help-scout-mcp-server
npm install && npm run build

# Create .env file with your credentials (OAuth2)
echo "HELPSCOUT_CLIENT_ID=your-client-id" > .env
echo "HELPSCOUT_CLIENT_SECRET=your-client-secret" >> .env

# Start the server
npm start

故障排除

常见问题

认证失败

# Verify your credentials
echo $HELPSCOUT_CLIENT_ID
echo $HELPSCOUT_CLIENT_SECRET

# Test with curl
curl -X POST https://api.helpscout.net/v2/oauth2/token \
  -d "grant_type=client_credentials&client_id=$HELPSCOUT_CLIENT_ID&client_secret=$HELPSCOUT_CLIENT_SECRET"

连接超时

• 检查您的网络连接 api.helpscout.net
• 验证没有防火墙阻止HTTPS流量
• 考虑增加 HTTP_SOCKET_TIMEOUT 环境变量

速率限制

• 服务器通过指数回退自动处理速率限制
• 如果您经常看到429错误，请减少并发请求
• 监视重试模式的日志

空搜索结果

• 使用API凭据验证收件箱权限
• 检查对话是否存在以及您是否有访问权限
• 尝试更广泛的搜索词或不同的时间范围

调试模式

启用调试日志以排除问题：

LOG_LEVEL=debug npx help-scout-mcp-server

获取帮助

如果你仍然有问题：

1. 检查 现有问题
2. 启用调试日志记录并共享相关日志
3. 包括您的配置（无凭据！）

贡献

我们欢迎捐款！以下是如何开始：

🚀 快速开发设置

git clone https://github.com/drewburchfield/help-scout-mcp-server.git
cd help-scout-mcp-server
npm install

🔧 开发工作流程

# Run tests
npm test

# Type checking
npm run type-check

# Linting
npm run lint

# Build for development
npm run build

# Start development server
npm run dev

📋 提交前

• ✅ 所有测试均通过(npm test)
• ✅ 类型检查通过(npm run type-check)
• ✅ 林廷传球(npm run lint)
• ✅ 为新功能添加测试
• ✅ 必要时更新文档

🐛 错误报告

报告错误时，请包括：

• 帮助Scout MCP服务器版本
• Node.js版本
• 身份验证方法（OAuth2/个人访问令牌）
• 错误消息和日志
• 重现步骤

💡 功能请求

我们很想听听你的想法！请打开一个问题，描述：

• 你试图解决的问题
• 您提出的解决方案
• 你考虑过的任何替代方法

支持

• 问题: GitHub问题
• 讨论: GitHub讨论
• NPM包: 帮助侦察mcp服务器

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

需要帮助？ 打开一个问题 或查看我们的 文档.