Brilliant Directories API — Универсальная интеграция с ИИ

npm version license MCP

Предоставьте любому ИИ-агенту полный доступ к вашему сайту на BD с помощью одного API-ключа.

170 эндпоинтов по 32 ресурсам: участники, лиды, публикации, отзывы, категории, шаблоны писем, страницы (главная, лендинги), 301 редиректы, смарт-списки, виджеты, меню, формы, тарифные планы и многое другое.

30-секундный быстрый старт

Одна команда. Ответ на два вопроса. Готово.

npx brilliant-directories-mcp --setup

Мастер запросит URL вашего сайта BD и API-ключ, проверит соединение, спросит, какое приложение вы используете (Cursor / Claude Desktop / Windsurf / Claude Code), и создаст конфигурацию за вас. Никакого редактирования JSON.

Перезапустите приложение, а затем спросите свой ИИ:

"List members on my BD site"

Получите API-ключ в разделе BD Admin > Developer Hub > Generate API Key.

Для ИИ-агентов / скриптов (неинтерактивно)

Если ИИ-агент направляет вас, он может попросить вставить одну команду с уже заполненными данными:

npx brilliant-directories-mcp --setup --url https://your-site.com --api-key YOUR_KEY --client cursor

Это выполнит полную настройку без дополнительных запросов. Замените cursor на claude-desktop, windsurf, claude-code или print (выведет JSON-конфигурацию вместо записи в файл).

Настройка по платформам

Claude Code / Cursor / Windsurf / Cline (MCP)

Вариант А — npx (рекомендуется, установка не требуется):

claude mcp add bd-api -- npx brilliant-directories-mcp --api-key YOUR_KEY --url https://your-site.com

Вариант Б — Глобальная установка:

npm install -g brilliant-directories-mcp
claude mcp add bd-api -- brilliant-directories-mcp --api-key YOUR_KEY --url https://your-site.com

Cursor / Windsurf / Cline — добавьте в ваш файл конфигурации MCP (~/.cursor/mcp.json и т.д.):

{
  "mcpServers": {
    "bd-api": {
      "command": "npx",
      "args": ["-y", "brilliant-directories-mcp", "--api-key", "YOUR_KEY", "--url", "https://your-site.com"]
    }
  }
}

Затем спросите свой ИИ: "List all members on my BD site" или "Create a new member with email john@example.com"

ChatGPT (GPT Actions)

В вашем GPT: Configure > Actions > Create new action

В разделе Schema выберите Import from URL и вставьте:

https://raw.githubusercontent.com/brilliantdirectories/brilliant-directories-mcp/main/openapi/bd-api.json

