helcim-mcp

No oficial — Servidor MCP comunitario y kit de desarrollo para la API de Helcim. Seguro, tipado, amigable con agentes y solo lectura por defecto. No afiliado, patrocinado, mantenido ni respaldado por Helcim Inc.

helcim-mcp es un monorepo TypeScript de calidad de producción que hace que sea seguro y fácil para agentes de IA (y humanos) trabajar con la plataforma de pagos de Helcim. Incluye tres componentes:

1. @helcim-mcp/server — un servidor MCP que expone solo lectura de herramientas de Helcim (clientes, facturas, transacciones con tarjeta, lotes de tarjetas, planes de suscripción recurrentes, suscripciones, prueba de conexión).

2. @helcim-mcp/core — un cliente de API de Helcim tipado y consciente de idempotencia con errores normalizados, manejo de límites de tasa y redacción de secretos.

3. @helcim-mcp/webhooks — un verificador independiente de webhooks de Helcim (verificación de firma HMAC-SHA256, validación de marcas de tiempo, protección contra reproducción, eventos tipados).

¿Por qué usar esto?

• Quieres que un agente de IA responda preguntas sobre tus datos de Helcim — "¿qué facturas están pendientes?", "muestra transacciones recientes con tarjeta", "encuentra el cliente de esta factura", "¿qué suscripciones necesitan atención?" — sin arriesgar jamás una mutación financiera.

• Quieres un cliente de Helcim limpio y tipado que maneje las peculiaridades de la API (HTTP 200 ≠ éxito, formas de objetos errors, idempotencia, límites de tasa, paginación) para que no tengas que hacerlo tú.

• Quieres verificar webhooks de Helcim de forma segura con comparación de firmas en tiempo constante y protección contra reproducción, sin reinventar el esquema HMAC.

El servidor MCP es solo lectura por defecto. Físicamente no puede crear, actualizar, eliminar ni mover dinero — no existen tales herramientas. Incluso un token con privilegios completos de procesamiento no puede provocar una mutación financiera a través de este servidor.

Inicio rápido

1. Obtén un token de API de Helcim

Inicia sesión en tu cuenta de Helcim (o en una cuenta de desarrollador de prueba), ve a Todas las herramientas → Integraciones → Configuraciones de acceso a la API y crea una configuración. Para uso de solo lectura, establece General: Lectura, Configuraciones: Lectura y Procesamiento de transacciones: Ninguno.

2. Ejecuta el servidor MCP

# From source
git clone https://github.com/tejasghalsasi/helcim-mcp.git
cd helcim-mcp
pnpm install
pnpm rebuild esbuild   # required: pnpm 11 blocks esbuild's postinstall by default
pnpm build

# Set your token (never commit it)
export HELCIM_API_TOKEN="your_token_here"

# Run over stdio
node packages/mcp/dist/index.js

3. Conéctalo a un cliente MCP

Agrega esto a la configuración de tu cliente MCP (por ejemplo, Claude Desktop, Cursor o cualquier cliente MCP):

{
  "mcpServers": {
    "helcim": {
      "command": "node",
      "args": ["/absolute/path/to/helcim-mcp/packages/mcp/dist/index.js"],
      "env": {
        "HELCIM_API_TOKEN": "your_token_here"
      }
    }
  }
}

4. Pregúntale a tu agente

Una vez conectado, tu agente puede llamar a herramientas como:

• connection_test — confirma que el token funciona.

• list_invoices con status: "DUE" — "¿qué facturas están pendientes?"

• list_card_transactions — "muestra transacciones recientes con tarjeta."

• get_customer — "encuentra el cliente de esta factura."

• list_subscriptions con hasFailedPayments: true — "¿qué suscripciones necesitan atención?"

Cómo funciona el modo de solo lectura

• El servidor MCP expone únicamente herramientas de lectura. No hay herramientas de pago, reembolso, captura, reversión, retiro, liquidación ni eliminación.

• El cliente central no expone ningún método de escritura en v1.

• Si una versión futura agrega escrituras, requerirá una variable de entorno HELCIM_ENABLE_WRITES=true explícita y un indicador de característica de alto riesgo separado para mutaciones financieras, con documentación sólida y pruebas.

• HTTP 200 no se trata como éxito. Helcim advierte explícitamente que un 200 no significa que la acción solicitada se haya realizado; el cliente expone errors en el cuerpo como errores tipados.

Cómo se protegen las credenciales

• El token de API se lee solo de la variable de entorno HELCIM_API_TOKEN. Nunca codificado, nunca confirmado, nunca registrado.

• Todas las líneas de registro y mensajes de error pasan por redact(). Cadenas similares a tokens, números de tarjeta y valores F6L4 se reemplazan con <redacted-...>.

