establish-mcp

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

Все прочие скиллы поставки предполагают, что тулы iskron_* уже в сессии. Этот скилл их туда приводит — и кончается сессией, в которой ответил вызов iskron_me или iskron_orient.

Когда звать

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

Когда не звать. Хоть один тул 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 печатается при загрузке скилла).

Подписку инбокса роли мост не ставит и не чинит; стоящие хуки не удаляет. Очередь роли — iskron_orient(focus=<роль>) на входе и по поводу; кадр приходит адресату и участникам дела. Отсутствие подписки — не поломка транспорта, doctor и сторож её не проверяют.

Первый ход — doctor

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

Одна команда, ничего не правящая: сборка моста и Node, домашняя копия против этого файла, свежий релиз, адрес сервера и откуда он взят, ответ сервера, грант (или личный токен — живым рукопожатием), записи в конфигах харнесов (Claude Code, OpenCode, Codex) и раздел «субагенты» — у каждого файла агента проекта своя запись моста-спутника, исполнимая на этой ОС, и пробный запуск спутника: ответил ли он и примет ли API схемы его тулов (пробный спутник — сам мост и пишет то же, что мост). Зови его из каталога проекта: записи 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

Прочие харнесы: { "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 в конфиге (она переименует тулы и смешает сессии), а плагин поставки, вторым файлом тем же ходом:

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

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

Codex

Манифест плагина несёт запись 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_THREAD_ID и CODEX_HOME, которые Codex кладёт в окружение команд). Ему нужна дверь — демон codex app-server daemon start под коротким CODEX_HOME и песочница треда, пускающая к ~/.iskron-bridge; это ход человека до запуска сессии, порядок — в SETUP.md. Открыта ли дверь, говорит doctor; нет её — сторож выйдет кодом 2, передай его слова человеку и слушай watchdog-exit. Как держать сторожа — скилл 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 …)): отдай её человеку целиком со временем конца, он откроет её на любом устройстве, телефон подойдёт, и мост сам заберёт грант. Код живёт до названного времени, и до него каждый вызов отдаёт тот же код; новый выдаст только вызов после конца — тогда отдай новый. Вход по коду требует клиента на сервере авторизации — iskron-bridge (иной — ISKRON_BRIDGE_DEVICE_CLIENT) с аудиторией адреса mcp; его заводит оператор сервера. Нет клиента — мост кода не даёт и говорит это в той же ошибке (no sign-in by code: …): передай человеку как ход оператора, сам не обходи. Без страницы с кодом — ssh -L ПОРТ:127.0.0.1:ПОРТ <хост> и та же локальная ссылка, либо личный токен. Грант ложится в ~/.iskron-bridge/ и дальше обновляется сам.

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

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

Сервер: use

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

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

Обновление

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

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

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

Харнес без stdio-серверов MCP (claude.ai и подобные) или машина без Node 22+ (кроме OpenCode, где мост идёт на его Bun) — пути к графу нет. Скажи человеку прямо, чего не хватает: Node или харнеса со 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, и начатый по ней клик пропадёт, ссылку откроют заново. Мост сборки старше 7.3.0 ждёт клика и без открытой ссылки.
• Все агенты машины разом просят вход — обычно живы процессы моста прежней сборки, они не берут общий замок обновления и гасят грант. Найди их: ps ax | grep -E 'iskron-bridge|iskron\.mjs' (у плагинного моста версия стоит в пути). Затем update и перезапуск сессий со старой сборкой.
• В браузере после пароля — «в ссылке для входа не хватает обязательных параметров» (Windows; в ошибке моста этого нет): вкладку открыл мост прежней сборки и обрезал адрес. Открой ссылку моста из ответа тула целиком — http://127.0.0.1:ПОРТ/login?k=…, — затем update.