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 です。ブリッジは自動でブラウザーを開こうとします。リンクをユーザーに渡し、ログイン後に呼び出しを再試行してください。リンクはマシン全体で共有され、少なくとも1つのブリッジが待ち受けている間は有効です。ブラウザーを開かない場合は、ISKRON_BRIDGE_NO_BROWSER=1 または --no-browser を指定します。ブリッジはリンクを表示するだけになります。リンクはブリッジが動作するマシン上でのみ有効です。サーバーがコードによるログインを提供している場合、同じエラーにもう1つのリンクとして、コード付きのログインページ（… 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 を参照します。ユーザーがロシア語を話さない場合は、最初のログイン前に一度だけ、Iskron の英語版を使うか尋ねてください。

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 の後、Connectors タブで Connect をクリックしてください。ツールが応答したら、制約を伝えてください。利用枠がないこと、チャネルのフレームが届かないこと、記録が利用枠のないユーザーのキーで署名されていること、案件に聞き取り可能な待機時間がないことです。実際の作業には、stdio サーバーを使うハーネス内のブリッジ付きプラグインを使用してください（上記「ブリッジまたは記録がない場合 — インストールする」を参照）。

利用できる方法がない場合 — ブリッジもコネクターも使えません。Node 22+ がないマシン（ブリッジが同梱の Bun で動作する OpenCode を除く）、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.