# AndroidBuilder MCP Server

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 can safely inspect AIA/AIX archives offline.

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

## Tools

| Tool | Mode | Notes |
|---|---|---|
| `get_project_info` | Read | Project, active screen, view, IDE type, URL |
| `list_screens` | Read | Lists available screens |
| `switch_screen` | Read/navigation | Switches active screen |
| `get_component_tree` | Read | Designer component tree |
| `get_component_properties` | Read | Selects component by name when possible |
| `get_blocks_xml` | Read | Exports Blockly XML |
| `update_component_property` | Write | Requires `ANDROIDBUILDER_ALLOW_WRITE=1` |
| `add_blocks` | Write | Requires `ANDROIDBUILDER_ALLOW_WRITE=1` |
| `clear_blocks` | Destructive | Requires `ANDROIDBUILDER_ALLOW_WRITE=1` and `confirm: "CLEAR_BLOCKS"` |
<<<<<<< Updated upstream
| `click_element` | Unsafe fallback | Requires both write flags and `confirm: "CLICK_ELEMENT"` |
=======
| `click_element` | Unsafe fallback | Requires `ANDROIDBUILDER_ALLOW_UNSAFE_CLICK=1` and `confirm: "CLICK_ELEMENT"` |
>>>>>>> Stashed changes
| `list_ide_tabs` / `select_ide_tab` | Navigation | Explicit trusted-tab selection |
| `inspect_aia` / `validate_aia` / `diff_aia` | Offline read | Safe project archive inspection |
| `inspect_aix` / `validate_aix` | Offline read | Safe extension metadata inspection |
| `read_archive_entry` | Offline read | Bounded single-entry read |
| `get_component_catalog` / `get_component_schema` / `search_components` | Read | Provider-discovered component metadata |
| `get_block_diagnostics` | Read | Counts, warnings, and orphaned value blocks |
| `take_screenshot` | Read | Designer, blocks, or full-page PNG |
| `update_component_properties` | Write | Verified sequential batch update |

All tool results include `success`. Errors include a stable `code`; mutation timeouts include `outcome: "unknown"` and must be verified before retrying.

## Requirements

- Node.js `>=22.12`
- Chrome or Chromium launched with remote debugging enabled

```powershell
chrome.exe --remote-debugging-port=9222
```

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

## Install

```bash
npm install
npm run build
```

Run the server:

```bash
node dist/index.js
```

## MCP Config

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

```json
{
  "mcpServers": {
    "androidbuilder-mcp": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "BROWSER_DEBUG_PORT": "9222",
        "ANDROIDBUILDER_ALLOW_WRITE": "0"
      }
    }
  }
}
```

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

## Environment

| Variable | Default | Description |
|---|---:|---|
| `BROWSER_DEBUG_PORT` | `9222` | Chrome remote debugging port |
| `EVAL_TIMEOUT_MS` | `15000` | Max time for page evaluation |
| `ANDROIDBUILDER_DEBUG` | `0` | Verbose stderr logging |
| `ANDROIDBUILDER_ALLOW_WRITE` | `0` | Enables property/block mutations |
| `ANDROIDBUILDER_ALLOW_UNSAFE_CLICK` | `0` | Enables arbitrary CSS click fallback |
| `ANDROIDBUILDER_PROJECT_ROOT` | empty | Dedicated root for relative AIA/AIX paths |
| `BLOCKLY_XML_MAX_BYTES` | `1048576` | Maximum Blockly XML mutation size |

## Multi-IDE compatibility

<<<<<<< Updated upstream
The server recognizes IDEs by exact hostname and exposes provider capabilities and a `validated` flag through `get_project_info`. Providers currently share conservative GWT/Blockly fallbacks; AppyBuilder is read-only. A recognized provider is not automatically validated—run live contract tests against a disposable project before advertising production support.
=======
The server recognizes IDEs by exact hostname and exposes provider capabilities and a `validated` flag through `get_project_info`. MIT App Inventor, AndroidBuilder, Kodular, and Niotron adapters use isolated strategies; AppyBuilder is experimental and read-only. A recognized provider is not automatically considered validated—run the live contract suite against a disposable project before advertising production support.
>>>>>>> Stashed changes

## Codex, Claude, and Antigravity

- Codex plugin manifest: `.codex-plugin/plugin.json`
- Portable MCP config: `.mcp.json`
- Open Agent Skill: `skills/androidbuilder-mcp/SKILL.md`

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

## Comparison with appinventor-mcp

The useful transport-independent features from `rhyumiranda/appinventor-mcp` were adapted to the existing CDP bridge. See [docs/appinventor-mcp-comparison.md](docs/appinventor-mcp-comparison.md) for the architectural comparison, adopted features, and rejected high-risk RPC mutations.

## Development


```bash
npm run build
npm test
npm pack --dry-run
```

`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`.

## Recognized IDEs

- AndroidBuilder
- MIT App Inventor 2
- MIT App Inventor Code
- Niotron
- Kodular
- AppyBuilder

## License

MIT