helcim-mcp

Inoffizieller Community-MCP-Server und Entwickler-Toolkit für die Helcim-API. Sicher, typisiert, agentenfreundlich und standardmäßig schreibgeschützt. Nicht verbunden mit, gesponsert von, gepflegt von oder unterstützt von Helcim Inc.

helcim-mcp ist ein produktionsreifes TypeScript-Monorepo, das es KI-Agenten (und Menschen) sicher und einfach macht, mit der Helcim-Zahlungsplattform zu arbeiten. Es enthält drei Komponenten:

1. @helcim-mcp/server — ein MCP-Server, der schreibgeschützte Helcim-Tools bereitstellt (Kunden, Rechnungen, Kartentransaktionen, Kartenabrechnungen, wiederkehrende Zahlungspläne, Abonnements, Verbindungstest).

2. @helcim-mcp/core — ein typisierter, idempotenzbewusster Helcim-API-Client mit normalisierten Fehlern, Rate-Limit-Behandlung und Geheimnis-Redaktion.

3. @helcim-mcp/webhooks — ein eigenständiger Helcim-Webhook-Verifizierer (HMAC-SHA256-Signaturprüfung, Zeitstempelvalidierung, Replay-Schutz, typisierte Ereignisse).

Warum sollten Sie das verwenden?

• Sie möchten, dass ein KI-Agent Fragen zu Ihren Helcim-Daten beantwortet – „Welche Rechnungen sind offen?", „Zeige letzte Kartentransaktionen", „Finde den Kunden für diese Rechnung", „Welche Abonnements benötigen Aufmerksamkeit?" – ohne jemals eine finanzielle Mutation zu riskieren.

• Sie möchten einen sauberen, typisierten Helcim-Client, der die Eigenheiten der API behandelt (HTTP 200 ≠ Erfolg, errors-Objektformen, Idempotenz, Rate-Limits, Paginierung), damit Sie es nicht tun müssen.

• Sie möchten Helcim-Webhooks sicher verifizieren mit Konstantzeit-Signaturvergleich und Replay-Schutz, ohne das HMAC-Schema neu zu erfinden.

Der MCP-Server ist standardmäßig schreibgeschützt. Er kann physisch kein Geld erstellen, aktualisieren, löschen oder bewegen – es gibt keine solchen Tools. Selbst ein Token mit vollständigen Verarbeitungsrechten kann über diesen Server keine finanzielle Mutation auslösen.

Schnellstart

1. Holen Sie sich ein Helcim-API-Token

Melden Sie sich bei Ihrem Helcim-Konto (oder einem Entwicklertestkonto) an, gehen Sie zu Alle Tools → Integrationen → API-Zugriffskonfigurationen und erstellen Sie eine Konfiguration. Für schreibgeschützte Nutzung setzen Sie Allgemein: Lesen, Einstellungen: Lesen und Transaktionsverarbeitung: Keine.

2. Führen Sie den MCP-Server aus

# 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. Verbinden Sie ihn mit einem MCP-Client

Fügen Sie dies zu Ihrer MCP-Client-Konfiguration hinzu (z. B. Claude Desktop, Cursor oder einem beliebigen MCP-Client):

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

4. Fragen Sie Ihren Agenten

Sobald verbunden, kann Ihr Agent Tools wie diese aufrufen:

• connection_test — bestätigen, dass das Token funktioniert.

• list_invoices mit status: "DUE" — „Welche Rechnungen sind offen?"

• list_card_transactions — „Zeige letzte Kartentransaktionen."

• get_customer — „Finde den Kunden für diese Rechnung."

• list_subscriptions mit hasFailedPayments: true — „Welche Abonnements benötigen Aufmerksamkeit?"

Wie der Schreibschutzmodus funktioniert

• Der MCP-Server stellt nur Lese-Tools bereit. Es gibt keine Zahlungs-, Rückerstattungs-, Erfassungs-, Stornierungs-, Abhebungs-, Abrechnungs- oder Lösch-Tools.

• Der Core-Client stellt in v1 keine Schreibmethoden bereit.

• Wenn eine zukünftige Version Schreibvorgänge hinzufügt, erfordert dies eine explizite HELCIM_ENABLE_WRITES=true-Umgebungsvariable und ein separates Hochrisiko-Feature-Flag für finanzielle Mutationen, mit ausführlicher Dokumentation und Tests.

• HTTP 200 wird nicht als Erfolg behandelt. Helcim warnt ausdrücklich, dass eine 200-Antwort nicht bedeutet, dass die angeforderte Aktion erfolgreich war; der Client zeigt errors im Body als typisierte Fehler an.

Wie Anmeldeinformationen geschützt werden

• Das API-Token wird nur aus der Umgebungsvariable HELCIM_API_TOKEN gelesen. Niemals hartcodiert, niemals committet, niemals protokolliert.

• Alle Protokollzeilen und Fehlermeldungen durchlaufen redact(). Token-ähnliche Zeichenfolgen, Kartennummern und F6L4-Werte werden durch <redacted-...> ersetzt.

• Das Token wird niemals dem Modell ausgesetzt. Der MCP-Server gibt nur redigierte Daten und typisierte Fehlercodes zurück.

• Siehe SECURITY.md für das vollständige Sicherheitsmodell.

Architektur

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

Das Monorepo-Layout:

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

Beispielinteraktion

Agent: „Welche Rechnungen sind derzeit offen?"

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 }
  ] }

Agent: „Zeige letzte Kartentransaktionen."

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" }
  ] }

Agent: „Finde den Kunden, der mit dieser Rechnung verbunden ist."

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

Agent: „Zeige Abonnements, die Aufmerksamkeit benötigen."

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

Agent: „Verarbeite eine Rückerstattung für Transaktion 25557533."

→ Error: Unknown tool: process_refund

Der Agent kann kein Geld bewegen. Es gibt kein solches Tool.

Webhook-Verifizierung

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 });
  }
}

Siehe examples/webhook-nextjs.md für ein vollständiges Next.js-Beispiel.

Umgebungsvariablen

Siehe docs/environment.md für die vollständige Referenz.

Entwicklung

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

Lizenz

MIT. Siehe LICENSE.

Haftungsausschluss

Dies ist ein unabhängiges Community-Projekt. Es ist nicht mit Helcim Inc. verbunden, wird nicht von Helcim Inc. gesponsert, gepflegt oder unterstützt. „Helcim" ist eine Marke von Helcim Inc. und wird hier nur zur Beschreibung der API-Kompatibilität verwendet. Dieses Projekt verwendet keine Helcim-Logos oder -Markenzeichen.