Подключение ИИ-ассистента через MCP

Подключение к BGModeller

Model Context Protocol (MCP) позволяет ассистенту вызывать инструменты BGModeller. Нужен клиент с поддержкой удалённых MCP-серверов через Streamable HTTP и подключение к интернету. Руководство можно читать офлайн; инструменты выполняются на публичном сервере.

Для больших динамических расчётов клиент также должен уметь программно принимать, сохранять и обрабатывать результаты в файлах. Одной поддержки MCP недостаточно. До запуска ассистент должен проверить эти возможности; если их нет, предупредить пользователя до вызова simulate_model. Подробнее — работа с большими результатами.

В настройках MCP вашего клиента добавьте удалённый сервер с этими параметрами. Включите его инструменты, при необходимости переподключитесь и попросите ассистента вызвать get_capabilities. URL предназначен для протокола: открытие адреса как обычной страницы в браузере не проверяет подключение.

Пример для Codex CLI

codex mcp add bgmodeller --url https://bgmodeller.mkefweb.com/mcp
codex mcp list

Если инструменты не появились, переподключитесь или начните новый сеанс. Способ подключения MCP в Codex описан в официальной документации OpenAI. В других клиентах используйте их интерфейс настроек, транспорт Streamable HTTP и тот же URL сервера.

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

Ниже приведены имена инструментов на сервере; клиент может добавлять к ним префикс. Все физические величины задаются в единицах СИ.

Чтение руководства и справочника блоков

Ассистент может читать руководство непосредственно через MCP, без отдельного инструмента браузера. Используйте известные идентификаторы тем и разделов для адресных вызовов get_documentation. Если идентификаторы неизвестны, вызовите list_documentation: он возвращает topics с названиями тем, их идентификаторами topic и массивами sections. У разделов блоков есть поле component; для примитивов также указана физическая область domain. Повторно используйте уже прочитанную документацию в рамках задачи.

Примеры вызовов инструментов для чтения описания гидроцилиндра:

list_documentation({"language":"ru"})
get_documentation({"topic":"cylinder","language":"ru"})
get_documentation({"topic":"cylinder","section":"block-CylinderDA","language":"ru"})

Первый вызов нужен только для поиска неизвестных идентификаторов; второй читает всю тему, третий — только раздел блока. Для английского используйте "language":"en" или не указывайте язык. Для сопротивления в гидравлике выберите "topic":"hydraulics","section":"block-R", а для механического демпфера — "topic":"mechanics","section":"block-R". Используйте известные или найденные идентификаторы, а не URL или путь к файлу.

В ответе data.content содержит текст, data.url — ссылку на исходную страницу или раздел, а data.links — связанные темы. Для перехода к связанной теме передайте её topic, language и, если есть, section в следующий вызов get_documentation. Не передавайте весь объект ссылки: title и url не являются аргументами инструмента.

Текст берётся из того же руководства, что открывается в браузере. Сохраняются уравнения, таблицы, подписи и текстовые описания схем; изображения не передаются. Если нужно рассмотреть рисунок, откройте data.url. Нижние и верхние индексы в тексте обозначаются как A_{A} и x^{2}.

Чтение документации не запускает расчёт и не требует токена задачи, но учитывается в общем ограничении частоты API-запросов. Если новые инструменты не появились после обновления сервера, переподключите MCP в клиенте. При ошибке 404 для темы или раздела заново получите список через list_documentation.

Пример: расчёт механической модели

После подключения попробуйте такой запрос:

1. Один раз прочитайте get_capabilities и get_library, затем get_example с {"name":"mechanical_two_mass"} и соответствующие описания механических блоков через get_documentation. Повторно используйте полученные сведения; вызывайте list_examples или list_documentation только для поиска неизвестных идентификаторов. Используйте структуру полученной модели, не подбирайте имена компонентов и портов наугад.
2. Вызовите validate_model с {"model": …}. Принятая задача возвращает http_status: 202 и объект data с job_id и job_token.
3. Вызывайте get_job с обоими значениями. Соблюдайте retry_after; иначе ожидайте 1, 2, 4, затем 8 секунд, сохраняя интервал 8 секунд при следующих опросах. При статусе completed вызовите get_result. Не публикуйте токен. Проверьте http_status, признак успеха, диагностику и причину завершения: завершённая задача не обязательно содержит успешный расчёт.
4. Возьмите data.model из успешного результата проверки. Передайте его в analyze_model, дождитесь выполнения и получите результат этой задачи. Исправьте ошибки топологии до симуляции: успешная проверка документа ещё не означает, что модель можно рассчитать.
5. Передайте проверенную модель в simulate_model, дождитесь выполнения и получите результат. До интерпретации рядов проверьте статус завершения, время и диагностику. Каждый запуск возвращает собственные идентификатор и токен задачи.

