@openaisdk/billing-mcp 0.2.1 → 1.0.1

package/.env.example

@@ -0,0 +1,14 @@
+# Договор имён — как у @openaisdk/billing-sdk (без завершающего /)
+BILLING_API_URL=http://127.0.0.1:4001
+
+# Project-scoped integration key (Admin UI → Интеграция или вывод pnpm db:seed)
+BILLING_API_KEY=
+
+# UUID проекта: подставляется в инструменты, если projectId не передан в аргументах
+BILLING_PROJECT_ID=
+
+# UUID tenant — заголовок x-tenant-id (как в OpenAPI/SDK); опционально при M2M-ключе
+BILLING_HTTP_X_TENANT_ID=
+
+# Устаревшее имя base URL (читается, если BILLING_API_URL не задан)
+# BILLING_API_BASE_URL=http://127.0.0.1:4001

package/README.md

@@ -1,20 +1,141 @@
-# @openaisdk/billing-mcp
+# `@openaisdk/billing-mcp` (billing-catalog MCP)
 
-MCP-сервер для **управления каталогом** в Billing API: проекты, **планы**, **цены** (REST `v1/projects/.../plans`, `.../prices`).
+[MCP](https://modelcontextprotocol.io/)‑сервер по 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/другом клиенте для работы с планами и ценами.
+
+---
+
+## Термины
+
+| Термин | Значение |
+|--------|----------|
+| **Tenant** | Изолированный арендатор платформы; определяется на стороне API по ключу. |
+| **Project** | Продукт/линейка внутри tenant; у него свой каталог. `projectId` — UUID. |
+| **Plan** | Тарифный план (код уникален в рамках project). |
+| **Price** | Цена для плана (интервал `month` / `year`, сумма в минорных единицах). |
+| **Feature** | Возможность или лимит (`boolean` / `limit`). |
+| **Plan-feature** | Привязка фичи к плану с флагом и/или лимитом. |
+| **Project-scoped API key** | Ключ M2M из Admin UI → Интеграция; даёт доступ только к данным своего project (см. ADR-010). |
+
+---
+
+## 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 (потребители вне монорепозитория)
+
+```bash
+pnpm add -g @openaisdk/billing-mcp@latest
+# или без глобальной установки — см. npx ниже
+```
+
+### Из монорепозитория `saas-billing`
+
+```bash
+pnpm install
+pnpm --filter @openaisdk/billing-mcp run build
+```
+
+Запуск собранного сервера:
+
+```bash
+node packages/billing-catalog-mcp/dist/index.js
+```
+
+Локальная отладка без сборки:
+
+```bash
+pnpm --filter @openaisdk/billing-mcp run dev
+```
+
+---
 
 ## Переменные окружения
 
+Сервер подгружает `.env` из **текущей рабочей директории** процесса (`dotenv/config`). В Cursor обычно задают `env` в конфиге MCP или `cwd` на корень проекта, где лежит `.env`.
+
 | Переменная | Обязательно | Описание |
 |------------|-------------|----------|
-| `BILLING_API_KEY` | да | Project-scoped integration key (получить через Admin UI → Integration) |
-| `BILLING_PROJECT_ID` | да | UUID проекта (Admin UI → Settings или `pnpm db:seed` output) |
-| `BILLING_API_BASE_URL` | нет | По умолчанию `http://127.0.0.1:4001` |
+| `BILLING_API_KEY` | **Да** | Project-scoped integration key (Bearer). Без него процесс завершится при старте. |
+| `BILLING_API_URL` | Нет | Base URL Billing API **без** завершающего `/`. По умолчанию `http://127.0.0.1:4001`. |
+| `BILLING_PROJECT_ID` | Нет | UUID проекта: подставляется, если в аргументе инструмента не передан `projectId`. |
+| `BILLING_HTTP_X_TENANT_ID` | Нет | UUID tenant → заголовок `x-tenant-id` (согласовано с SDK / OpenAPI). |
 
-Ключ передаётся как `Authorization: Bearer <key>`. `BILLING_TENANT_ID` / `DEV_TENANT_ID` больше не нужны.
+Устаревший алиас: `BILLING_API_BASE_URL` (используется только если `BILLING_API_URL` пуст).
 
-## Cursor
+**Безопасность:** не коммитьте ключи. Для CI используйте секреты окружения.
 
-В `.cursor/mcp.json` добавьте сервер (после `pnpm install` и `pnpm --filter @openaisdk/billing-mcp run build`):
+Источник истины по именам — `.env.example` в каталоге пакета и `@openaisdk/billing-sdk` (те же четыре переменные).
+
+---
+
+## Подключение MCP-клиента (пример Cursor)
+
+Файл настроек: `.cursor/mcp.json` (или аналог в вашем клиенте).
+
+### Вариант A: `npx` (после публикации пакета)
+
+```json
+{
+  "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: сборка из клонированного репозитория
 
 ```json
 {
@@ -24,41 +145,102 @@ MCP-сервер для **управления каталогом** в Billing A
       "args": ["packages/billing-catalog-mcp/dist/index.js"],
       "cwd": "${workspaceFolder}",
       "env": {
-        "BILLING_API_BASE_URL": "http://127.0.0.1:4001",
-        "BILLING_API_KEY": "<project-scoped integration key>",
-        "BILLING_PROJECT_ID": "<project-uuid>"
+        "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>"
       }
     }
   }
 }
 ```
 
-Для разработки без сборки можно `tsx`:
+После изменения конфигурации перезапустите MCP в клиенте (в Cursor: Settings → MCP → Restart).
 
-```json
-"command": "pnpm",
-"args": ["exec", "tsx", "packages/billing-catalog-mcp/index.ts"],
-"cwd": "${workspaceFolder}"
-```
+**Локальный быстрый старт credentials:** `pnpm db:seed` — в консоли появятся в том числе project UUID и API key; подставьте их в `env` и используйте UUID как `projectId` в инструментах.
+
+Дополнительно по нескольким MCP-серверам репозитория: [docs/mcp-integration-guide.md](../../docs/mcp-integration-guide.md).
+
+---
 
 ## Инструменты (tools)
 
-- `billing_list_projects` — проекты тенанта
-- `billing_list_plans` / `billing_get_plan` / `billing_create_plan` / `billing_update_plan`
-- `billing_list_prices` / `billing_get_price` / `billing_create_price` / `billing_update_price`
+Ответы приходят как **JSON-текст** в content MCP. При ошибке HTTP или валидации клиент получит сообщение с префиксом `Error: ...`.
 
-`billing_create_price`: укажите `planId` **или** `planCode` (например `team`), плюс `code`, `amountMinor` (копейки), `interval` (`month` | `year`).
+### Проекты
 
-## Сборка
+| Tool | Назначение |
+|------|------------|
+| `billing_list_projects` | `GET /v1/projects` — проекты tenant’а, доступные ключу. Аргументов нет. |
 
-```bash
-pnpm --filter @openaisdk/billing-mcp run build
-```
+### Планы
 
-## Локальный запуск (проверка)
+| Tool | Назначение |
+|------|------------|
+| `billing_list_plans` | Список планов. Нужен `projectId`. |
+| `billing_get_plan` | План по ID: `projectId`, `planId`. |
+| `billing_create_plan` | Создание: `projectId`, `code`, `name`; опционально `description`, `isPublic`, `isActive`, `sortOrder`. |
+| `billing_update_plan` | PATCH: `projectId`, `planId`; поля плана кроме `code`. |
 
-```bash
-BILLING_API_KEY=<key> BILLING_PROJECT_ID=<uuid> pnpm --filter @openaisdk/billing-mcp run dev
-```
+### Цены
+
+| Tool | Назначение |
+|------|------------|
+| `billing_list_prices` | Список цен проекта. |
+| `billing_get_price` | Цена по ID: `projectId`, `priceId`. |
+| `billing_create_price` | Создание: `projectId`, `code`, `amountMinor`, `interval` (`month` \| `year`). Нужен **`planId` или `planCode`**. Опционально: `currency` (по умолчанию `RUB`), `intervalCount`, `trialDays`, `isActive`. |
+| `billing_update_price` | PATCH: `projectId`, `priceId`. Поля: `code`, `amountMinor`, `currency`, `interval`, `intervalCount`, `trialDays`, `isActive`. План сменить нельзя. |
+
+### Фичи и plan-features
+
+| Tool | Назначение |
+|------|------------|
+| `billing_list_features` | Список фич проекта. |
+| `billing_create_feature` | Создать фичу: `projectId`, `code`, `name`, `kind` (`boolean` \| `limit`). |
+| `billing_list_plan_features` | Привязки фич к плану. Нужны `projectId` и **`planId` или `planCode`**. |
+| `billing_create_plan_feature` | Привязать фичу к плану: `projectId`, `featureId`, плюс **`planId` или `planCode`**. Для лимитов: `limitValue` (для безлимита — `null` в JSON аргумента); для boolean — `enabled`. |
+
+### Разработка и сиды MegaRetro
+
+| Tool | Назначение |
+|------|------------|
+| `billing_reset_project_catalog` | `POST /v1/dev/projects/:projectId/reset-catalog` — жёсткий сброс каталога и связанных billing-сущностей проекта. На стороне API действует **DevOnlyGuard**: в **production** недоступно. Не удаляет customer accounts и сам project. |
+| `billing_reset_and_seed_megaretro_catalog` | Сброс проекта (как выше), затем полный сид каталога MegaRetro (планы, цены, trial, фичи, add-on и т.д. по внутреннему канону репозитория). |
+| `billing_upsert_megaretro_features_and_limits` | Без сброса: идемпотентно создаёт недостающие фичи и привязки для планов free/team/business/enterprise. |
+
+Инструменты с «MegaRetro» в названии заточены под **пилотный каталог** первого consumer’а; для других продуктов используйте обычные CRUD-инструменты.
+
+---
+
+## Ошибки и ограничения
+
+- **Нет ключа:** при старте — ошибка с текстом про `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](../../docs/mcp-integration-guide.md) — обзор MCP в репозитории и auth после ADR-010.
+- [ADR-010: Project-scoped Integration Auth](../../docs/adr/ADR-010-project-scoped-integration-auth.md).
+- [Consumer integration guide](../../docs/consumer-integration-guide.md) — M2M-интеграция приложений (шире, чем MCP).
+- Публичные контракты API: [docs/api/public-api-v1.md](../../docs/api/public-api-v1.md), [docs/api/admin-api.md](../../docs/api/admin-api.md) (актуальные пути уточняйте по OpenAPI/Swagger вашего стенда).
+
+---
+
+## Лицензия
 
