npm - @amazon-devices/amazon-devices-buildertools-mcp - Versions diffs - 0.1.23 → 0.1.26 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.ja.md +388 -0
package/README.md +181 -24
package/dist/assets/vega-developer-context.db +0 -0
package/dist/startserver +5 -5
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,5 +1,7 @@
 # Amazon Devices Builder Tools MCP Server
+**English** | [日本語](README.ja.md)
 A Model Context Protocol (MCP) server that provides context and tools for AI agents to develop and debug apps for Amazon's [Vega OS](https://developer.amazon.com/apps-and-games/vega).
 ## Migration Notice
@@ -8,13 +10,19 @@ A Model Context Protocol (MCP) server that provides context and tools for AI age
 ## Features
-The Amazon Devices Builder Tools MCP is designed to help with:
+The Amazon Devices Builder Tools MCP supports the following capabilities:
-1. **Development Guidance**: Access comprehensive documentation about Vega app development patterns, best practices, and architecture
-2. **Performance Analysis**: Analyze trace files to identify performance bottlenecks and optimize app launch times
-3. **Debugging**: Get detailed information about CLI commands, configuration, and troubleshooting
-4. **Project Setup**: Learn about project structure, dependencies, and template usage
-5. **Feature Implementation**: Find guidance on implementing specific features like navigation, focus management, media playback, and authentication
+| App Dev Area                   | Description                                                                                      | Example Prompts                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Onboarding**                 | Onboard to Vega app development using AI agents with setup guidance and Q&A support              | <ul><li>`Help me set up Vega app project and test my VPKG on Virtual Device?`</li><li>`Help me setup Vega SDK?`</li><li>`Build and run the app on Virtual device/Connected Device.`</li><li>`Can you tell me about vega app development?`</li><li>`What is the Vega CLI command for measuring cpu usage on a Vega device?`</li></ul> |
+| **Performance**                | Debug and fix Time to First Frame (TTFF), Time to Fully Drawn (TTFD), and UI re-rendering issues | <ul><li>`Why is the TTFF higher for my Vega app?`</li><li>`Can you help me debug and fix Time to First Frame issue in my Vega app?`</li><li>`Why is the TTFD higher for my Vega app?`</li><li>`Can you help me minimize unnecessary re-renders in my app?`</li><li>`Find any re-rendering issues in my app.`</li></ul>               |
+| **Performance Best Practices** | Analyze components and code to ensure they follow React Native Vega performance best practices   | <ul><li>`Help me analyze if this component is following React Native Vega performance best practices`</li></ul>                                                                                                                                                                                                                      |
+| **Best Practices**             | Validate manifest files and implement Vega components following best practices                   | <ul><li>`Can you help me upgrade my MovieCarousel.tsx from Carousel V1 to V2?`</li><li>`Can you help me implement Carousel?`</li><li>`Can you validate my manifest file and update as needed for my app?`</li></ul>                                                                                                                  |
+| **UI Development**             | Create Vega app UI from screenshots and design mockups                                           | <ul><li>`I have an image at {image_path}. Create a Vega app by creating a new folder using the sample template, update the sample test app to match the image, and confirm that the app can be built and run.`</li></ul>                                                                                                             |
+| **Focus Management**           | Implement D-Pad navigation and focus management for TV interfaces                                | <ul><li>`Can you create an app with 2 buttons to show case focus management?`</li></ul>                                                                                                                                                                                                                                              |
+| **Give Feedback** | Provide feedback to Amazon about your experience with the MCP | <ul><li>`I want to provide feedback`</li><li>`How can I provide vega mcp feedback?`</li></ul> |
+| **Crash Analysis**              | Diagnose JavaScript, Native, LMK, and ANR crashes with automated ACR analysis                    | <ul><li>`Why did my app crash?`</li><li>`Help me analyze this ACR file /path/to/crash.acr`</li></ul>                                                                                                                                                                                                                                                |
+| **SDK & CLI**                  | Install/update SDK and efficiently run CLI tools via spec-driven CLI                             | <ul><li>`Install/update SDK from AI agents`</li><li>`Build my app`</li><li>`Run my app on virtual device`</li><li>`Run my app on physical device`</li><li>`Run KPI Visualizer and get performance results`</li></ul>                                                                                                                 |
 ## One-Click Installation
@@ -32,48 +40,96 @@ Some of the popular AI Agents support installing MCP servers with a single click
 [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)
 ## Installation with script
 Run the following command to **automatically** install Amazon Devices Builder Tools MCP in your AI Agent and add Vega-specific context document to your project to guide AI agents:
