a1-yandex-kit-setup

A1 Yandex KIT のセットアップ

コミュニケーション

ユーザー向けのメッセージを送る前に、必ず ../a1-yandex-kit/references/merchant-communication.md を完全に読み、その内容を適用してください。

入力されたリクエストと音声の文字起こしのどちらでも、コンシェルジュ形式でセットアップを進めてください。 呼び出し元となった分岐から開始します。

• 短い案内リクエスト Связь с магазином の場合は、次の質問を1つだけします。 Что сделать: подключить магазин или переподключить его с новым токеном?
• 接続または再接続の具体的なリクエストは、必要な情報を収集し、候補のトークンが検証に合格した後に、選択したクライアントのユーザーレベルの MCP 設定を更新する許可となります。接続の再インストールとトークンの変更は、どちらも再接続リクエストです。

プロジェクトローカルのスキルをインストールしても、設定対象がそのプロジェクトだけに限定されるわけではありません。

設定と読み取り専用の直接スモークテストには scripts/setup.mjs を使用してください。 相対パスはすべて、ユーザーのプロジェクトではなく、このスキルディレクトリを基準に解決してください。

1. クライアントと前提条件を特定する

ホストから現在のクライアントを明確に判断できる場合は、それを推定してください。そうでない場合は、次の短い質問を1つだけします。 В каком приложении вы сейчас хотите подключить Яндекс KIT?

回答を次のいずれかに正規化してください。

claude-code、claude-desktop、cursor、codex、vscode、kimi、 kimi-desktop、hermes、openclaw。

Kimi Code と Kimi Desktop は別のクライアントとして扱ってください。Kimi Code CLI には kimi のみを使用し、Kimi Work デスクトップアプリには kimi-desktop を使用してください。ユーザーが「Kimi」とだけ言い、ホストから区別できない場合は、次のように質問します。 Вы используете приложение Kimi на компьютере или Kimi Code в терминале?

テスト済みのクライアントについては、次を実行します。

node "<skill-directory>/scripts/setup.mjs" status --client <client> --json

status は、トークンの要求や設定の変更を行う前に、Node.js 20+ と実行可能な npx の両方を確認します。いずれかの前提条件を満たせない場合は、オペレーティングシステムに適した Node.js のインストールリンクまたは手順を1つだけ提示し、そこで停止してください。インストールは、そのオペレーティングシステムのインストーラーに任せます。別のクライアントの場合は、独立した事前チェックを実行し、ステップ2の互換性ラダーに進みます。

Claude Code、Cursor、VS Code、Kimi Code では、status は、既知のプロジェクトまたはローカルスコープの yandex-kit という名前のサーバーが、ユーザーレベルのエントリーを上書きするかどうかも確認します。名前が完全に一致する場合は、管理対象の代替名 a1-yandex-kit-global を選択します。名前の異なる MCP サーバーはすべて無視します。以前に設定された正規の代替名は、後続の実行でも引き続き選択されます。

node "<skill-directory>/scripts/setup.mjs" preflight --json

status は、ラダーによってサポート対象の形式とパスが確定した後に限り、実行してください。 status が既存ファイルを解析できないと報告した場合は、そのファイルを保持したままステップ2に進んでください。互換性ラダーにより、この実行の残りの処理でネイティブ CLI が選択される場合があります。 Node.js 20+、npx、および1つのクライアントを特定できた時点で、このステップは完了です。

2. 互換性プロファイルを検証する

選択したクライアントについて references/client-profiles.md を読みます。クライアントの CLI を利用できる場合は、インストール済みクライアントのバージョンまたは MCP のヘルプを確認し、解決されたユーザーレベルのパスと設定形式がローカルのインストール環境に一致することを確認してください。

各情報が一致する場合は、テスト済みのプロファイルを使用します。解析できない設定は不一致として扱い、変更せずに互換性ラダーに進んでください。それ以外の不一致がある場合、クライアントが不明な場合、または上記に記載のないクライアントの場合は、references/compatibility.md を完全に読み、互換性ラダーを実行してください。ラダーでは、セットアップの残りの処理に使うアダプターを1つ選択します。検証済みの形式と絶対パスを使用するファイルアダプターか、文書化された追加コマンドと検証コマンドを使用するネイティブ CLI のいずれかです。解析できなかったファイルに対する既知のクライアント向けのネイティブ CLI フォールバックも含め、この選択をステップ3、4、5に引き継いでください。選択したアダプターが、ローカルの情報または最新の公式ベンダードキュメントによってサポートされていることを確認した時点で、このステップは完了です。

