MCP-сервер для Федресурса: компании, граждане и банкротство — fedresurs.ru

MCP-сервер СУДиДЕЛО для Федресурса позволяет получать сведения о компаниях, гражданах, банкротстве и арбитражных управляющих через ИИ-помощника. Подключите сервер к совместимому клиенту и опишите задачу обычными словами: найти карточку по ИНН, показать публикации, прочитать сообщение или получить вложение.

Источник сведений — Федресурс. MCP получает данные через API СУДиДЕЛО в пределах прав вашего пользователя. В каталоге 31 инструмент: сведения о компаниях и гражданах, публикации управляющих, архивные снимки, импорт и проверки доступности.

Что можно делать

  • Находить компанию по ИНН, читать сохранённые данные, карточки, публикации и списки вложений.
  • Получать карточку гражданина по ИНН или идентификатору, сведения о банкротстве и связанные публикации.
  • Читать сведения об арбитражном управляющем, его публикации и отчёты.
  • Открывать полный текст публикации и получать доступные вложения граждан, управляющих и архива.
  • По вашему поручению запускать импорт данных и отдельно проверять его состояние.
  • Работать с доступными архивными снимками: читать состав снимка, листать публикации и получать сохранённые материалы.

Данные могут быть ранее сохранены в системе. Дата ответа помощника сама по себе не подтверждает свежесть сведений: проверяйте даты, состояние импорта и признаки источника в результате.

Что нужно для начала

  • Учётная запись СУДиДЕЛО с доступом к нужному разделу мониторинга: компаниям Федресурса или физическим лицам.
  • MCP-клиент с поддержкой Streamable HTTP и модель, умеющая вызывать инструменты. Для входа через браузер нужна поддержка этого способа авторизации.
  • При ручной настройке — API KEY из раздела «Интеграция → API». См. инструкцию по открытому API. При браузерном входе копировать ключ не требуется.
  • Для импорта гражданина и архива — дополнительное право создания записей мониторинга физических лиц. Для архива также требуется действующая личная подписка или предоставленный доступ к архивным объектам.
  • Для сохранения вложений — клиент, который получает результат целиком, декодирует base64 и умеет записывать файлы.

Успешное подключение не открывает все данные автоматически. Доступ к каждому действию и объекту проверяется отдельно; видимый инструмент может вернуть отказ, если у пользователя нет нужных прав.

Какой адрес выбрать

На обоих адресах доступны одинаковые 31 инструмент и два способа входа. Для клиента на компьютере в России можно использовать адрес с -ru, для зарубежного сервиса — основной адрес. Если выбранный адрес недоступен из вашей сети, переключитесь на другой.

  • Основной, вход через браузер: https://mcp-fedresurs.torkndgov.ru/mcp-oauth.
  • Для России / запасной, вход через браузер: https://mcp-fedresurs-ru.torkndgov.ru/mcp-oauth.
  • Основной, по API KEY: https://mcp-fedresurs.torkndgov.ru/mcp.
  • Для России / запасной, по API KEY: https://mcp-fedresurs-ru.torkndgov.ru/mcp.

Оба адреса используют один и тот же ключ сотрудника и одинаковые права. При смене адреса сохраните настройки и подключитесь заново. Открытие MCP-адреса как обычной страницы браузера не заменяет подключение в клиенте.

Подключение в агенте ИИ

Способ 1. Войти через браузер

Добавьте remote MCP в совместимом клиенте. Пример конфигурации для подключения через адрес для России:

{
  "mcpServers": {
    "sudodelo-fedresurs": {
      "url": "https://mcp-fedresurs-ru.torkndgov.ru/mcp-oauth"
    }
  }
}
  1. Сохраните настройки и начните подключение сервера.
  2. В открывшемся браузере войдите в свою учётную запись СУДиДЕЛО. Выполните дополнительное подтверждение входа, если система его запросит.
  3. Проверьте подключаемое приложение и нажмите «Подключить». Если вы уже вошли, подтверждение подключения может открыться сразу.
  4. После успешной авторизации вернитесь в клиент и проверьте появление инструментов с префиксом fedresurs_.

Пароль вводится на странице входа СУДиДЕЛО. Передавать пароль или API KEY в чат не требуется. Для основного адреса замените только url на https://mcp-fedresurs.torkndgov.ru/mcp-oauth.

Способ 2. Указать API KEY вручную

Используйте адрес с окончанием /mcp и передавайте ключ в заголовке X-Sudodelo-Api-Key:

