@iola_adm/yoshkar-ola-public-mcp

v0.1.9

Published

24 days ago

STDIO launcher for the Yoshkar-Ola Public MCP remote server.

0High
0Medium
0Low

iola_adm

mcp model-context-protocol open-data yoshkar-ola

MCP-сервер открытых данных Йошкар-Олы

Публичный MCP-сервер для доступа к открытым данным городского округа "Город Йошкар-Ола".

Сервер предоставляет внешним AI-инструментам структурированный доступ к открытым наборам данных городского округа "Город Йошкар-Ола". В первом релизе доступны только данные, подготовленные для внешнего использования.

Доступный endpoint

https://apiiola.yasg.ru/mcp

Transport:

streamable-http

Этот endpoint является обычным публичным remote MCP-сервером. Его можно подключать не только в IOLA CLI, но и во внешние MCP-клиенты: Codex, Claude Desktop/Code, ChatGPT custom MCP app, OpenAI Responses API и другие клиенты с поддержкой streamable HTTP.

Проверка доступности и версии:

https://apiiola.yasg.ru/mcp-health
https://apiiola.yasg.ru/mcp-version

Для локальных MCP-клиентов также доступен transport stdio через команду:

yoshkar-ola-public-mcp-stdio

Локальный stdio-прокси к публичному MCP endpoint можно запускать без Python-установки через npm:

npx -y @iola_adm/yoshkar-ola-public-mcp

npm-wrapper требует Node.js >=22.5.0. Сам remote MCP endpoint от локальной версии Node.js пользователя не зависит.

Локальный Codex skill можно установить или обновить одной командой:

npx -y @iola_adm/yoshkar-ola-public-mcp install-skill codex

Данные первого релиза

Сейчас через MCP-сервер доступны:

муниципальные школы;
муниципальные детские сады.

Источник данных для MCP:

https://apiiola.yasg.ru/api/v1

Источники сведений

Основной эталонный источник данных - "Цифровой мозг городского округа". Данные в нем поддерживаются в актуальном состоянии за счет регулярных автоматизированных обновлений из государственных информационных систем, отраслевых информационных ресурсов и иных официальных источников.

Возвращаемые поля

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

display_order - порядковый номер для отображения;
inn - ИНН;
legal_address - юридический адрес;
address - фактический/публичный адрес;
phone - телефон;
email - электронная почта;
website - официальный сайт;
fns_kpp - КПП по данным ФНС;
fns_ogrn - ОГРН по данным ФНС;
fns_full_name - полное наименование по данным ФНС;
fns_short_name - сокращенное наименование по данным ФНС;
fns_entity_type - тип юрлица;
fns_registration_date - дата регистрации юрлица;
fns_region_name - регион по данным ФНС;
fns_status - статус юрлица;
fns_address - юридический адрес по данным ФНС;
fns_head_position - должность руководителя по данным ФНС;
fns_head_name - ФИО руководителя по данным ФНС;
license_number - номер образовательной лицензии;
license_date - дата лицензии/последнего изменения;
license_order - приказ/основание лицензии;
license_term - срок действия;
license_status - статус лицензии;
license_issuing_organ - орган, выдавший лицензию.

MCP-инструменты

`list_schools`

Возвращает список школ.

Параметры:

limit - сколько записей вернуть, по умолчанию 100, максимум 200;
offset - смещение, по умолчанию 0.

Пример запроса:

Покажи список муниципальных школ Йошкар-Олы.

`search_schools`

Ищет школы по названию, ИНН, адресу, руководителю, email или сайту.

Параметры:

query - строка поиска;
limit - максимум результатов, по умолчанию 20.

Примеры:

Найди школу № 29.

Какая школа находится на улице Петрова?

`get_school_by_inn`

Возвращает одну школу по ИНН.

Параметры:

inn - ИНН организации.

`list_kindergartens`

Возвращает список детских садов.

Параметры:

limit - сколько записей вернуть, по умолчанию 100, максимум 200;
offset - смещение, по умолчанию 0.

`search_kindergartens`

Ищет детские сады по названию, ИНН, адресу, руководителю, email или сайту.

Параметры:

query - строка поиска;
limit - максимум результатов, по умолчанию 20.

`get_kindergarten_by_inn`

Возвращает один детский сад по ИНН.

Параметры:

inn - ИНН организации.

`get_data_update_info`

Возвращает дату последнего обновления открытых данных.

Пример запроса:

Когда последний раз обновлялись данные?

`get_server_info`

Возвращает версию MCP-сервера, актуальную версию skill, доступные слои данных, URI resource с инструкциями и команды обновления локального skill.

