Freshdesk MCP Server

Freshdesk MCP服务器


用于Freshdesk API v2集成的模型上下文协议（MCP）服务器实现。此服务器提供用于通过MCP接口管理票证、联系人、代理、公司和对话的工具。

特性

• 完成Freshdesk API v2集成：全力支持Freshdesk核心资源
• 内置身份验证：具有输入验证的基于API密钥的安全身份验证
• 速率限制：具有可配置限制的自动速率限制处理
• 错误处理：具有重试逻辑和指数回退的全面错误处理
• 类型安全：具有严格类型的完整TypeScript实现
• 日志记录：使用Pino进行结构化日志记录
• 安全：输入验证、注入预防和身份验证安全测试

安装

npm install
npm run build

配置

创建一个 .env 项目根目录中的文件，包含以下变量：

# Required
FRESHDESK_DOMAIN=yourcompany.freshdesk.com  # or just "yourcompany"
FRESHDESK_API_KEY=your_api_key_here

# Optional
FRESHDESK_MAX_RETRIES=3          # Maximum retry attempts (default: 3)
FRESHDESK_TIMEOUT=30000          # Request timeout in ms (default: 30000)
FRESHDESK_RATE_LIMIT=50          # Rate limit per minute (default: 50)
LOG_LEVEL=info                   # Log level: debug, info, warn, error

用法

启动服务器

# Development mode with auto-reload
npm run dev

# Production mode
npm start

MCP客户端配置

添加到MCP客户端配置中：

{
  "mcpServers": {
    "freshdesk": {
      "command": "node",
      "args": ["/path/to/freshdesk-mcp/dist/index.js"],
      "env": {
        "FRESHDESK_DOMAIN": "yourcompany.freshdesk.com",
        "FRESHDESK_API_KEY": "your_api_key_here"
      }
    }
  }
}

可用工具

1.门票_管理

管理Freshdesk工单-创建、更新、列出、获取、删除和搜索工单。

行动：

• create：创建新票证
• update：更新现有工单
• list：列出带过滤器的门票
• get：获得一张特定的票
• delete：删除工单
• search：通过查询搜索门票

2.联系人_管理

管理Freshdesk联系人-创建、更新、列出、获取、删除、搜索和合并联系人。

行动：

• create：创建新联系人
• update：更新现有联系人
• list：使用筛选器列出联系人
• get：获取特定联系人
• delete：删除联系人
• search：搜索联系人
• merge：合并多个联系人

3.代理_管理

管理Freshdesk代理-列出、获取、更新代理，并查看他们的组和角色。

行动：

• list：列出所有代理
• get：找一个特定的代理人
• update：更新代理详细信息
• get_current：获取当前经过身份验证的代理
• list_groups：列出代理的组
• list_roles：列出代理的角色

4.公司管理

管理Freshdesk公司-创建、更新、列出、获取、删除、搜索公司和列出公司联系人。

行动：

• create：创建新公司
• update：更新现有公司
• list：列出公司
• get：找一家特定的公司
• delete：删除公司
• search：搜索公司
• list_contacts：列出公司中的联系人

5.对话管理

管理Freshdesk工单对话-创建回复和笔记，列出、获取、更新和删除对话。

行动：

• create_reply：向工单添加回复
• create_note：在票上添加注释
• list：列出票证对话
• get：进行一次特定的对话
• update：更新对话
• delete：删除对话

示例用法

创建工单

{
  "tool": "tickets_manage",
  "arguments": {
    "action": "create",
    "params": {
      "subject": "Need help with login",
      "description": "I cannot log into my account",
      "email": "customer@example.com",
      "priority": 2,
      "status": 2,
      "tags": ["login", "urgent"]
    }
  }
}

搜索联系人

{
  "tool": "contacts_manage",
  "arguments": {
    "action": "search",
    "params": {
      "query": "john@example.com",
      "page": 1,
      "per_page": 10
    }
  }
}

添加对工单的回复

{
  "tool": "conversations_manage",
  "arguments": {
    "action": "create_reply",
    "params": {
      "ticket_id": 12345,
      "body": "
Thank you for contacting us. We'll help you resolve this issue.
"
    }
  }
}

发展

运行测试

npm test
npm run test:watch
npm run test:coverage

装订和格式化

npm run lint
npm run lint:fix
npm run format
npm run format:check

类型检查

npm run typecheck

建筑

src/
├── api/          # API client implementation
├── auth/         # Authentication logic
├── core/         # Core types and interfaces
├── tools/        # MCP tool implementations
├── utils/        # Utility functions (logging, errors, rate limiting)
└── index.ts      # Main server entry point

错误处理

服务器实现了全面的错误处理：

• 网络错误：使用指数回退自动重试
• 速率限制：遵守带有自动节流功能的Freshdesk API费率限制
• 身份验证错误：清除无效API密钥的错误消息
• 验证错误：带有详细错误消息的输入验证
• API错误：根据Freshdesk API响应进行正确的错误映射

安全

• API密钥从未被记录或公开
• 所有输入都使用Zod模式进行验证
• 到Freshdesk API的安全HTTPS连接
• 基于环境的配置

许可证

麻省理工学院