{
  "mcpServers": {
    "sudodelo-fedresurs": {
      "url": "https://mcp-fedresurs-ru.torkndgov.ru/mcp",
      "headers": {
        "X-Sudodelo-Api-Key": "<ваш ключ доступа СУДиДЕЛО>"
      }
    }
  }
}

Замените плейсхолдер своим ключом, сохраните настройки и переподключите сервер. Ключ отправляется клиентом с каждым запросом и не входит в аргументы инструментов. Для основного адреса используйте https://mcp-fedresurs.torkndgov.ru/mcp.

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

Как подключить в LM Studio

Общий порядок настройки соответствует официальной инструкции LM Studio по MCP. Для этого сервера проверены HTTP-подключение и протокол браузерного входа на обоих адресах; работа именно MCP Федресурса через интерфейс LM Studio отдельно не проверялась.

  1. Загрузите модель с поддержкой вызова инструментов. Локальной модели нужен доступ в Интернет для обращения к удалённому MCP-серверу.
  2. Откройте панель Integrations или Program, затем Install → Edit mcp.json. Названия элементов зависят от версии приложения. В Windows файл обычно находится в %USERPROFILE%\.lmstudio\mcp.json; перед изменением сохраните копию.
  3. Добавьте sudodelo-fedresurs по одному из примеров выше. Если в файле уже есть серверы, добавьте новую запись внутрь существующего объекта mcpServers, сохранив остальные подключения.
  4. Сохраните файл, включите mcp/sudodelo-fedresurs в интеграциях чата. При браузерном способе завершите вход и подтвердите подключение.
  5. Проверьте каталог: должны появиться 31 инструмент с префиксом fedresurs_, в том числе fedresurs_person_by_inn и fedresurs_company.
  6. Отправьте запрос в чат. Если клиент спрашивает разрешение на вызов, проверьте инструмент и параметры. Импорт разрешайте, когда вы действительно поручили загрузить данные.

Например: «Через sudodelo-fedresurs получи сохранённую карточку гражданина по ИНН [12 цифр], затем покажи первые 20 публикаций о банкротстве. Импорт и обновление пока не запускай».

Проверьте фактический вызов инструмента и его результат в интерфейсе. Текстовое сообщение модели «данные получены» само по себе не подтверждает обращение к серверу.

Примеры запросов в чате

  • «Покажи сохранённые сведения Федресурса о компании с ИНН [ИНН компании] и её публикации».
  • «Найди гражданина по ИНН [12 цифр], покажи сведения о банкротстве и первые 20 публикаций».
  • «Покажи последние пять публикаций арбитражного управляющего с ИНН [12 цифр]».
  • «Открой полный текст выбранной публикации и перечисли её вложения».
  • «Запусти импорт данных этого гражданина и проверь состояние задания. Сообщи отдельно, когда импорт будет завершён».
  • «Для доступного архивного снимка покажи публикации о банкротстве и перейди на следующую страницу».

Текст в квадратных скобках замените настоящим ИНН. ИНН передаётся строкой без пробелов с сохранением начальных нулей: для компании допустимы 10 или 12 цифр, для гражданина и управляющего — 12. Идентификаторы объектов помощник должен брать из фактических ответов, а не придумывать.

Каталог инструментов

В обычном чате точное имя вводить необязательно. Каталог помогает понять доступные действия и проверить, какой инструмент вызвал помощник.

Компании — 9 инструментов

Граждане — 8 инструментов

Арбитражные управляющие — 4 инструмента

Архив — 7 инструментов

Доступность — 3 инструмента

Как работать с импортом и архивом

Импорт запускается по вашему поручению. Ответ 202 означает, что задание принято, но ещё не подтверждает готовность данных. Для компании проверяйте fedresurs_company_status по ИНН, для гражданина — fedresurs_person_import_job, для архива — fedresurs_archive_import_job по идентификатору задания.

После таймаута сначала выясните состояние уже запущенной операции. Автоматических повторов нет. Для архивного импорта сохраняйте operation_id и исходные параметры: повтор той же операции использует тот же идентификатор. Изменение параметров с прежним идентификатором приводит к конфликту 409.

Архивный импорт принимает ровно один способ выбора гражданина: inn или person_uuid. Политика attachment_policy="links" сохраняет ссылки на вложения, "fetch" запрашивает их загрузку.

Для чтения архива нужны идентификатор гражданина и точный snapshot_id из ответа системы. Сначала откройте состав снимка, затем список публикаций. При переходе на следующую страницу передавайте полученный nextCursor в параметре cursor без изменения, сохраняя снимок, фильтры и размер страницы. Снимок не следует считать гарантированным состоянием всего первоисточника на один момент времени, если источник сообщает sourceSnapshotGuaranteed=false.

