@payretailers/mcp

Servidor oficial del Model Context Protocol (MCP) para la API de pagos de PayRetailers.

Convierte cualquier asistente de IA compatible con MCP en un experto en integración de PayRetailers. Este servidor expone las guías oficiales, las habilidades tácticas, la referencia de endpoints y las herramientas de integración (búsqueda, validación específica por país, manual de webhooks) como recursos, herramientas y prompts de MCP de primera clase.

Funciona con Cursor, Claude Desktop, Claude Code, Windsurf, Antigravity, Zed, VS Code + Copilot, JetBrains IDEs, Continue.dev, Cline y cualquier otro cliente que hable MCP sobre stdio.

Por qué usarlo

Cuando instalas este servidor, tu asistente de IA deja de adivinar sobre PayRetailers y comienza a consultar la fuente de verdad en cada paso.

• Código correcto al primer intento. El asistente lee la forma real de OpenAPI para cada endpoint (get_endpoint_spec), por lo que el código generado usa los nombres de campo, tipos y combinaciones obligatorias reales, no algo tomado de otro PSP.

• Consciente del país desde el principio. Pide un payin PIX y el asistente sabe que PIX es solo para Brasil, espera BRL, necesita un CPF válido de 11 dígitos y que el QR caduca rápido. Pide SPEI y sabe que México requiere CURP o RFC, MXN, y que CLABE se aprovisiona de forma asíncrona. Todo impulsado por get_country_rules.

• Payloads validados antes de llegar al sandbox. validate_payload ejecuta validación real de checksum en CPF, CNPJ, RUT, DNI, RUC, CC, NIT, CURP, RFC, CLABE, además de reglas transversales (unidades mínimas enteras, URLs de notificación HTTPS, coincidencia moneda/país, compatibilidad método/país, claves de idempotencia, matriz de campos obligatorios del cliente, forma de AmountModel de suscripciones, contrato de reintento de PIX Automático). Detectas errores en tu editor, no en una respuesta 400 INVALID_MODEL_SCHEMA.

• Receptores de webhook diseñados correctamente. get_webhook_playbook devuelve el vocabulario canónico de eventos, las políticas de reintento y el contrato de firma/reproducción. validate_webhook_handler detecta los seis anti-patrones más dañinos (ack después de procesar, falta de deduplicación por eventId, errores de negocio como 500, firma deshabilitada en producción, suposiciones de orden por reloj, falta de HTTPS) antes de que escribas una sola línea de código de receptor.

• Prompts de comando slash para los flujos difíciles. Escribe /integrate-pix-payin, /integrate-subscriptions, /implement-webhook-handler, /integrate-payout-fx, /build-checkout, /debug-401-auth o /reconcile-with-graphql y obtén una implementación con forma de producción en la pila de tu elección.

• Cero configuración, cero red, apto para uso sin conexión. Todo se incluye en el zip de la versión. Sin cuenta, sin clave de API, sin llamadas salientes solo para responder una pregunta sobre la documentación. Las credenciales solo se necesitan para la herramienta (planificada) simulate_transaction.

En el interior tienes 7 herramientas, 7 prompts, 158 recursos de documentación (Guías + Habilidades + Referencia + Recetas + documentos conceptuales), todo reflejado textualmente desde el repositorio payretailers-ai-docs.

Related MCP server: Payman AI Documentation MCP Server

Qué expone

Recursos

Acceso estructurado y amigable para LLM a la documentación de PayRetailers.

La lista completa se anuncia dinámicamente al conectar: los clientes pueden navegar por ella mediante su selector de recursos.

Herramientas

Acciones que el LLM puede invocar en lugar de adivinar.

Prompts

Plantillas listas para usar que el desarrollador puede seleccionar con / en Cursor / Claude Desktop / etc.

Instalación

Dos rutas compatibles. Elige una:

• Opción A — Zip precompilado desde GitHub Releases (recomendada hoy): sin cuenta de npm, sin compilación, funciona totalmente sin conexión una vez descargado. Esta es la distribución oficialmente soportada mientras @payretailers/mcp no esté aún en npm.

• Opción B — Compilar desde el código fuente: para colaboradores y despliegues con requisitos de seguridad que quieran auditar el código antes de ejecutarlo.

La opción C — instalar desde npm como @payretailers/mcp — está planificada pero aún no disponible. Cuando el paquete se publique, los fragmentos npx -y @payretailers/mcp de la sección Configuración por cliente funcionarán directamente.