-Stdio ждёт MCP-клиент; для ручной проверки используйте Cursor или тестовый MCP-клиент.
+MIT (см. `package.json`).

package/dist/index.js

@@ -8,17 +8,22 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { seedMegaretroCatalog as runMegaretroCatalogSeed, upsertMegaretroFeaturesAndLimits, } from './megaretro-catalog-seed.js';
 function getBaseUrl() {
-    return (process.env.BILLING_API_BASE_URL ?? 'http://127.0.0.1:4001').replace(/\/$/, '');
+    const raw = process.env.BILLING_API_URL?.trim() ||
+        process.env.BILLING_API_BASE_URL?.trim() ||
+        'http://127.0.0.1:4001';
+    return raw.replace(/\/$/, '');
 }
 function buildHeaders(extra) {
     const h = { ...extra };
-    // Auth: project-scoped integration key (ADR-010).
-    // Tenant и project резолвятся из ключа на стороне API — x-tenant-id не нужен.
     const key = process.env.BILLING_API_KEY?.trim();
     if (!key) {
         throw new Error('Задайте BILLING_API_KEY в .env / env MCP (project-scoped integration key, создаётся в Admin UI → Интеграция)');
     }
     h['Authorization'] = `Bearer ${key}`;
+    const tenantId = process.env.BILLING_HTTP_X_TENANT_ID?.trim();
+    if (tenantId) {
+        h['x-tenant-id'] = tenantId;
+    }
     return h;
 }
 async function billingFetch(path, init = {}) {
@@ -64,6 +69,32 @@ async function resolvePlanIdFromArgs(projectId, args) {
     }
     return planId;
 }
