Freshdesk

Freshdesk MCP 服务

一个 Model Context Protocol (MCP) 服务，可为 AI 助手提供对 Freshdesk 客户支持平台的结构化访问，包括工单、联系人、公司、Agent、群组、知识库以及 SLA/工作时间配置。

**注意：**本项目由 Wyre Technology 维护。它封装了已发布的 @wyre-technology/node-freshdesk SDK。

快速开始

主要部署方式是通过 WYRE MCP Gateway，由它托管容器化服务并注入每个请求所需的凭据。若要自行运行：

Claude Code（CLI）：

claude mcp add freshdesk-mcp \
  -e FRESHDESK_DOMAIN=your-subdomain \
  -e FRESHDESK_API_KEY=your-api-key \
  -- npx -y github:WYRE-AI/freshdesk-mcp

FRESHDESK_DOMAIN 是 .freshdesk.com 前面的部分（对于 https://acme.freshdesk.com，它是 acme）。在 Freshdesk 门户的 Profile Settings 下查找 FRESHDESK_API_KEY。

功能

• 🔌 MCP 协议合规性：支持工具、提示词和请求信息收集
• 🎫 全面的服务台功能：工单、联系人、公司、Agent、群组、解决方案、SLA 策略、工作时间和预设回复
• 🌳 决策树导航：从 freshdesk_navigate 开始，输入一个域以显示其工具，并使用 freshdesk_back 返回，从而保持工具列表精简且聚焦
• ⚠️ 破坏性操作防护：明确标记不可逆和影响重大的工具，并在运行前通过请求信息收集确认
• 🔒 安全认证：使用 Freshdesk API 密钥进行 HTTP Basic Auth（域名 + 密钥）
• 🌐 双重传输方式：stdio（本地）和 Streamable HTTP（远程/Docker/gateway）
• 🐳 支持 Docker：提供容器化部署、HTTP 传输和运行状况检查

通过 Gateway 连接

当 AUTH_MODE=gateway 时，每个 /mcp 请求都必须包含由 WYRE MCP Gateway 注入的凭据。缺少任一请求头时都会返回 401，且不会回退到进程环境中的 FRESHDESK_DOMAIN 或 FRESHDESK_API_KEY。

请求头	映射到	说明
x-freshdesk-domain	FRESHDESK_DOMAIN	Freshdesk 账户子域名
x-freshdesk-api-key	FRESHDESK_API_KEY	Freshdesk API 密钥

每个请求均为无状态：gateway 提供凭据，服务仅针对该请求重新构建 Freshdesk 客户端。设置 CONDUIT_S2S_SECRET 时，请求还必须包含有效的 X-Gateway-S2S 请求头。

配置

复制 .env.example，并设置以下变量。stdio 传输会读取 FRESHDESK_DOMAIN 和 FRESHDESK_API_KEY，不会使用 CONDUIT_S2S_SECRET。

变量	描述	默认值
FRESHDESK_DOMAIN	账户子域名（位于 .freshdesk.com 之前）。stdio 必需；当 AUTH_MODE=env 时，HTTP 也必需。网关模式不会读取此变量。	—
FRESHDESK_API_KEY	Freshdesk API 密钥。stdio 必需；当 AUTH_MODE=env 时，HTTP 也必需。网关模式不会读取此变量。	—
MCP_TRANSPORT	传输模式（stdio 或 http）	stdio
AUTH_MODE	env（进程环境）或 gateway（每个请求使用 x-freshdesk-domain 和 x-freshdesk-api-key，不回退到环境变量）。容器镜像和 Compose 的默认值为 gateway。	env
CONDUIT_S2S_SECRET	HTTP 必需。每次 /mcp 请求都会将此 HMAC 密钥与 X-Gateway-S2S 进行校验。如果此变量为空或为已知占位值（changeme、placeholder、secret、your-s2s-secret 及类似的公开示例值），进程会记录错误并以非零状态码退出。未设置时，Compose 不会启动。切勿提交真实值。使用 openssl rand -hex 32 生成。此值绝不会写入日志。	—
MCP_ALLOW_INSECURE_DEV	仅在本地开发时，设置为 1，以便在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不会强制校验 X-Gateway-S2S，且只绑定到 127.0.0.1。更宽泛的 MCP_HTTP_HOST（包括 0.0.0.0）会被忽略，并记录覆盖情况。已知占位密钥仍会被拒绝。	—
MCP_HTTP_HOST	当 MCP_TRANSPORT=http 时的绑定地址。未设置时绑定到 127.0.0.1。配置了 CONDUIT_S2S_SECRET 时会采用此值（容器镜像设置为 0.0.0.0）。没有密钥时，不安全开发模式绕过配置会强制绑定到 127.0.0.1。	127.0.0.1
MCP_HTTP_PORT	HTTP 服务端口	8080
LOG_LEVEL	日志级别（debug、info、warn、error）	info

