@amazon-devices/amazon-devices-buildertools-mcp 0.1.30 → 0.1.32

package/README.md

@@ -4,10 +4,6 @@
 
 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 supports the following capabilities:
@@ -20,13 +16,14 @@ The Amazon Devices Builder Tools MCP supports the following capabilities:
 | **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> |
+| **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>                                                                                                                                                                                                                                                |
 | **Key Input Latency**          | Diagnose and resolve key input latency issues through JS Thread performance and input event analysis | <ul><li>`Why is my app responding slowly to key presses?`</li><li>`Help me diagnose key input latency in my Vega app`</li><li>`My button clicks feel laggy, can you help?`</li></ul>                                                                                                                                                 |
 | **UI Fluidity**                | Diagnose UI fluidity KPI failures through component re-rendering and CPU performance analysis    | <ul><li>`My app's UI fluidity score is low, help me diagnose it`</li><li>`Help me fix frame drops and jank in my Vega app`</li><li>`Why is scrolling not smooth in my app?`</li></ul>                                                                                                                                                |
-| **App Migration**              | Convert FireOS WebView apps to Vega WebView apps while maintaining visual and functional consistency | <ul><li>`Convert my FOS WebView app to a Vega Web App`</li><li>`Help me migrate my FireOS web app at /path/to/fos-app to Vega`</li></ul>                                                                                                                                                                                            |
+| **App Porting** *(Beta)*       | Port FireOS apps to Vega or wrap a web URL as a Vega app, with auto-detection of app type. Supports four input paths: FOS WebView → Vega WebView, FOS React Native → VegaScript, FOS Native (Java/Kotlin) → VegaScript *(partial support)*, and Web URL → Vega WebView. | <ul><li>`Port my TV app to Vega`</li><li>`Help me migrate my FireOS app at /path/to/fos-app to Vega`</li><li>`Port my FOS React Native app to VegaScript`</li><li>`Convert my FOS WebView app to a Vega Web App`</li><li>`Wrap https://example.com as a Vega WebView app`</li></ul> |
 | **Appstore IAP Integration**   | Integrate and test Amazon Appstore In-App Purchasing (IAP) SDK in Vega apps                      | <ul><li>`Help me integrate IAP in my Vega app`</li><li>`How do I set up In-App Purchasing for my Vega app?`</li><li>`Help me test IAP in my Vega app`</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>                                                                                                                 |
+| **Remote Knowledge Search**    | Search and retrieve documentation from developer.amazon.com and community.amazondeveloper.com to get AI assistance on any documented app development topic beyond curated local workflows | <ul><li>`How can I do a beta test of my Vega app?`</li><li>`What are the accessibility guidelines for Vega apps?`</li><li>`How do I submit my app to the Amazon Appstore?`</li><li>`What DRM options are available for Vega?`</li></ul>                                                                                                |
 
 ## One-Click Installation
 
@@ -116,13 +113,10 @@ npx -y @amazon-devices/amazon-devices-buildertools-mcp@latest init-context --hel
 
 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)
