establish-mcp

Establish MCP — транспорт до графа

Все прочие скиллы поставки предполагают, что тулы iskron_* уже в сессии. Этот скилл их туда приводит — и кончается сессией, в которой ответил вызов iskron_me(action="whoami") или iskron_orient; дальше — entry.

Когда звать

• тулов iskron_* в сессии нет, или они есть и отказывают транспортом: не подключено, вход OAuth, токен отвергнут, молчание;
• первый вход на машине — браузером или личным токеном;
• записи уходят без автора и после повторного iskron_stand (standing, «Дерево починки») — тулы идут мимо моста или мост старой сборки;
• смена сервера (русская или английская версия, другой экземпляр сервера), проверка или обновление поставки, вопрос «какая версия моста».

Когда не звать. Хоть один тул iskron_* в этой сессии ответил по существу — транспорт есть, вернись к задаче (кроме записей без автора выше). Отказ самого графа (нет узла, нет прав, 422) — не транспорт. Агенту, у которого тулы графа свои, а не из этой поставки, скилл не нужен.

Что стоит на машине

Сервер удалённый; на машину ставится только эта поставка, и она несёт свой транспорт — мост iskron-bridge: файл scripts/iskron.mjs рядом с этим скиллом (далее <мост>). Один файл несёт stdio-MCP-мост, сторожей стояния и служебные подкоманды; их перечень и флаги печатает node <мост> --help. Мост держит грант сам (один вход на всю машину) и привязку стояния: только он держит место, слух канала и подпись записей местом — без него записи агента уходят без автора. Прямое подключение сервера коннектором — запасной путь веб-клиента, и называется он всегда с ценой (ниже, «Мост не поднять»).

Мост приходит сам: плагин Claude Code и плагин Codex несут его записью MCP (claude mcp list → plugin:iskron:iskron; codex mcp list → iskron, command node, Auth: Unsupported — так и должно быть, грант у моста свой), в pi его поднимает расширение пакета, в OpenCode — плагин поставки. Где <мост> на этой машине: домашняя копия ~/.iskron-bridge/iskron-bridge.mjs (мост, однажды поднятый харнесом, кладёт её сам); путь, который печатает claude mcp list или codex mcp list; путь в блоке [iskron-bridge] ответа iskron_stand; в крайнем случае $SKILL_DIR/scripts/iskron.mjs ($SKILL_DIR печатается при загрузке скилла).

Первый ход — doctor

node ~/.iskron-bridge/iskron-bridge.mjs doctor      # или node <мост> doctor

Одна команда, ничего не правящая: сборка, адрес сервера и его ответ, грант или токен, записи в конфигах харнесов и раздел «субагенты» — запись моста-спутника у каждого файла агента проекта и его пробный запуск. Зови его из каталога проекта: записи OpenCode и файлы агентов он ищет вверх по дереву от своего каталога. Делай, что он сказал: каждая его строка называет факт и путь, а расхождение — командой починки. Цитируй сборку из его первой строки (vX.Y.Z+хеш) в любом разговоре о поломке.

Моста или записи нет — поставь

Порядок по харнесам — ~/.iskron-bridge/SETUP.md (его кладёт update; нет файла — node <мост> update положит, или прочти SETUP.md в корне github.com/iskron-ai/skills). Штатный путь — плагин: Claude Code claude plugin marketplace add iskron-ai/skills и claude plugin install iskron@iskron; pi pi install git:github.com/iskron-ai/skills; Codex — ниже, своим разделом. После — новая сессия (в Claude Code можно /reload-plugins).

Без плагина мост ставится копией в устойчивый дом (никогда не ссылайся из конфига внутрь версионированного пути установки) и регистрируется stdio-сервером в пользовательском конфиге харнеса, не проектном — граф следует за человеком через все репозитории:

mkdir -p ~/.iskron-bridge && cp "$SKILL_DIR/scripts/iskron.mjs" ~/.iskron-bridge/iskron-bridge.mjs
claude mcp add --scope user iskron-bridge -- node ~/.iskron-bridge/iskron-bridge.mjs     # Claude Code

Прочие харнесы: { "mcpServers": { "iskron-bridge": { "command": "node", "args": ["/абс/путь/.iskron-bridge/iskron-bridge.mjs"] } } } — абсолютный путь, где ~ не раскрывается. Нужен Node 22+.

