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.

Servidor MCP de Frontapp

Un servidor de Protocolo de Contexto de Modelo (MCP) para integrar Modelos de Lenguaje Grandes (LLM) con la plataforma de comunicación con el cliente de Frontapp.

📚 Ver la documentación completa en /docs

Descripción general

Este proyecto implementa un servidor MCP que actúa como puente entre los LLM y la API de Frontapp. Permite a los LLM acceder y manipular datos de Frontapp (conversaciones, contactos, etiquetas, etc.) y automatizar los flujos de trabajo de Frontapp mediante comandos de lenguaje natural.

El servidor admite actualizaciones en tiempo real y automatización basada en eventos mediante webhooks de Frontapp.

Características

Gestión de conversaciones : recuperar, crear, actualizar y gestionar conversaciones
Gestión de contactos : acceder y actualizar la información de contacto
Gestión de etiquetas : aplicar y eliminar etiquetas de las conversaciones
Gestión de la bandeja de entrada : acceder a la información de la bandeja de entrada
Gestión de usuarios : recuperar detalles del usuario
Integración de webhook : recibe y procesa eventos en tiempo real desde Frontapp
Autenticación segura : verifique las firmas de webhook y gestione la autenticación de API
Almacenamiento seguro de credenciales : almacene información confidencial con cifrado AES-256
Compatibilidad con HTTPS : comunicaciones seguras con cifrado TLS/SSL

Arquitectura

El servidor MCP sigue una arquitectura modular:

API Gateway : gestiona solicitudes entrantes de LLM y webhooks de Frontapp
Manejadores de solicitudes : procesan solicitudes de LLM e interactúan con la API de Frontapp
Manejadores de webhook : procesan webhooks desde Frontapp y actualizan el contexto LLM
Cliente API de Frontapp : encapsula la lógica para interactuar con la API de Frontapp
Modelos de datos : definen la estructura de los datos intercambiados entre los LLM, el servidor MCP y Frontapp
Configuración : almacena la configuración del servidor MCP

Prerrequisitos

Node.js (v16 o superior)
npm o hilo
Credenciales de la API de Frontapp
Una URL de acceso público para webhooks (para uso en producción)

Instalación

Instalación mediante herrería

Para instalar frontapp-mcp para Claude Desktop automáticamente a través de Smithery :

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

Para obtener instrucciones de instalación detalladas, consulte la Guía de instalación .

Inicio rápido:

Clonar el repositorio:
git clone https://github.com/zqushair/Frontapp-MCP.git cd Frontapp-MCP
Instalar dependencias:
npm install
Cree y configure el archivo .env :
cp .env.example .env # Edit the .env file with your Frontapp API credentials
Construir y comenzar el proyecto:
npm run build npm start

Documentación

La documentación completa está disponible en el directorio /docs :

📖 Documentación principal : descripción general e introducción
🔧 Guía de instalación : instrucciones de configuración detalladas
Referencia de API : herramientas y puntos finales disponibles
🔔 Integración de webhook : procesamiento de eventos en tiempo real
Guía de almacenamiento de credenciales : gestión segura de credenciales
Guía de configuración de HTTPS : configuración de comunicaciones seguras
💻 Guía de desarrollo - Contribuyendo al proyecto

Uso

Uso de la API

La integración MCP de Frontapp expone un conjunto de herramientas que los LLM pueden llamar mediante el protocolo MCP. Para obtener información detallada sobre las herramientas disponibles y sus parámetros, consulte la Referencia de la API .

Biblioteca de clientes

El proyecto incluye una biblioteca de cliente TypeScript ( src/frontapp-mcp-client.ts ) que los LLM pueden usar para interactuar con el servidor 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?');

La biblioteca del cliente proporciona:

Métodos de tipos seguros para todas las herramientas disponibles
Manejo de errores con controladores de errores personalizados
Lógica de reintento con retroceso exponencial
Interfaces TypeScript completas

Un ejemplo completo del uso del cliente está disponible en src/examples/client-usage-example.ts .

Integración de webhooks

La integración permite recibir y procesar webhooks desde Frontapp para notificaciones de eventos en tiempo real. Para obtener información detallada sobre la integración de webhooks, consulte la Guía de Integración de Webhooks .

Desarrollo

Para obtener información detallada sobre el desarrollo, consulte la Guía de desarrollo .

Comandos de desarrollo rápido

# 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

Implementación de Docker

El proyecto incluye un Dockerfile para la implementación en contenedores. Este proceso de compilación multietapa crea una imagen de producción optimizada.

Construyendo la imagen de Docker

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

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

Solución de problemas de compilación de Docker

Si encuentra errores de TypeScript durante la compilación de Docker, es necesario corregirlos para que la compilación se complete correctamente. Los problemas más comunes incluyen:

Errores de tipo en los controladores de webhook (consulte la sección Seguridad de tipos de TypeScript en la Guía de desarrollo)
Afirmaciones de tipo faltantes para valores potencialmente indefinidos
Manejo inadecuado de propiedades opcionales

Siempre ejecute npm run typecheck o npm run build localmente antes de compilar la imagen de Docker para detectar y solucionar estos problemas de manera temprana.

Consideraciones de seguridad

Almacene las credenciales de API de forma segura utilizando el administrador de credenciales con cifrado AES-256
Genere claves de cifrado seguras utilizando el script proporcionado: npm run generate-key
Habilite HTTPS para todas las comunicaciones mediante el soporte HTTPS integrado
Generar certificados autofirmados para desarrollo: npm run generate-cert
Utilice certificados de autoridades de certificación confiables para la producción
Verifique las firmas de webhook para asegurarse de que provienen de Frontapp
Implementar la limitación de velocidad para evitar el abuso
Validar todos los datos entrantes para evitar ataques de inyección

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Contribuyendo

¡Agradecemos sus contribuciones! Consulte la Guía de Desarrollo para saber cómo contribuir al proyecto.

Expresiones de gratitud

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

Un servidor de protocolo de contexto de modelo que integra LLM con la plataforma de comunicación con el cliente de Frontapp, lo que permite el acceso a conversaciones, contactos y etiquetas al tiempo que admite actualizaciones en tiempo real a través de webhooks.

Frontapp MCP Server