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

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Amazon.com, Inc. or its affiliates.  All rights reserved.
+
+These materials are licensed as "Program Materials" under the Program Materials License Agreement (the "Agreement").  The Agreement is available at https://developer.amazon.com/support/legal/pml.  See the Agreement for the specific terms and conditions of the Agreement.  Capitalized terms not defined in this file have the meanings given to them in the Agreement.  
+
+If you do not agree to the above terms and conditions, you may not use any file in this package. 
+
+YOUR USE OF THE PROGRAM MATERIALS IN OR ASSOCIATED WITH THIS PACKAGE IS AT YOUR SOLE RISK.  IN NO EVENT WILL AMAZON BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION ANY DIRECT, INDIRECT, CONSEQUENTIAL, SPECIAL, INCIDENTAL, OR PUNITIVE DAMAGES (INCLUDING FOR ANY LOSS OF GOODWILL, BUSINESS INTERRUPTION, LOST PROFITS OR DATA, OR COMPUTER FAILURE OR MALFUNCTION) ARISING FROM OR RELATING TO SUCH PROGRAM MATERIALS, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, EVEN IF AMAZON HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.  THESE LIMITATIONS AND DISCLAIMERS APPLY EXCEPT TO THE EXTENT PROHIBITED BY APPLICABLE LAW.

package/README.md

@@ -0,0 +1,277 @@
+# Amazon Devices Builder Tools MCP Server
+
+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
+
+> **Important**: This MCP server has been renamed from `@amazon-devices/vega-devtools-mcp` to `@amazon-devices/amazon-devices-buildertools-mcp`. If you have the previous version installed, please update the mcp config to remove `@amazon-devices/vega-devtools-mcp` and use `@amazon-devices/amazon-devices-buildertools-mcp` server to receive the latest updates and features.
+
+## Features
+
+The Amazon Devices Builder Tools MCP is designed to help with:
+
+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
+
+## One-Click Installation
+
+Some of the popular AI Agents support installing MCP servers with a single click. Below are the one-click install options available.
+
+### Install MCP on Kiro
+
+[![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)
+
+### Install MCP on Cursor
+
+[![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)
+
+### Install MCP on VSCode
+
+[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. 
+
+```bash
+npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest --init-context
+```
+
+This interactive command will:
+
+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 
+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
+
+### 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
+
+# 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
+
+> ℹ️ 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.
+
+## Configure Amazon Devices Builder Tools MCP manually
+
+To manually configure the Amazon Devices Builder Tools MCP, add the MCP configuration in your AI Agent's MCP settings:
+
+```json
+  "amazon-devices-buildertools-mcp": {
+      "command": "npx",
+      "args": ["-y", "@amazon-devices/amazon-devices-buildertools-mcp@latest"],
+      "type": "stdio"
+  }
+```
+
+Each Agent has slightly different instructions, but many involve using an "mcp.json" (or similar) file where you can add the specific configuration for this new MCP server.
+
+Below we list some popular AI agents and the link to how to install MCP servers.
+
+| #   | AI Agent               | MCP Setup Instructions Link                                                                                                                                    |
+| --- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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)                                                                                             |
+
+_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
+
+## 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 --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)
+```
+
+### Verify Amazon Devices Builder Tools MCP is installed in your AI Agent
+
+In your AI Agent's chat interface, run the following prompt
+
+```
+List the tools provided by Amazon Devices Builder Tools MCP
+```
+
+You should see a response that includes the following tools:
+
+- analyze_perfetto_traces
+- read_document
+- list_documents
+
+## MCP Tools
+
+The Amazon Devices Builder Tools MCP provides the following tools to assist with Vega app development:
+
+### 1. `read_document`
+
+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
+```
+
+### 2. `list_documents`
+
+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
+```
+
+### 3. `analyze_perfetto_traces`
+
+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`
+- `customQuery` (optional): Custom PerfettoSQL query to execute (overrides queryType and kpiType if provided)
+- `processNames` (optional): Additional process names to filter by
+- `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
+```
+
+### 4. `get_app_hot_functions`
+
+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)
+- `includeLibraryFunctions` (optional): Flag to indicate whether to include library functions (default: false)
+- `startTimeOffset` (optional): Start time offset in seconds from trace beginning (e.g., 5.2 for analysis starting 5.2 seconds after trace start)
+- `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
+```
+
+## MCP Prompts
+
+> Check if your AI Agents supports MCP Prompts (`/prompts`) in https://modelcontextprotocol.io/clients
+
+Amazon Devices Builder Tools MCP provides the following pre-defined prompt templates for common workflows that can be 1-click executed in `/prompts` in your AI Agent:
+
+**Important**: Always run `/prompts` in your AI Agent to see the full list of prompts provided by Amazon Devices Builder Tools MCP
+
+### 1. `diagnose_kpi_ttff`
+
+**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
+```
+
+### 2. `diagnose_kpi_ttfd`
+
+**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
+```
+
+### 3. `apply_performance_best_practices`
+
+**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
+```
+
+### 4. `detect_component_re-renders`
+
+**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
+```
+
+### 5. `upgrade_carousel_component`
+
+**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
+```