Frontapp MCP Server

Frontapp MCP 服务

请访问官方文档 https://dev.frontapp.com/docs/mcp-server，并以该文档为准。

用于将大语言模型（LLM）与 Frontapp 客户沟通平台集成的模型上下文协议（MCP）服务。

📚 查看 /docs 中的完整文档

概述

本项目实现了一个 MCP 服务，用作 LLM 与 Frontapp API 之间的桥梁。它使 LLM 能够访问和操作 Frontapp 数据（对话、联系人、标签等），并通过自然语言命令自动执行 Frontapp 工作流。

该服务支持实时更新，并使用 Frontapp 的 webhook 实现事件驱动自动化。

功能

• 对话管理：检索、创建、更新和管理对话
• 联系人管理：访问和更新联系人信息
• 标签管理：为对话添加和移除标签
• 收件箱管理：访问收件箱信息
• 用户管理：检索用户详细信息
• Webhook 集成：接收并处理来自 Frontapp 的实时事件
• 安全身份验证：验证 webhook 签名并处理 API 身份验证
• 安全凭据存储：使用 AES-256 加密存储敏感信息
• HTTPS 支持：通过 TLS/SSL 加密确保通信安全

架构

该 MCP 服务采用模块化架构：

1. API 网关：处理来自 LLM 的请求以及来自 Frontapp 的 webhook
2. 请求处理器：处理来自 LLM 的请求并与 Frontapp API 交互
3. Webhook 处理器：处理来自 Frontapp 的 webhook 并更新 LLM 上下文
4. Frontapp API 客户端：封装与 Frontapp API 交互的逻辑
5. 数据模型：定义 LLM、MCP 服务和 Frontapp 之间交换的数据结构
6. 配置：存储 MCP 服务的设置

前提条件

• Node.js（v16 或更高版本）
• npm 或 yarn
• Frontapp API 凭据
• 可公开访问的 webhook URL（用于生产环境）

安装

通过 Smithery 安装

通过 Smithery 为 Claude Desktop 自动安装 frontapp-mcp：

npx -y @smithery/cli install @zqushair/frontapp-mcp --client claude

有关详细安装说明，请参阅安装指南。

快速开始：

1. 克隆仓库：

   git clone https://github.com/zqushair/Frontapp-MCP.git
   cd Frontapp-MCP
   

2. 安装依赖项：

   npm install
   

3. 创建并配置 .env 文件：

   cp .env.example .env
   # Edit the .env file with your Frontapp API credentials
   

4. 构建并启动项目：

   npm run build
   npm start
   

文档

完整文档位于 /docs 目录中：

• 📖 主文档 - 概述和简介
• 🔧 安装指南 - 详细的设置说明
• 📚 API 参考 - 可用工具和端点
• 🔔 Webhook 集成 - 实时事件处理
• 🔒 凭据存储指南 - 安全的凭据管理
• 🔐 HTTPS 设置指南 - 安全通信设置
• 💻 开发指南 - 为项目作出贡献

用法

API 用法

Frontapp MCP 集成提供了一组工具，LLM 可通过 MCP 协议调用。有关可用工具及其参数的详细信息，请参阅 API 参考。

客户端库

本项目包含一个 TypeScript 客户端库（src/frontapp-mcp-client.ts），LLM 可使用它与 MCP 服务交互：

import { FrontappMcpClient } from './frontapp-mcp-client.js';

// Create a client instance
const client = new FrontappMcpClient('http://localhost:3000');

// Get a list of conversations
const conversations = await client.getConversations({ status: 'open' });

// Send a message to a conversation
await client.sendMessage('cnv_123', 'Hello, how can I help you today?');

客户端库提供：

• 所有可用工具的类型安全方法
• 通过自定义错误处理器进行错误处理
• 带指数退避的重试逻辑
• 全面的 TypeScript 接口

完整的客户端用法示例见 src/examples/client-usage-example.ts。

Webhook 集成

该集成支持接收和处理来自 Frontapp 的 webhook，以实时通知事件。有关 webhook 集成的详细信息，请参阅 Webhook 集成指南。

开发

有关开发的详细信息，请参阅开发指南。

快速开发命令

# Start development server with hot reloading
npm run dev

# Run tests
npm run test:api
npm run test:conversations
npm run test:tags
npm run test:contacts
npm run test:webhooks

# Lint and format code
npm run lint
npm run format

# Build for production
npm run build

# Check TypeScript types without compiling
npm run typecheck

Docker 部署

项目包含一个用于容器化部署的 Dockerfile。此多阶段构建流程会创建经过优化的生产镜像。

构建 Docker 镜像

# Build the Docker image
docker build -t frontapp-mcp .

# Run the Docker container
docker run -p 3000:3000 --env-file .env frontapp-mcp

Docker 构建故障排除

如果在 Docker 构建过程中遇到 TypeScript 错误，必须先修复这些错误，构建才能成功。常见问题包括：

1. webhook 处理程序中的类型错误（请参阅《开发指南》中的 TypeScript 类型安全部分）
2. 缺少对可能未定义值的类型断言
3. 未正确处理可选属性

在构建 Docker 镜像之前，务必在本地运行 npm run typecheck 或 npm run build，以便尽早发现并修复这些问题。

安全注意事项

• 使用凭据管理器和 AES-256 加密安全地存储 API 凭据
• 使用提供的脚本生成强加密密钥：npm run generate-key
• 使用内置 HTTPS 支持为所有通信启用 HTTPS
• 为开发生成自签名证书：npm run generate-cert
• 在生产环境中使用来自可信证书颁发机构的证书
• 验证 webhook 签名，确保请求来自 Frontapp
• 实施速率限制以防止滥用
• 验证所有传入数据以防止注入攻击

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

贡献

欢迎贡献！有关如何为项目做出贡献的信息，请参阅开发指南。

致谢

• Frontapp API 文档
• Model Context Protocol