+/** Согласовано с @openaisdk/billing-sdk: BILLING_PROJECT_ID в env подставляется, если аргумент пустой. */
+const SCHEMA_PROJECT_ID = {
+    type: 'string',
+    description: 'UUID проекта. Если не передан — используется BILLING_PROJECT_ID из окружения (как в billing-sdk).',
+};
+function mergeDefaultProjectId(toolName, raw) {
+    if (toolName === 'billing_list_projects') {
+        return { ...raw };
+    }
+    const pid = raw.projectId;
+    if (pid != null && String(pid).trim() !== '') {
+        return { ...raw };
+    }
+    const envPid = process.env.BILLING_PROJECT_ID?.trim();
+    if (envPid) {
+        return { ...raw, projectId: envPid };
+    }
+    return { ...raw };
+}
+function requireProjectId(args) {
+    const p = args.projectId;
+    if (p != null && String(p).trim() !== '') {
+        return String(p);
+    }
+    throw new Error('Укажите projectId в аргументах инструмента или задайте BILLING_PROJECT_ID в окружении (те же имена переменных, что у @openaisdk/billing-sdk).');
+}
 const tools = [
     {
         name: 'billing_list_projects',
@@ -76,9 +107,9 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                projectId: { type: 'string', description: 'UUID проекта' },
+                projectId: SCHEMA_PROJECT_ID,
             },
-            required: ['projectId'],
+            required: [],
         },
     },
     {
@@ -87,10 +118,10 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                projectId: { type: 'string' },
+                projectId: SCHEMA_PROJECT_ID,
                 planId: { type: 'string' },
             },
