Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazonアプリストア
Ring
AWS
ドキュメント
Support
Contact Us
My Cases

Console

as

開発
設計と開発
公開
リファレンス
サポート

AI活用開発に向けたAmazon Devices Builder Toolsのトラブルシューティング

AI活用開発に向けたAmazon Devices Builder Toolsのトラブルシューティング

このページでは、AI活用開発に向けたAmazon Devices Builder Toolsをセットアップして使用するときに発生する可能性のある一般的な問題の解決方法について説明します。これには、接続エラー（MCP error -32000: Connection closed）、コンテキストドキュメントが見つからない問題、スキルがトリガーされない問題などが含まれます。各項目には、問題の説明、考えられる原因、および段階的な解決策が含まれています。

セットアップの手順については、AI活用開発に向けたAmazon Devices Builder Toolsのセットアップを参照してください。

トラブルシューティングを行う前に

Amazon Devices Builder Toolsが実行されていて、AIエージェントに接続されていることを確認します。エージェントのチャットで、以下のように入力します。

クリップボードにコピーしました。

   List the tools provided by Amazon Devices Builder Tools

応答として、analyze_perfetto_traces、get_app_hot_functions、list_documents、read_asset、read_document、search_documentation、symbolicate_acrのようなツールが表示されます。

check-statusコマンドを実行して、セットアップを検証することもできます。

クリップボードにコピーしました。

   npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest check-status

完全に構成されている場合、次のような出力が表示されます。

Agent                  │ Context Document         │ MCP Configuration
───────────────────────┼──────────────────────────┼──────────────────────────
Kiro                   │ ✅ v5.1                   │ ✅ Configured

📊 Summary:
   Total agents checked: 1
   ✅ Fully configured: 1

ツールの一覧が表示され、check-statusでエージェントが完全に構成されていることが示されたら、MCPサーバーは機能しています。そうでない場合は、以下のセクションで説明する問題を参照してください。

よくある問題

ほとんどの問題では、最初の手順として、プロジェクトディレクトリからcheck-statusを実行してください。これにより、サポートされているすべてのエージェントについて、コンテキストドキュメント（存在、バージョン、破損の有無）とMCP構成が検証されます。

原因： MCPサーバーのインストールまたは構成に問題があるか、構成後にAIエージェントの再起動が必要です。

解決策：

  1. MCPサーバーのインストールを確認します。

    クリップボードにコピーしました。

    npx @amazon-devices/amazon-devices-buildertools-mcp@latest --help

    パッケージが正しくインストールされている場合は、使用できるコマンドの一覧（init-context、check-status）がヘルプメッセージに表示されます。

    パッケージがインストールされていない場合は、「command not found」またはモジュールの解決エラーが表示されます。セットアップコマンドを実行してインストールしてください。

  2. AIエージェントの設定ファイルで、mcpServersの下にamazon-devices-buildertools-mcpエントリが存在することを確認します。
  3. 構成変更後、AIエージェントを再起動します。

  4. Amazonデバイス固有の質問をたずねて、修正されたかどうかを確認します。

    例： 「How do I build a Vega app?」

    エージェントがAmazonデバイス固有の手順で応答すれば、問題は解決されています。

ドキュメントがamazon-devices-buildertools-mcpのバージョンに含まれていないというエラーメッセージが表示される

原因： ドキュメント名にタイプミスがあるか、ドキュメントが存在しない、またはMCPサーバーのバージョンが古い可能性があります。

解決策：

  1. 入手可能なドキュメントを一覧表示します。

    クリップボードにコピーしました。

    Show me all the documents in Amazon Devices Builder Tools
  2. 使用したドキュメントの名前を、手順1で返された一覧と比較します。名前が存在し、スペルが完全に一致することを確認してください。

  3. init-contextを再実行して、コンテキストドキュメントを更新します。npxコマンドで@latestを使用すると、常に最新リリースが取得されます。

    クリップボードにコピーしました。

    npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context
  4. 正しい名前を使用してドキュメントリクエストを再試行します。ドキュメントが読み込まれると、問題は解決します。

AIエージェントがAmazonデバイス固有のガイダンスではなく一般的な応答を生成する

原因： コンテキストの初期化が完了していないか、コンテキストファイルが見つからないか、AIエージェントがコンテキストファイルを認識していない可能性があります。