Когда появится запрос bd_site_url, введите URL вашего сайта BD (например, https://mysite.com)
Настройте аутентификацию: API Key, тип Auth: Custom, имя заголовка: X-Api-Key, вставьте ваш ключ

n8n

Вариант А — Импорт OpenAPI-спецификации (рекомендуется):

Импортируйте URL спецификации как пользовательское определение API:

https://raw.githubusercontent.com/brilliantdirectories/brilliant-directories-mcp/main/openapi/bd-api.json

n8n запросит URL вашего сайта BD и API-ключ при импорте. Редактирование файлов не требуется.

Вариант Б — Узел Plain HTTP Request:

Создайте новый рабочий процесс, добавьте узел HTTP Request
Установите:
- Метод: GET
- URL: https://your-site.com/api/v2/user/get
- Заголовок: X-Api-Key: YOUR_KEY

Make / Zapier

Make: Создайте пользовательское приложение, используя OpenAPI-спецификацию, или используйте HTTP-модуль с заголовком X-Api-Key.

Zapier: Если у вас уже есть приложение BD Zapier, оно использует тот же базовый API. Для новых эндпоинтов используйте Webhooks by Zapier с заголовком X-Api-Key.

curl / Любой HTTP-клиент

# Verify your API key
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/token/verify

# List members
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/user/get?limit=10

# Create a member
curl -X POST -H "X-Api-Key: YOUR_KEY" \
  -d "email=new@example.com&password=secret123&subscription_id=1&first_name=Jane&last_name=Doe" \
  https://your-site.com/api/v2/user/create

# Search members
curl -X POST -H "X-Api-Key: YOUR_KEY" \
  -d "q=dentist&address=Los Angeles&limit=10" \
  https://your-site.com/api/v2/user/search

# Update a member
curl -X PUT -H "X-Api-Key: YOUR_KEY" \
  -d "user_id=42&company=New Company Name" \
  https://your-site.com/api/v2/user/update

Устранение неполадок

Проверьте настройку одной командой:

npx brilliant-directories-mcp --verify --api-key YOUR_KEY --url https://your-site.com

Выведет OK, если учетные данные работают, или FAIL с ошибкой в противном случае. Хороший первый шаг при любых проблемах с подключением.

Режим отладки — посмотрите, что именно происходит:

npx brilliant-directories-mcp --debug --verify --api-key YOUR_KEY --url https://your-site.com

Логирует каждый API-запрос и ответ в stderr (ваш API-ключ автоматически скрывается), затем завершает работу. Полезно, когда что-то не работает и вы хотите поделиться выводом со службой поддержки BD.

Уберите --verify, чтобы запустить полноценный MCP stdio-сервер с отладочным логированием — в обычном терминале будет казаться, что он завис, так как MCP-серверы работают постоянно через stdio, ожидая подключения ИИ-клиента. Используйте --debug --verify для однократной отладки из оболочки.

Распространенные проблемы:

401 Unauthorized — API-ключ неверный, отозван или не имеет прав доступа к эндпоинту
404 Not Found — URL сайта неверный (проверьте опечатки; https:// добавляется автоматически, если отсутствует)
429 Too Many Requests — достигнут лимит запросов (по умолчанию 100 запросов/60 сек); подождите или увеличьте лимит в админ-панели BD
Unknown tool (от Claude) — MCP-сервер не загрузил OpenAPI-спецификацию; переустановите с помощью npm install -g brilliant-directories-mcp

Аутентификация

Все запросы требуют заголовок X-Api-Key:

X-Api-Key: your-api-key-here

API-ключи ограничены правами доступа — вы контролируете, к каким эндпоинтам может обращаться каждый ключ.

Лимиты запросов

По умолчанию: 100 запросов каждые 60 секунд на один API-ключ. По запросу: до 1 000 запросов в минуту — свяжитесь со службой поддержки Brilliant Directories, чтобы увеличить лимит вашего сайта (любое значение от 100 до 1000/мин).

Лимит устанавливается на стороне сервера BD, это не настраиваемая пользователем опция в админ-панели. Если вы ожидаете высокую нагрузку на API, напишите в поддержку BD перед массовыми операциями и попросите временное или постоянное увеличение.

При превышении лимита API возвращает HTTP 429 Too Many Requests. MCP-сервер передает это как ошибку, на которую может отреагировать ваш ИИ-агент — он будет знать, что нужно сделать паузу или порекомендовать запросить более высокий лимит.

Планирование массовых операций: если вы просите агента импортировать/обновить сотни записей, либо (а) сначала запросите более высокий лимит в поддержке BD, либо (б) скажите агенту работать в умеренном темпе (например, "import these 500 members, pausing to respect the 100/min rate limit").

Пагинация

Все эндпоинты списков поддерживают пагинацию:

Параметр	Описание
`limit`	Записей на страницу (по умолчанию 25, макс. 100)
`page`	Токен курсора из `next_page` в предыдущем ответе

Ответ включает: total, current_page, total_pages, next_page, prev_page

Фильтрация

Все эндпоинты списков поддерживают фильтрацию:

GET /api/v2/user/get?property=city&property_value=Los Angeles&property_operator==

Несколько фильтров:

GET /api/v2/user/get?property[]=city&property_value[]=Los Angeles&property[]=state_code&property_value[]=CA

Операторы: =, LIKE, >, <, >=, `<=

Сортировка

GET /api/v2/user/get?order_column=last_name&order_type=ASC

Доступные ресурсы

Ресурс	Базовый путь	Операции
Пользователи/Участники	`/api/v2/user/`	list, get, create, update, delete, search, login, transactions, subscriptions
Отзывы	`/api/v2/users_reviews/`	list, get, create, update, delete, search
Клики	`/api/v2/users_clicks/`	list, get, create, update, delete
Лиды	`/api/v2/leads/`	list, get, create, match, update, delete
Соответствия лидов	`/api/v2/lead_matches/`	list, get, create, update, delete
Публикации	`/api/v2/data_posts/`	list, get, create, update, delete, search, fields
Группы портфолио	`/api/v2/users_portfolio_groups/`	list, get, create, update, delete, search, fields
Фото портфолио	`/api/v2/users_portfolio/`	list, get, create, update, delete
Типы публикаций	`/api/v2/data_categories/`	list, get, create, update, delete, custom_fields
Категории	`/api/v2/category/`	list, get, create, update, delete
Группы категорий	`/api/v2/category_group/`	list, get, create, update, delete
Услуги	`/api/v2/list_services/`	list, get, create, update, delete
Услуги пользователя	`/api/v2/rel_services/`	list, get, create, update, delete
Фото пользователя	`/api/v2/users_photo/`	list, get, create, update, delete
Метаданные пользователя	`/api/v2/users_meta/`	list, get, create, update, delete
Теги	`/api/v2/tags/`	list, get, create, update, delete
Группы тегов	`/api/v2/tag_groups/`	list, get, create, update, delete
Типы тегов	`/api/v2/tag_types/`	list, get, create, update, delete
Связи тегов	`/api/v2/rel_tags/`	list, get, create, update, delete
Виджеты	`/api/v2/data_widgets/`	list, get, create, update, delete, render
Шаблоны писем	`/api/v2/email_templates/`	list, get, create, update, delete
Формы	`/api/v2/form/`	list, get, create, update, delete
Поля форм	`/api/v2/form_fields/`	list, get, create, update, delete
Тарифные планы	`/api/v2/subscription_types/`	list, get, create, update, delete
Меню	`/api/v2/menus/`	list, get, create, update, delete
Элементы меню	`/api/v2/menu_items/`	list, get, create, update, delete
Отписка	`/api/v2/unsubscribe_list/`	list, get, create, update, delete
Смарт-списки	`/api/v2/smart_lists/`	list, get, create, update, delete
Страницы (SEO/статичные)	`/api/v2/list_seo/`	list, get, create, update, delete
Редиректы (301)	`/api/v2/redirect_301/`	list, get, create, update, delete
Типы данных	`/api/v2/data_types/`	list, get, create, update, delete
Настройки сайта	`/api/v2/website_settings/`	refreshCache

Обнаружение полей

Некоторые эндпоинты поддерживают динамическое обнаружение полей:

# Get all available user fields
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/user/fields

# Get custom fields for a specific post type
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/data_posts/fields?form_name=my-form

Файлы

Файл	Назначение
`openapi/bd-api.json`	Спецификация OpenAPI 3.1 (единый источник истины)
`mcp/index.js`	MCP-сервер для Claude/Cursor
`mcp/package.json`	Определение npm-пакета
`docs/*.md`	Документация API-эндпоинтов
`LICENSE`	Лицензия MIT
`CHANGELOG.md`	История версий

Стабильные URL ресурсов

Для инструментов, импортирующих спецификации по URL (ChatGPT Actions, n8n, Postman):

https://raw.githubusercontent.com/brilliantdirectories/brilliant-directories-mcp/main/openapi/bd-api.json

Безопасность

API-ключи никогда не встраиваются в пакет
Все запросы идут напрямую с машины пользователя на их сайт BD
Никакие данные не проходят через сторонние серверы
Права доступа API-ключа контролируют, какие эндпоинты доступны
Относитесь к своему API-ключу как к паролю

Поддержка

Поддержка BD: https://support.brilliantdirectories.com
Документация API: https://support.brilliantdirectories.com/support/solutions/articles/12000108045

brilliant-directories-mcp