@openaisdk/billing-mcp (billing-catalog MCP)

MCP‑сервер по stdio для работы с каталогом Billing Platform через REST API: проекты, планы, цены, фичи и привязки фич к планам (plan-features). Подходит для Cursor, Claude Desktop и любых клиентов с поддержкой MCP.

Пакет в репозитории: packages/billing-catalog-mcp
Имя на npm: @openaisdk/billing-mcp
Бинарь: billing-catalog-mcp

Контекст и цель

В multi-tenant billing у tenant есть один или несколько projects. У каждого project свой каталог: plans, prices, features, entitlements (через подписки). Этот MCP не заменяет Admin UI и не обслуживает checkout — он даёт агентам и разработчикам программный доступ к каталогу того project, к которому привязан integration key.

Зачем использовать MCP: настройка демо-каталога, сценарии в IDE с ИИ, скриптоподобные операции без написания отдельного HTTP-клиента.

Аудитория

• Разработчики платформы и интеграторы, у которых уже есть доступ к Billing API.
• Команды, которые подключают MCP в Cursor/другом клиенте для работы с планами и ценами.

Термины

Scope: что делает сервер

Реализовано в коде:

• Чтение списка projects tenant’а (в рамках прав ключа).
• CRUD plans и prices для выбранного projectId.
• Список/создание features, список/создание plan-features.
• Вспомогательные инструменты для локальной разработки и пилотов: сброс каталога проекта (через dev-эндпоинт API), сид MegaRetro, идемпотентное обновление фич/лимитов MegaRetro.

Не входит в scope пакета:

• Подписки, инвойсы, customer accounts, checkout, webhooks (для этого — Billing API/SDK/Admin UI).
• Обход аутентификации без ключа: модель только Bearer project-scoped key (см. ниже).

Предпосылки

1. Развёрнутый Billing API (локально или удалённо).
2. Project-scoped integration key (BILLING_API_KEY): создаётся в Admin UI → Интеграция или выдаётся после pnpm db:seed в консоли (локальная разработка).
3. UUID project — в аргументах инструментов (projectId) или в переменной BILLING_PROJECT_ID (тот же договор, что у @openaisdk/billing-sdk).

Auth (ADR-010): Authorization: Bearer <BILLING_API_KEY>. Если задан BILLING_HTTP_X_TENANT_ID, в запросы добавляется заголовок x-tenant-id (как в OpenAPI/SDK). Tenant/project по-прежнему резолвятся из ключа на стороне API.

Установка

Из npm (потребители вне монорепозитория)

pnpm add -g @openaisdk/billing-mcp@latest
# или без глобальной установки — см. npx ниже

Из монорепозитория saas-billing

pnpm install
pnpm --filter @openaisdk/billing-mcp run build

Запуск собранного сервера:

node packages/billing-catalog-mcp/dist/index.js

Локальная отладка без сборки:

pnpm --filter @openaisdk/billing-mcp run dev

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

Сервер подгружает .env из текущей рабочей директории процесса (dotenv/config). В Cursor обычно задают env в конфиге MCP или cwd на корень проекта, где лежит .env.

Устаревший алиас: BILLING_API_BASE_URL (используется только если BILLING_API_URL пуст).

Безопасность: не коммитьте ключи. Для CI используйте секреты окружения.

Источник истины по именам — .env.example в каталоге пакета и @openaisdk/billing-sdk (те же четыре переменные).

Подключение MCP-клиента (пример Cursor)

Файл настроек: .cursor/mcp.json (или аналог в вашем клиенте).

Вариант A: npx (после публикации пакета)

{
  "mcpServers": {
    "billing-catalog": {
      "command": "npx",
      "args": ["-y", "@openaisdk/billing-mcp@latest"],
      "env": {
        "BILLING_API_URL": "http://127.0.0.1:4001",
        "BILLING_API_KEY": "<project-scoped-key>",
        "BILLING_PROJECT_ID": "<project-uuid>",
        "BILLING_HTTP_X_TENANT_ID": "<tenant-uuid>"
      }
    }
  }
}

Вариант B: сборка из клонированного репозитория

{
  "mcpServers": {
    "billing-catalog": {
      "command": "node",
      "args": ["packages/billing-catalog-mcp/dist/index.js"],
      "cwd": "${workspaceFolder}",
      "env": {
        "BILLING_API_URL": "http://127.0.0.1:4001",
        "BILLING_API_KEY": "<из вывода pnpm db:seed или Admin UI>",
        "BILLING_PROJECT_ID": "<из seed / Admin UI>",
        "BILLING_HTTP_X_TENANT_ID": "<из seed / Admin UI>"
      }
    }
  }
}

После изменения конфигурации перезапустите MCP в клиенте (в Cursor: Settings → MCP → Restart).

Локальный быстрый старт credentials: pnpm db:seed — в консоли появятся в том числе project UUID и API key; подставьте их в env и используйте UUID как projectId в инструментах.

Дополнительно по нескольким MCP-серверам репозитория: docs/mcp-integration-guide.md.

Инструменты (tools)

Ответы приходят как JSON-текст в content MCP. При ошибке HTTP или валидации клиент получит сообщение с префиксом Error: ....

Проекты

Планы

Цены

Фичи и plan-features

Разработка и сиды MegaRetro

Инструменты с «MegaRetro» в названии заточены под пилотный каталог первого consumer’а; для других продуктов используйте обычные CRUD-инструменты.

Сводка планов, цен, фич и привязок из сида (Markdown): docs/megaretro-catalog-seed.md.

Ошибки и ограничения

• Нет ключа: при старте — ошибка с текстом про BILLING_API_KEY.
• HTTP-ошибки API: возвращаются как Error: HTTP <status>: <body>.
• Dev reset: эндпоинт /v1/dev/... отключён в production-сборке API; не рассчитывайте на сброс в бою.
• Суммы: amountMinor — в минорных единицах (копейки для RUB).
• planCode: резолвится через список планов проекта; при опечатке будет ошибка «план не найден».

Верификация (чеклист)

• Billing API доступен по BILLING_API_URL (или дефолт localhost).
• BILLING_API_KEY — действующий project-scoped key; при необходимости заданы BILLING_PROJECT_ID / BILLING_HTTP_X_TENANT_ID.
• Вызов billing_list_projects возвращает JSON со списком проектов.
• Вызов billing_list_plans с правильным projectId возвращает планы (или пустой массив).
• После изменения mcp.json MCP перезапущен.

Ссылки

• MCP Integration Guide — обзор MCP в репозитории и auth после ADR-010.
• ADR-010: Project-scoped Integration Auth.
• Consumer integration guide — M2M-интеграция приложений (шире, чем MCP).
• Публичные контракты API: docs/api/public-api-v1.md, docs/api/admin-api.md (актуальные пути уточняйте по OpenAPI/Swagger вашего стенда).

Лицензия

MIT (см. package.json).