Ответы инструментов содержат http_status, retry_after и data. Ассистент должен сообщать статус и ошибки, сохранять файл модели вместе с результатами и показывать только необходимые выборки вместо полных численных массивов.

Большие динамические результаты: требования к клиенту

Динамический расчёт может вернуть большой набор временных рядов для множества элементов и переменных схемы. Поиск значений в нужные моменты времени, экстремумов и событий требует программной обработки; полный JSON в контексте ассистента не заменяет работу с файлами.

1. До запуска: убедиться, что клиент может принять ответ инструмента в коде без вывода больших массивов в контекст, сохранить его в доступный файл и затем читать и обрабатывать этот файл программно. Если это невозможно или возможности не подтверждены, предупредить пользователя до запуска большого расчёта и предложить клиент с такой поддержкой. Меньший объём расчёта можно предложить только с объяснением влияния на запрошенный результат; нельзя молча сокращать временной интервал или разрешение.
2. При получении: get_result возвращает полный JSON, а не готовый файл. Сохранить полученные данные непосредственно из кода до истечения срока хранения, без печати полного ответа и без переписывания массивов ассистентом. Сохранить исходные численные данные, идентификаторы переменных и элементов, единицы, временные координаты, диагностику и статус решателя. Проверить запись и читаемость файла; нормализованную модель сохранить отдельно.
3. При обработке: загружать файл в коде и выбирать переменные по идентификаторам, значения по временным координатам, экстремумы и события. Если запрошенного момента нет в выходной сетке, явно указать выбранный ближайший шаг или способ интерполяции. Ассистенту передавать пути к файлам, фактический интервал расчёта, число точек, статус завершения, существенную диагностику и компактную выборку с единицами и идентификаторами.
4. При представлении: строить графики, таблицы и экспорты из сохранённых данных, сохраняя оригинал с полным разрешением. Прореживание для отображения должно сохранять значимые экстремумы и события. Не запускать расчёт повторно только ради изменения оформления.

Открытие модели в редакторе

1. Сохраните объект модели из результата проверки (data.model) в файл .json в кодировке UTF-8, например two-mass.json. В файл модели не должны попадать полный ответ инструмента, идентификатор и токен задачи или ограждения блока кода Markdown.
2. Откройте редактор BGModeller. Сначала сохраните текущую работу, затем нажмите Open на панели инструментов и выберите JSON-файл.
3. Проверьте параметры компонентов, начальные условия, соединения и расположение элементов. Нажмите Analyze и Simulate для проверки и расчёта в редакторе, затем Save для сохранения изменений.

JSON модели сохраняет расположение элементов и настройки, но не включает результаты симуляции. Для больших динамических расчётов обязательно сохраняйте полные численные результаты отдельно по правилам файловой обработки. MCP не открывает браузер и не сохраняет файлы на вашем компьютере автоматически: это делает клиент. Подробнее — результаты и файлы в редакторе.

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

MCP и расчёты в браузере используют общую очередь публичного сервиса и общие квоты на IP-адрес. У облачного ассистента может быть общий исходящий IP, поэтому квоту могут делить несколько пользователей. MCP не увеличивает доступные вычислительные ресурсы.

Получайте актуальные data.limits и data.mcp_limits через get_capabilities. Стандартная публичная конфигурация:

• Сервис занят или превышена частота запросов (429): выдержите паузу retry_after, если она указана, и реже опрашивайте статус. Проверка документа и анализ тоже расходуют квоты расчётов.
• Ошибка модели (422): прочитайте диагностику, исправьте указанные компоненты или соединения и повторите проверку.
• Задача не найдена или истёк срок хранения (404): проверьте, что идентификатор и токен относятся к одной задаче. Скачивайте результаты сразу; после истечения срока они не восстанавливаются. При необходимости запустите новый расчёт из сохранённой модели.
• Соединение потеряно при отправке: задача уже может выполняться. Не отправляйте её повторно автоматически; если получили идентификатор и токен, сначала проверьте эту задачу.
• Инструменты недоступны: проверьте точный HTTPS-адрес, транспорт и включение инструментов в клиенте. При недоступности MCP редактор в браузере может продолжать работать.