Opción A — Instalar desde GitHub Releases

Requisitos previos: Node.js 20 o posterior (node --version). Nada más — el zip de la versión es autocontenido.

1. Abre la página de Releases y descarga el último payretailers-mcp-vX.Y.Z.zip de la sección "Assets" de la versión superior.

2. Descomprímelo en cualquier lugar. Ubicaciones habituales:

   • Windows: C:\Tools\payretailers-mcp

   • macOS / Linux: ~/tools/payretailers-mcp

3. Añade el servidor a tu cliente MCP (consulta Configuración por cliente más abajo, o las guías paso a paso enlazadas allí). Apunta a la ruta absoluta de dist/index.js dentro de la carpeta descomprimida.

4. Recarga / reinicia tu cliente MCP. El servidor aparecerá junto a tus otras herramientas.

Guías de configuración paso a paso con capturas de pantalla y comprobaciones de verificación:

• Cursor

• Claude Code CLI

• Claude Desktop

• VS Code + GitHub Copilot

Comprobación rápida opcional antes o después de conectarlo — demuestra que el paquete funciona correctamente de principio a fin:

cd /path/to/payretailers-mcp-X.Y.Z
node scripts/smoke-test.mjs

Resultado esperado: PASS ✅ al final, con 7 herramientas, 158 recursos, 7 prompts, 5 plantillas de recursos anunciados.

Opción B — Compilar desde el código fuente

Para colaboradores, o si tu política de seguridad requiere auditar el código antes de ejecutarlo. Requisitos previos: Node.js 20 o posterior, git.

git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js (bundle + runtime deps)
npm start              # optional: run over stdio manually (Ctrl+C to stop)

data/ (Guías, Skills, Referencia, Recetas, documentación conceptual, JSON curado) está incluido en el repositorio — no necesitas npm run sync:docs a menos que estés replicando un checkout actualizado de payretailers-ai-docs en la misma máquina.

Luego conecta dist/index.js a tu cliente MCP de la misma manera que en la Opción A.

Configuración por cliente

¿Prefieres una guía completa con comprobaciones de verificación y solución de problemas? Consulta las guías paso a paso en docs/setup/ para Cursor, Claude Code, Claude Desktop y VS Code + Copilot. Los fragmentos siguientes son el JSON mínimo necesario si ya conoces tu cliente.

Cada cliente recibe los mismos tres datos: un comando (node), un array de args que apunta a la ruta absoluta de dist/index.js, y un bloque env opcional para la futura herramienta simulate_transaction.

Reemplaza C:/Tools/payretailers-mcp/dist/index.js más abajo con la ruta absoluta donde descomprimiste la versión. En Windows usa barras diagonales en el JSON — las barras invertidas deben escaparse y causan errores confusos.

Cursor

Añade a ~/.cursor/mcp.json (global) o .cursor/mcp.json (por proyecto):

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"],
      "env": {
        "PAYRETAILERS_ENV": "sandbox",
        "PAYRETAILERS_SHOP_ID": "your_sandbox_shop_id",
        "PAYRETAILERS_SECRET_KEY": "your_sandbox_secret_key",
        "PAYRETAILERS_SUBSCRIPTION_KEY": "your_sandbox_subscription_key"
      }
    }
  }
}

El bloque env es opcional — los Recursos, search_docs y todos los validadores funcionan sin credenciales.

Claude Desktop

Añade a tu claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

Windsurf

Añade a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

VS Code + Copilot

Añade a .vscode/mcp.json (espacio de trabajo) o abre el archivo de ámbito de usuario con la Paleta de comandos → MCP: Open User Configuration:

{
  "servers": {
    "payretailers": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

Nota: VS Code es el caso especial — la clave raíz es "servers" (no "mcpServers"). Las herramientas MCP solo se ejecutan en el modo Agente de Copilot Chat.

Zed

Añade a ~/.config/zed/settings.json:

{
  "context_servers": {
    "payretailers": {
      "command": {
        "path": "node",
        "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
      }
    }
  }
}

Continue.dev

Añade a ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "payretailers",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  ]
}

JetBrains AI Assistant

Abre Settings → AI Assistant → MCP Servers → Add e introduce:

• Name: payretailers

• Command: node

• Arguments: C:/Tools/payretailers-mcp/dist/index.js (ruta absoluta)

Otros clientes

Cualquier cliente que hable MCP sobre stdio puede consumir este servidor. Apunta a node <ruta-absoluta-a>/dist/index.js y listo.