Пример запроса:

Какая версия MCP-сервера и какие слои данных доступны?

`list_data_layers`

Возвращает список доступных открытых слоев данных.

Пример запроса:

Какие слои данных сейчас доступны?

`search_all`

Ищет по всем доступным слоям данных.

Параметры:

query - строка поиска;
limit_per_layer - максимум результатов по каждому слою, по умолчанию 10, максимум 50.

Пример запроса:

Найди Пчелку во всех слоях данных.

Универсальные инструменты слоев

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

layer_list - список слоев и поисковых схем;
layer_schema - схема одного слоя;
layer_suggest - подбор слоя по вопросу пользователя;
layer_query - поиск по конкретному слою;
layer_get - получение одной записи по ИНН или ближайшему совпадению.
layer_answer_context - компактный RAG-контекст с фактами, источниками и правилами ответа для модели.
layer_stats - статистика заполненности публичных полей слоя;
layer_facets - частотный список значений публичного поля;
quality_summary и quality_findings - проверки качества данных;
mcp_diagnostics - подробная диагностика MCP, API, cache, tools и слоев.

Список схем также доступен как MCP resource:

yoshkar-ola://layers

Подключение в MCP-клиенте

Если клиент поддерживает remote MCP / streamable HTTP, укажите:

https://apiiola.yasg.ru/mcp

Авторизация на первом этапе не требуется, потому что сервер отдает только открытые публичные данные.

Если клиент работает только с локальными MCP-серверами, используйте stdio entrypoint после установки Python-пакета:

yoshkar-ola-public-mcp-stdio

Или npm-wrapper, который проксирует локальный stdio в публичный remote MCP:

npx -y @iola_adm/yoshkar-ola-public-mcp

npm-wrapper нужен только клиентам, которым требуется локальный stdio процесс. Если клиент умеет подключать remote MCP напрямую, используйте https://apiiola.yasg.ru/mcp без npm-wrapper.

Подключение в ChatGPT / OpenAI

Для ChatGPT и OpenAI API есть три рабочих сценария.

ChatGPT Apps / custom MCP app

В ChatGPT Web сервер подключается как remote MCP app. Используйте публичный endpoint:

https://apiiola.yasg.ru/mcp

Локальный stdio transport для ChatGPT напрямую не подходит: ChatGPT подключается к удаленным MCP-серверам. Если сервер находится в приватной сети или на машине разработчика, используйте совместимый tunnel/remote gateway.

Custom GPT через Actions

Для GPT Actions можно подключить не MCP endpoint, а обычный публичный REST API. Готовая OpenAPI-схема находится здесь:

docs/openapi/chatgpt-actions.openapi.yaml

В GPT editor откройте Actions, создайте новое action и вставьте эту схему. Авторизация для первого релиза не требуется.

Важно: в настройках одного Custom GPT используется либо Apps, либо Actions. Если нужен именно MCP, выбирайте custom MCP app; если нужен простой REST-доступ к первым слоям, выбирайте GPT Actions.

OpenAI Responses API

В OpenAI API remote MCP подключается как инструмент mcp:

{
  "type": "mcp",
  "server_label": "yoshkar_ola_public_data",
  "server_description": "Открытые данные городского округа \"Город Йошкар-Ола\".",
  "server_url": "https://apiiola.yasg.ru/mcp",
  "require_approval": "never"
}

Официальная документация OpenAI:

https://help.openai.com/en/articles/11487775-connectors-in-chatgpt
https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta.svgz
https://developers.openai.com/api/docs/guides/tools-connectors-mcp
https://help.openai.com/en/articles/9442513-configuring-actions-in-gpts

Подключение в Codex

Команды ниже соответствуют локальной справке Codex CLI codex mcp add --help: для удаленного streamable HTTP-сервера используется --url, для локального stdio-сервера команда указывается после --.

Remote MCP:

codex mcp add yoshkarOlaPublicData --url https://apiiola.yasg.ru/mcp
codex mcp list

Локальный stdio MCP:

python -m pip install -e .
codex mcp add yoshkarOlaPublicDataLocal -- yoshkar-ola-public-mcp-stdio
codex mcp list

Локальный stdio MCP через npm:

codex mcp add yoshkarOlaPublicDataNpm -- npx -y @iola_adm/yoshkar-ola-public-mcp
codex mcp list

Skill для Codex находится в каталоге:

skills/yoshkar-ola-open-data/SKILL.md

Чтобы использовать его локально, установите skill через npm:

npx -y @iola_adm/yoshkar-ola-public-mcp install-skill codex