-            required: ['projectId', 'planId'],
+            required: ['planId'],
         },
     },
     {
@@ -99,7 +130,7 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                projectId: { type: 'string' },
+                projectId: SCHEMA_PROJECT_ID,
                 code: { type: 'string', description: 'slug, напр. team, business' },
                 name: { type: 'string' },
                 description: { type: 'string', description: 'опционально' },
@@ -107,7 +138,7 @@ const tools = [
                 isActive: { type: 'boolean', description: 'по умолчанию true' },
                 sortOrder: { type: 'number', description: 'по умолчанию 0' },
             },
-            required: ['projectId', 'code', 'name'],
+            required: ['code', 'name'],
         },
     },
     {
@@ -116,7 +147,7 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                projectId: { type: 'string' },
+                projectId: SCHEMA_PROJECT_ID,
                 planId: { type: 'string' },
                 name: { type: 'string' },
                 description: { type: 'string' },
@@ -124,7 +155,7 @@ const tools = [
                 isActive: { type: 'boolean' },
                 sortOrder: { type: 'number' },
             },
-            required: ['projectId', 'planId'],
+            required: ['planId'],
         },
     },
     {
@@ -133,9 +164,9 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                projectId: { type: 'string' },
+                projectId: SCHEMA_PROJECT_ID,
             },
-            required: ['projectId'],
+            required: [],
         },
     },
     {
@@ -144,10 +175,10 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                projectId: { type: 'string' },
+                projectId: SCHEMA_PROJECT_ID,
                 priceId: { type: 'string' },
             },
-            required: ['projectId', 'priceId'],
+            required: ['priceId'],
         },
     },
     {
@@ -156,7 +187,7 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                projectId: { type: 'string' },
+                projectId: SCHEMA_PROJECT_ID,
                 planId: { type: 'string', description: 'UUID плана (если нет planCode)' },
                 planCode: { type: 'string', description: 'код плана, напр. team' },
                 code: { type: 'string', description: 'уникальный код цены в проекте, напр. team_monthly' },
@@ -167,7 +198,7 @@ const tools = [
                 trialDays: { type: 'number' },
                 isActive: { type: 'boolean', description: 'по умолчанию true' },
             },
-            required: ['projectId', 'code', 'amountMinor', 'interval'],
+            required: ['code', 'amountMinor', 'interval'],
         },
     },
     {
@@ -176,7 +207,7 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                projectId: { type: 'string' },
+                projectId: SCHEMA_PROJECT_ID,
                 priceId: { type: 'string' },
                 code: { type: 'string' },
                 amountMinor: { type: 'number' },
@@ -186,7 +217,7 @@ const tools = [
                 trialDays: { type: 'number' },
                 isActive: { type: 'boolean' },
             },
-            required: ['projectId', 'priceId'],
+            required: ['priceId'],
         },
     },
     {
@@ -195,9 +226,9 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                projectId: { type: 'string', description: 'UUID проекта (напр. megaretro)' },
+                projectId: SCHEMA_PROJECT_ID,
             },
