Servidor MCP para Alegra API
Este proyecto implementa un servidor compatible con el Protocolo de Contexto de Modelo (MCP) que actúa como un puente hacia la API de contabilidad de Alegra. Permite que los Modelos de Lenguaje Grandes (LLMs) interactúen de forma segura con una amplia gama de recursos de Alegra, como facturas, contactos, ítems, pagos y más.
Elaborado por Juan Sánchez.
Características
- Integración Completa con Alegra: Ofrece una herramienta (
AlegraAPI) para realizar operaciones CRUD (GET,POST,PUT,DELETE) en la mayoría de los endpoints de la API de Alegra. - Amplia Gama de Recursos: Soporta una gran variedad de recursos, incluyendo
invoices,contacts,items,credit-notes,purchase-orders,bills,warehouses,bank-accounts,taxes, entre muchos otros. - Operaciones Flexibles: Permite la consulta de colecciones de recursos, la obtención de un recurso por su ID específico, la creación de nuevos recursos y la actualización o eliminación de los existentes.
- Búsqueda y Filtrado: Admite el uso de parámetros de consulta para filtrar y paginar resultados en las solicitudes
GET. - Manejo de Cuerpo de Solicitud: Utiliza el parámetro
queryParamspara enviar el cuerpo (body) de las solicitudesPOSTyPUT. - Registro de Actividad: Todas las solicitudes y errores se registran en un archivo local
alegra-mcp.logpara facilitar la depuración y el seguimiento.
Aviso de Seguridad Importante
Sus credenciales de Alegra nunca salen de su máquina.
Este servidor está diseñado con la seguridad como prioridad. La autenticación con la API de Alegra se gestiona de la siguiente manera:
- Credenciales Locales: El servidor lee su usuario (
ALEGRA_USER) y token (ALEGRA_TOKEN) directamente desde un archivo.enven su entorno local en el momento en que se realiza cada solicitud. - Sin Almacenamiento: Las credenciales no están codificadas en el programa, no se almacenan en ninguna base de datos ni se guardan en el estado del servidor.
- Protección en Git: El archivo
.gitignoreestá configurado para excluir explícitamente cualquier archivo.env, evitando que sus credenciales sean enviadas accidentalmente a un repositorio de código.
Usted puede utilizar su LLM de confianza para validar el código y confirmar que sus credenciales no son almacenadas ni transmitidas a terceros. El archivo clave para revisar es
src/auth.ts, donde se leen las variables de entorno para generar los headers de autorización.
Método 1: Ejecución Directa con NPX (para usuarios finales) - Fácil
Si no necesita modificar el código y solo desea utilizar la herramienta con su LLM, puede configurar su cliente MCP (por ejemplo, en el settings.json de VS Code) para que descargue y ejecute el servidor automáticamente.
Agregue la siguiente configuración a su cliente MCP:
{
"mcpservers": {
"Alegra-MCP-Public": {
"command": "npx",
"args": [
"-y",
"@juancsanchez/alegra-mcp"
],
"env": {
"ALEGRA_USER": "su_email@dominio.com",
"ALEGRA_TOKEN": "su_token_de_api_aqui"
}
}
}
}
Esta configuración le indica a su cliente que use npx para ejecutar la última versión del paquete, pasando sus credenciales de forma segura a través de variables de entorno, sin necesidad de clonar o instalar el proyecto manualmente.
Método 2: Instalación Local (para desarrolladores)
Siga estos pasos si desea modificar o examinar el código.
Requisitos Previos
- Node.js: Se requiere la versión 18 o superior.
- Credenciales de Alegra: Necesita un usuario y un token de API de su cuenta de Alegra.
Instalación y Configuración
-
Clonar el Repositorio
git clone https://github.com/juancsanchez/Alegra-MCP cd alegra-mcp -
Instalar Dependencias
npm install -
Configurar las Credenciales Cree un archivo llamado
.enven la raíz del proyecto.touch .envAñada sus credenciales de Alegra al archivo
.env:# Archivo .env ALEGRA_USER="su-correo@ejemplo.com" ALEGRA_TOKEN="su_token_secreto_de_la_api"
Uso
-
Compilar el Código
npm run build -
Iniciar el Servidor
npm start