Ecommerce Order Handle MCP

Este MCP (Model Context Protocol) proporciona herramientas para gestionar órdenes de ecommerce, permitiendo consultar información de órdenes y actualizar direcciones de entrega.

Funcionalidades

• Consulta de órdenes: Permite buscar información de una orden usando el ID, email o teléfono del cliente.
• Actualización de direcciones: Permite actualizar la dirección de entrega de una orden existente. La validación de la dirección debe ser realizada por el agente de IA que utiliza este MCP.
• Capacidades del MCP: Implementa el protocolo MCP completo, incluyendo las funcionalidades list_tools y execute_tool para descubrir y ejecutar las herramientas disponibles.

Instalación

1. Clona el repositorio
2. Instala las dependencias:

   npm install

3. Crea un archivo .env basado en el archivo .env.example proporcionado y configura tus variables de entorno.
4. Compila el código TypeScript:

   npm run build

Configuración

El MCP requiere las siguientes variables de entorno:

• BASE_URL: URL base para la API (ejemplo: "https://gcompras.co"). Las subrutas /api/mpc/order ya están definidas internamente.
• API_TOKEN: Token de autenticación para la API. Se usará como Bearer Token en las solicitudes.

Uso con Model Context Protocol

Este MCP implementa completamente el Model Context Protocol y expone sus capacidades a través de stdio, lo que permite que sea utilizado por cualquier cliente que soporte el protocolo MCP.

Operaciones del Protocolo MCP

El servidor implementa las siguientes operaciones estándar del protocolo MCP:

• list_tools: Permite a los clientes descubrir las herramientas disponibles en el MCP.
• execute_tool: Permite a los clientes ejecutar una herramienta específica con los parámetros necesarios.

Herramientas (Tools)

consultar_orden

Permite consultar información detallada de una orden utilizando ID de orden, email o teléfono del cliente.

Parámetros:

• order_id (opcional): ID de la orden a consultar
• email (opcional): Email del cliente que realizó la orden
• phone (opcional): Número de teléfono del cliente que realizó la orden

actualizar_direccion_orden

Actualiza la dirección de entrega de una orden existente. El agente de IA debe validar previamente que la dirección contenga toda la información necesaria.

Parámetros:

• order_id: ID de la orden a actualizar
• address: Nueva dirección de entrega
• neighborhood (opcional): Barrio de la dirección
• locality (opcional): Localidad (solo para Bogotá)
• reference_point (opcional): Punto de referencia si no hay barrio
• is_house (opcional): Indica si es una casa
• is_apartment (opcional): Indica si es un apartamento

Publicación

Este paquete está disponible en el registro público de npm. Puedes instalarlo directamente con:

npm install ecommerce-order-handle-mcp

O ejecutarlo sin instalación con npx:

npx ecommerce-order-handle-mcp

Ejecutar con npx

Este MCP puede ser ejecutado directamente con npx, lo que permite utilizarlo sin necesidad de instalarlo globalmente:

npx ecommerce-order-handle-mcp --BASE_URL=https://gcompras.co --API_TOKEN=tu_token_de_acceso

También puedes especificar la versión:

npx [email protected] --BASE_URL=https://gcompras.co --API_TOKEN=tu_token_de_acceso

O usar variables de entorno:

BASE_URL=https://gcompras.co API_TOKEN=tu_token_de_acceso npx ecommerce-order-handle-mcp

Ejemplos de uso con un cliente MCP

Para usar este MCP con un cliente compatible con el protocolo MCP (como un LLM que implementa MCP), debes iniciar el MCP y permitir que el cliente se conecte a través de stdin/stdout:

# Iniciar el MCP con npx
npx ecommerce-order-handle-mcp --BASE_URL=https://api.ejemplo.com --API_TOKEN=tu_token_secreto

El MCP estará disponible para que cualquier cliente MCP interactúe con él. Por ejemplo, un cliente MCP podría:

1. Listar las herramientas disponibles (list_tools)
2. Ejecutar la herramienta "consultar_orden" con parámetros como el ID de la orden
3. Ejecutar la herramienta "actualizar_direccion_orden" para modificar la dirección de entrega

Instalación global

Si prefieres, puedes instalar el paquete globalmente:

npm install -g ecommerce-order-handle-mcp

Y luego ejecutarlo directamente:

ecommerce-order-handle-mcp --BASE_URL=https://gcompras.co --API_TOKEN=tu_token_de_acceso

Configuración en n8n

Para configurar este MCP en n8n:

1. Crea un nuevo nodo "Execute Command"
2. En el campo "Command", escribe:

   npx ecommerce-order-handle-mcp --BASE_URL=https://gcompras.co --API_TOKEN=tu_token_de_acceso

3. Asegúrate de reemplazar la URL de ejemplo y el token con los valores reales para tu API

Pruebas

El proyecto incluye pruebas unitarias y de integración para validar el correcto funcionamiento de las herramientas, servicios y la implementación del protocolo MCP. Para ejecutar las pruebas:

npm test

También puedes ejecutar las pruebas en modo watch durante el desarrollo:

npm run test:watch

O generar un informe de cobertura:

npm run test:coverage

Tipos de pruebas

El proyecto incluye los siguientes tipos de pruebas:

1. Pruebas unitarias de herramientas: Verifican el funcionamiento correcto de cada herramienta individual (consultOrder, updateOrderAddress).
2. Pruebas de servicios API: Validan las llamadas a la API externa, con verificación de parámetros y manejo de respuestas.
3. Pruebas del servidor MCP: Comprueban que el servidor implementa correctamente el protocolo MCP, incluyendo list_tools y execute_tool.
4. Pruebas del CLI: Verifican que la interfaz de línea de comandos funciona correctamente y procesa los argumentos adecuadamente.

Cobertura de pruebas

Las pruebas cubren los siguientes escenarios:

• consultOrder: Consulta de órdenes por ID, email y teléfono, así como manejo de errores.
• updateOrderAddress: Actualización de dirección con diferentes combinaciones de parámetros y manejo de errores.
• API Service: Validación de las llamadas a la API externa, con verificación de parámetros y manejo de respuestas.
• Servidor MCP: Verificación de la conexión cliente-servidor, listado de herramientas y ejecución de herramientas.
• CLI: Comprobación de la ejecución con diferentes parámetros y opciones de línea de comandos.

Guía para el agente de IA

El agente de IA que utilice este MCP debe:

1. Para validación de direcciones:

   • Si la dirección es en Bogotá, debe identificar y extraer el barrio y la localidad.
   • Para otras ciudades, solo necesita identificar el barrio.
   • Si no se menciona el barrio explícitamente, debe solicitar un punto de referencia.
   • Debe identificar si la dirección corresponde a una casa o apartamento.

2. Para actualizar direcciones:

   • Realizar la validación antes de llamar a la herramienta.
   • Proporcionar todos los campos extraídos al llamar a la herramienta actualizar_direccion_orden.

Licencia

ISC

Publicación automática

Este paquete se publica automáticamente en npm cuando se hace push a la rama main. El proceso de publicación está configurado mediante GitHub Actions en el archivo .github/workflows/publish.yml.

Instalación desde npm

Para instalar este paquete desde npm:

npm install ecommerce-order-handle-mcp

O con npx:

npx ecommerce-order-handle-mcp