@amazon-devices/amazon-devices-buildertools-mcp 0.1.23 → 0.1.26

package/README.ja.md

@@ -0,0 +1,388 @@
+# Amazon Devices Builder Tools MCP サーバー
+
+[English](README.md) | **日本語**
+
+Model Context Protocol (MCP) サーバーで、AIエージェントがAmazonの[Vega OS](https://developer.amazon.com/apps-and-games/vega)向けアプリの開発とデバッグを行うためのコンテキストとツールを提供します。
+
+## 移行のお知らせ
+
+> **重要**: このMCPサーバーは `@amazon-devices/vega-devtools-mcp` から `@amazon-devices/amazon-devices-buildertools-mcp` に名称変更されました。以前のバージョンをインストールしている場合は、MCPの設定を更新して `@amazon-devices/vega-devtools-mcp` を削除し、`@amazon-devices/amazon-devices-buildertools-mcp` サーバーを使用して最新のアップデートと機能を受け取ってください。
+
+## 機能
+
+Amazon Devices Builder Tools MCPは以下の機能をサポートしています：
+
+| アプリ開発領域 | 説明 | プロンプト例 |
+|--------------|-------------|-----------------|
+| **オンボーディング** | セットアップガイダンスとQ&Aサポートを使用して、AIエージェントでVegaアプリ開発にオンボード | <ul><li>`Vegaアプリプロジェクトをセットアップして、仮想デバイスでVPKGをテストするのを手伝ってください`</li><li>`Vega SDKのセットアップを手伝ってください`</li><li>`仮想デバイス/接続デバイスでアプリをビルドして実行してください`</li><li>`Vegaアプリ開発について教えてください`</li><li>`VegaデバイスでCPU使用率を測定するためのVega CLIコマンドは何ですか？`</li></ul> |
+| **パフォーマンス** | Time to First Frame (TTFF)、Time to Fully Drawn (TTFD)、およびUI再レンダリングの問題をデバッグして修正 | <ul><li>`なぜ私のVegaアプリのTTFFが高いのですか？`</li><li>`VegaアプリのTime to First Frameの問題をデバッグして修正するのを手伝ってください`</li><li>`なぜ私のVegaアプリのTTFDが高いのですか？`</li><li>`アプリの不要な再レンダリングを最小限に抑えるのを手伝ってください`</li><li>`アプリの再レンダリングの問題を見つけてください`</li></ul> |
+| **パフォーマンスベストプラクティス** | コンポーネントとコードを分析して、React Native Vegaのパフォーマンスベストプラクティスに従っているかを確認 | <ul><li>`このコンポーネントがReact Native Vegaのパフォーマンスベストプラクティスに従っているか分析するのを手伝ってください`</li></ul> |
+| **ベストプラクティス** | マニフェストファイルを検証し、ベストプラクティスに従ってVegaコンポーネントを実装 | <ul><li>`MovieCarousel.tsxをCarousel V1からV2にアップグレードするのを手伝ってください`</li><li>`Carouselの実装を手伝ってください`</li><li>`マニフェストファイルを検証して、アプリに必要な更新を行ってください`</li></ul> |
+| **UI開発** | スクリーンショットとデザインモックアップからVegaアプリのUIを作成 | <ul><li>`{image_path}に画像があります。サンプルテンプレートを使用して新しいフォルダを作成し、画像に合わせてサンプルテストアプリを更新して、アプリをビルドして実行できることを確認してください。`</li></ul> |
+| **フォーカス管理** | TVインターフェース用のD-Padナビゲーションとフォーカス管理を実装 | <ul><li>`フォーカス管理を示すために2つのボタンを持つアプリを作成できますか？`</li></ul> |
+| **SDK & CLI** | SDKのインストール/更新と、仕様駆動型CLIを介した効率的なCLIツールの実行 | <ul><li>`AIエージェントからSDKをインストール/更新`</li><li>`アプリをビルド`</li><li>`仮想デバイスでアプリを実行`</li><li>`物理デバイスでアプリを実行`</li><li>`KPI Visualizerを実行してパフォーマンス結果を取得`</li></ul> |
+| **クラッシュ分析**              | JavaScript、Native、LMK、ANRクラッシュの自動ACR分析による診断                    | <ul><li>`なぜアプリがクラッシュしたのですか？`</li><li>`このACRファイルを分析してください /path/to/crash.acr`</li></ul>                                                                                                                                                                                                                                                |
+| **フィードバックの提供** | MCPの使用体験についてAmazonにフィードバックを提供 | <ul><li>`フィードバックを提供したい`</li><li>`Vega MCPのフィードバックを提供するにはどうすればよいですか？`</li></ul> |
+
+## ワンクリックインストール
+
+一部の人気のあるAIエージェントは、ワンクリックでMCPサーバーをインストールすることをサポートしています。以下は利用可能なワンクリックインストールオプションです。
+
+### KiroにMCPをインストール
+
+[![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=amazon-devices-buildertools-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40amazon-devices%2Famazon-devices-buildertools-mcp%40latest%22%5D%2C%22disabled%22%3Afalse%7D)
+
+### CursorにMCPをインストール
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=amazon-devices-buildertools-mcp&config=eyJjb21tYW5kIjoibnB4IC15IEBhbWF6b24tZGV2aWNlcy9hbWF6b24tZGV2aWNlcy1idWlsZGVydG9vbHMtbWNwQGxhdGVzdCJ9)
+
+### VSCodeにMCPをインストール
+
+[Add to VSCode](vscode:mcp/install?%7B%22name%22%3A%22amazon-devices-buildertools-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40amazon-devices%2Famazon-devices-buildertools-mcp%40latest%22%5D%7D)
+
+
+## スクリプトによるインストール
+
+以下のコマンドを実行して、AIエージェントにAmazon Devices Builder Tools MCPを**自動的に**インストールし、AIエージェントをガイドするためのVega固有のコンテキストドキュメントをプロジェクトに追加します：
+
+> ℹ️ 重要: MCPのワンクリックインストール後でも、`npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context` を実行して、プロジェクトディレクトリに優先AIエージェント用のVegaコンテキストドキュメントをインストールすることが重要です。
+
+> ⚠️ **非推奨のお知らせ**: `--init-context` フラグは非推奨であり、将来のバージョンで削除されます。代わりに `init-context` サブコマンドを使用してください。
+
+```bash
+# 推奨（新しいサブコマンド）
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context
+
+# 非推奨（削除予定）
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest --init-context
+```
+
+このコマンドは**インタラクティブ**モードと**非インタラクティブ**モードの両方をサポートしています：
+
+**インタラクティブモード（デフォルト）:**
+1. **利用可能なAIエージェント**とそのコンテキストファイル要件を表示
+2. サポートされているリストから**優先AIエージェントを選択**
+3. Amazon Devices Builder Tools MCPサーバーを設定するために**選択したエージェントのMCP設定を更新**
+4. **コンテキストインストールディレクトリを尋ねる**（デフォルトは現在の作業ディレクトリ）
+5. マージまたは更新コンテンツを提供することで**既存のコンテキストファイルを処理**
+6. 選択したAIエージェントの正しい場所に**適切なコンテキストファイルを作成**
+
+**非インタラクティブモード:**
+コマンドラインオプションを使用してプロンプトをスキップし、セットアッププロセスを自動化します。
+
+### コマンドラインオプション
+
+```bash
+init-context [options]
+
+オプション:
+  -a, --agent <type>               対象のAIエージェント（cursor、cline、kiro、claude-code-cli、
+                                   claude-code-desktop、github-copilot、amazon-q、other）
+  -p, --context-document-path      コンテキストドキュメントを保存するパス
+  -d, --skip-context-document      コンテキストドキュメントのインストールをスキップ（MCP設定のみ）
+  -m, --skip-mcp-config            MCP設定をスキップ（コンテキストドキュメントのみ）
+  -f, --force                      すべての確認プロンプトをスキップして強制上書き
+  -h, --help                       init-contextコマンドのヘルプを表示
+```
+
+> ⚠️ **注意**: コマンドラインオプションは `init-context` サブコマンドでのみサポートされています。非推奨の `--init-context` フラグはこれらのオプションをサポートしていません。
+
+### 使用例
+
+```bash
+# プロジェクトディレクトリに移動
+cd my-vega-project
+
+# インタラクティブモード（デフォルト）
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context
+
+# 特定のエージェントで非インタラクティブ
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context --agent cursor --force
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context -a cursor -f
+
+# MCP設定のみ（コンテキストドキュメントをスキップ）
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context --agent cursor --skip-context-document
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context -a cursor -d
+
+# カスタムパスでコンテキストドキュメントのみ（MCP設定をスキップ）
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context --agent kiro --context-document-path ./docs --skip-mcp-config
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context -a kiro -p ./docs -m
+
+# ヘルプを表示
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context --help
+```
+
+### インタラクティブモードのプロンプト
+
+インタラクティブモードで実行すると、以下のガイドが表示されます：
+# 1. AIエージェントを選択（例：Cursorの場合は「1」、Kiroの場合は「6」、その他/カスタムの場合は「8」）
+# 2. エージェントのMCP設定ファイルを自動的に更新するにはy/nを入力
+# 3. デフォルトのコンテキストドキュメントインストールパスを選択するか、カスタムパスを入力
+# 4. アクションを選択：マージ、更新、またはファイルを保存。続行する前にインストールされたコンテキストドキュメントを確認してください。
+
+### 他のAIエージェントでの使用
+
+AIエージェントがサポートされているリストにない場合は、**「その他/カスタムエージェント」**を選択してください。これにより以下が提供されます：
+
+-   **完全なコンテンツを表示**: 手動コピー用の完全なコンテキストを表示
+-   **手動セットアップ**: コンテンツをエージェントの設定ディレクトリにコピー
+
+> ℹ️ 重要: エージェントのMCP設定からMCPサーバーを起動してください（まだ起動していない場合） - 現在実行中のMCPを確認して、amazon-devices-buildertools-mcpが実行中/接続済みとしてリストされていることを確認してください。
+
+## Amazon Devices Builder Tools MCPを手動で設定
+
+Amazon Devices Builder Tools MCPを手動で設定するには、AIエージェントのMCP設定にMCP設定を追加します：
+
+```json
+  "amazon-devices-buildertools-mcp": {
+      "command": "npx",
+      "args": ["-y", "@amazon-devices/amazon-devices-buildertools-mcp@latest"],
+      "type": "stdio"
+  }
+```
+
+各エージェントには若干異なる手順がありますが、多くは「mcp.json」（または類似の）ファイルを使用して、この新しいMCPサーバーの特定の設定を追加できます。
+
+以下に、いくつかの人気のあるAIエージェントとMCPサーバーのインストール方法へのリンクをリストします。
+
+| #   | AIエージェント               | MCPセットアップ手順リンク                                                                                                                                    |
+| --- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Cursor                 | [手順](https://cursor.com/docs/context/mcp#using-mcpjson)                                                                                              |
+| 2   | Github Copilot         | [手順](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp/extend-copilot-chat-with-mcp) 次に「Configuring MCP Servers Manually」を選択 |
+| 3   | Claude Code        | [手順](https://code.claude.com/docs/en/mcp#option-3%3A-add-a-local-stdio-server)                                                                       |
+| 4   | Claude Code Desktop    | [手順](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)                                                                       |
+| 5   | Amazon Q IDE Extension | [手順](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/mcp-ide.html)                                                                          |
+| 6   | Amazon Q CLI           | [手順](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-config-CLI.html)                                                      |
+| 7   | Kiro                   | [手順](https://kiro.dev/docs/mcp/)                                                                                                                     |
+| 8   | Cline                  | [手順](https://docs.cline.bot/mcp/configuring-mcp-servers)                                                                                             |
+
+_エージェントがリストにない場合は、続行する前にMCPをサポートしていることを確認してください。_
+
+> ℹ️ 重要: 設定後、`npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context` を実行して、プロジェクトディレクトリに優先AIエージェント用のVegaコンテキストドキュメントをインストールしてください
+
+## 使用方法
+
+### コマンドラインオプション
+
+```bash
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context       # Amazon Devices Builder Tools MCPをインストールし、AIエージェント用のVegaコンテキストを初期化
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest check-status       # AIエージェントのセットアップステータスを確認
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest --version          # バージョン情報を表示
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest -v                 # バージョン情報を表示（エイリアス）
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest --help             # ヘルプメッセージを表示
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest -h                 # ヘルプメッセージを表示（エイリアス）
+```
+
+### エージェントセットアップステータスの確認
+
+MCPサーバーとコンテキストドキュメントをインストールした後、`check-status` コマンドを使用してセットアップを確認できます：
+
+```bash
+# すべてのエージェントを確認
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest check-status
+
+# 特定のエージェントを確認
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest check-status --agent kiro
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest check-status -a cursor
+
+# ヘルプを表示
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest check-status --help
+```
+
+**確認内容:**
+- ✅ コンテキストドキュメントのインストール状態とバージョン
+- ✅ MCP設定の状態
+- ✅ レガシー設定の検出
+- ✅ 全体的なセットアップの概要
+
+**出力例:**
+
+```
+====================================================
+🔍 Checking Agent Setup Status
+====================================================
+
+─────────────────────────────────────────────────────────────────────────────
+Agent                  │ Context Document         │ MCP Configuration        
+─────────────────────────────────────────────────────────────────────────────
+Cursor                 │ ✅ v5.1                   │ ✅ Configured             
+Kiro                   │ ✅ v5.1                   │ ✅ Configured             
+─────────────────────────────────────────────────────────────────────────────
+
+📊 Summary:
+   Total agents checked: 2
+   ✅ Fully configured: 2
+   ⚠️  Partially configured: 0
+   ❌ Not configured: 0
+```
+
+### AIエージェントにAmazon Devices Builder Tools MCPがインストールされていることを確認
+
+AIエージェントのチャットインターフェースで、以下のプロンプトを実行します
+
+```
+Amazon Devices Builder Tools MCPが提供するツールをリストしてください
+```
+
+以下のツールを含む応答が表示されるはずです：
+
+- analyze_perfetto_traces
+- read_document
+- list_documents
+
+## MCPツール
+
+Amazon Devices Builder Tools MCPは、Vegaアプリ開発を支援するために以下のツールを提供します：
+
+### 1. `read_document`
+
+Amazon Vega OSのアプリ開発に関連するドキュメントを読み取ります。このツールは、Vegaアプリ開発とデバッグトピックに関する包括的なドキュメントへのアクセスを提供します。
+
+**パラメータ:**
+- `document_name`（必須）: 読み取るドキュメントの名前（例：`react-native-for-vega-performance-best-practices.md`）。`.md`拡張子を持つマークダウンドキュメントである必要があります。
+
+**使用例:**
+```
+react-native-for-vega-performance-best-practices.mdドキュメントを読み取ってください
+```
+
+### 2. `list_documents`
+
+Amazon Vega OSのアプリ開発に関連する利用可能なすべてのVegaドキュメントをリストします。`read_document`ツールを使用して取得できる利用可能なドキュメントの名前と説明を返します。
+
+**パラメータ:**
+- `documentType`（オプション）: タイプでドキュメントをフィルタリング。有効な値：`KB`（ナレッジベース）、`PROMPT`、`STEERING`、`WORKFLOW`
+
+**使用例:**
+```
+利用可能なすべてのVegaドキュメントをリストしてください
+```
+または
+```
+タイプKBのドキュメントをリストしてください
+```
+
+### 3. `analyze_perfetto_traces`
+
+Perfettoトレースプロセッサを使用してVegaプラットフォームトレースを分析し、KPIメトリックと関連するパフォーマンスデータを抽出します。このツールは、パフォーマンスの問題を診断し、アプリの起動時間を分析するのに役立ちます。
+
+**パラメータ:**
+- `traceFilePath`（必須）: 分析するトレースファイルへのパス。通常、`iter_*_vs_trace`のような名前でVegaパフォーマンスデータ出力ディレクトリにあります
+- `queryType`（オプション）: 実行するクエリのタイプ。デフォルト：`kpi_analysis`
+- `kpiType`（オプション）: 分析する特定のKPIタイプ。オプション：`ttff`（Time to First Frame）、`ttfd`（Time to First Display）、`all`。デフォルト：`all`
+- `customQuery`（オプション）: 実行するカスタムPerfettoSQLクエリ（提供された場合、queryTypeとkpiTypeをオーバーライド）
+- `processNames`（オプション）: フィルタリングする追加のプロセス名
+- `appProcessName`（オプション）: 分析するメインアプリケーションプロセス名（提供されない場合は自動検出されます）
+
+**使用例:**
+```
+/path/to/iter_1_vs_traceのトレースファイルを分析してください
+```
+
+### 4. `get_app_hot_functions`
+
+CPUトレースファイルを読み取って分析し、パフォーマンスのボトルネックに寄与するホット関数（CPU集約的な操作）を特定します。このツールは、アプリケーションのどの関数が最もCPU時間を消費しているかを特定し、ターゲットを絞ったパフォーマンス最適化を可能にします。
+
+**パラメータ:**
+- `traceDataFilePath`（必須）: Activity Monitorからのトレースデータファイルへのパス。通常、`iter_<iteration>_trace<epoch>-converted.json`のような名前でVegaパフォーマンスデータ出力ディレクトリにあります（例：`iter_2_trace1766067380670018106-converted.json`）
+- `limit`（オプション）: 返すホット関数の最大数（デフォルト：10）
+- `useSelfTime`（オプション）: ソートにセルフCPU時間または合計CPU時間を使用するかどうかを示すフラグ（デフォルト：false）
+- `includeLibraryFunctions`（オプション）: ライブラリ関数を含めるかどうかを示すフラグ（デフォルト：false）
+- `startTimeOffset`（オプション）: トレース開始からの開始時間オフセット（秒単位）（例：トレース開始から5.2秒後に分析を開始する場合は5.2）
+- `endOffsetSeconds`（オプション）: トレース開始からの終了時間オフセット（秒単位）（例：トレース開始から15.8秒後に分析を終了する場合は15.8）
+
+**使用例:**
+```
+/path/to/iter_2_trace1766067380670018106-converted.jsonのトレースファイルでホット関数を分析してください
+```
+
+または時間ウィンドウフィルタリングを使用：
+```
+/path/to/trace.jsonで5秒から15秒までのホット関数を20関数の制限で分析してください
+```
+
+## MCPプロンプト
+
+> AIエージェントがhttps://modelcontextprotocol.io/clientsでMCPプロンプト（`/prompts`）をサポートしているか確認してください
+
+Amazon Devices Builder Tools MCPは、AIエージェントの`/prompts`でワンクリック実行できる一般的なワークフロー用の以下の事前定義されたプロンプトテンプレートを提供します：
+
+**重要**: Amazon Devices Builder Tools MCPが提供するプロンプトの完全なリストを表示するには、常にAIエージェントで`/prompts`を実行してください
+
+### 1. `diagnose_kpi_ttff`
+
+**説明:** VegaアプリケーションのTime to First Frame（TTFF）KPIを診断
+
+**パラメータ:**
+- `kpi_report_file_path`（必須、文字列）: KPIレポートファイルへの絶対パス
+- `kpi_to_diagnose`（必須、文字列）: 診断するKPIレポートからのKPIの名前
+
+**使用例:**
+```
+> @diagnose_kpi_ttff /path/to/report.json ttff
+```
+
+### 2. `diagnose_kpi_ttfd`
+
+**説明:** VegaアプリケーションのTime to Fully Drawn（TTFD）KPIを診断
+
+**パラメータ:**
+- `kpi_report_file_path`（必須、文字列）: KPIレポートファイルへの絶対パス
+- `kpi_to_diagnose`（必須、文字列）: 診断するKPIレポートからのKPIの名前
+
+**使用例:**
+```
+> @diagnose_kpi_ttfd /path/to/report.json ttfd
+```
+
+### 3. `apply_performance_best_practices`
+
+**説明:** コンポーネントレンダリング、メモリ管理、ナビゲーション、ネットワーク最適化、状態管理を含むReact Nativeアプリケーションのパフォーマンスの問題を診断して最適化します。
+
+**パラメータ:**
+- `app_source_path`（必須、文字列）: 分析用のReact Nativeアプリケーションソースコードディレクトリへのパス
+
+**使用例:**
+```
+> @apply_performance_best_practices /path/to/my-vega-app/src
+```
+
+### 4. `detect_component_re-renders`
+
+**説明:** React Nativeツールを使用して、コンポーネントの再レンダリングによって引き起こされるVegaアプリケーションのUI流動性パフォーマンスの問題を診断して最適化します。
+
+**パラメータ:**
+- `vega_app_package_path`（必須、文字列）: Vegaアプリパッケージルートディレクトリへの絶対パス
+
+**使用例:**
+```
+> @detect_component_re-renders /path/to/my-vega-app
+```
+
+### 5. `upgrade_carousel_component`
+
+**説明:** Vega SDKのCarouselコンポーネントの新しいバージョンへの移行を支援します。
+
+**パラメータ:**
+- `current_implementation_file_path`（必須、文字列）: CarouselのV1実装を含むファイルへの絶対パス
+- `current_version`（必須、文字列）: パッケージに依存しないCarouselの現在のバージョン
+- `target_version`（必須、文字列）: パッケージに依存しないCarouselのターゲットバージョン
+
+**使用例:**
+```
+> @upgrade_carousel_component /path/to/HomeScreen.tsx 1.0.6 2.0.0
+```
+
+### 6. `diagnose_crash`
+
+**説明:** JavaScript、Native、LMK（Low Memory Killer）、ANR（Application Not Responding）クラッシュを含むVegaアプリケーションのクラッシュを診断します。ACRファイルを自動検出し、スタックトレースをシンボリケートし、適切な分析ワークフローにルーティングします。
+
+**パラメータ:**
+
+- `acr_file_path`（任意、文字列）: ACRファイルへのパス。指定しない場合、デバイスの一時ディレクトリからACRファイルを自動検出します。
+
+**使用例:**
+
+```
+> @diagnose_crash /path/to/crash.acr
+```