/health 无需身份验证，也不会读取凭据。

HTTP 身份验证

当设置了 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须包含 X-Gateway-S2S：

t=<unix seconds>,v1=<hex hmac-sha256>

v1 是对 ASCII 消息 t=<unix seconds> 计算得到的小写十六进制 HMAC-SHA256，密钥为 CONDUIT_S2S_SECRET。时间戳与服务端时钟的差值必须在 300 秒以内。缺少或无效的标头会在读取任何供应商凭据之前返回 401。密钥绝不会写入日志或错误响应正文。

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 x-freshdesk-domain 和 x-freshdesk-api-key。这些标头是该请求唯一的凭据来源。缺少标头会返回 401。服务端不会回退到进程环境中的 FRESHDESK_DOMAIN 或 FRESHDESK_API_KEY。

X-Gateway-S2S: t=1710000000,v1=<hmac-sha256 of "t=1710000000">
x-freshdesk-domain: acme
x-freshdesk-api-key: <api key>

单租户 HTTP（AUTH_MODE=env）仍要求提供有效的 X-Gateway-S2S 标头。供应商凭据随后从 FRESHDESK_DOMAIN 和 FRESHDESK_API_KEY 获取。

工具概览

该服务采用决策树导航。在顶层，你只能看到 freshdesk_navigate、freshdesk_back 和 freshdesk_status。调用 freshdesk_navigate 并指定一个领域，即可查看该领域的工具；调用 freshdesk_back 可返回顶层。

领域	工具
tickets	搜索、列出、获取、创建、更新、回复、添加备注、列出对话、更新对话、删除*、删除对话*
contacts	搜索、列出、获取、创建、更新、自动补全、设为 Agent†、恢复、发送邀请、合并†、软删除†、硬删除*
companies	搜索、列出、获取、创建、更新、自动补全、删除*
agents	列出、获取、我、创建、更新、删除*
groups	列出、获取、创建、更新、删除*
solutions	类别 / 文件夹 / 文章：列出、获取、创建、更新、删除*
sla-business	SLA 策略（列出、创建、更新）、营业时间（列出、获取）、预设回复（列出文件夹、获取文件夹、列出回复）

* = Tier A（不可逆删除）——标记为 ⚠ DESTRUCTIVE — IRREVERSIBLE，需要确认。 † = Tier B（影响重大但可逆）——标记为 ⚠ HIGH-IMPACT，需要确认。

读取工具（搜索 / 列出 / 获取 / 自动补全 / 状态）不带警告，并标记为只读。

freshdesk_status 会通过调用 agents/me 执行实时连接检查。

Docker 部署

该镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。将端口发布到回环地址，并传入 S2S 密钥。在网关模式下，领域和 API 密钥会随每个请求通过 x-freshdesk-domain 和 x-freshdesk-api-key 传入，而不会从环境中读取。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  freshdesk-mcp

当 CONDUIT_S2S_SECRET 未设置时，Compose 会拒绝启动；它会设置 AUTH_MODE=gateway，发布 127.0.0.1:8080:8080，并且不会设置 FRESHDESK_DOMAIN、FRESHDESK_API_KEY 或 env_file：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up -d

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用 FRESHDESK_DOMAIN 和 FRESHDESK_API_KEY：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e FRESHDESK_DOMAIN=your-subdomain \
  -e FRESHDESK_API_KEY=your-api-key \
  -p 127.0.0.1:8080:8080 \
  freshdesk-mcp

不使用密钥的本地 HTTP 仅供开发使用。即使 MCP_HTTP_HOST 为 0.0.0.0，它也会绑定到 127.0.0.1，并记录警告。使用已知的占位密钥仍会导致启动被拒绝：

MCP_ALLOW_INSECURE_DEV=1 npm run start:http

请参阅 docker-compose.yml。构建时会通过 BuildKit npmrc 密钥从 GitHub Packages 安装 @wyre-technology/node-freshdesk（绝不会写入镜像层）：

printf '@wyre-ai:registry=https://npm.pkg.github.com\n@wyre-technology:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=%s\n' "$(gh auth token)" > /tmp/.npmrc
docker build --secret id=npmrc,src=/tmp/.npmrc -t freshdesk-mcp .
rm /tmp/.npmrc

开发

export NODE_AUTH_TOKEN=$(gh auth token)   # to install @wyre-technology/node-freshdesk
npm install
npm run build       # Build the project
npm run dev         # Watch mode
npm run test        # Run tests
npm run lint        # Type-check
npm run clean       # Remove dist/

# HTTP refuses to start until CONDUIT_S2S_SECRET is set
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 npm run start:http

测试

npm test            # Run test suite
npm run test:watch  # Watch mode

贡献

请参阅 CONTRIBUTING.md 了解指南。

许可证

Apache 2.0 — 版权所有 WYRE Technology