3. トークンを取得する

保存されているトークンを読み取ったり表示したりせず、選択したアダプターの証拠と status の結果を使用してください。対応するファイルアダプターがないネイティブ CLI の場合は、ドキュメントに記載された一覧表示／表示コマンドを使用してください。既存の管理対象 yandex-kit または a1-yandex-kit-global のエントリーは、トークンを読み取ろうとせずに configured: true として扱います。

具体的な接続や再接続を行うたびに token-route を実行し、同じ取得フローに従います。既存のトークンがある場合、ローカルのファイルアダプタールートでは、保護されたページの replace モードを選択します。チャットを選択したり、保護されたページを省略可能にしたりすることはありません。このルートで再接続する場合、置き換えを書き込む前に、必ず新しい1回限りのページ URL を取得します。ネイティブ CLI とホステッドルートでは、ドキュメントに記載された安全な入力方法またはシークレットの仕組みを使用し、明示的に選択された場合にのみチャットを使用します。

初回接続のリクエスト時に、すでにトークンが設定されている場合は、次のように尋ねます。 Токен Яндекс KIT уже сохранён в настройках. Хотите переподключить магазин с новым токеном?

• нет の場合は、次のメッセージで完了します。 Принято! Оставляем действующий токен Яндекс KIT без изменений. Всё работает в прежнем режиме.
• да の場合は、以下の手順に進み、再接続します。

トークンを求める前にオンボーディングする

どのルートでも、会話内で最初にトークンを求める前に、短いオンボーディングメッセージを1つ送信します。オーナーが使用する言語（merchant-communication.md）で、ストア接続後に任せられる業務を3つか4つ挙げ、残る手順がトークンの入力だけであることを伝えます。例：

После подключения мне можно будет поручать дела магазина: обновлять цены и остатки, следить за заказами, запускать акции и промокоды, наводить порядок в каталоге. Остался один шаг — токен магазина.

環境にルートを選択させる

node "<skill-directory>/scripts/setup.mjs" token-route --json

• route: "web" — デスクトップのループバックが利用できます。選択されたアダプターが検証済みのファイルアダプターの場合は、接続や再接続のたびに、以下のローカルの1回限りのページを使用します。環境の結果だけでは、アプリ内ブラウザーがヘルパーにアクセスできるとは限りません。ブラウザーとシェルが同じデスクトップ上で実行されていることを確認してください。
• route: "hosted" — セッションはリモートです（reason に SSH、コンテナー、またはヘッドレスを示すマーカーが含まれます）。そのため、ブラウザーからローカルページにアクセスできません。以下のホステッドルートを使用し、この環境で通常利用できるサポート対象のルートとして提示してください。開けないリンクをユーザーに渡さないよう、ページは完全に省略します。

ネイティブ CLI アダプター

互換性の選択手順でネイティブ CLI が選ばれた場合、構成を解析できなかったためにフォールバックした既知のクライアントも含め、すべての環境ルートでこのアダプターを使用します。現在、ネイティブ CLI には対応するページアダプターがありません。利用可能な場合は、クライアントのドキュメントに記載された安全な入力方法またはネイティブの認証情報設定を使用してください。ホステッドルートでは、環境優先の分岐を使用します。オーナーが明示的にそのルートを選択しない限り、チャットでトークンを要求しないでください。チャットで受け取ったトークンは、smoke-token --token-stdin で検証し、ステップ4で native-configure を使用して設定します。その後、ステップ5で references/compatibility.md に定められたネイティブの一覧表示／表示コマンド、またはテストコマンドを使って検証します。ホステッド環境からトークンが提供される場合は、代わりに、クライアントのドキュメントに記載された環境変数による受け渡しと読み取り専用の検証に従ってください。ファイルアダプターのないネイティブ CLI でチャットを使用する場合は、構成前の直接スモークがスモーク検証の証拠となります。このアダプターでは、ローカルページや、ファイルベースの status、client-check、スモークコマンドを選択しないでください。

ローカルの1回限りのページ（route: "web" + ファイルアダプター）