-            required: ['projectId'],
+            required: [],
         },
     },
     {
@@ -206,9 +237,9 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                projectId: { type: 'string', description: 'UUID проекта megaretro' },
+                projectId: SCHEMA_PROJECT_ID,
             },
-            required: ['projectId'],
+            required: [],
         },
     },
     {
@@ -217,9 +248,9 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                projectId: { type: 'string', description: 'UUID проекта' },
+                projectId: SCHEMA_PROJECT_ID,
             },
-            required: ['projectId'],
+            required: [],
         },
     },
     {
@@ -227,8 +258,8 @@ const tools = [
         description: 'Список фич проекта (GET /v1/projects/:id/features)',
         inputSchema: {
             type: 'object',
-            properties: { projectId: { type: 'string' } },
-            required: ['projectId'],
+            properties: { projectId: SCHEMA_PROJECT_ID },
+            required: [],
         },
     },
     {
@@ -237,12 +268,12 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                projectId: { type: 'string' },
+                projectId: SCHEMA_PROJECT_ID,
                 code: { type: 'string' },
                 name: { type: 'string' },
                 kind: { type: 'string', enum: ['boolean', 'limit'] },
             },
-            required: ['projectId', 'code', 'name', 'kind'],
+            required: ['code', 'name', 'kind'],
         },
     },
     {
@@ -251,11 +282,11 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                projectId: { type: 'string' },
+                projectId: SCHEMA_PROJECT_ID,
                 planId: { type: 'string' },
                 planCode: { type: 'string', description: 'напр. team, business' },
             },
-            required: ['projectId'],
+            required: [],
         },
     },
     {
@@ -264,7 +295,7 @@ const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                projectId: { type: 'string' },
+                projectId: SCHEMA_PROJECT_ID,
                 planId: { type: 'string' },
                 planCode: { type: 'string' },
                 featureId: { type: 'string' },
@@ -274,7 +305,7 @@ const tools = [
                     description: 'для kind=limit; для безлимита передайте null через сырой JSON аргумента',
                 },
             },
-            required: ['projectId', 'featureId'],
+            required: ['featureId'],
         },
     },
 ];
@@ -290,33 +321,35 @@ function pickBody(args, keys) {
     }
     return out;
 }
