AndroidBuilder MCP Server

<<<<<<< Updated upstream Local Model Context Protocol server for MIT App Inventor, AndroidBuilder, Kodular, Niotron, and AppyBuilder. It connects to a Chrome/Chromium session through the Chrome DevTools Protocol and lets MCP clients inspect the Designer and Blocks workspaces.

The server is safe by default: read tools are available immediately, while write tools require explicit environment flags.

Tools

Related MCP server: Chrome DevTools MCP

Requirements

• Node.js >=22.12

• Chrome or Chromium launched with remote debugging enabled

======= MCP server for MIT App Inventor and AndroidBuilder automation through Chrome DevTools Protocol, plus safe offline inspection of .aia and .aix archives. Kodular, Niotron, and AppyBuilder origins are recognized for discovery but remain experimental for live operations.

Capabilities

Live IDE tools:

• list_ide_tabs, select_ide_tab, get_project_info

• get_component_tree, get_component_properties, update_component_property

• add_blocks, get_blocks_xml, clear_blocks

• switch_screen, list_screens

• click_element (disabled unless ANDROIDBUILDER_UNSAFE_TOOLS=1)

Offline tools:

• inspect_aia, validate_aia, diff_aia

• inspect_aix, validate_aix

• read_archive_entry

Offline tools are read-only. They do not extract, execute, modify, or repackage project files.

Requirements

• Node.js 18 or newer

• Chrome/Chromium started with a loopback CDP port, preferably using a dedicated profile:

Stashed changes

chrome.exe --remote-debugging-port=9222 --user-data-dir="$env:TEMP\androidbuilder-cdp"

<<<<<<< Updated upstream Open your App Inventor-family IDE and load the project in that Chrome session.

Install

======= Open the project in the browser before calling live tools. CDP grants this server control over tabs accessible to that browser profile.

Install and run

Stashed changes

npm install
npm run build
<<<<<<< Updated upstream

Run the server:

node dist/index.js

MCP Config

Use .mcp.json in this repository for local development:

npm start

MCP client configuration should invoke the package binary or the installed `dist/index.js`; do not use a machine-specific path:
>>>>>>> Stashed changes

```json
{
  "mcpServers": {
    "androidbuilder-mcp": {
<<<<<<< Updated upstream
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "BROWSER_DEBUG_PORT": "9222",
        "ANDROIDBUILDER_ALLOW_WRITE": "0"
=======
      "command": "androidbuilder-mcp",
      "env": {
        "BROWSER_DEBUG_PORT": "9222",
        "ANDROIDBUILDER_PROJECT_ROOT": "C:/projects",
        "ANDROIDBUILDER_DEBUG": "0"
>>>>>>> Stashed changes
      }
    }
  }
}

<<<<<<< Updated upstream For clients that do not resolve relative paths from the repository root, replace dist/index.js with an absolute path.

Environment

=======

Environment variables

Stashed changes

Codex, Claude, and Antigravity

• Codex plugin manifest: .codex-plugin/plugin.json

• Portable MCP config: .mcp.json

• Open Agent Skill: skills/build-app-inventor-apps/SKILL.md

See docs/compatibility.md for client-specific setup notes.

| EVAL_TIMEOUT_MS | 15000 | Page evaluation timeout; mutation timeouts have unknown outcome | | ANDROIDBUILDER_DEBUG | 0 | Verbose stderr logging when set to 1 | | ANDROIDBUILDER_UNSAFE_TOOLS | unset | Must be 1 to enable click_element | | ANDROIDBUILDER_PROJECT_ROOT | unset | Required root for offline archive paths | | AIA_MAX_COMPRESSED_BYTES | 31457280 | Compressed AIA limit | | AIX_MAX_COMPRESSED_BYTES | 52428800 | Compressed AIX limit | | ARCHIVE_MAX_UNCOMPRESSED_BYTES | 209715200 | Total decompressed entry limit | | ARCHIVE_MAX_ENTRIES | 10000 | Maximum ZIP entries | | ARCHIVE_MAX_RATIO | 100 | Maximum uncompressed/compressed ratio | | ARCHIVE_MAX_READ_ENTRY_BYTES | 5242880 | Maximum entry returned by read_archive_entry |

Safe workflows

For live work, call list_ide_tabs first and explicitly select a tab when more than one trusted IDE tab is open. Confirm project and screen with get_project_info. Component reads and writes select and verify the named component; property updates are re-read after mutation.

clear_blocks is two-phase. The first call returns a backup XML, hash, block count, and confirmation token. Call it again with that token only after confirming the backup and intended deletion. Never retry a mutation after a timeout without reading the state first.

For offline work, set ANDROIDBUILDER_PROJECT_ROOT and pass only relative paths. AIA inspection understands youngandroidproject/project.properties, src/**/*.scm, src/**/*.bky, assets, and external components. AIX inspection reports component descriptors, build metadata, artifacts, permissions, dependencies, native libraries, and hashes. Embedded code is never executed.

Stashed changes

Development

npm run build
npm test
npm pack --dry-run

<<<<<<< Updated upstream npm test builds the server, runs a real MCP SDK smoke test, verifies write tools are gated, checks the no-Chrome error path, and validates package metadata.

Troubleshooting

• Failed to connect to Chrome CDP: start Chrome with --remote-debugging-port=9222.

• No active AndroidBuilder/App Inventor tab found: open a project in the debug Chrome session.

• Component tree (.gwt-Tree) not found: switch to Designer view.

• Blockly is not available: switch to Blocks view.

• Write tool rejected: restart the MCP server with ANDROIDBUILDER_ALLOW_WRITE=1.

  The operational agent guidance is versioned at skills/androidbuilder-mcp/SKILL.md.

Stashed changes

Scope

<<<<<<< Updated upstream

• AndroidBuilder

• MIT App Inventor 2

• MIT App Inventor Code

• Niotron

• Kodular

• AppyBuilder

  Supported live IDEs: MIT App Inventor and AndroidBuilder. Other recognized hosts are experimental until they have dedicated fixtures. This project does not claim to import/export projects through the UI, compile APK/AAB, edit/repack AIA/AIX, or modify compiled AIX code.

Stashed changes

License

MIT