Cuando npm esté disponible

Cuando @payretailers/mcp se publique en npm, las mismas configuraciones funcionarán con la forma abreviada:

{ "command": "npx", "args": ["-y", "@payretailers/mcp"] }

Sin cambios en env, sin necesidad de mantener una carpeta descomprimida.

Verificar que funciona

Después de recargar tu cliente MCP deberías ver, en la entrada de estado del servidor, algo como:

7 herramientas · 158 recursos · 7 prompts · 5 plantillas de recursos

• Cursor: Ctrl+Shift+P → Customize → pestaña MCPs. Busca payretailers con un punto verde y expándelo.

• Claude Desktop: comprueba el cajón de herramientas en un chat nuevo; las herramientas de PayRetailers deberían aparecer junto a tus otros MCP.

• VS Code / Zed / Continue.dev / Windsurf: consulta la documentación de cada cliente para su panel de estado MCP.

Si tu asistente no parece llamar a las herramientas, fuérzalo una vez prefijando un prompt con "Usa el MCP de PayRetailers para...". Una vez que ha invocado una herramienta en una conversación, tiende a seguir haciéndolo.

Solución de problemas

El servidor no se inicia. Ejecuta el paquete manualmente desde una terminal:

node /path/to/payretailers-mcp/dist/index.js

Si permanece en silencio esperando entrada, el paquete está bien — el problema está en el lado del cliente (error tipográfico en la ruta de la configuración, barras diagonales vs. invertidas en Windows, proceso incorrecto reiniciado). Si imprime un error, las causas más comunes son Node < 20 (actualiza Node) o una descarga truncada (vuelve a descargar el zip).

El cliente muestra recuentos antiguos (p. ej. 5 herramientas, 89 recursos). Algunos clientes almacenan en caché la enumeración de herramientas/recursos MCP. Alterna el servidor OFF → ON en el panel MCP del cliente, o añade una entrada env no utilizada a la configuración (p. ej. "MCP_VERSION": "0.4.1") para forzar un reinicio.

El modelo no parece llamar a ninguna herramienta MCP. Asegúrate de que el chat esté en modo Agente (no en modo Preguntar / solo lectura). Algunos modelos ligeros son menos propensos a llamar herramientas — cambia a un modelo de primer nivel para las primeras invocaciones, y el asistente recordará que las herramientas están disponibles durante el resto de la conversación.

¿Dónde están los registros? Cada cliente MCP tiene un panel de registros MCP que captura el protocolo de enlace JSON-RPC, errores de análisis y stderr del servidor. En Cursor: Ctrl+Shift+U → desplegable → MCP Logs.

Variables de entorno

Opcionales — solo se requieren para la futura herramienta simulate_transaction (Fase 4). Todo lo demás (Recursos, search_docs, Prompts) funciona sin credenciales.

Seguridad: el servidor nunca registra credenciales ni las persiste. Viven en memoria durante la sesión y solo se envían a api-sandbox.payretailers.com o api.payretailers.com cuando invocas simulate_transaction.

Ejemplo de uso

Una vez configurado, pide a tu asistente de IA en lenguaje natural:

"Crea mi primer payin PIX en el sandbox por R$50 en Brasil. Usa Node.js."

Entre bastidores, el asistente:

1. Llamará a search_docs({ query: "pix payin brazil" }) → encontrará la skill brazil-pix-payin.

2. Leerá payretailers://skill/brazil-pix-payin para los pasos exactos.

3. Generará código ejecutable con el endpoint, las cabeceras, las unidades menores y el formato CPF correctos.

O usa el prompt /integrate-pix-payin directamente para una respuesta completamente estructurada.

Validar un payload antes del envío

Una vez que el asistente ha redactado un payload, puede validarlo antes de llamar a la API:

// tools/call → validate_payload
{
  "operation": "create-transaction",
  "country": "BR",
  "method": "PIX",
  "payload": {
    "trackingId": "abc-12345678",
    "amount": 100.50,              // will be flagged: use 10050 (minor units)
    "currency": "USD",             // will be flagged: BR expects BRL
    "notificationUrl": "http://example.com/wh", // will be flagged: must be HTTPS
    "customer": {
      "firstName": "Ana",
      "lastName": "Santos",
      "email": "ana@example.com",
      "personalId": "12345678900"  // will be flagged: invalid CPF checksum
    }
  }
}