-> ℹ️ Important: It is important to run `npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest --init-context` to install the Vega-context document for your preferred AI agent in the project directory. This step is required even after one-click install of mcp.
+> ℹ️ Important: It is important to run `npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context` to install the Vega-context document for your preferred AI agent in the project directory. This step is required even after one-click install of mcp.
+> ⚠️ **Deprecation Notice**: The `--init-context` flag is deprecated and will be removed in a future version. Please use the `init-context` subcommand instead.
 ```bash
+# Recommended (new subcommand)
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context
+# Deprecated (will be removed)
 npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest --init-context
 ```
-This interactive command will:
+This command supports both **interactive** and **non-interactive** modes:
+**Interactive Mode (default):**
 1. **Display available AI agents** and their context file requirements
 2. **Let you select your preferred AI agent** from the supported list
-3. **Update selected agent's MCP settings** to configure the Amazon Devices Builder Tools MCP server
+3. **Update selected agent's MCP settings** to configure the Amazon Devices Builder Tools MCP server
 4. **Ask for context installation directory** (defaults to current working directory)
 5. **Handle existing context files** by offering to merge or update content
 6. **Create the appropriate context file** in the correct location for your chosen AI agent
+**Non-Interactive Mode:**
+Use command-line options to skip prompts and automate the setup process.
+### Command Line Options
+```bash
+init-context [options]
+Options:
+  -a, --agent <type>               Target AI agent (cursor, cline, kiro, claude-code-cli,
+                                   claude-code-desktop, github-copilot, amazon-q, other)
+  -p, --context-document-path      Path to save context document
+  -d, --skip-context-document      Skip context document installation (MCP config only)
+  -m, --skip-mcp-config            Skip MCP configuration (context document only)
+  -f, --force                      Skip all confirmation prompts and force overwrite
+  -h, --help                       Show help for init-context command
+```
+> ⚠️ **Note**: Command-line options are only supported with the `init-context` subcommand. The deprecated `--init-context` flag does not support these options.
 ### Example Usage
 ```bash
 # Navigate to your project directory
 cd my-vega-project
-# Initialize context for your AI agent
-npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest --init-context
+# Interactive mode (default)
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context
+# Non-interactive with specific agent
+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 config only (skip context document)
+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
+# Context document only with custom path (skip MCP config)
+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
+# Show help
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context --help
+```
+### Interactive Mode Prompts
+When running in interactive mode, you'll be guided through:
+# 1. Select your AI agent (e.g., "1" for Cursor, "6" for Kiro, "8" for Other/Custom)
-# Follow the interactive prompts:
-# 1. Select your AI agent (e.g., "5" for Kiro, "7" for Other/Custom)
 # 2. Enter y/n to automatically update Agent's MCP settings file
 # 3. Choose default context document installation path or enter custom path
 # 4. Choose action: merge, update or save file. Review the installed context document before proceeding.
-```
 ### Using with Other AI Agents
 If your AI agent isn't in the supported list, select **"Other/Custom Agent"** which provides:
--   **View full content**: Display the complete context for manual copying
--   **Manual setup**: Copy the content to your agent's configuration directory
+- **View full content**: Display the complete context for manual copying
+- **Manual setup**: Copy the content to your agent's configuration directory
 > ℹ️ Important: Start the MCP Server from Agent's MCP config, if not already started - check your current running MCPs to ensure the amazon-devices-buildertools-mcp is listed as running/connected.
@@ -97,28 +153,73 @@ Below we list some popular AI agents and the link to how to install MCP servers.
 | --- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 1   | Cursor                 | [Instructions](https://cursor.com/docs/context/mcp#using-mcpjson)                                                                                              |
 | 2   | Github Copilot         | [Instructions](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp/extend-copilot-chat-with-mcp) then choose "Configuring MCP Servers Manually" |
-| 3   | Claude Code CLI        | [Instructions](https://code.claude.com/docs/en/mcp#option-3%3A-add-a-local-stdio-server)                                                                       |
-| 4   | Amazon Q IDE Extension | [Instructions](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/mcp-ide.html)                                                                          |
-| 5   | Amazon Q CLI           | [Instructions](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-config-CLI.html)                                                      |
-| 6   | Kiro                   | [Instructions](https://kiro.dev/docs/mcp/)                                                                                                                     |
-| 7   | Cline                  | [Instructions](https://docs.cline.bot/mcp/configuring-mcp-servers)                                                                                             |
+| 3   | Claude Code            | [Instructions](https://code.claude.com/docs/en/mcp#option-3%3A-add-a-local-stdio-server)                                                                       |
+| 4   | Claude Code Desktop    | [Instructions](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)                                       |
+| 5   | Amazon Q IDE Extension | [Instructions](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/mcp-ide.html)                                                                          |
+| 6   | Amazon Q CLI           | [Instructions](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-config-CLI.html)                                                      |
+| 7   | Kiro                   | [Instructions](https://kiro.dev/docs/mcp/)                                                                                                                     |
+| 8   | Cline                  | [Instructions](https://docs.cline.bot/mcp/configuring-mcp-servers)                                                                                             |
 _If your agent is not listed, please ensure it supports MCP before continuing._
-> ℹ️ Important: Once configured, run `npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest --init-context` to install the Vega-context document for your preferred AI agent in the project directory
+> ℹ️ Important: Once configured, run `npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context` to install the Vega-context document for your preferred AI agent in the project directory
 ## Usage
 ### Command Line Options
 ```bash
-npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest --init-context     # Install Amazon Devices Builder Tools MCP and initialize Vega context for AI agents
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context       # Install Amazon Devices Builder Tools MCP and initialize Vega context for AI agents
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest check-status       # Check setup status of AI agents
 npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest --version          # Show version information
 npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest -v                 # Show version information (alias)
 npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest --help             # Show help message
 npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest -h                 # Show help message (alias)
 ```
+### Check Agent Setup Status
+After installing the MCP server and context documents, you can verify your setup using the `check-status` command:
+```bash
+# Check all agents
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest check-status
+# Check specific agent
+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
+# Show help
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest check-status --help
+```
+**What it checks:**
+- ✅ Context document installation status and version
+- ✅ MCP configuration status
+- ✅ Detection of legacy configurations
+- ✅ Overall setup summary
+**Example output:**
+```
+====================================================
+🔍 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
+```
 ### Verify Amazon Devices Builder Tools MCP is installed in your AI Agent
 In your AI Agent's chat interface, run the following prompt
@@ -130,8 +231,10 @@ List the tools provided by Amazon Devices Builder Tools MCP
 You should see a response that includes the following tools:
 - analyze_perfetto_traces
+- get_app_hot_functions
 - read_document
 - list_documents
+- read_asset
 ## MCP Tools
@@ -142,9 +245,11 @@ The Amazon Devices Builder Tools MCP provides the following tools to assist with
 Read documents related to App development for Amazon Vega OS. This tool provides access to comprehensive documentation about Vega app development and debugging topics.
 **Parameters:**
 - `document_name` (required): Name of the document to read (e.g., `react-native-for-vega-performance-best-practices.md`). Must be a markdown document with `.md` extension.
 **Example usage:**
 ```
 Read the document react-native-for-vega-performance-best-practices.md
 ```
@@ -154,13 +259,17 @@ Read the document react-native-for-vega-performance-best-practices.md
 List all available Vega documents related to App development for Amazon Vega OS. Returns name and description of available documents that can be retrieved using the `read_document` tool.
 **Parameters:**
 - `documentType` (optional): Filter documents by type. Valid values: `KB` (Knowledge Base), `PROMPT`, `STEERING`, `WORKFLOW`
 **Example usage:**
 ```
 List all available Vega documents
 ```
 or
 ```
 List documents of type KB
 ```
@@ -170,6 +279,7 @@ List documents of type KB
 Analyze Vega platform traces using Perfetto trace processor to extract KPI metrics and related performance data. This tool helps diagnose performance issues and analyze app launch times.
 **Parameters:**
 - `traceFilePath` (required): Path to the trace file to analyze. Usually found in Vega performance data output directories with names like `iter_*_vs_trace`
 - `queryType` (optional): Type of query to execute. Default: `kpi_analysis`
 - `kpiType` (optional): Specific KPI type to analyze. Options: `ttff` (Time to First Frame), `ttfd` (Time to First Display), `all`. Default: `all`
@@ -178,6 +288,7 @@ Analyze Vega platform traces using Perfetto trace processor to extract KPI metri
 - `appProcessName` (optional): Main application process name to analyze (will be auto-detected if not provided)
 **Example usage:**
 ```
 Analyze the trace file at /path/to/iter_1_vs_trace
 ```
@@ -187,6 +298,7 @@ Analyze the trace file at /path/to/iter_1_vs_trace
 Reads and analyzes CPU trace files to identify hot functions (CPU-intensive operations) contributing to performance bottlenecks. This tool helps pinpoint which functions in your application are consuming the most CPU time, enabling targeted performance optimization.
 **Parameters:**
 - `traceDataFilePath` (required): Path to the trace data file from the Activity Monitor. Usually found in Vega performance data output directories with names like `iter_<iteration>_trace<epoch>-converted.json` (e.g., `iter_2_trace1766067380670018106-converted.json`)
 - `limit` (optional): Maximum number of hot functions to return (default: 10)
 - `useSelfTime` (optional): Flag to indicate whether to use self CPU time or total CPU time for sorting (default: false)
@@ -195,15 +307,36 @@ Reads and analyzes CPU trace files to identify hot functions (CPU-intensive oper
 - `endOffsetSeconds` (optional): End time offset in seconds from trace beginning (e.g., 15.8 for analysis ending 15.8 seconds after trace start)
 **Example usage:**
 ```
 Analyze hot functions in the trace file at /path/to/iter_2_trace1766067380670018106-converted.json
 ```
 or with time window filtering:
 ```
 Analyze hot functions in /path/to/trace.json from 5 to 15 seconds with a limit of 20 functions
 ```
+### 5. `read_asset`
+Read assets referenced in Vega documentation. Assets are saved to a temporary location and the path is returned. Images can be viewed with
+`fs_read` and scripts executed with the appropriate interpreter (e.g., `python3`)
+**Parameters**
+- `asset_id` (required): Path of the asset to read (e.g., `assets/scripts/example.py` or `assets/images/diagram.png`)
+**Example usage:**
+```
+Read the script assets/scripts/setup.sh and execute it
+```
+or
+```
+Read the image assets/images/architecture.png and describe what it shows
+```
 ## MCP Prompts
 > Check if your AI Agents supports MCP Prompts (`/prompts`) in https://modelcontextprotocol.io/clients
@@ -217,10 +350,12 @@ Amazon Devices Builder Tools MCP provides the following pre-defined prompt templ
 **Description:** Diagnose Vega application's Time to First Frame (TTFF) KPI
 **Parameters:**
 - `kpi_report_file_path` (required, string): Absolute path to the KPI report file
 - `kpi_to_diagnose` (required, string): Name of the KPI from KPI report to diagnose
 **Example usage:**
 ```
 > @diagnose_kpi_ttff /path/to/report.json ttff
 ```
@@ -230,10 +365,12 @@ Amazon Devices Builder Tools MCP provides the following pre-defined prompt templ
 **Description:** Diagnose Vega application's Time to Fully Drawn (TTFD) KPI
 **Parameters:**
 - `kpi_report_file_path` (required, string): Absolute path to the KPI report file
 - `kpi_to_diagnose` (required, string): Name of the KPI from KPI report to diagnose
 **Example usage:**
 ```
 > @diagnose_kpi_ttfd /path/to/report.json ttfd
 ```
@@ -243,9 +380,11 @@ Amazon Devices Builder Tools MCP provides the following pre-defined prompt templ
 **Description:** Diagnose and optimize React Native application performance issues including component rendering, memory management, navigation, network optimization, and state management.
 **Parameters:**
 - `app_source_path` (required, string): Path to the React Native application source code directory for analysis
 **Example usage:**
 ```
 > @apply_performance_best_practices /path/to/my-vega-app/src
 ```
@@ -255,9 +394,11 @@ Amazon Devices Builder Tools MCP provides the following pre-defined prompt templ
 **Description:** Diagnose and optimize Vega application UI fluidity performance issues caused by component re-rendering using React Native tools.
 **Parameters:**
 - `vega_app_package_path` (required, string): Absolute path to the Vega app package root directory
 **Example usage:**
 ```
 > @detect_component_re-renders /path/to/my-vega-app
 ```
@@ -267,11 +408,27 @@ Amazon Devices Builder Tools MCP provides the following pre-defined prompt templ
 **Description:** Assists in migrating to newer versions of the Carousel component in the Vega SDK.
 **Parameters:**
 - `current_implementation_file_path` (required, string): Absolute path to the file containing the V1 implementation of Carousel
 - `current_version` (required, string): The current version of Carousel, independent of package
 - `target_version` (required, string): The target version of Carousel, independent of package
 **Example usage:**
 ```
 > @upgrade_carousel_component /path/to/HomeScreen.tsx 1.0.6 2.0.0
 ```
+### 6. `diagnose_crash`
+**Description:** Diagnose crashes in Vega applications including JavaScript, Native, LMK (Low Memory Killer), and ANR (Application Not Responding) crashes. Automatically discovers ACR files, symbolicates stack traces, and routes to the appropriate analysis workflow.
+**Parameters:**
+- `acr_file_path` (optional, string): Path to ACR file. If not provided, the tool will auto-discover ACR files from the device temp directory.
+**Example usage:**
+```
+> @diagnose_crash /path/to/crash.acr
+```

package/dist/assets/vega-developer-context.db CHANGED Viewed

Binary file