@juanzea/ptp-studio-mcp

Companion MCP local de PTP Studio: conecta tu PTP Studio (en el navegador) con un agente de IA (Claude Code, OpenCode…) para que opere la app en vivo — ver tus sitios/entornos, crear/consultar/cancelar sesiones de pago de Webcheckout (que quedan en tu Historial), navegar y dejar la app lista para operar.

No expone credenciales: el tranKey nunca llega al modelo. El checkout de Webcheckout se delega por HTTP al deploy de PTP Studio.

  Agente IA  ◄──MCP (stdio)──►  ptp-studio-mcp  ◄──WebSocket local──►  PTP Studio (tu navegador)
                                      │
                                      └──HTTP──►  checkout remoto (firma WSSE en el deploy)

Requisitos

• Node ≥ 20
• PTP Studio abierto en el navegador con el Puente MCP encendido (ícono 🔌 en la barra superior).

Uso

Regístralo como MCP local en tu agente. Ejemplos:

Claude Code

claude mcp add ptp-studio -- npx -y @juanzea/ptp-studio-mcp

OpenCode (opencode.json)

{
  "mcp": {
    "ptp-studio": {
      "type": "local",
      "command": ["npx", "-y", "@juanzea/ptp-studio-mcp"],
      "enabled": true,
    },
  },
}

Luego abre PTP Studio y enciende el Puente MCP. Pídele al agente, por ejemplo: "lista mis sitios", "crea una sesión de pago con el sitio X", "llévame al historial".

Configuración (opcional, por variables de entorno)

| Variable | Por defecto | Para qué | | ---------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PTP_CHECKOUT_MCP_URL | https://placetopay-checkout-mcp.juanzea.com/ | endpoint del checkout remoto (en dev, apúntalo al Worker local del checkout: http://localhost:8788/) | | PTP_BRIDGE_PORT | 4777 | puerto del puente WebSocket con el navegador | | PTP_MCP_HTTP_PORT | 4778 | puerto de coordinación entre companions (auto-spawn compartido) | | PTP_BRIDGE_ORIGINS | — | orígenes extra permitidos por el puente (coma-separado), además de localhost:4321, ptp-studio.juanzea.com y, temporalmente, ptp-studio.juanzea.workers.dev |

Puedes ponerlas en un .env junto al paquete (ver .env.example).

Cómo corre

• Auto-spawn compartido: cada agente lanza su propio proceso, pero solo uno es el "primario" (dueño del puente); los demás le reenvían. Cero conflictos aunque abras varios agentes.
• Seguridad: el puente solo acepta conexiones desde PTP Studio (allowlist de Origin) y escucha solo en 127.0.0.1. Todo ocurre en tu equipo.

Tools

• Estado (en vivo desde el navegador): list_sessions, list_sites, list_environments.
• Sitios: create_site, update_site, delete_site, set_active_site.
• Entornos: create_environment, update_environment (renombra en cascada los sitios), delete_environment.
• Navegación: navigate, list_routes.
• Endpoints: prefill_endpoint (deja una vista con el request precargado y editable, sin enviar), describe_endpoint y list_endpoints (forma REAL de la API de Webcheckout, fuente de verdad para armar requests).
• Mocks: list_mocks, create_mock, update_mock, delete_mock.
• Checkout por sitio (delegan al MCP de checkout con las credenciales del sitio; el tranKey nunca llega al modelo): check_auth_for_site, create_session_for_site, query_session_for_site, cancel_session_for_site.

Autor

Hecho por Juan Zea (@JuanZea).

Licencia

MIT — ver LICENSE.