La respuesta enumera cada problema con un code, severity, path, message, y a menudo un hint y suggestion — el LLM puede corregir el payload antes de gastar un viaje de red.

Desarrollo

git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js
npm test               # 93 unit tests
node scripts/smoke-test.mjs   # end-to-end stdio handshake + tool calls
npm start              # optional: run the server manually on stdio

data/ (Guías, Skills, Referencia, Recetas, documentación conceptual, JSON curado) está incluido en el repositorio. Ejecuta npm run sync:docs solo si tienes ../payretailers-ai-docs clonado y quieres actualizar el espejo.

El servidor se puede inspeccionar con el MCP Inspector oficial:

npx @modelcontextprotocol/inspector node dist/index.js

Publicación de versiones (mantenedores)

Las versiones se automatizan mediante GitHub Actions al empujar una etiqueta (v*.*.*). El flujo de trabajo:

1. Ejecuta lint, typecheck, pruebas unitarias, compilación y prueba de humo.

2. Ejecuta npm run pack:release para producir release/payretailers-mcp-vX.Y.Z.zip (dist/index.js empaquetado + espejo data/ + README + LICENSE + CHANGELOG + prueba de humo).

3. Crea una Release de GitHub y adjunta el zip.

4. Publica en npm como @payretailers/mcp solo si el secreto del repositorio NPM_TOKEN está configurado — de lo contrario, la versión es solo de GitHub.

Para crear una versión localmente y luego empujar la etiqueta:

# 1. Bump version in package.json, config.ts, CHANGELOG.md
# 2. Verify locally
npm run clean && npm ci && npm test && npm run build
node scripts/smoke-test.mjs
npm run pack:release        # writes release/payretailers-mcp-vX.Y.Z.zip

# 3. Commit + tag + push
git add -A
git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z      # this triggers .github/workflows/release.yml

El versionado semántico se aplica estrictamente: las versiones de parche corrigen errores, las versiones menores añaden herramientas/prompts/recursos sin romper los existentes, las versiones mayores solo para renombramientos/eliminaciones.

Hoja de ruta

• 0.1 ✅ Recursos (Guías, Skills), search_docs, prompt integrate-pix-payin.

• 0.2 ✅ Recursos (Referencia, Recetas), get_country_rules, get_test_data, get_endpoint_spec, prompts integrate-payout-fx, build-checkout, debug-401-auth, reconcile-with-graphql.

• 0.3 ✅ validate_payload con validación real de checksum para CPF, CNPJ, RUT, DNI, RUC, CC, NIT, CURP, RFC, CLABE + reglas transversales (unidades menores, moneda/país, webhooks HTTPS, método/país, idempotencia).

• 0.4 ✅ Categoría de recursos de documentación conceptual, get_webhook_playbook, validate_webhook_handler, validate_payload ampliado para operaciones de suscripción, prompts implement-webhook-handler, integrate-subscriptions.

• 0.4.1 ✅ Alineación del esquema de suscripciones (AmountModel, enumeración de frecuencia, authorizationType) — CHANGELOG.md.

• 0.5 — simulate_transaction (prueba en seco contra el sandbox), get_error_code, cobertura de países ampliada.

• 1.0 — Versión pública estable + listado en el Registro MCP oficial + publicación en npm.

Consulta CHANGELOG.md para más detalles.

Relacionado

• Guías de configuración paso a paso para Cursor, Claude Code, Claude Desktop y VS Code + Copilot: docs/setup/.

• Repositorio de documentación complementaria: payretailers-dev/payretailers-ai-docs — la fuente de Guías, Skills y el espejo de documentación.

• Documentación oficial: www.payretailers.dev.

• Guía para desarrollar con LLMs: www.payretailers.dev/docs/develop-with-llms.

• Model Context Protocol: modelcontextprotocol.io.

Licencia

Código fuente: MIT. Consulta LICENSE.

El contenido de documentación incluido en data/ (Guías, Skills, Referencia, Recetas) está licenciado bajo CC BY-ND 4.0, heredado del repositorio payretailers-ai-docs. Los archivos de datos curados (data/country-rules.json, data/test-data.json) también se publican bajo CC BY-ND 4.0.

Contribuciones

Los informes de errores y las solicitudes de funciones son bienvenidos a través de GitHub Issues. Las solicitudes de extracción de la comunidad se revisan pero se fusionan a discreción del equipo de PayRetailers — consulta CONTRIBUTING.md cuando esté disponible.