Как получить файл вложения

Содержимое файлов возвращают три инструмента: fedresurs_person_attachment, fedresurs_manager_attachment и fedresurs_archive_attachment. Инструменты вложений компаний возвращают списки и метаданные.

Результат скачивания содержит имя файла, MIME-тип, размер в байтах и данные.soderzhimoe_base64. Сохранение на диск выполняет клиент. Он должен получить полное содержимое, декодировать base64 и сохранить байты с проверкой размера. Формат вложения зависит от источника: это не обязательно PDF.

Лимит файла по умолчанию — 5 МиБ до base64. В проверке другого MCP на LM Studio 0.4.28+2 наблюдалось обрезание длинного результата после 50 000 символов. Это не установленный лимит MCP Федресурса, но повод проверить полноту результата в вашем клиенте. Из обрезанного base64 восстановить полный файл нельзя. Сообщение помощника, путь или ссылка на несуществующий файл не заменяют фактическое сохранение.

Важные ограничения

  • Чтение сохранённых данных, поиск и обновление — разные действия. Поиск компании может обновить кеш, а refresh=true у карточки гражданина запрашивает актуализацию источника.
  • Доступ зависит от прав сотрудника, организации, а для архива — также от действующего доступа к объектам. Подключение не обходит эти проверки.
  • Большие списки нужно читать постранично. Первая страница не подтверждает полноту всех публикаций.
  • Предел JSON-ответа по умолчанию — 16 МиБ, файла — 5 МиБ. При превышении сервер возвращает ошибку, частичный файл не выдаёт. У клиента могут быть дополнительные ограничения.
  • Работа зависит от доступности API и источника. Отсутствие данных или ошибка запроса сами по себе не означают отсутствие банкротства либо публикаций.
  • Проверка подключения не подтверждает успешный импорт или сохранение вложения. В рамках выпуска реальные импорты, архивные снимки и бинарные вложения в рабочем окружении отдельно не проверялись.

Если что-то не работает

  1. Не подключается сервер. Проверьте адрес и попробуйте другой домен. Для браузерного входа нужен /mcp-oauth, для ручного ключа — /mcp. После изменения переподключитесь.
  2. Нужно проверить доступность. Откройте проверку основного адреса или запасного адреса. Ответ status: ok подтверждает только работу процесса MCP. Для проверки сервиса данных вызовите fedresurs_health с действующим доступом.
  3. Отказ в доступе. Проверьте вход, ключ и право на выбранный раздел. Для импорта гражданина и архива проверьте дополнительное право; для архива — подписку или предоставленный доступ.
  4. Сессия не найдена после перезапуска. Переподключите сервер. При смене домена также нужна новая сессия.
  5. Неверный ИНН или идентификатор. Уберите пробелы, проверьте число цифр. UUID публикации, гражданина, задания и снимка берите из ответа соответствующего инструмента.
  6. Импорт долго выполняется или завершился таймаутом. Проверьте статус существующего задания до нового запуска. Для архивного повтора сохраните прежний operation_id и параметры.
  7. Файл не сохранился. Проверьте поддержку записи файлов и полноту base64 в клиенте. При превышении лимита или обрезании ответа используйте клиент, способный получить полный результат, либо доступный способ скачивания в СУДиДЕЛО.

Для программистов

Пример MCP-вызова карточки гражданина по ИНН:

{
  "name": "fedresurs_person_by_inn",
  "arguments": {
    "inn": "635003917262",
    "refresh": false
  }
}

Это пример параметров tools/call. Используйте ИНН нужного вам гражданина. Для последующих вызовов возьмите person_uuid из фактического результата. В списке публикаций гражданина параметр section принимает publications, publications_from_bankrupt_publisher или bankruptcy; размер страницы — до 100. Для публикаций компании по UUID — до 200, управляющего — до 20.

Результат содержит итог, разрешено, а после обращения к API — http_status, данные и заголовки. JSON источника сохраняется в данные. Проверяйте разрешено, MCP isError, статус и тело ответа: успешная доставка MCP-ответа сама по себе не подтверждает успешное действие. При 202 требуется отдельная проверка задания.

Для прямой интеграции используется группа /api/Fedresurs API СУДиДЕЛО. Контракт методов смотрите в Swagger. Другие возможности CRM описаны в статье об основном MCP-сервере СУДиДЕЛО.