token-route が route: "web" を報告し、互換性の選択手順で検証済みのファイルアダプターが選ばれた場合に限り、この分岐を選択します。選択したアダプターについて、互換性の選択手順で確定したものと同じ --format、--config、--project-dir、--server-name フラグを渡して、ページを長時間実行するバックグラウンドプロセスとして起動します。

node "<skill-directory>/scripts/setup.mjs" token-web --client <client> --json

動的なファイルアダプターの場合は、これらのフラグを明示的に指定してください。完全一致の名前が衝突した場合の a1-yandex-kit-global も含め、選択したサーバー名をそのまま維持してください。 最初の stdout 行は {"url": …, "expires_in_seconds": …} です。expires_in_seconds から有効期間（デフォルトでは 5 分）を取得し、現在のホストで実際に公開されている機能をすぐに確認してください。このページは、所有者が使えるホスト管理の永続的なブラウザー画面に表示してください。

• Codex では、mcp__codex_app__open_in_codex が利用可能な場合、target: { type: "browser", url: <url> } を指定して呼び出してください（対応している場合は右側に配置します）。これは永続的な Codex ブラウザーパネルです。このページでは cua_repl、createBrowserTab、browser-use、コンピューター操作によるタブ作成を使わないでください。これらのアクティビティ単位のタブは、アシスタントのターン終了時に閉じることがあります。
• Claude Code または Claude Desktop では、現在のセッションでクライアント標準のブラウザーまたはプレビューペインを使用してください。一時的な browser-use タブや画面操作タブで代用しないでください。標準ペインが利用できない場合、ローカルページにアクセスできない場合、または所有者が使える永続的な表示ではない場合は、OS のオープナーを使い、その後、以下のクリック可能な URL のフォールバックを提示してください。

クライアント固有のブラウザー API、アーティファクトの iframe、スクリーンショットのワークフローをでっち上げないでください。また、トークンが入力済みのフォームを決して確認しないでください。組み込みブラウザーが利用可能であっても、このシェルのループバックが同じデスクトップに接続されているとは限りません（ブラウザーはクラウドセッションや VM で動作している場合があります）。適切な永続的なアプリ内機能が公開されていない場合は、OS のデフォルトブラウザーオープナーを使用してください。

node "<skill-directory>/scripts/setup.mjs" open-token-page --url <url> --json

ホストのポリシーで OS オープナーの起動が許可されていない場合は、そのコマンドを省略し、クリック可能なフォールバックとして URL を直接提示してください。

このコマンドは token-web が出力したループバックのワンタイム URL のみを受け付け、シェルを介さずに OS オープナーを使用します。オープナーが見つからない場合、または起動に失敗した場合は opened: false を返します。オープナーの失敗によって、実行中の token-web プロセスが停止することはありません。opened: false が返された場合は、ページを開いたままにし、返された URL をクリック可能なフォールバックとして提示してください。正常に開いた場合は、ワンタイムページが開いたことを所有者に伝え、expires_in_seconds から取得した実際の有効期間を知らせてください。ワンタイムページの URL に含まれるシークレットはストアトークンではありません。ストアトークン自体を記録、表示、要求しないでください。

所有者がトークンを入力している間、このコマンドはページの提供を続けます。書き込み前に smoke-token と同じ読み取り専用の get_store 検証を実行します（同じ外部ネットワークアクセスが必要です）。トークンが拒否された場合は、再試行回数の上限を設けずにフォームを再表示し、成功するとステップ 4 の configure 書き込みをそのまま実行します。最終 JSON には configure のフィールドと smoke が含まれます。configured: true が報告された場合、ステップ 3 と 4 は完了しています。ロールバック用の値（changed、backupPath、backupHash、configHash）を保持し、ステップ 5 に進んでください。

表示された有効期間は、検証を待つ時間と設定書き込みの開始までの時間に適用されます。検証に成功して永続化が始まった後は、有効期間が切れたりブラウザーが閉じたりしても、そのコミットは実際の成功またはエラーと完全なメタデータを返して完了します。永続化が始まる前に有効期間が切れた場合、token-web は TOKEN_WEB_TIMEOUT を返し、書き込みは行いません。

