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，或反复登录失败的情况。令牌由用户在图谱的 Web 界面中生成并交给你；不要编造、猜测或拿别人的令牌。

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 服务的 Web 客户端（claude.ai、浏览器中的 ChatGPT）无法启动桥接程序——备用方案是直接配置 MCP 客户端连接器。由用户在客户端设置中添加：地址填写根路径 https://mcp.iskron.ru/（英文版为 https://mcp.iskron.ai/），不要填写 app.* 页面或测试环境；无需手动填写 OAuth 字段——客户端会根据元数据自行查找授权服务器；删除旧连接器并重新添加，不要修改旧连接器。在 claude.ai 和 Claude Desktop 中，服务器会以未授权状态添加——点击 Install 后，再在 Connectors 选项卡中点击 Connect。工具有响应后，说明限制：没有空间、频道帧无法送达、记录使用的是没有空间的用户密钥签名，案例中也没有可感知的等待状态；要正常工作，请在带有 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.