# Frontapp MCP连接器
## 基本信息
- Slug: `zqushair-frontapp-mcp`
- Source: modelscope
- Publisher: @zqushair/Frontapp-MCP
- Categories: communication / customer-support
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@zqushair/Frontapp-MCP
## 简介
一种集成了LLM的Model Context Protocol服务器，与Frontapp的客户沟通平台相结合，能够访问对话、联系人和标签，并通过网络钩子支持实时更新。
## 安装提示

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

## MCP Server 详情

# Frontapp MCP 服务器

[![smithery 徽章](https://smithery.ai/badge/@zqushair/frontapp-mcp)](https://smithery.ai/server/@zqushair/frontapp-mcp)

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

**[📚 在 /docs 查看完整文档](/docs/README.md)**

## 概览

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

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

## 特性

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

## 架构

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

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

## 前提条件

- Node.js (v16 或更高版本)
- npm 或 yarn
- Frontapp API 凭据
- 一个可用于生产的公开可访问 URL 以供 Webhook 使用

## 安装

### 通过 Smithery 安装

要通过 [Smithery](https://smithery.ai/server/@zqushair/frontapp-mcp) 自动为 Claude Desktop 安装 frontapp-mcp：

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


有关详细的安装说明，请参阅 [安装指南](/docs/installation.md)。

快速开始：

1. 克隆仓库：
   ```bash
   git clone https://github.com/zqushair/Frontapp-MCP.git
   cd Frontapp-MCP
   ```

2. 安装依赖项：
   ```bash
   npm install
   ```

3. 创建并配置 `.env` 文件：
   ```bash
   cp .env.example .env
   # 使用您的 Frontapp API 凭据编辑 .env 文件
   ```

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

## 文档

全面的文档可在 [/docs](/docs) 目录中找到：

- [📖 主文档](/docs/README.md) - 概述和介绍
- [🔧 安装指南](/docs/installation.md) - 详细的设置说明
- [📚 API 参考](/docs/api-reference.md) - 可用工具和端点
- [🔔 Webhook 集成](/docs/webhook-integration.md) - 实时事件处理
- [🔒 凭证存储指南](/docs/credential-storage-guide.md) - 安全的凭证管理
- [🔐 HTTPS 设置指南](/docs/https-setup-guide.md) - 安全通信设置
- [💻 开发指南](/docs/development-guide.md) - 贡献项目

## 使用方法

### API 使用

Frontapp MCP 集成提供了一组可以通过 MCP 协议被 LLMs 调用的工具。有关可用工具及其参数的详细信息，请参阅[API 参考](/docs/api-reference.md)。

### 客户端库

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

```typescript
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 集成指南](/docs/webhook-integration.md)。

## 开发

有关详细的开发信息，请参阅[开发指南](/docs/development-guide.md)。

### 快速开发命令

```bash
# 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 镜像

```bash
# 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 类型安全](/docs/development-guide.md#typescript-type-safety)部分）
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 文件。

## 贡献

欢迎贡献！请参阅 [开发指南](/docs/development-guide.md) 了解如何为项目做出贡献的信息。

## 致谢

- [Frontapp API 文档](https://dev.frontapp.com/reference/introduction)
- [模型上下文协议](https://github.com/modelcontextprotocol/mcp)