MCP-сервер для ИИ-клиентов

Возможности

• Подключить к данным сети внешний ИИ-клиент — Claude Desktop, Claude Code, Cursor или свой агент — по протоколу MCP.
• Дать клиенту те же 19 инструментов, что у встроенного помощника ИИ: фрагменты, поиск, выборка по условиям, трассировка, локализация аварии, запросы по сети, анализ режима, сводка по теме участков, износ, похожие аварии, места повторных отказов, качество данных, расчёты, сценарии.
• Запустить из клиента гидравлический расчёт (run_calculation) — единственный инструмент, который что-то меняет. Остальные 18 только читают.
• Скопировать готовую команду для Claude Code или настройку mcpServers для Claude Desktop и Cursor.

Клиент работает с вашими правами: что вам не видно или запрещено в окне, то недоступно и через MCP.

Как это работает

Где найти. Меню пользователя → личный кабинет → раздел «ИИ-клиенты (MCP)». В нём: адрес сервера, кнопка «Выдать токен на N дн.» и список инструментов.

Токен. Кнопка выдаёт отдельный токен, который действует только на адресе MCP: открыть с ним окна ТГИД или другие адреса API нельзя. Токен показывается один раз; после выдачи появляются команда Claude Code и настройка mcpServers с ним — их копируют кнопками рядом. Срок — 30 дней (администратор может задать до 90).

Отозвать токен по одному нельзя. Досрочно токен закрывает смена пароля или блокировка учётной записи (для учётных записей ТГИД; доменные учётные записи — только блокировкой). Остальное — дождаться срока.

Сервер. Один адрес …/mcp, запросы POST в формате JSON-RPC. Клиент сначала спрашивает список инструментов (tools/list), затем вызывает их (tools/call). У каждого инструмента — название по-русски, описание параметров и пометка «только чтение».

Ограничения:

• не больше 60 вызовов инструментов в минуту на пользователя;
• run_calculation — не больше 5 запусков за 10 минут и только с правом «Запуск расчётов»;
• в одном пакете — не больше 10 запросов, тело запроса — не больше 1 МБ;
• запрос из браузера со стороннего сайта (заголовок Origin не из разрешённых) отклоняется.

Расчёт из клиента — настоящий. run_calculation ставит в очередь такой же расчёт, как кнопка в окне: он попадает в список расчётов, и карта по умолчанию открывает фрагмент последнего расчёта. Просите клиента запускать расчёт только тогда, когда он вам действительно нужен.

Что нужно для работы

• Учётная запись ТГИД. Выдать токен может любой вошедший пользователь.
• MCP, включённый на сервере. Если он выключен, раздела «ИИ-клиенты (MCP)» в кабинете нет.
• ИИ-клиент с поддержкой MCP по HTTP (Streamable HTTP) и заголовка Authorization: Bearer.
• Помощник ИИ на сервере для MCP не нужен: модель — на стороне вашего клиента, и платите за неё вы.

Примеры

Длина сети фрагмента 74 (копия Алматы). Инструмент «Запросы по сети» (network_statistics) возвращает длину участков 394 839,6 м — 394,8 км: подача 197,3 км, обратка 197,6 км. Те же числа даёт встроенный помощник на этот вопрос.

Список инструментов на стенде копии Алматы: tools/list вернул 19 инструментов, и названия совпадают со строкой «Инструменты: …» в кабинете.

Если не получается

• Клиент пишет «401» или «Unauthorized» — токен истёк или вставлен не целиком. Выдайте новый.
• «Пароль сменён — выдайте новый токен ИИ-клиента» — после смены пароля старые токены не действуют.
• «Слишком часто: не больше 60 вызовов в минуту — подождите» — клиент вызывает инструменты в цикле; подождите минуту.
• «Не больше 5 запусков за 10 минут…» — дождитесь окончания расчётов (task_status).
• Инструмент отвечает, что нет прав, — у вашей роли нет нужного права; клиент получает то же, что окно.
• Раздела «ИИ-клиенты (MCP)» нет в кабинете — MCP выключен на сервере, обратитесь к администратору.

Для администратора

• Флаги: MCP_ENABLED (включить сервер), MCP_TOKEN_DAYS (срок токена, по умолчанию 30, не больше 90), CORS_ALLOWED_ORIGINS (с каких сайтов браузер может обращаться к /mcp).
• Токен — подписанный JWT с назначением mcp и отпечатком пароля; отдельной таблицы токенов нет, поэтому отзыв — только сменой пароля или блокировкой учётной записи.
• При отключённой проверке входа (AUTH_DISABLED, только для стендов) /mcp принимает вызовы без токена — от имени администратора. На сервере с доступом извне так не включайте.
• Вызовы инструментов пишутся в журнал действий от имени владельца токена.

Для разработчика

• Протокол: POST /mcp (JSON-RPC 2.0, initialize, tools/list, tools/call, пакет до 10); GET и DELETE → 405. Сведения для кабинета — GET /api/v1/mcp/info (адрес, срок, инструменты), выдача токена — POST /api/v1/mcp/token.
• Сервер: routers/mcp.py (протокол без SDK, проверка Origin и токена), реестр инструментов tgid_mcp/tools.py (RATE_LIMIT, CALC_RATE_LIMIT, права и пометка read_only); тот же реестр использует помощник ai/assistant.py. Описание — docs/mcp.md в репозитории API.
• Веб: components/McpClientPanel.vue (в AccountDialog), utils/mcpClient.ts (команда Claude Code и настройка mcpServers).
• Тесты: API — tests/test_mcp.py; веб — tests/utils/mcpClient.spec.ts; e2e — e2e/functions/ai.spec.ts (список инструментов в кабинете против tools/list, токен подменён).