Или скопируйте каталог skill в директорию skills вашего Codex-профиля. Пример для PowerShell:

$skills = "$env:USERPROFILE\.codex\skills"
New-Item -ItemType Directory -Force -Path $skills
Copy-Item -Recurse -Force .\skills\yoshkar-ola-open-data "$skills\yoshkar-ola-open-data"

Подключение в Claude

Для Claude.ai, Claude Desktop и Claude Code используйте один из двух вариантов, если он доступен в вашей версии клиента:

remote connector / custom connector:

https://apiiola.yasg.ru/mcp

локальный MCP через stdio в конфигурации Claude Desktop:

{
  "mcpServers": {
    "yoshkarOlaPublicData": {
      "command": "yoshkar-ola-public-mcp-stdio"
    }
  }
}

локальный MCP через npm-wrapper:

{
  "mcpServers": {
    "yoshkarOlaPublicData": {
      "command": "npx",
      "args": ["-y", "@iola_adm/yoshkar-ola-public-mcp"]
    }
  }
}

Skill-инструкцию из skills/yoshkar-ola-open-data/SKILL.md можно добавить в Claude Project instructions, Claude Skills или другой механизм проектных инструкций, если он доступен в используемом клиенте.

Официальная документация Anthropic по MCP:

https://docs.anthropic.com/en/docs/mcp
https://docs.anthropic.com/en/docs/claude-code/mcp
https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector

Подключение в GigaChat

Для GigaChat-сценариев используйте MCP через агентный слой, например GigaChain/LangChain MCP adapters:

для локального запуска используйте команду yoshkar-ola-public-mcp-stdio;
для удаленного запуска используйте публичный endpoint https://apiiola.yasg.ru/mcp, если выбранный MCP-клиентский слой поддерживает streamable HTTP;
если конкретная интеграция ожидает SSE, используйте совместимый MCP gateway или proxy между клиентом и этим сервером.

Skill-инструкцию используйте как system prompt / instructions для агента.

Официальный пример Sber/GigaChain:

https://developers.sber.ru/docs/ru/gigachain/tutorials/agent-gigachat-mcp

Подключение в Yandex AI Studio / YandexGPT

В Yandex AI Studio можно подключать MCP-серверы через MCP Hub. Для внешнего MCP-сервера используйте endpoint:

https://apiiola.yasg.ru/mcp

Если сценарий строится не через MCP Hub, а через function calling, реализуйте тонкий слой функций, который вызывает инструменты этого MCP-сервера и возвращает результат модели. Skill-инструкцию из skills/yoshkar-ola-open-data/SKILL.md используйте как системную инструкцию агента.

Официальная документация Yandex Cloud:

https://yandex.cloud/ru/docs/ai-studio/concepts/mcp-hub/

Локальный запуск

Установить зависимости:

python -m venv .venv
.venv/bin/pip install -e ".[dev]"

Запустить сервер:

MCP_HOST=127.0.0.1 MCP_PORT=8001 MCP_PATH=/mcp .venv/bin/yoshkar-ola-public-mcp

На Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\pip.exe install -e ".[dev]"
$env:MCP_HOST = "127.0.0.1"
$env:MCP_PORT = "8001"
$env:MCP_PATH = "/mcp"
.\.venv\Scripts\yoshkar-ola-public-mcp.exe

Запустить локальный stdio transport:

.venv/bin/yoshkar-ola-public-mcp-stdio

На Windows PowerShell:

.\.venv\Scripts\yoshkar-ola-public-mcp-stdio.exe

Запустить локальный stdio-прокси через npm:

npm install
npm start

Или напрямую:

node npm/bin/yoshkar-ola-public-mcp.js

npm-пакет

Репозиторий содержит npm-wrapper для MCP-клиентов, которым удобнее запускать локальный stdio-сервер через npx. Wrapper не реализует отдельную копию бизнес-логики: он запускает mcp-remote и подключает локальный stdio к публичному endpoint https://apiiola.yasg.ru/mcp.

Требуется Node.js >=22.5.0. Для локальной разработки можно использовать .nvmrc или .node-version из репозитория.

Пакет опубликован в npm:

https://www.npmjs.com/package/@iola_adm/yoshkar-ola-public-mcp

Основные команды:

