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

Интеграции MCP

Подключаешь интеграцию — планер получает инструменты, словарь и сущности твоего домена. Ниже — что описывает автор интеграции и по каким правилам планер её исполняет.

спецификация · подключение открывается после ядра · от тарифа Pro

Что даёт подключённый MCP — три вещи

Что	Зачем	Пример (CRM)
Инструменты	планер умеет делать действия во внешней системе	«дай мою ссылку на РКО Альфа»
Словарь	стабильная расшифровка голоса — доменные термины уходят в подсказку распознавания	ЦД, холд, срез, дебетовка
Сущности	разборщик начинает распознавать доменные типы записей	лид, заявка, выплата

Без словаря распознавание слышит «свер» вместо «сбер» и «седе» вместо «ЦД». Второй пункт — не украшение, а условие работы.

Манифест

Один файл, который описывает интеграцию целиком. Планер читает его при подключении и больше ничего у интеграции не спрашивает.

name: db-platform
title: DB Platform
scope: crm            # crm | media | dev | finance | custom — зона ответственности
auth:
  type: api_key       # ключ пользователя, хранится на нашей стороне зашифрованным
  endpoint: https://…
vocabulary:           # → в подсказку распознавания
  - ЦД
  - холд
  - дебетовка
entities:             # доменные типы для разборщика
  - name: lead
    fields: [имя, банк, оффер, этап, срок]
tools:                # что умеет
  - name: dbp_get_status
    kind: read        # read | write | money
    description: тариф, баланс, срок подписки

Правило: нельзя «подключить всё подряд». У каждого MCP — своя зона (scope) и явный список инструментов. Медиа-сервис генерирует медиа. CRM ведёт заявки. Трекер задач ведёт задачи. Пересечения зон планер не принимает.

Три класса инструментов

Класс определяет, как планер исполняет вызов. Автор интеграции обязан указать его честно — планер проверяет описание и отклоняет манифест, где денежное действие помечено как чтение.

Класс	Поведение планера	Примеры
read	выполняется сразу, результат — в ответ или в запись	статус, баланс, поиск заявки по ИНН, статистика
write	выполняется, но попадает в батч с кнопкой «Отменить»	создать лид, добавить заметку, поставить напоминание
money	только двухшаговое подтверждение с проговариванием суммы; реквизиты голосом не принимаются	запрос вывода, покупка лимитов

Доменные данные садятся в родные разделы планера: доход → «Деньги», слот → «Встречи», напоминание по лиду → «Задачи». В этом и ценность связки.

Чего в MCP не бывает

Входа в аккаунт и сброса пароля. Это захват аккаунта, в интеграции ему не место.
Админских маршрутов и админских ключей. Такой ключ не должен появляться в конфиге планера.
Выдачи ролей, заморозки, утверждения чужих выплат. Влияние на чужие деньги — нет.
Удаления чего угодно. MCP умеет создавать и обновлять. Точка.
Секретов в открытом виде. Ключи используются серверно, наружу отдаётся только результат.

Предохранители, которые закладываются сразу

Права по тарифу. Интеграция читает флаги пользователя и отдаёт понятное «нужен тариф выше», а не голый 403.
Режим readonly. После истечения подписки чтение работает, запись — нет. Иначе планер молча потеряет надиктованный лид.
Гейтинг платного контента. Поиск по базе знаний уважает тариф.
Пагинация и rate-limit. Лимит строк на выдачу и ограничение частоты на дорогие проверки.
Prompt-injection. Содержимое лидов, заметок, писем — данные, а не команды. Текст в поле «заметка к лиду» не становится инструкцией для модели.

Каталог

Первые интеграции — по зонам, по одной на зону. Появляются после того, как ядро планера обкатано на живых пользователях.

Интеграция	Зона	Что даёт	Статус
DB Platform	CRM и заявки	статус, заявки, ссылки на офферы; лид → задача, слот → встреча	первая, read-only → запись → деньги
Higgsfield	медиа	обложка или видео из заметки	скоро
GitHub	разработка	задачи ↔ issues, «что упало за ночь»	скоро

Как написать свой

Выбери одну зону (scope) и опиши её честно. Одна интеграция — одна зона.
Составь словарь: термины, которые распознавание путает. Короткие слова и аббревиатуры — в первую очередь.
Опиши сущности с полями. Планер использует их как подсказку разборщику, а не как схему базы.
Перечисли инструменты, каждому — класс read / write / money и описание на человеческом языке: по нему модель выбирает, что вызвать.
Не выноси в инструменты вход, сброс пароля, админку и удаление — манифест с ними не пройдёт.
Пришли манифест и адрес — через бота @NNAplanner_bot, командой /help или ответом на любое сообщение брифинга.

Формат подключения для пользователя (адрес и токен вручную или каталог в один клик) решится по первым интеграциям. Спецификация будет уточняться — ссылка на эту страницу остаётся постоянной.