helcim-mcp

Неофициальный community MCP-сервер и набор инструментов разработчика для Helcim API. Безопасный, типизированный, удобный для агентов и по умолчанию только для чтения. Не связан с Helcim Inc., не спонсируется, не поддерживается и не одобряется ею.

helcim-mcp — это production-quality TypeScript-монорепозиторий, который делает работу с платёжной платформой Helcim безопасной и простой для ИИ-агентов (и людей). Он включает три компонента:

1. @helcim-mcp/server — MCP-сервер, предоставляющий инструменты только для чтения для Helcim (клиенты, счета, карточные транзакции, карточные батчи, планы регулярных платежей, подписки, проверка соединения).

2. @helcim-mcp/core — типизированный Helcim API-клиент с поддержкой идемпотентности, нормализованными ошибками, обработкой лимитов запросов и редактированием секретов.

3. @helcim-mcp/webhooks — автономный верификатор вебхуков Helcim (проверка подписи HMAC-SHA256, проверка временных меток, защита от повторов, типизированные события).

Зачем это использовать?

• Вы хотите, чтобы ИИ-агент отвечал на вопросы о ваших данных Helcim — «какие счета не оплачены?», «покажи последние карточные транзакции», «найди клиента по этому счёту», «какие подписки требуют внимания?» — без какого-либо риска финансовых изменений.

• Вы хотите чистый, типизированный Helcim-клиент, который обрабатывает особенности API (HTTP 200 ≠ успех, формы объекта errors, идемпотентность, лимиты, пагинацию), чтобы вам не приходилось делать это самостоятельно.

• Вы хотите безопасно проверять вебхуки Helcim с постоянным по времени сравнением подписей и защитой от повторов, не изобретая заново схему HMAC.

MCP-сервер по умолчанию только для чтения. Он физически не может создавать, обновлять, удалять или перемещать деньги — таких инструментов нет. Даже токен с полными правами обработки не может инициировать финансовые изменения через этот сервер.

Быстрый старт

1. Получите API-токен Helcim

Войдите в свой аккаунт Helcim (или тестовый аккаунт разработчика), перейдите в All Tools → Integrations → API Access Configurations и создайте конфигурацию. Для использования только для чтения установите General: Read, Settings: Read, и Transaction Processing: None.

2. Запустите 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. Подключите его к MCP-клиенту

Добавьте это в конфигурацию вашего MCP-клиента (например, Claude Desktop, Cursor или любой MCP-клиент):

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

4. Спросите своего агента

После подключения ваш агент может вызывать такие инструменты, как:

• connection_test — подтвердить, что токен работает.

• list_invoices с status: "DUE" — «какие счета не оплачены?»

• list_card_transactions — «покажи последние карточные транзакции».

• get_customer — «найди клиента по этому счёту».

• list_subscriptions с hasFailedPayments: true — «какие подписки требуют внимания?»

Как работает режим только для чтения

• MCP-сервер предоставляет только инструменты чтения. Нет инструментов для платежей, возвратов, захвата, отмены, вывода средств, расчётов или удаления.

• Основной клиент не предоставляет методов записи в v1.

• Если будущая версия добавит запись, потребуется явная переменная окружения HELCIM_ENABLE_WRITES=true и отдельный флаг высокого риска для финансовых изменений, с подробной документацией и тестами.

• HTTP 200 не считается успехом. Helcim явно предупреждает, что ответ 200 не означает, что запрошенное действие выполнено; клиент выявляет errors в теле как типизированные ошибки.

Как защищены учётные данные

• API-токен считывается только из переменной окружения HELCIM_API_TOKEN. Никогда не захардкожен, никогда не коммитится, никогда не логируется.

• Все строки журнала и сообщения об ошибках проходят через redact(). Строки, похожие на токены, номера карт и значения F6L4 заменяются на <redacted-...>.

• Токен никогда не передаётся модели. MCP-сервер возвращает только отредактированные данные и типизированные коды ошибок.

• См. SECURITY.md для полной модели безопасности.

Архитектура

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

Структура монорепозитория:

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

Пример взаимодействия

Агент: «Какие счета сейчас не оплачены?»

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

Агент: «Покажи последние карточные транзакции».

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

Агент: «Найди клиента, связанного с этим счётом».

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

Агент: «Покажи подписки, требующие внимания».

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

Агент: «Обработай возврат для транзакции 25557533».

→ Error: Unknown tool: process_refund

Агент не может перемещать деньги. Такого инструмента нет.

Проверка вебхуков

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

См. examples/webhook-nextjs.md для полного примера Next.js.

Переменные окружения

См. docs/environment.md для полной справки.

Разработка

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

Лицензия

MIT. См. LICENSE.

Отказ от ответственности

Это независимый community-проект. Он не связан с Helcim Inc., не спонсируется, не поддерживается и не одобряется ею. «Helcim» — это товарный знак Helcim Inc., и он используется здесь только для описания совместимости с API. Этот проект не использует логотипы или брендинг Helcim.