-
-# 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.
+1. Select your AI agent (e.g., "1" for Cursor, "6" for Kiro, "8" 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
 
@@ -232,56 +226,17 @@ You should see a response that includes the following tools:
 
 - analyze_perfetto_traces
 - get_app_hot_functions
-- read_document
 - list_documents
-- search_documentation
-- execute_query
-- get_database_schema
 - read_asset
-- diagnose_crash
-- diagnose_key_input_latency
-- diagnose_ui_fluidity
-- convert_fos_webview_to_vega
+- read_document
+- search_documentation
+- symbolicate_acr
 
 ## 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`
+### 1. `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.
 
@@ -300,7 +255,7 @@ Analyze Vega platform traces using Perfetto trace processor to extract KPI metri
 Analyze the trace file at /path/to/iter_1_vs_trace
 ```
 
-### 4. `get_app_hot_functions`
+### 2. `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.
 
@@ -325,76 +280,90 @@ 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. `search_documentation`
+### 3. `list_documents`
 
-Search Vega development documentation using full-text search. Returns document IDs and relevant snippets matching the query. Use `read_document` with the returned ID to get full content.
+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:**
 
-- `query` (required): Search query string to find relevant documents
-- `snippet_tokens` (optional): Maximum tokens in returned snippets (default: 32)
+- `documentType` (optional): Filter documents by type. Valid values: `KB` (Knowledge Base), `PROMPT`, `STEERING`, `WORKFLOW`
 
 **Example usage:**
 
 ```
-Search for documents about "performance optimization"
+List all available Vega documents
 ```
 
-or with custom snippet length:
+or
 
 ```
-Search for "React Native best practices" with 64 token snippets
+List documents of type KB
 ```
 
-### 6. `get_database_schema`
+### 4. `read_asset`
 
-Get the schema for the Vega documentation database. Call this before using `execute_query` to understand available tables, columns, and FTS5 syntax.
+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:**
 
-**Parameters:** None
+- `asset_id` (required): Path of the asset to read (e.g., `assets/scripts/example.py` or `assets/images/diagram.png`)
 
 **Example usage:**
 
 ```
-Get the database schema for Vega documentation
+Read the script assets/scripts/setup.sh and execute it
+```
+
+or
+
+```
+Read the image assets/images/architecture.png and describe what it shows
 ```
 
-### 7. `execute_query`
+### 5. `read_document`
 
-Execute a SQL query against the Vega documentation database. Use this tool for more complex queries when `search_documentation` is insufficient. Use `get_database_schema` first to understand available tables and FTS5 syntax. The database is read-only.
+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:**
 
-- `sql_query` (required): SQL query to execute against the documentation database
+- `document_uri` (required): URI of the document to read. Accepts a local document name (e.g., `vega_cli_commands_reference.md`) or a developer.amazon.com URL.
 
 **Example usage:**
 
 ```
-Execute query to search for "performance OR optimization" with custom snippets
+Read the document react_native_for_vega_architecture.md
 ```
 
-or with a specific SQL query:
+### 6. `search_documentation`
 
-```
-Execute query: SELECT dc.id, snippet(document_content_fts, 0, "<b>", "</b>", "...", 64) FROM document_content_fts JOIN document_content dc ON document_content_fts.rowid = dc.rowid WHERE document_content_fts MATCH "performance OR optimization" ORDER BY rank LIMIT 10
-```
+Search Vega development documentation using full-text search. Returns document URIs and relevant snippets matching the query. Use `read_document` with the returned URI to get full content.
 
-### 8. `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:**
 
-**Parameters**
-- `asset_id` (required): Path of the asset to read (e.g., `assets/scripts/example.py` or `assets/images/diagram.png`)
+- `query` (required): Search query string to find relevant documents
 
 **Example usage:**
+
 ```
-Read the script assets/scripts/setup.sh and execute it
+Search for documents about "performance optimization"
 ```
 
-or
+### 7. `symbolicate_acr`
+
+Symbolicate ACR (Amazon Crash Report) files and create a report. Supports both GDB-based native crash symbolication and JavaScript stack trace symbolication.
+
+**Parameters:**
+
+- `acrFilePath` (required): Path to the ACR file to symbolicate
+- `decodeMode` (required): `gdb` for native crashes (requires `debugFsPath` or `deviceId`), `js` for JavaScript stack traces
+- `debugFsPath` (optional): Path to Debug Root FS. Used with `gdb` mode.
+- `deviceId` (optional): Target device serial number to fetch Debug FS. Used with `gdb` mode.
+
+**Example usage:**
 
 ```
-Read the image assets/images/architecture.png and describe what it shows
+Symbolicate the crash file at /path/to/crash.acr using JS mode
 ```
 
 ## MCP Prompts
@@ -405,24 +374,37 @@ Amazon Devices Builder Tools MCP provides the following pre-defined prompt templ
 
 **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`
+### 1. `apply_performance_best_practices`
 
-**Description:** Diagnose Vega application's Time to First Frame (TTFF) KPI
+**Description:** Diagnose and optimize React Native application performance issues including component rendering, memory management, navigation, network optimization, and state management.
 
 **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
+- `app_source_path` (required, string): Path to the React Native application source code directory for analysis
 
 **Example usage:**
 
 ```
-> @diagnose_kpi_ttff /path/to/report.json ttff
+> @apply_performance_best_practices /path/to/my-vega-app/src
 ```
 
-### 2. `diagnose_kpi_ttfd`
+### 2. `detect_component_re-renders`
 
-**Description:** Diagnose Vega application's Time to Fully Drawn (TTFD) KPI
+**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
+```
+
+### 3. `diagnose-slowAppLaunch`
+
+**Description:** Diagnose Vega application's slow app launch KPIs (TTFF and/or TTFD).
 
 **Parameters:**
 
@@ -432,88 +414,86 @@ Amazon Devices Builder Tools MCP provides the following pre-defined prompt templ
 **Example usage:**
 
 ```
-> @diagnose_kpi_ttfd /path/to/report.json ttfd
+> @diagnose-slowAppLaunch /path/to/report.json ttff
 ```
 
-### 3. `apply_performance_best_practices`
+### 4. `diagnose_crash`
 
-**Description:** Diagnose and optimize React Native application performance issues including component rendering, memory management, navigation, network optimization, and state management.
+**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:**
 
-- `app_source_path` (required, string): Path to the React Native application source code directory for analysis
+- `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:**
 
 ```
-> @apply_performance_best_practices /path/to/my-vega-app/src
+> @diagnose_crash /path/to/crash.acr
 ```
 
-### 4. `detect_component_re-renders`
+### 5. `diagnose_key_input_latency`
 
-**Description:** Diagnose and optimize Vega application UI fluidity performance issues caused by component re-rendering using React Native tools.
+**Description:** Diagnose and resolve key input latency issues in React Native Vega apps through systematic analysis of JS Thread performance, CPU bottlenecks, and input event handling optimization.
 
 **Parameters:**
 
 - `vega_app_package_path` (required, string): Absolute path to the Vega app package root directory
+- `app_process_name` (optional, string): Name of the app process experiencing input latency. If not provided, resolved automatically from manifest.toml.
+- `perfetto_trace_file_path` (optional, string): Absolute path to existing Perfetto trace file (if already captured)
+- `target_component_or_button` (optional, string): Specific button or component name to investigate
+- `latency_threshold_ms` (optional, number): Maximum acceptable input latency in milliseconds. Default is 100.
 
 **Example usage:**
 
 ```
-> @detect_component_re-renders /path/to/my-vega-app
+> @diagnose_key_input_latency /path/to/my-vega-app
 ```
 
-### 5. `upgrade_carousel_component`
+### 6. `diagnose_ui_fluidity`
 
-**Description:** Assists in migrating to newer versions of the Carousel component in the Vega SDK.
+**Description:** Comprehensive diagnosis of UI fluidity KPI failures for React Native Vega apps through systematic analysis of component re-rendering and CPU performance bottlenecks.
 
 **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
+- `vega_app_package_path` (required, string): Absolute path to the Vega app package root directory
 
 **Example usage:**
 
 ```
-> @upgrade_carousel_component /path/to/HomeScreen.tsx 1.0.6 2.0.0
+> @diagnose_ui_fluidity /path/to/my-vega-app
 ```
 
-### 6. `diagnose_crash`
+### 7. `fix_hot_functions`
 
-**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.
+**Description:** Diagnose and optimize Vega application UI fluidity issues by analyzing and fixing CPU-intensive hot functions.
 
 **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.
+- `vega_app_package_path` (required, string): Absolute path to the Vega app package root directory
 
 **Example usage:**
 
 ```
-> @diagnose_crash /path/to/crash.acr
+> @fix_hot_functions /path/to/my-vega-app
 ```
 
-### 7. `diagnose_key_input_latency`
+### 8. `react_native_for_vega_add_simple_media_playback_implementation`
 
-**Description:** Diagnose and resolve key input latency issues in React Native Vega apps through systematic analysis of JS Thread performance, CPU bottlenecks, and input event handling optimization.
+**Description:** Add a simple media playback implementation to an existing React Native for Vega application.
 
 **Parameters:**
 
 - `vega_app_package_path` (required, string): Absolute path to the Vega app package root directory
-- `app_process_name` (optional, string): Name of the app process experiencing input latency. If not provided, resolved automatically from manifest.toml.
-- `perfetto_trace_file_path` (optional, string): Absolute path to existing Perfetto trace file (if already captured)
-- `target_component_or_button` (optional, string): Specific button or component name to investigate
-- `latency_threshold_ms` (optional, number): Maximum acceptable input latency in milliseconds. Default is 100.
 
 **Example usage:**
 
 ```
-> @diagnose_key_input_latency /path/to/my-vega-app
+> @react_native_for_vega_add_simple_media_playback_implementation /path/to/my-vega-app
 ```
 
-### 8. `diagnose_ui_fluidity`
+### 9. `react_native_for_vega_ai_assisted_rn_upgrade`
 
-**Description:** Diagnose UI fluidity KPI failures in React Native Vega apps through systematic analysis of component re-rendering and CPU performance bottlenecks.
+**Description:** Trigger generic turn-based workflow for React Native version upgrades with AI-assisted migration.
 
 **Parameters:**
 
@@ -522,20 +502,21 @@ Amazon Devices Builder Tools MCP provides the following pre-defined prompt templ
 **Example usage:**
 
 ```
-> @diagnose_ui_fluidity /path/to/my-vega-app
+> @react_native_for_vega_ai_assisted_rn_upgrade /path/to/my-vega-app
 ```
 
-### 9. `convert_fos_webview_to_vega`
+### 10. `upgrade_carousel_component`
 
-**Description:** Convert an existing FireOS WebView application to a Vega WebView application while maintaining visual and functional consistency using Vega's WebView component.
+**Description:** Assists in migrating to newer versions of the Carousel component in the Vega SDK.
 
 **Parameters:**
 
-- `fos_app_workspace_path` (required, string): Path to the FireOS web app source code
-- `vega_app_workspace_path` (required, string): Path where the Vega app should be created
+- `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:**
 
 ```
-> @convert_fos_webview_to_vega /path/to/fos-web-app /path/to/vega-app
+> @upgrade_carousel_component /path/to/HomeScreen.tsx 1.0.6 2.0.0
 ```