Bitrefill MCP Server (Пример реализации)

Это пример / эталонная реализация. Для использования в продакшене подключайтесь к официальному хостингу Bitrefill eCommerce MCP по адресу https://api.bitrefill.com/mcp. Он поддерживается компанией Bitrefill, поддерживает OAuth и предоставляет те же инструменты без необходимости запуска, развертывания или обновления чего-либо с вашей стороны.

Используйте этот репозиторий, если хотите узнать, как можно создать Bitrefill MCP, сделать форк, расширить его или самостоятельно разместить кастомизированный вариант на базе Bitrefill API v2.

Этот сервер использует Bitrefill API v2 (https://api.bitrefill.com/v2) с заголовком Authorization: Bearer ${BITREFILL_API_KEY}. Только параметры запроса проверяются с помощью Zod; ответы API возвращаются как JSON-текст без изменений.

Использование официального удаленного MCP (рекомендуется для продакшена)

Bitrefill eCommerce MCP размещается на серверах Bitrefill и является рекомендуемым способом интеграции с ChatGPT, Claude Desktop / Code, Cursor и любым другим MCP-совместимым клиентом.

• OAuth (рекомендуется). Укажите клиенту адрес:

  https://api.bitrefill.com/mcp

  Вы будете перенаправлены на Bitrefill для входа и авторизации доступа. Обработка API-ключа не требуется.

• API-ключ. Добавьте свой ключ из bitrefill.com/account/developers:

  https://api.bitrefill.com/mcp/YOUR_API_KEY

Руководства по настройке для каждого клиента: ChatGPT, Claude Desktop, Claude Code, Cursor.

Related MCP server: agentstorefront-mcp

Когда использовать этот репозиторий вместо официального

Запускайте этот локальный MCP только в том случае, если вам нужно:

• Изучить рабочую эталонную реализацию MCP-сервера Bitrefill.

• Сделать форк для добавления пользовательских инструментов, промптов, валидации, логирования или маршрутизации.

• Разместить его в частной сети или изолированной среде (air-gapped).

• Поэкспериментировать с более широким набором эндпоинтов v2 (этот пример предоставляет 18 инструментов, в то время как официальный удаленный MCP намеренно предоставляет ограниченный набор из 7; см. eCommerce MCP).

Для повседневных задач типа «купить подарочные карты / eSIM через ИИ-ассистента» отдавайте предпочтение хостинговому серверу, указанному выше.

Конфигурация

1. Создайте API-ключ: Аккаунт Bitrefill → Разработчикам.

2. Установите его в переменные окружения (или в .env для локального запуска):

BITREFILL_API_KEY=your_api_key_here

Если BITREFILL_API_KEY отсутствует, инструменты не будут зарегистрированы (v2 требует аутентификации даже для ping).

Инструменты (v1.0.0)

Критическое изменение по сравнению с 0.x: старые имена инструментов в формате snake_case (search, create_invoice, unseal_order и т.д.) были удалены. Используйте имена, указанные выше. В v2 нет unseal_order; GET /orders/{id} возвращает redemption_info после доставки.

Ресурсы

• bitrefill://payment-methods: допустимые строки payment_method для buy-products / create-esim-invoice

• bitrefill://category-slugs: значения запроса category (B2B) для списка/поиска товаров

• bitrefill://product-types: ключи семейств продуктов

• bitrefill://product-types/{productType}: слаги категорий для каждого семейства

Структура проекта

src/
  index.ts
  types/api.ts          # Optional TS shapes for API JSON (not validated at runtime)
  constants/            # payment_method list, category slugs
  handlers/             # resources.ts, tools.ts
  schemas/              # Zod: inputs only
  services/             # API calls (search, products, invoices, orders, esims, misc)
  utils/api/            # base (BitrefillApiError), authenticated (Bearer v2)

Разработка

pnpm install
pnpm run build
pnpm run typecheck
pnpm run lint

Дымовые тесты (только для MCP из этого репозитория)

Дымовые тесты всегда запускают сервер этого пакета (node build/index.js после pnpm run build). Они не открывают https://api.bitrefill.com/mcp или любой другой удаленный URL MCP.

Рекомендуется: MCP-клиент внутри процесса (stdio к build/index.js):

pnpm run build
pnpm run smoke

То же самое, что pnpm run test-services (алиас).

Опционально: CLI MCP Inspector, также только против этого сервера:

pnpm run build
pnpm run smoke:inspector

Все 18 инструментов (Inspector CLI, строки сводки, фиктивные ID для примера):

pnpm run test:inspector:all-tools

Inspector использует --tool-arg key=value (повторять для нескольких ключей), а не один JSON-блок. Для вложенных данных используйте JSON в значении, например: --tool-arg 'products=[{"product_id":"x","value":10}]'.

Интерактивный UI (только для локального сервера):

pnpm run build
pnpm run inspector

Примеры:

pnpm dlx @modelcontextprotocol/inspector node build/index.js --cli --method tools/call --tool-name ping
pnpm dlx @modelcontextprotocol/inspector node build/index.js --cli --method tools/call --tool-name product-details --tool-arg id=test-gift-card-code

Примеры для клиентов (самостоятельно размещенный пример)

Напоминание: для продакшена отдавайте предпочтение хостинговому https://api.bitrefill.com/mcp (OAuth), а не конфигурации stdio ниже.

Конфигурация MCP в стиле Cursor / Claude, передайте ключ в env:

{
  "mcpServers": {
    "bitrefill": {
      "command": "npx",
      "args": ["-y", "bitrefill-mcp-server"],
      "env": {
        "BITREFILL_API_KEY": "your_api_key_here"
      }
    }
  }
}

Docker, например -e BITREFILL_API_KEY=... или --env-file .env.

Хостинговый удаленный MCP (установка не требуется, рекомендуется):

{
  "mcpServers": {
    "bitrefill": {
      "url": "https://api.bitrefill.com/mcp"
    }
  }
}

Документация

• Документация Bitrefill (индекс llms)

• Bitrefill eCommerce MCP (хостинг): официальный удаленный сервер, рекомендуется для продакшена

• Руководства по настройке: ChatGPT, Claude, Cursor

Лицензия

MIT