AI导哈

Freshdesk MCP服务器

用于Freshdesk API v2集成的Model Context Protocol服务器实现，提供管理工单、联系人、代理、公司和对话的工具。

  • by Enreign
  • TypeScript
  • 本地部署
  • 12 星标
  • 更新于
在 GitHub 查看 Enreign/freshdeck-mcp

使用说明

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": "<p>Thank you for contacting us. We'll help you resolve this issue.</p>"
    }
  }
}

发展

运行测试

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连接
  • 基于环境的配置

许可证

麻省理工学院

相关 MCP