永続化の前に token-web が TOKEN_WEB_TIMEOUT で終了した場合は、期限切れの URL を破棄し、新しい token-web を実行してください。新しい URL でブラウザーを開く手順を繰り返し、期限切れの URL を再び開かないでください。その間、現在の設定は変更しないでください。TOKEN_WEB_UNAVAILABLE または TOKEN_WEB_ABUSE で終了した場合は、診断内容を説明し、現在の設定を変更しないでください。利用可能な場合は、文書化されたセキュア入力またはシークレットの経路を使用してください。所有者が明示的にチャットを選択するまでは、デフォルトでトークンのチャットへの貼り付けを要求または提案しないでください。チャットを利用できるのは、所有者が明示的に選択した後のみです。再接続にも同じ新しいワンタイムページの手順を使用します。

ホステッドルート（route: "hosted"）

まず、クライアントのセッション環境設定またはシークレット設定を案内してください。そこに保存したトークンが会話に入ることはありません。

Ассистент работает в удалённой сессии, поэтому локальная страница ввода токена здесь не откроется — это нормальный, предусмотренный маршрут. Надёжнее всего задать токен переменной YANDEX_KIT_TOKEN в настройках окружения или секретов этой сессии: тогда он не попадёт в переписку.

ユーザーがそれらの設定にトークンを保存したら、管理対象サーバーに変数を公開する方法についてクライアントのドキュメントに従い、ステップ 5 で接続を確認してください。ユーザーがその設定にアクセスできない場合は、チャットルートを明示的に使いたいかどうか尋ねてください。その選択を待ってからトークンを求め、選択されたアダプターブランチ（ネイティブ CLI の場合は native-configure、ファイルアダプターの場合は configure）に進んでください。依頼された作業が完了したら、次のことを一度だけ伝えてください。

Токен побывал в истории этого чата. Когда закончите задачу, его можно отозвать в кабинете Яндекс KIT: Настройки → API — и при необходимости выпустить новый.

明示的なチャットルート（オーナーが選択した場合のみ）

• オーナーがチャットを明示的に選択し、configured が false の場合は、次のように尋ねてください。 Для настройки потребуется токен Яндекс KIT. Чтобы его получить, зайдите в кабинет Яндекс KIT: Настройки → API и скопируйте ключ. Вставьте его сюда — я привяжу его к приложению и не буду повторять в ответе. Токен останется в истории этого чата и будет сохранён в пользовательском конфиге приложения.
• 再インストールやトークンの置き換えを含め、オーナーが再接続にチャットを明示的に選択した場合は、次のように尋ねてください。 Пришлите новый токен из **Настройки → API** — я обновлю подключение и не буду повторять его в ответе. Новый токен останется в истории этого чата и будет сохранён в пользовательском конфиге приложения.

チャットでトークンを受け取ってください。トークンをそのまま返答したり、要約、引用、ログへの記録、シェルコマンドへの埋め込みをしたりしないでください。新しいトークンは、setup.mjs への標準入力を通じてのみ渡してください。トークンの後に改行を 1 つ書き込みます。最初の改行で入力が終わるため、ヘルパーはただちに起動し、標準入力のパイプが閉じるのを待つことはありません。改行の後に標準入力を閉じても問題ありません。

新しいトークンまたは置き換えトークンを書き込む前に、読み取り専用の MCP スモークテストを直接実行して検証してください。

node "<skill-directory>/scripts/setup.mjs" smoke-token --token-stdin --json

smoke-token と smoke の実行には外部ネットワークへのアクセスが必要です。ヘルパーは npm レジストリにアクセスして mcp-yandex-kit@latest を起動し、Yandex KIT API にアクセスして get_store を実行します。Codex のようにシェルコマンドをサンドボックス化するホストでは、初回からネットワークアクセスを許可してこれらのコマンドを実行してください。まず隔離サンドボックスで試すのではなく、ネットワーク対応または権限昇格された実行モードをリクエストしてください。ヘルパーはサーバーを起動する前に接続を確認し、ネットワークがブロックされている場合は code: "NETWORK_UNAVAILABLE" で速やかに失敗します。その場合はトークンの問題と判断せず、同じコマンドをネットワークアクセスありで再実行してください。スモークテスト全体で共通の実時間制限が適用されるため、約 1 分以内に完了するか失敗します。