解決策：

  1. プロジェクトディレクトリからcheck-statusを実行します（トラブルシューティングを行う前にを参照）。出力に問題が報告された場合は、提示された推奨手順に従います。

  2. check-statusの結果、コンテキストドキュメントが見つからないか古くなっていると報告された場合は、init-contextを再実行します（開始の手順を参照）。

  3. 現在のチャットの会話を閉じ、新しいチャットを開始します。

  4. Amazonデバイス固有の質問をたずねて、エージェントから適切なガイダンスが提供されるかどうかを確認します。

    例： 「Can you list all documents related to feature development on Vega?」

    エージェントがAmazonデバイス固有のガイダンスで応答すれば、問題は解決されています。

エージェントスキルが自動的にトリガーされない

原因： AIエージェントでスキルが検出されるようにするには、コンテキストの初期化が必要です。適切に設定されていない場合、エージェントはスキルのメタデータを認識できません。

解決策：

  1. プロジェクトディレクトリからcheck-statusを実行して、スキルのインストールを含むセットアップ全体を検証します（トラブルシューティングを行う前にを参照）。

  2. check-statusで問題が報告された場合は、init-contextを再実行して、スキルを正しくインストールします（開始の手順を参照）。

  3. エージェントのグローバルスキルディレクトリにSKILL.mdファイルが存在することを確認します。一般的なスキルディレクトリの場所は次のとおりです。

    AIエージェント スキルディレクトリのパス
    Kiro ~/.kiro/skills/
    Cursor ~/.cursor/skills/またはプロジェクトルートの.cursor/skills/
    Claude Code ~/.claude/skills/

  4. AIエージェントセッションを再起動します。

    スキルはプロンプトマッチングに基づいてトリガーされます。スキルに関連する固有のキーワードを使用してください。

    例： amazon-devices-vega-setup-sdkスキルの場合は「Set up Vega SDK」

  5. それでもスキルがトリガーされない場合は、まず使用可能なスキルの一覧を取得します。

    クリップボードにコピーしました。

    List all available Amazon Devices Builder Tools skills

    次に、特定のスキルを参照します。

    クリップボードにコピーしました。

    Use the amazon-devices-vega-build-and-run skill to help me deploy my app

    スキルがトリガーされ、手順のガイドが提供されれば、問題は解決しています。

不要なエージェントスキルが自動的に読み込まれる

原因： init-contextコマンドは、使用可能なすべてのエージェントスキルをグローバルにインストールします。ワークフローに関係のない特定のスキルを削除できます。

解決策：

  1. AIエージェントのスキルディレクトリを特定します（スキルディレクトリの場所を参照）。

  2. 削除するスキルのSKILL.mdファイルを削除します。

    たとえば、amazon-devices-vega-media-playerスキルを削除するには、次のコマンドを実行します。

    クリップボードにコピーしました。

    rm ~/.kiro/skills/amazon-devices-vega-media-player/SKILL.md

  3. AIエージェントセッションを再起動します。削除したスキルはトリガーされなくなります。

amazon-devices-buildertools-mcpを読み込めない

構成を追加した後、IDEがMCPの初期化に失敗し、次のエラーが表示されます。

MCP error -32000: Connection closed

原因： パッケージのインストールに失敗したか、Nodeバージョンが一致しません。

解決策：

  1. IDEの外部でパッケージが動作することを確認します。

    クリップボードにコピーしました。

    npx @amazon-devices/amazon-devices-buildertools-mcp@latest --help

    ヘルプメッセージが表示されたら、パッケージは正しくインストールされています。手順3に進んでください。

  2. コマンドが失敗する場合は、パッケージをグローバルにインストールします。

    クリップボードにコピーしました。

    npm install -g @amazon-devices/amazon-devices-buildertools-mcp@latest

  3. 現在のNodeバージョンでパッケージが表示されることを確認します。

    クリップボードにコピーしました。

    npm list -g

    各Nodeバージョンは、それぞれ固有のグローバルインストールを保持しています。たとえば、nvm use 20 && npm list -gで表示される一覧は、nvm use 22 && npm list -gの一覧とは異なります。

  4. 現在のチャットの会話を閉じ、新しいチャットを開始します。

  5. 使用可能なツールの一覧をエージェントにたずねます。

    例： 「What tools does Amazon Devices Builder Tools provide?」

    エージェントの応答としてツールの一覧が返されれば、問題は解決しています。

amazon-devices-buildertools-mcpがasdfで動作しない

原因：asdfは、直接のノードバイナリではなくシェルスクリプトラッパーを作成します。MCPサーバーは実際のノードバイナリを想定しているため、標準のnpxベースの構成はCLIでは機能しますが、IDEではMCP error -32000: Connection closedで失敗します。

