Enlace de pago Comax MCP

Un servidor FastMCP que se integra con Comax para crear enlaces de pago, gestionar pedidos y obtener información de clientes. Desarrollado con FastMCP , un framework TypeScript para servidores MCP.

[!NOTA]
Este servidor está diseñado para interactuar con el sistema de pago/ERP de Comax.

Características

Integración de Comax: proporciona herramientas para operaciones clave de Comax.
FastMCP Core: aprovecha FastMCP para obtener una funcionalidad robusta del servidor MCP que incluye:
- Definición de herramienta simple con validación del esquema Zod
- Gestión de sesiones
- Registro y manejo de errores
- SSE para comunicación remota (configurable)
- CORS (habilitado por defecto)
- Notificaciones de progreso (para herramientas de larga duración, si se implementaron)
- Eventos de servidor tipificados
- CLI para pruebas y depuración

Instalación

Asegúrese de tener Node.js y pnpm (o npm/yarn) instalados.

# Clone the repository (if you haven't already)
# git clone <your-repo-url>
# cd <your-repo-name>

# Install dependencies
pnpm install

Configuración

Este servidor requiere varias credenciales e ID para interactuar con la API de Comax. Actualmente, están codificadas como constantes en src/index.ts pero idealmente deberían configurarse mediante variables de entorno para su uso en producción.

Configuración requerida (ver src/index.ts ):

ORDER_LOGIN_ID , ORDER_LOGIN_PASSWORD : Para operaciones de pedidos de Comax.
TOKEN_LOGIN_NAME , TOKEN_LOGIN_PASSWORD : Para la generación de tokens de crédito Comax.
PAYMENT_LOGIN_ID , PAYMENT_LOGIN_PASSWORD : Para la página de pago de Comax.
BRANCH_ID , STORE_ID , PRICE_LIST_ID : Identificadores operativos predeterminados de Comax.
RETURN_PAGE : URL para redirección después del pago.
COMAX_ORDER_ENDPOINT , COMAX_TOKEN_ENDPOINT , COMAX_PAYMENT_PAGE , COMAX_CUSTOMER_ENDPOINT : URL de los puntos finales de la API de Comax.

Considere usar una biblioteca como dotenv para administrarlos en un archivo .env para el desarrollo local.

Inicio rápido

El siguiente es un ejemplo simplificado de cómo se define una herramienta en este servidor ( src/index.ts ):

import { FastMCP } from "fastmcp";
import { z } from "zod"; // Using Zod for schema validation

const server = new FastMCP({
  name: "Comax Payment Link MCP",
  version: "1.0.0",
});

// Example: Create Comax Payment Link Tool
server.addTool({
  name: "create_comax_payment_link",
  description: "Creates a Comax order and returns a payment link.",
  parameters: z.object({
    customerId: z.string().default("22222"),
    customerName: z.string(),
    customerPhone: z.string(),
    customerCity: z.string(),
    items: z.array(z.object({ // Simplified item schema
      sku: z.string(),
      quantity: z.number().int().positive(),
      price: z.number().positive(),
      totalSum: z.number().positive(),
    })).min(1),
    // ... other parameters
  }),
  execute: async (args, { log }) => {
    log.info("Attempting to create Comax payment link for", args.customerName);
    // ... logic to call Comax API ...
    const paymentUrl = "https://example-payment-url.com/pay?token=XYZ"; // Placeholder
    log.info("Payment link created successfully.");
    return {
      content: [
        {
          type: "text",
          text: `Comax payment link created.\nOrder DocNumber: 12345\nPayment Link: ${paymentUrl}`,
        },
      ],
    };
  },
});

server.start({
  transportType: "stdio", // Or "sse" for network access
});

console.log("Comax Payment Link MCP server started");

Puede probar el servidor en la terminal utilizando la CLI de FastMCP.

Herramientas disponibles

Este servidor expone las siguientes herramientas para interactuar con Comax:

create_comax_payment_link : crea un pedido de Comax y devuelve un enlace de pago.
update_comax_order_payment : actualiza un pedido de Comax con la confirmación del pago.
get_comax_customer_details : obtiene los detalles del cliente comercial de Comax por CustomerID.
get_comax_order_status : recupera el estado de un pedido de Comax por número de documento o referencia.
get_comax_order_details : obtiene información detallada de un pedido de Comax.
get_comax_order_pdf_link : obtiene un enlace PDF para un pedido de Comax.
set_comax_order_status : establece el estado de un pedido de Comax.
get_comax_orders_by_credit_card : obtiene los pedidos asociados con un número de tarjeta de crédito.
get_comax_orders_simple : Recupera pedidos según un rango de fechas y filtros opcionales. Si el resultado es una URL XML, obtiene y proporciona una muestra de registros.
chk_item_exists_in_orders : comprueba si existe un artículo específico en un pedido.
set_comax_order_self_pickup : marca un pedido de Comax para recogida personal.

