前端应用-MCP

Name: 前端应用-MCP
Author: zqushair

作者：zqushair11 星标更新：2025-10-29

安装使用来源：spider==github.com

项目介绍

Frontapp MCP 服务器

这是一个用于集成大型语言模型（LLMs）与 Frontapp 客户沟通平台的 Model Context Protocol (MCP) 服务器。

📚 查看完整文档在 /docs

概述

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

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

特性

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

架构

MCP 服务器遵循模块化架构：

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

先决条件

Node.js (v16 或更高版本)
npm 或 yarn
Frontapp API 凭据
一个公开可访问的 URL 用于 webhook（生产用途）

安装

通过 Smithery 安装

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

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
# 使用您的 Frontapp API 凭据编辑 .env 文件

构建并启动项目：
```
npm run build
npm start
```

文档

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

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

使用方法

API 使用

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

客户端库

项目包含一个 TypeScript 客户端库 (src/frontapp-mcp-client.ts)，LLMs 可以使用它来与 MCP 服务器交互：

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

// 创建客户端实例
const client = new FrontappM_ McpClient('http://localhost:3000');

// 获取对话列表
const conversations = await client.getConversations({ status: 'open' });

// 向对话发送消息
await client.sendMessage('cnv_123', '你好，今天我能帮你做什么？');

客户端库提供了：

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

完整的客户端使用示例可以在 src/examples/client-usage-example.ts 中找到。

Webhook 集成

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

开发

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

快速开发命令

# 启动带有热重载的开发服务器
npm run dev

# 运行测试
npm run test:api
npm run test:conversations
npm run test:tags
npm run test:contacts
npm run test:webhooks

# 校验和格式化代码
npm run lint
npm run format

# 为生产构建
npm run build

# 不编译检查 TypeScript 类型
npm run typecheck

Docker 部署

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

构建 Docker 镜像

# 构建 Docker 镜像
docker build -t frontapp-mcp .

# 运行 Docker 容器
docker run -p 3000:3000 --env-file .env frontapp-mcp

Docker 构建故障排除

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

在 webhook 处理器中的类型错误（请参阅开发指南中的 TypeScript 类型安全性部分）
对可能未定义值的缺失类型断言
不正确的处理可选属性

始终在本地运行 npm run typecheck 或 npm run build 来尽早捕获并修复这些问题。

安全注意事项

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