Servidor MCP de Reembolsos de PageFly

Servidor MCP (Model Context Protocol) para el agente de IA Hugo de Crisp para gestionar las solicitudes de reembolso de PageFly de principio a fin.

Expone nueve herramientas agrupadas en tres capas:

Búsqueda (fixtures simulados)

• check_subscription → obtener el plan actual de una tienda o correo electrónico

• get_billing_history → listar cada factura / próximo cargo para una tienda

Lógica pura

• classify_refund_case → asignar el contexto a uno de los 7 casos de manual (TH1–TH7)

• calculate_refund → cálculo de reembolso prorrateado a 30 días o multiclíclico con deducción

• collect_refund_info → decidir la siguiente pregunta a realizar y detectar bloqueos

• generate_refund_message → redactar la respuesta al cliente a partir de las plantillas de PageFly

Estado (Turso / libSQL)

• get_case_state → reanudar un caso por URL de tienda

• save_case_state → persistir el progreso en cada paso significativo

• list_pending_cases → revisar casos pendientes de un gestor, cliente o pago de factura

Construido con el SDK de Typescript de @modelcontextprotocol.

Entorno

Copia .env.example a .env y rellena tus credenciales de Turso:

TURSO_DATABASE_URL=libsql://<your-db>.turso.io
TURSO_AUTH_TOKEN=<token>
PORT=3000

Las migraciones se ejecutan automáticamente al iniciar el servidor; es seguro volver a ejecutarlas.

Related MCP server: Spaceship MCP

I. Instalación y ejecución

Para empezar con este servidor MCP, puedes ejecutarlo localmente o utilizar la versión alojada.

Uso de la versión alojada

Este servidor MCP ya viene alojado y listo para conectarse a tu espacio de trabajo de Crisp si deseas probarlo rápidamente. Puedes acceder a él en: https://crisp-mcp-demo.fly.dev/mcp

Ejecución local

Requisitos previos:

• Node.js 24.x instalado

• un teclado (opcional, pero recomendado)

Paso 1 — Clonar el repositorio

Abre una terminal en la carpeta deseada y ejecuta:

git clone https://github.com/NTHieu002/refund-crisp-mcp.git
cd refund-crisp-mcp

Paso 2 — Ejecutar el servidor

Puedes compilar e iniciar el servidor, o ejecutarlo directamente en modo de desarrollo.

Para compilar y ejecutar el servidor, usa:

npm ci
npm run build
npm run start

O para ejecutarlo en modo de desarrollo con tsx (modo watch), usa:

npm ci
npm run dev

Paso 3 — Exponer el servidor (si se ejecuta localmente)

Si deseas ejecutar el servidor localmente, necesitarás exponerlo a través de un túnel para que Crisp pueda acceder a él. Este paquete está preconfigurado para usar Cloudflared, aunque puedes usar cualquier solución de túnel que prefieras.

Si Cloudflared aún no está instalado en tu máquina, sigue este enlace para encontrar las instrucciones de instalación para tu sistema operativo:

Una vez instalado, abre una nueva terminal y ejecuta:

npm run tunnel

Puedes visitar la URL de tu túnel para confirmar que funciona. Deberías ver un mensaje de bienvenida.

Scripts disponibles

• npm run dev → servidor de desarrollo (watch)

• npm run build → compilar TypeScript

• npm run start → ejecutar servidor compilado

• npm run tunnel → exponer localhost mediante Cloudflare Tunnel

• npm run inspect → ejecuta el inspector de @modelcontextprotocol

II. Conexión a Crisp

Esta sección es una guía de inicio rápido para conectar este servidor MCP a tu espacio de trabajo de Crisp. Recomendamos también consultar nuestra documentación oficial para obtener instrucciones más detalladas.

Requisitos previos:

• una cuenta de Crisp

• un espacio de trabajo de Crisp en el plan Essentials o Plus

Paso 1 — Navega a app.crisp.chat

Paso 2 — En el menú AI Agent, dirígete a AI Agent → Automate → Integrations & MCP → External MCP servers** y haz clic en la zona Add MCP server.

Paso 3 — Introduce la URL de tu servidor MCP (ya sea tu URL alojada/tunelizada o nuestra versión alojada) y pulsa Add MCP Server.

Paso 4 — Configura el servidor MCP:

1. Ponle un nombre

2. Pulsa Refresh tools from server si tus herramientas no se obtuvieron automáticamente

3. Habilita el servidor MCP

4. Pulsa el botón Save changes

Paso 5 — ¡Tu servidor MCP debería estar registrado y listo para usar!

III. Pruebas del servidor MCP

Todavía en el menú Automations, puedes ir a Playground para probar tu servidor MCP y diferentes modelos de IA. ¡Hazle una pregunta!

Ejemplos de Playground

Preguntas de un solo paso:

¿Podrías comprobar si se ha procesado el reembolso de mi pedido OID_002?

Hola, ¿están habilitadas las notificaciones en mi cuenta baptiste@acme.com?

La IA puede encadenar múltiples llamadas a herramientas (ej. encontrar tu cuenta, listar pedidos recientes y obtener detalles del producto):

¿Los artículos de mi pedido OID_001 siguen en garantía?

¿Cuándo se entregará mi último pedido? Soy chris@acme.com

Prueba también preguntas parciales y deja que la IA te solicite información adicional:

¿Cuál fue el importe de mi último pedido?

No encuentro mi número de seguimiento, ¿puedes ayudarme?

Cuentas y pedidos disponibles

• chris@acme.com

  • OID_003

  • OID_006

• baptiste@acme.com

  • OID_001

  • OID_004

• dinis@acme.com

  • OID_002

  • OID_005

  • OID_007

Buenas prácticas de MCP

Diseño de MCP

• Descripción del servidor: Describe el propósito general del servidor MCP

• Nombramiento de herramientas: utiliza nombres claros y explícitos (ej. get_order, no orderLookup)

• Descripciones de herramientas: Describe de forma concisa qué hace la herramienta, cuándo llamarla y, opcionalmente, proporciona ejemplos de casos de uso

• Esquemas: Proporciona esquemas precisos para las entradas de las herramientas para garantizar un uso correcto

Verificación del usuario

En la configuración de tu servidor MCP, también puedes requerir opcionalmente que los usuarios se autentiquen antes de que la IA pueda llamar a una herramienta MCP. Esto refuerza la seguridad en operaciones sensibles.

Si el usuario aún no está autenticado, Crisp le enviará un código OTP por correo electrónico o SMS antes de permitir que la IA llame a tu herramienta MCP.

Para hacer eso, simplemente navega a tu servidor MCP y pulsa Manage. En cada herramienta, puedes activar la opción Require user identification verification.

Autenticación del servidor

En producción, es posible que desees restringir el acceso a tu servidor MCP y evitar el uso no autorizado. Hay dos métodos de autenticación disponibles:

• Bearer Token: un token estático enviado en el encabezado Authorization de cada solicitud

• Basic Auth: un nombre de usuario y contraseña enviados en el encabezado Authorization de cada solicitud