Frontapp MCP服务器
用于将大型语言模型（LLM）与Frontapp的客户通信平台集成的模型上下文协议（MCP）服务器。
概述
该项目实现了一个MCP服务器，作为LLM和Frontapp的API之间的桥梁。它使LLM能够访问和操作Frontapp数据（对话、联系人、标签等），并使用自然语言命令自动化Frontapp工作流。
服务器支持使用Frontapp的webhooks进行实时更新和事件驱动的自动化。
特性
- 会话管理：检索、创建、更新和管理对话
- 联系人管理：访问和更新联系信息
- 标签管理：在对话中应用和删除标签
- 收件箱管理：访问收件箱信息
- 用户管理：检索用户详细信息
- Webhook集成：从Frontapp接收和处理实时事件
- 安全认证：验证webhook签名并处理API身份验证
- 安全凭证存储：使用AES-256加密存储敏感信息
- HTTPS支持：使用TLS/SSL加密进行安全通信
建筑
MCP服务器遵循模块化架构：
- API网关：处理来自LLM和来自Frontapp的Webhook的传入请求
- 请求处理程序：处理LLM的请求并与Frontapp API交互
- Webhook处理程序：处理来自Frontapp的Webhook并更新LLM上下文
- Frontapp API客户端：封装与Frontapp API交互的逻辑
- 数据模型：定义LLM、MCP服务器和Frontapp之间交换的数据结构
- 配置：存储MCP服务器的设置
先决条件
- Node.js（v16或更高版本）
- npm或纱线
- Frontapp API证书
- 一个可公开访问的webhooks URL（用于生产环境）
安装
通过Smithery安装
通过以下方式自动安装Claude Desktop的frontapp mcp 史密瑟里:
npx -y @smithery/cli install @zqushair/frontapp-mcp --client claude有关详细的安装说明，请参阅 安装指南.
快速启动：
- 克隆存储库：
git clone https://github.com/zqushair/Frontapp-MCP.git
cd Frontapp-MCP- 安装依赖项：
npm install- 创建和配置
.env文件：
cp .env.example .env
# Edit the .env file with your Frontapp API credentials- 构建并启动项目：
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 typecheckDocker部署
该项目包括一个用于容器化部署的Dockerfile。这个多阶段构建过程创建了一个优化的生产映像。
构建Docker镜像
# Build the Docker image
docker build -t frontapp-mcp .
# Run the Docker container
docker run -p 3000:3000 --env-file .env frontapp-mcpDocker构建故障排除
如果你在Docker构建过程中遇到TypeScript错误，需要在构建成功之前修复它们。常见问题包括：
- webhook处理程序中的类型错误（请参阅 TypeScript类型安全 开发指南中的部分）
- 潜在未定义值缺少类型断言
- 可选属性处理不当
始终运行 npm run typecheck 或 npm run build 在构建Docker镜像之前，先在本地捕获并修复这些问题。
安全考虑
- 使用带有AES-256加密的凭据管理器安全地存储API凭据
- 使用提供的脚本生成强加密密钥：
npm run generate-key - 使用内置的HTTPS支持为所有通信启用HTTPS
- 生成用于开发的自签名证书：
npm run generate-cert - 使用来自可信证书颁发机构的证书进行生产
- 验证webhook签名，以确保它们来自Frontapp
- 实施限速以防止滥用
- 验证所有传入数据以防止注入攻击
许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
贡献
欢迎投稿！请查看 开发指南 了解如何为项目做出贡献。