npx -y @iola_adm/yoshkar-ola-public-mcp
npx -y @iola_adm/yoshkar-ola-public-mcp doctor
npx -y @iola_adm/yoshkar-ola-public-mcp tools
npx -y @iola_adm/yoshkar-ola-public-mcp call layer_query '{"layer":"schools","query":"директор Кузнецов","limit":1}'
npx -y @iola_adm/yoshkar-ola-public-mcp call layer_answer_context '{"question":"в какой школе директор Кузнецов","limit":3}'
npx -y @iola_adm/yoshkar-ola-public-mcp call layer_stats '{"layer":"schools"}'
npx -y @iola_adm/yoshkar-ola-public-mcp call quality_summary '{}'
npx -y @iola_adm/yoshkar-ola-public-mcp install-skill codex
npx -y @iola_adm/yoshkar-ola-public-mcp check-updates

Команды диагностики:

doctor - проверяет Node.js, npm-wrapper, health/version remote MCP, наличие обязательных layer-инструментов и версию локального Codex skill;
tools - выводит список MCP-инструментов, которые отдает remote endpoint;
call - вызывает один MCP-инструмент и печатает JSON-ответ, удобно для проверки деплоя и новых слоев.

Проверить пакет локально:

npm install
npm test
npm run release-check
npm pack --dry-run

Опубликовать новую версию пакета:

npm adduser
npm publish --access public --provenance

Основной процесс публикации описан в docs/release.md. Для автоматической публикации npm нужен GitHub secret NPM_TOKEN. Автодеплой remote MCP на VPS можно включить через repository variable MCP_DEPLOY_ENABLED=true и deploy secrets, описанные в docs/release.md.

Команда npx -y @iola_adm/yoshkar-ola-public-mcp работает из любого проекта. Локальную сборку перед публикацией можно проверять через npm start.

Обновления skill

Новые MCP-инструменты и слои данных становятся доступны пользователям remote MCP после деплоя сервера. Локальные skills у пользователей сами не перезаписываются, поэтому сервер предоставляет инструмент get_server_info, resource yoshkar-ola://guidance/open-data и prompt yoshkar_ola_open_data_guidance с актуальными инструкциями.

Для обновления Codex skill:

npx -y @iola_adm/yoshkar-ola-public-mcp install-skill codex

Переменные окружения

CPR_PUBLIC_API_BASE_URL - базовый URL публичного API, по умолчанию https://apiiola.yasg.ru/api/v1;
CPR_PUBLIC_API_TIMEOUT - timeout HTTP-запросов к API в секундах, по умолчанию 20;
CPR_PUBLIC_API_CACHE_TTL - TTL кэша в секундах, по умолчанию 300;
YOSHKAR_OLA_PUBLIC_MCP_URL - remote MCP endpoint для npm-wrapper, по умолчанию https://apiiola.yasg.ru/mcp;
MCP_HOST - host MCP-сервера, по умолчанию 127.0.0.1;
MCP_PORT - port MCP-сервера, по умолчанию 8001;
MCP_PATH - путь MCP endpoint, по умолчанию /mcp.

См. также .env.example.

Примеры

Готовые примеры подключения находятся в docs/examples/:

codex.md;
claude-desktop.json;
openai-responses-api.js;
python-fastmcp-client.py;
curl-public-api.md.

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

Сервер предназначен только для получения открытых данных городского округа. Если вы обнаружили неточность в данных или считаете, что какая-либо информация не должна быть опубликована, сообщите об этом сопровождающим проекта приватным каналом.

Ограничения

Этот MCP-сервер не является полным реестром всех данных ЦПР. Он предоставляет только те наборы и поля, которые явно добавлены в код и одобрены для открытого доступа.

Деплой

Пример шаблона systemd-сервиса и nginx-location находится в каталоге deploy/. Конкретные параметры боевого окружения задаются на стороне инфраструктуры.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

MCP-сервер открытых данных Йошкар-Олы

Доступный endpoint

Данные первого релиза

Источники сведений

Возвращаемые поля

MCP-инструменты

list_schools

search_schools

get_school_by_inn

list_kindergartens

search_kindergartens

get_kindergarten_by_inn

get_data_update_info

get_server_info

list_data_layers

search_all

Универсальные инструменты слоев

Подключение в MCP-клиенте

Подключение в ChatGPT / OpenAI

ChatGPT Apps / custom MCP app

Custom GPT через Actions

OpenAI Responses API

Подключение в Codex

Подключение в Claude

Подключение в GigaChat

Подключение в Yandex AI Studio / YandexGPT

Локальный запуск

npm-пакет

Обновления skill

Переменные окружения

Примеры

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

Ограничения

Деплой

`list_schools`

`search_schools`

`get_school_by_inn`

`list_kindergartens`

`search_kindergartens`

`get_kindergarten_by_inn`

`get_data_update_info`

`get_server_info`

`list_data_layers`

`search_all`