hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Integrations

Handles environment variable configuration for the Frontapp MCP server, including API credentials and other settings.
Provides containerized deployment options for the Frontapp MCP server with included Dockerfile and multi-stage build process.
Enables access to the repository containing the Frontapp MCP server for installation and deployment purposes.

Frontapp MCP 服务器

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

📚 在 /docs 查看完整文档

概述

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

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

特征

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

建筑学

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

API 网关：处理来自 LLM 和 Frontapp 的 webhook 的传入请求
请求处理程序：处理来自 LLM 的请求并与 Frontapp API 交互
Webhook Handlers ：处理来自 Frontapp 的 webhook 并更新 LLM 上下文
Frontapp API 客户端：封装与 Frontapp API 交互的逻辑
数据模型：定义 LLM、MCP 服务器和 Frontapp 之间交换的数据结构
配置：存储 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

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

快速入门：

克隆存储库：
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 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 错误，则需要先修复这些错误，构建才能成功。常见问题包括：

Webhook 处理程序中的类型错误（请参阅开发指南中的TypeScript 类型安全部分）
缺少对潜在未定义值的类型断言
可选属性处理不当

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

安全注意事项

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

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

贡献

欢迎贡献！请参阅开发指南，了解如何为项目做出贡献。

致谢

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

模型上下文协议服务器将 LLM 与 Frontapp 的客户通信平台相集成，从而能够访问对话、联系人和标签，同时支持通过 webhook 进行实时更新。

Frontapp MCP Server