Bitrefill

Bitrefill MCP-сервер (пример реализации)

Это пример / эталонная реализация. Для промышленного использования подключайтесь к официальному хостируемому 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 (рекомендуется для production)

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.

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

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

• Изучить работающую эталонную реализацию Bitrefill MCP-сервера.
• Сделать форк для добавления собственных инструментов, подсказок, валидации, логирования или маршрутизации.
• Разместить у себя в частной сети или изолированной среде.
• Экспериментировать с более широким набором конечных точек v2 (этот пример предоставляет 18 инструментов, в то время как официальный удаленный MCP намеренно предоставляет ограниченный набор из 7; см. eCommerce MCP).

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

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

1. Создайте API-ключ: Bitrefill аккаунт → Разработчики.
2. Установите в переменных окружения (или .env для локальных запусков):

BITREFILL_API_KEY=your_api_key_here

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

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

Инструмент	API
search-products	GET /products/search (с q) или GET /products (просмотр)
product-details	GET /products/{id}
buy-products	POST /invoices
get-invoice-by-id	GET /invoices/{id}
get-order-by-id	GET /orders/{id}
list-invoices	GET /invoices
list-orders	GET /orders
pay-invoice	POST /invoices/{id}/pay
get-account-balance	GET /accounts/balance
check-phone-number	GET /check_phone_number
ping	GET /ping
list-esim-products	GET /products/esims
get-esim-product	GET /products/esims/{id}
create-esim-invoice	POST /esims
get-esim-invoice	GET /esims/invoice/{id}
pay-esim-invoice	POST /esims/invoice/{id}/pay
list-esims	GET /esims
get-esim	GET /esims/{id}

Критическое изменение по сравнению с 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: значения B2B category запроса для списка/поиска продуктов
• bitrefill://product-types: ключи семейств продуктов
• bitrefill://product-types/{productType}: slugs категорий для каждого семейства

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

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

Smoke-тесты (только для MCP этого репозитория)

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

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

pnpm run build
pnpm run smoke

То же, что и pnpm run test-services (псевдоним).

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

pnpm run build
pnpm run smoke:inspector

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

pnpm run test:inspector:all-tools

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

Интерактивный интерфейс (только локальный сервер):

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

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

Напоминание: для production предпочтительнее использовать размещенный 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 (размещенный): официальный удаленный сервер, рекомендуется для production
• Руководства по настройке: ChatGPT, Claude, Cursor

Лицензия

MIT