解決策：

  1. MCPをインストールします。

    クリップボードにコピーしました。

    npm install -g @amazon-devices/amazon-devices-buildertools-mcp@latest

  2. Nodeバイナリのパスを取得します。

    クリップボードにコピーしました。

    % asdf which node

    次のような出力が表示されます。

    ~/ASDF_DATA/installs/nodejs/22.20.0/bin/node

  3. amazon-devices-buildertools-mcpバイナリのパスを取得します。

    クリップボードにコピーしました。

    % asdf which amazon-devices-buildertools-mcp

    次のような出力が表示されます。

    <>/ASDF_DATA/installs/nodejs/22.20.0/bin/amazon-devices-buildertools-mcp

  4. 手順2と3のパスを使用して、AIエージェントのMCP設定ファイルを更新します。プレースホルダーのパスを実際の出力に置き換えてください。

    クリップボードにコピーしました。

    "amazon-devices-buildertools-mcp-npx": {
    "type": "stdio",
    "command": "<>/ASDF_DATA/installs/nodejs/22.20.0/bin/node", // 上記でコピーしたパス
    "args": [
        "<>/ASDF_DATA/installs/nodejs/22.20.0/bin/amazon-devices-buildertools-mcp" // 上記でコピーしたパス
   ]
},

  5. 現在のチャットの会話を閉じ、新しいチャットを開始します。

  6. 新しいチャットで、使用可能なツールの一覧をエージェントにたずねて、ツールが読み込まれていることを確認します。

    例： 「What tools does Amazon Devices Builder Tools provide?」

npmパッケージのページが日本語で提供されない

原因： Amazon Devices Builder Toolsのnpmパッケージのページ（英語のみ）は、英語でのみ提供されています。npmレジストリは日本語ロケールをサポートしていません。

解決策：

代わりに、メインのセットアップページのセットアップ手順を使用してください。このページには日本語版があり、必要なインストールと構成の手順がすべて記載されています。npmコマンド（npx、npm install）は、ロケールにかかわらず同じように動作します。

Gemini CLIでプロジェクトディレクトリからステアリングドキュメントが読み込まれない

原因： Gemini CLIには、プロジェクトディレクトリにインストールされているGEMINI.mdステアリングドキュメントが読み込まれないという既知の問題があります。詳細については、google-gemini/gemini-cli（英語のみ）を参照してください。

解決策：

ファイルが自動的に読み込まれるようにするには、ファイルをホームディレクトリにコピーします。

クリップボードにコピーしました。

   cp GEMINI.md ~/.gemini/GEMINI.md

または、Gemini CLIセッションでread GEMINI.mdと入力して、手動でファイルを読み込みます。

GitHub Copilotでステアリングドキュメントが読み込まれない

原因： GitHub Copilotでは、一部の構成でAGENTS.mdステアリングドキュメントが自動的に読み込まれないことがあります。これは既知の問題です。詳細については、community/discussions（英語のみ）を参照してください。

解決策：

Copilotのチャットセッションでread AGENTS.mdと入力して、コンテキストを手動で読み込みます。

アプリの移行ワークフローで期待どおりの結果が得られない

原因： アプリの移行ワークフロー（アプリの移植）はベータ版であり、以下の移行パスのみをサポートしています。

  • Fire OS WebViewアプリ → Vegaウェブアプリ
  • Fire OS React Nativeアプリ → VegaScriptアプリ
  • 汎用TVアプリ → Vegaアプリ（アプリタイプの自動検出に対応）

これらのパスに該当しない移行や、カスタムのネイティブモジュール、マルチアクティビティアーキテクチャ、大幅にカスタマイズされたFire OS APIを含む複雑な移行では、期待どおりの結果が得られない場合があります。

解決策：

  • アプリが、サポートされている上記の移行パスのいずれかに一致していることを確認します。
  • 複雑な移行では、自動化されたワークフローに加えて手動の移行手順が必要になる場合があります。
  • パスがサポートされていることを確認したら、移行プロンプトを再実行します。

それでもワークフローで予期しない出力が生成される場合は、AIエージェントのチャットで「I want to provide feedback」というプロンプトを使用して、フィードバックを送信してください。

Last updated: 2026年5月20日

フォローする

サポート対象デバイス

amazon_developer_logo

© 2010-2026, Amazon.com, Inc. or its affiliates. All Rights Reserved. 無断複写·転載を禁じます。

利用規約

Amazon開発者ブログ

お問い合わせ