• El token nunca se expone al modelo. El servidor MCP solo devuelve datos redactados y códigos de error tipados.

• Consulta SECURITY.md para conocer el modelo de seguridad completo.

Arquitectura

flowchart LR
    subgraph Client["MCP Client (LLM)"]
        A[Agent]
    end

    subgraph Server["@helcim-mcp/server"]
        M[MCP Server<br/>stdio transport]
        T[Read-only tools<br/>13 tools]
    end

    subgraph Core["@helcim-mcp/core"]
        C[HelcimClient]
        H[HelcimHttpClient<br/>auth, idempotency,<br/>rate-limit, redaction]
        E[Normalized errors]
    end

    subgraph Webhooks["@helcim-mcp/webhooks"]
        W[HelcimWebhookVerifier<br/>HMAC-SHA256, replay protection]
    end

    subgraph Helcim["Helcim API"]
        API[api.helcim.com/v2]
    end

    A -->|JSON-RPC over stdio| M
    M --> T
    T --> C
    C --> H
    H -->|HTTPS + api-token| API
    W -.->|verifies signed events| API

La estructura del monorepo:

helcim-mcp/
├── packages/
│   ├── core/       # Typed Helcim API client (read-safe)
│   ├── mcp/        # MCP server (read-only tools)
│   ├── webhooks/   # Webhook verifier
│   └── fixtures/   # Deterministic mock responses + test vectors
├── examples/       # Copy-paste usage examples
├── docs/           # Architecture, env reference, troubleshooting
└── scripts/        # Smoke test, CI helpers

Ejemplo de interacción

Agente: "¿Qué facturas están pendientes?"

list_invoices(status: "DUE")
→ { count: 2, invoices: [
    { invoiceId: 28658838, invoiceNumber: "INV1000", status: "DUE", currency: "CAD", customerId: 2488717 },
    { invoiceId: 28658839, invoiceNumber: "INV1001", status: "DUE", currency: "USD", customerId: 2488718 }
  ] }

Agente: "Muestra transacciones recientes con tarjeta."

list_card_transactions(limit: 5)
→ { count: 2, transactions: [
    { transactionId: 25557533, status: "APPROVED", type: "purchase", amount: 100.99, currency: "CAD", cardType: "MC", customerCode: "CST1000" },
    { transactionId: 25557534, status: "DECLINED", type: "purchase", amount: 250.00, currency: "CAD", cardType: "VI", customerCode: "CST1001" }
  ] }

Agente: "Encuentra el cliente asociado con esta factura."

get_invoice(invoiceId: 28658838) → { customerId: 2488717, ... }
get_customer(customerId: 2488717) → { customerCode: "CST1000", businessName: "Acme Widgets Ltd", ... }

Agente: "Muestra suscripciones que requieren atención."

list_subscriptions(hasFailedPayments: true)
→ { count: 1, subscriptions: [ { id: 42, status: "ACTIVE", hasFailedPayments: true, customerCode: "CST1000", ... } ] }

Agente: "Procesa un reembolso para la transacción 25557533."

→ Error: Unknown tool: process_refund

El agente no puede mover dinero. No existe tal herramienta.

Verificación de webhooks

import { HelcimWebhookVerifier } from '@helcim-mcp/webhooks';

const verifier = new HelcimWebhookVerifier(process.env.HELCIM_VERIFIER_TOKEN!);

// In your webhook handler (e.g. Next.js route handler):
export async function POST(req: Request) {
  const body = await req.text();
  const headers = Object.fromEntries(req.headers.entries());
  try {
    const verified = verifier.verify(headers, body);
    // verified.event.type === 'cardTransaction' | 'terminalCancel'
    return new Response('ok', { status: 200 });
  } catch (err) {
    return new Response('invalid signature', { status: 401 });
  }
}

Consulta examples/webhook-nextjs.md para ver un ejemplo completo de Next.js.

Variables de entorno

Consulta docs/environment.md para la referencia completa.

Desarrollo

pnpm install
pnpm rebuild esbuild  # pnpm 11 blocks esbuild's postinstall by default
pnpm build        # build all packages
pnpm test         # run all tests
pnpm typecheck    # type-check all packages
pnpm lint         # prettier check
pnpm smoke        # verify the built server exposes only read-only tools

Licencia

MIT. Consulta LICENSE.

Aviso legal

Este es un proyecto comunitario independiente. No está afiliado, patrocinado, mantenido ni respaldado por Helcim Inc. "Helcim" es una marca comercial de Helcim Inc. y se utiliza aquí únicamente para describir la compatibilidad con la API. Este proyecto no utiliza logotipos ni marcas de Helcim.