認証に失敗した場合（code: "SMOKE_AUTH"）は、トークン置き換え用のプロンプトで別のトークンを求め、検証が成功するかユーザーが明示的にキャンセルするまで繰り返してください。再試行回数に上限を設けないでください。設定はまだ開始されていないため、キャンセルしても現在のクライアント設定は変更されません。その他のスモークテストの失敗は、それぞれの診断として扱い、別のトークンを求めないでください。

ローカルページで configured: true が報告された場合、または候補となるトークンのいずれかで get_store が成功した場合に、このステップは完了です。既存の初回接続に対して明示的に нет が選ばれた場合は、この時点に達することなくスキルが終了します。

4. ユーザーレベルのクライアントを設定する

ローカルページ経由で保存されたトークンは設定済みです。token-web がこの手順の書き込みを実行したので、報告された値を使って手順 5 に進んでください。

選択したネイティブ CLI アダプターでチャットから受け付けたトークンについては、既知のクライアントからのネイティブフォールバックも含め、 references/compatibility.mdに従い、 native-configureを実行します。このヘルパーは標準入力からトークンを読み取り、ドキュメントに記載された子プロセスの引数にトークンを代入します。トークンをエージェントが発行するシェルコマンドやシェル履歴に含めず、出力からも伏せます。この分岐では、ファイルアダプターのconfigureコマンドを実行しないでください。

選択したファイルアダプターでチャットから受け付けたトークンについては、ヘルパーを対話型プロセスで実行し、トークンの後に改行を付けて標準入力に書き込みます。改行によって入力が完了するため、ヘルパーはパイプが閉じるまで待機しません。既知のプロファイルでは、次を使用します。

node "<skill-directory>/scripts/setup.mjs" configure --client <client> --token-stdin --json

動的ファイルアダプターでは、ラダーによって確認された機能とパスがある場合、それらを渡します。

node "<skill-directory>/scripts/setup.mjs" configure --client <label> --format <format> --config <absolute-path> --token-stdin --json

どちらの方法でも、正規サーバーは常に次のとおりです。

npx -y mcp-yandex-kit@latest

選択した管理対象エントリーのみを追加または更新してください。名前の異なるすべてのMCPサーバーと、無関係なクライアント設定はそのまま維持してください。別のサーバーを削除、名前変更、無効化、書き換えしないでください。プロジェクトまたはローカルの完全一致するyandex-kitエントリーがユーザーレベルの名前と競合する場合、そのエントリーには手を加えず、代わりにa1-yandex-kit-globalを設定してください。

開始時に選択した具体的なセットアップ依頼を設定の承認として扱い、ホストアプリケーションで避けられないファイルシステムの承認のみを提示してください。既存の設定を安全に解析できない場合は変更せず、互換性ラダーに戻って、クライアントのドキュメントに記載されたネイティブ CLIを試してください。ネイティブ方式も利用できない、または失敗した場合にのみ、技術的な引き継ぎを行ってください。

ファイルアダプターでは、ヘルパーがconfigured: trueを報告し、トークンが印字されずに存在し、無関係なクライアント設定が維持され、変更対象の既存設定ごとにバックアップが存在すると、この手順は完了です。POSIXシステムでは、変更後の設定ファイルとそのバックアップのモードは0600でなければなりません。ネイティブ CLIでは、ドキュメントに記載された追加コマンドが正常に終了すると、この手順は完了です。設定の変更はクライアントが行います。

5. 接続を証明する

テスト済みのファイルアダプターでは、ヘルパークライアントのチェックを実行します。

node "<skill-directory>/scripts/setup.mjs" client-check --client <client> --json

非対話型の MCP 診断機能がない GUI クライアントでは、structural を期待されるクライアントチェックとして扱います。動的ファイルアダプターでは、公式ドキュメントに基づいて確立されたクライアントレベルの検証を使用し、ラダーで検証済みの形式とパスを維持します。ヘルパーの client-check は、テスト済みのファイルプロファイルにのみ使用します。選択したネイティブ CLI アダプターでは、互換性ラダーに記載された文書化済みの list/show コマンドまたは test コマンドを使用して、実際に有効な管理対象定義を正確に検証します。ネイティブアダプターでは、ファイルベースの client-check コマンドは使用しません。