Claude Desktop — скиллы в нём загружены в приложение, и файла моста рядом на диске нет: мост скачивается из последнего выпуска, не с main (TAG=$(curl -fsSI https://github.com/iskron-ai/skills/releases/latest | tr -d '\r' | sed -n 's|^[Ll]ocation: .*/releases/tag/||p'), затем curl -fsSL --create-dirs "https://raw.githubusercontent.com/iskron-ai/skills/$TAG/skills/establish-mcp/scripts/iskron.mjs" -o ~/.iskron-bridge/iskron-bridge.mjs; на Windows — PowerShell-рецепт SETUP.md с curl.exe), запись выше вписывается в claude_desktop_config.json (путь по системе — SETUP.md, ветка Claude Desktop), приложение перезапускается. Оболочки у тебя нет — продиктуй это человеку.

OpenCode — не запись mcp в конфиге (она переименует тулы и смешает сессии), а плагин поставки, вторым файлом тем же ходом:

mkdir -p ~/.config/opencode/plugins && cp "$SKILL_DIR/scripts/opencode-plugin.js" ~/.config/opencode/plugins/iskron.js

Плагин поднимает мост из домашней копии на Bun самого OpenCode (Node не нужен); пока входа нет, тул iskron_bridge называет адрес входа. Запись mcp, которую назвал doctor, убирает человек правкой названного файла.

Проверяй вызовом, не конфигом: перезапусти MCP-слой харнеса и позови iskron_me(action="whoami") или iskron_realm(action="list"). Ответил — подключено; всё меньшее — нет.

Codex

codex plugin marketplace add https://github.com/iskron-ai/skills
codex plugin add iskron@iskron

Манифест плагина несёт запись MCP iskron — сам мост: node ./skills/establish-mcp/scripts/iskron.mjs от корня плагина. Копировать и править config.toml не нужно. Проверка — codex mcp list: iskron с command node и Auth: Unsupported. Это норма, а не поломка: грант держит мост (вход — ниже, «Вход»), codex mcp login здесь не нужен. После первого запуска мост лежит и домашней копией ~/.iskron-bridge/iskron-bridge.mjs — по ней зови doctor и update. Первый вызов тула в сессии Codex — проверка, как и везде.

• Без плагина: после копии в дом — codex mcp add iskron-bridge -- node "$HOME/.iskron-bridge/iskron-bridge.mjs".
• codex exec: вызовы MCP требуют одобрения, и без него отбиваются словами approval policy is never — тулы видны, но не зовутся. Живьём вызов прошёл с --dangerously-bypass-approvals-and-sandbox — он снимает и песочницу, только для внешне изолированной среды; более узкий --approve-for-me есть в codex exec --help, но с тулами графа не проверялся.
• Обновление плагина: codex plugin marketplace upgrade iskron, затем codex plugin remove iskron@iskron (без @iskron отказывает) и codex plugin add iskron@iskron; новая сессия.
• Слух канала: сторож node "<мост>" watchdog-codex <ключ> из оболочки сессии Codex. Ему нужна дверь — демон codex app-server и песочница треда, пускающая к ~/.iskron-bridge: ход человека до запуска сессии, порядок — SETUP.md; открыта ли — говорит doctor. Код 2 и держание сторожа — standing, «Выбор сторожа».

Вход

OAuth. Первый вызов без гранта отвечает ошибкой со ссылкой входа — адрес самого моста http://127.0.0.1:ПОРТ/login; мост пробует открыть браузер сам. Отдай ссылку человеку, после его входа повтори вызов. Ссылка одна на всю машину и рабочая, пока её слушает хоть один мост. Без браузера — ISKRON_BRIDGE_NO_BROWSER=1 или --no-browser: мост только печатает ссылку. Ссылка локальна для машины моста. Если сервер даёт вход по коду, рядом в той же ошибке стоит вторая — страница входа с кодом (… or sign in from another device: <ссылка> (code …, valid until … UTC …)): отдай её человеку целиком со временем конца, он откроет её на любом устройстве, телефон подойдёт, и мост сам заберёт грант. Код живёт до названного времени, и до него каждый вызов отдаёт тот же код; новый выдаст только вызов после конца — тогда отдай новый. Мост говорит no sign-in by code: … — на сервере авторизации нет клиента входа по коду: передай человеку как ход оператора сервера, сам не обходи. Без страницы с кодом — ssh -L ПОРТ:127.0.0.1:ПОРТ <хост> и та же локальная ссылка, либо личный токен. Грант ложится в ~/.iskron-bridge/ и дальше обновляется сам.

Личный токен вместо OAuth — безголовая машина, CI, или вход не проходит раз за разом. Токен выпускает человек в веб-интерфейсе графа и отдаёт тебе; не выдумывай, не угадывай, не бери чужой.

mkdir -p ~/.iskron-bridge && (umask 077; printf '%s\n' "$ISKRON_TOKEN" > ~/.iskron-bridge/token)
node ~/.iskron-bridge/iskron-bridge.mjs doctor      # скажет, принят ли токен

Либо переменная ISKRON_BRIDGE_TOKEN в окружении процесса моста — она старше файла. С токеном мост не ходит в браузер вовсе; токен отвергнут — новый от человека в тот источник, что назван в ошибке; убран токен — мост вернётся к OAuth. В конфиг харнеса и в URL токен не пишется никогда.

Сервер: use

Без аргумента мост смотрит в https://mcp.iskron.ru. Человек говорит не по-русски — один раз, до первого входа, спроси, хочет ли он английскую версию Искрона:

node ~/.iskron-bridge/iskron-bridge.mjs use en      # mcp.iskron.ai; use ru — обратно; use <url> — другой сервер

Выбор пишется в ~/.iskron-bridge/server и доезжает до плагинной записи без аргументов. Грант у моста раздельный по адресу: смена адреса — новый вход. ISKRON_BRIDGE_URL или URL аргументом старше файла. Сервер не по умолчанию не угадывай — возьми у человека или из AGENTS.md репозитория.

Обновление

На рабочих адресах (mcp.iskron.ru, mcp.iskron.ai) мост обновляет себя сам и о свежем релизе говорит строкой ПОСТАВКА ОТСТАЛА в ответе тула — передай её человеку. После use <url> другого сервера релизы он не спрашивает вовсе — только по требованию:

node ~/.iskron-bridge/iskron-bridge.mjs update

Кладёт свежий мост, плагин OpenCode (если стоит) и SETUP.md в дом и печатает «Дальше»: скиллы обновляет канал харнеса по свежему SETUP.md, затем перезапусти сессии — мост прежней сборки живёт до конца своей. Какая сборка стоит — node <мост> --version.

Мост не поднять

Веб-клиент без stdio-серверов (claude.ai, ChatGPT в браузере) моста не поднимет — запасной путь: коннектор MCP клиента напрямую. Заводит его человек в настройках клиента: адрес — корень https://mcp.iskron.ru/ (английская версия — https://mcp.iskron.ai/), не окно app.* и не стенд; поля OAuth вручную не заполняются — клиент находит сервер авторизации по метаданным сам; прежний коннектор удаляется и заводится заново, не правится. В claude.ai и Claude Desktop сервер приезжает неавторизованным — после Install нажать Connect на вкладке Connectors. Тулы ответили — назови цену: места нет, кадры канала не доходят, записи подписаны ключом человека без места, слышимого ожидания в деле нет; для работы — плагин с мостом в харнесе со stdio-серверами (выше, «Моста или записи нет — поставь»).

Пути нет — ни моста, ни коннектора: машина без Node 22+ (кроме OpenCode, где мост идёт на его Bun), клиент без stdio и без коннекторов, нет браузера для входа и личного токена. Скажи человеку прямо, чего не хватает и чем это устранить; устранил — подключай заново.

Ошибки моста

Мост не отвечает тишиной: каждая его ошибка называет iskron-bridge, сборку, причину и вердикт — что делать. Читай его слово и делай, что оно велит; вердикт «исход неизвестен» после пишущего вызова значит «перечитай цель, прежде чем повторять». Вызовы висят без всякой ошибки — харнес говорит не с этим мостом: сверь doctor и процесс, который конфиг реально запустил. Сборка в ошибке старше релиза — сперва update и перезапуск сессий, потом разбор. История гранта словами сервера — ~/.iskron-bridge/grant.log.

Чего мост не советует сам:

• session recovery failed — сервер перезапустился и отверг переинициализацию: перезапусти MCP-соединение харнеса (переподключение сервера или новая сессия).
• all candidate callback ports … are held — мост просит освободить порт. Найди держателя: lsof -iTCP:ПОРТ -sTCP:LISTEN (Windows: netstat -ano | findstr :ПОРТ). Если это мост с незакрытым входом, SIGTERM (pkill) снимает его сразу, пока его локальную ссылку никто не открывал: запись входа остаётся, и следующий мост подхватит этот вход и отдаст тот же код. Ссылку уже открыли — он ждёт клика человека до пяти минут; не ждать — только kill -9, и начатый по ней клик пропадёт, ссылку откроют заново.
• Все агенты машины разом просят вход — обычно живы процессы моста прежней сборки, они не берут общий замок обновления и гасят грант. Найди их: ps ax | grep -E 'iskron-bridge|iskron\.mjs' (у плагинного моста версия стоит в пути). Затем update и перезапуск сессий со старой сборкой.
• В браузере после пароля — «в ссылке для входа не хватает обязательных параметров» (Windows; в ошибке моста этого нет): вкладку открыл мост прежней сборки и обрезал адрес. Открой ссылку моста из ответа тула целиком — http://127.0.0.1:ПОРТ/login?k=…, — затем update.