-async function handleTool(name, args) {
+async function handleTool(name, rawArgs) {
+    const args = mergeDefaultProjectId(name, rawArgs);
     switch (name) {
         case 'billing_list_projects':
             return billingFetch('/v1/projects');
         case 'billing_list_plans':
-            return billingFetch(`/v1/projects/${args.projectId}/plans`);
+            return billingFetch(`/v1/projects/${requireProjectId(args)}/plans`);
         case 'billing_get_plan':
-            return billingFetch(`/v1/projects/${args.projectId}/plans/${args.planId}`);
+            return billingFetch(`/v1/projects/${requireProjectId(args)}/plans/${args.planId}`);
         case 'billing_create_plan':
-            return billingFetch(`/v1/projects/${args.projectId}/plans`, {
+            return billingFetch(`/v1/projects/${requireProjectId(args)}/plans`, {
                 method: 'POST',
                 body: JSON.stringify(pickBody(args, ['code', 'name', 'description', 'isPublic', 'isActive', 'sortOrder'])),
             });
         case 'billing_update_plan':
-            return billingFetch(`/v1/projects/${args.projectId}/plans/${args.planId}`, {
+            return billingFetch(`/v1/projects/${requireProjectId(args)}/plans/${args.planId}`, {
                 method: 'PATCH',
                 body: JSON.stringify(pickBody(args, ['name', 'description', 'isPublic', 'isActive', 'sortOrder'])),
             });
         case 'billing_list_prices':
-            return billingFetch(`/v1/projects/${args.projectId}/prices`);
+            return billingFetch(`/v1/projects/${requireProjectId(args)}/prices`);
         case 'billing_get_price':
-            return billingFetch(`/v1/projects/${args.projectId}/prices/${args.priceId}`);
+            return billingFetch(`/v1/projects/${requireProjectId(args)}/prices/${args.priceId}`);
         case 'billing_create_price': {
+            const projectId = requireProjectId(args);
             let planId = args.planId;
             const planCode = args.planCode;
             if (!planId && planCode) {
-                planId = await resolvePlanId(String(args.projectId), planCode);
+                planId = await resolvePlanId(projectId, planCode);
             }
             if (!planId) {
                 throw new Error('Укажите planId или planCode');
@@ -331,13 +364,13 @@ async function handleTool(name, args) {
                 trialDays: args.trialDays,
                 isActive: args.isActive ?? true,
             };
-            return billingFetch(`/v1/projects/${args.projectId}/prices`, {
+            return billingFetch(`/v1/projects/${projectId}/prices`, {
                 method: 'POST',
                 body: JSON.stringify(body),
             });
         }
         case 'billing_update_price':
-            return billingFetch(`/v1/projects/${args.projectId}/prices/${args.priceId}`, {
+            return billingFetch(`/v1/projects/${requireProjectId(args)}/prices/${args.priceId}`, {
                 method: 'PATCH',
                 body: JSON.stringify(pickBody(args, [
                     'code',
@@ -350,26 +383,28 @@ async function handleTool(name, args) {
                 ])),
             });
         case 'billing_reset_project_catalog':
-            return billingFetch(`/v1/dev/projects/${args.projectId}/reset-catalog`, {
+            return billingFetch(`/v1/dev/projects/${requireProjectId(args)}/reset-catalog`, {
                 method: 'POST',
             });
         case 'billing_reset_and_seed_megaretro_catalog':
-            return seedMegaretroCatalog(String(args.projectId));
+            return seedMegaretroCatalog(requireProjectId(args));
         case 'billing_upsert_megaretro_features_and_limits':
-            return upsertMegaretroFeaturesAndLimits(billingFetch, String(args.projectId));
+            return upsertMegaretroFeaturesAndLimits(billingFetch, requireProjectId(args));
         case 'billing_list_features':
-            return billingFetch(`/v1/projects/${args.projectId}/features`);
+            return billingFetch(`/v1/projects/${requireProjectId(args)}/features`);
         case 'billing_create_feature':
-            return billingFetch(`/v1/projects/${args.projectId}/features`, {
+            return billingFetch(`/v1/projects/${requireProjectId(args)}/features`, {
                 method: 'POST',
                 body: JSON.stringify(pickBody(args, ['code', 'name', 'kind'])),
             });
         case 'billing_list_plan_features': {
-            const planId = await resolvePlanIdFromArgs(String(args.projectId), args);
-            return billingFetch(`/v1/projects/${args.projectId}/plans/${planId}/plan-features`);
+            const projectId = requireProjectId(args);
+            const planId = await resolvePlanIdFromArgs(projectId, args);
+            return billingFetch(`/v1/projects/${projectId}/plans/${planId}/plan-features`);
         }
         case 'billing_create_plan_feature': {
-            const planId = await resolvePlanIdFromArgs(String(args.projectId), args);
+            const projectId = requireProjectId(args);
+            const planId = await resolvePlanIdFromArgs(projectId, args);
             const body = { featureId: args.featureId };
             if (args.enabled !== undefined) {
                 body.enabled = args.enabled;
@@ -377,7 +412,7 @@ async function handleTool(name, args) {
             if (Object.prototype.hasOwnProperty.call(args, 'limitValue')) {
                 body.limitValue = args.limitValue;
             }
-            return billingFetch(`/v1/projects/${args.projectId}/plans/${planId}/plan-features`, {
+            return billingFetch(`/v1/projects/${projectId}/plans/${planId}/plan-features`, {
                 method: 'POST',
                 body: JSON.stringify(body),
             });
@@ -410,7 +445,7 @@ async function main() {
     buildHeaders();
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error('Billing Catalog MCP on stdio (project-scoped key configured)');
+    console.error('Billing Catalog MCP on stdio (BILLING_API_KEY; base URL BILLING_API_URL; optional BILLING_PROJECT_ID, BILLING_HTTP_X_TENANT_ID)');
 }
 main().catch((e) => {
     console.error(e);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openaisdk/billing-mcp",
-  "version": "0.2.1",
+  "version": "1.0.1",
   "description": "MCP server: управление планами и ценами Billing API (catalog)",
   "type": "module",
   "main": "dist/index.js",
@@ -8,7 +8,9 @@
     "billing-catalog-mcp": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    ".env.example"
   ],
   "publishConfig": {
     "access": "public"