Consulte src/index.ts para conocer los parámetros exactos y los detalles de implementación de cada herramienta.

Conceptos básicos (FastMCP)

Herramientas

Las herramientas de MCP permiten a los servidores exponer funciones ejecutables que los clientes (como modelos de IA u otras aplicaciones) pueden invocar para realizar acciones. Este servidor utiliza herramientas para interactuar con la API de Comax.

FastMCP utiliza la especificación del esquema estándar para definir los parámetros de las herramientas. Este servidor utiliza principalmente Zod para este propósito.

Ejemplo de definición de herramienta (Zod):

import { z } from "zod";

server.addTool({
  name: "example_comax_tool",
  description: "An example tool description.",
  parameters: z.object({
    someParameter: z.string().describe("Description for the parameter"),
    // ... other parameters
  }),
  execute: async (args, { log, reportProgress }) => {
    log.info("Executing example_comax_tool with", args);
    // Your tool logic here - e.g., call Comax API
    // reportProgress({ progress: 50, total: 100 }); // Optional progress reporting
    return {
      content: [{ type: "text", text: "Tool execution finished." }],
    };
  },
});

Registro y manejo de errores

Registro: las herramientas pueden usar log.info() , log.warn() , etc., del contexto execute para enviar mensajes de registro.
Errores de usuario: arroja UserError desde fastmcp para los errores que se pretende mostrar al usuario final.
Progreso: utilice reportProgress para operaciones de larga duración.

Sesiones

FastMCP asigna una nueva instancia de servidor para cada conexión de cliente, lo que permite una comunicación 1:1. Se puede acceder a los datos específicos de la sesión si se configura la autenticación en el servidor FastMCP (no confundir con la autenticación de la API de Comax, que se gestiona por solicitud dentro de las herramientas).

Ejecución de su servidor

Prueba con `mcp-cli`

La forma más rápida de probar y depurar su servidor es con fastmcp dev :

# Ensure you are in the project root directory
npx fastmcp dev src/index.ts

Esto ejecutará su servidor con mcp-cli para probar y depurar su servidor MCP en la terminal.

Inspeccionar con `MCP Inspector`

Otra forma es utilizar el MCP Inspector para inspeccionar su servidor con una interfaz web:

npx fastmcp inspect src/index.ts

Ejecución con SSE para acceso a la red

Para que el servidor sea accesible a través de la red (por ejemplo, para un cliente remoto o Smithery):

// In src/index.ts, modify server.start:
server.start({
  transportType: "sse",
  sse: {
    endpoint: "/sse", // Or your desired endpoint
    port: 8080,       // Or your desired port
  },
});

Luego, ejecute node src/index.js (después de compilar TS a JS, por ejemplo, con tsc ) o use tsx para ejecución directa: npx tsx src/index.ts .

Preguntas frecuentes

¿Cómo usarlo con Claude Desktop (o clientes MCP similares)?

Siga la guía general en https://modelcontextprotocol.io/quickstart/user y configure el cliente MCP para iniciar su servidor.

Ejemplo de entrada mcp_config.json :

{
  "mcpServers": {
    "comax-gimo-mcp": {
      "command": "npx",
      "args": [
        "tsx",
        "/FULL/PATH/TO/YOUR/gimo-mcp/src/index.ts" // Replace with the absolute path
      ],
      "env": {
        // If you move Comax credentials to environment variables, define them here:
        // "ORDER_LOGIN_ID": "your_order_login_id",
        // "ORDER_LOGIN_PASSWORD": "your_order_login_password",
        // ... and so on for all required credentials/configs
      }
    }
  }
}

Asegúrese de que la ruta a src/index.ts sea correcta y que todas las variables de entorno necesarias (si elige usarlas en lugar de constantes) estén configuradas.

Integración de herrería

Este proyecto se integrará con Smithery para facilitar la automatización de mejoras de código, pruebas y flujos de trabajo de implementación mediante solicitudes de extracción de GitHub. Smithery requerirá los permisos de GitHub correspondientes para crear ramas y proponer cambios.

Expresiones de gratitud

Este servidor está construido utilizando FastMCP .
FastMCP está inspirado en la implementación de Python de Jonathan Lowin .
Partes del código base de FastMCP se adoptaron de LiteMCP y del protocolo Model ContextでSSEをやってみる.