ファイルアダプターのクライアントチェックでは、名前がリストに表示されることだけでなく、実際に有効な管理対象定義を検証する必要があります。ローカルで変更されたクライアントのパスや優先順位ルールが原因で引き続き SERVER_SHADOWED になる場合は、configure、client-check、smoke に --server-name a1-yandex-kit-global を渡して、同じ検証済みトークンを a1-yandex-kit-global の下に一度だけ設定します。シャドウイングしているプロジェクトのエントリーと、その他すべての MCP サーバーは変更しないでください。

ファイルアダプターでは、続けて次を実行します。

node "<skill-directory>/scripts/setup.mjs" smoke --client <client> --json

動的アダプターでは、検証済みの --format フラグと --config フラグを繰り返し使用します。サポート対象のファイルアダプターがない、選択したネイティブ CLI では、手順 3 の成功した直接スモークテストを使用し、ファイルベースの smoke --client コマンドは実行しないでください。 スモークテストでは、MCP の初期化ハンドシェイクを完了し、ツールを一覧表示して get_store を見つけ、get_store のみを呼び出す必要があります。書き込みツールは呼び出してはなりません。

パス、スキーマ、またはクライアントコマンドが変更されたために選択したファイルアダプターが失敗した場合は、configure または token-web が changed: true を報告したときに限り、この実行での変更だけを元に戻してから、互換性分岐を実行します。既存の設定の場合は、この実行で返されたロールバック値をすべて使用します。どちらのヘルパーも同じフィールドを報告します。

node "<skill-directory>/scripts/setup.mjs" rollback --config <configPath> --backup <backupPath> --backup-hash <backupHash> --expected-hash <configHash> --json

この実行で設定ファイルを作成した場合は、次を使用します。

node "<skill-directory>/scripts/setup.mjs" rollback --config <configPath> --created --expected-hash <configHash> --json

ハッシュチェックによってロールバックが拒否された場合は、新しい設定を保持し、そのパスを報告します。書き込み後のチェックで認証失敗が報告された場合は、この実行によるファイル変更があれば元に戻してから、手順 3 の無制限トークン検証ループに戻ります。設定が不正な形式の場合は修復せず、技術担当への引き継ぎを行う前に、文書化されたネイティブ CLI を試してください。

選択したアダプターの検証に合格し、この実行中に読み取り専用のスモークテストの証明にも合格したら、この手順は完了です。テスト済みのファイルアダプターでは client-check とファイルベースの smoke を使用し、動的ファイルアダプターではベンダーの検証とファイルベースの smoke を使用します。チャットで設定されたネイティブ CLI ではネイティブ検証と、設定前に成功した smoke-token の結果を使用します。ホスト環境優先のネイティブ CLI では、文書化された読み取り専用の証明を使用します。

6. ホスト側で停止せずに作業できるようにする

接続が証明されたら、 references/approval-policies.md を最後まで読んでください。ストアが以前に接続されていた場合でも、インポート中に Allow のプロンプトが繰り返し表示されるとユーザーが報告したときは、同じ分岐を使用します。

現在のクライアントの機能を調べ、この許可によって現在および将来のすべての Yandex KIT ツールが対象になることを伝え、このコンピューターで Работу без остановок を有効にするか一度だけ尋ねます。да の後、管理対象サーバーのワイルドカードを適用します。許可を得る前に、警告で削除、注文、プロモーション、ストア管理を明示しなければなりません。後から追加された個々のツールについて、再度尋ねてはなりません。

ヘルパーが automatic、guided、または unsupported を報告し、作業開始前に必要な再起動や UI 操作が残っていれば、ユーザーがその内容を把握した時点で、この手順は完了です。

7. 簡単に完了する

検証済みのクライアントに、ドキュメントに記載された非対話型の再読み込みコマンドがある場合に限り、MCP を自動的に再読み込みしてください。それ以外の場合は、references/client-profiles.md にある再起動の指示を 1 つだけ提示してください。アプリケーションを強制終了しないでください。

次のような短い結果で締めくくってください。

Готово — Яндекс KIT подключён к Cursor. Проверка прошла: вижу магазин «Название».

設定内容、トークンの一部、診断ダンプ、追加のターミナルコマンドは表示しないでください。ユーザーに選択したクライアントとストアのチェック成功が表示され、必要な場合の再起動操作が 1 つ以下であれば、セットアップは完了です。