# App Inventor MCP

An MCP (Model Context Protocol) server that lets AI agents build and edit MIT App Inventor projects. The agent creates real `.aia` files on disk, which you then import into App Inventor via *Projects > Import (.aia)*.

Part of the AIA Stitch family. Sister project: [aia-stitch](https://github.com/SirHumza/aia-stitch) (web UI for merging projects).

## Why

App Inventor is a visual drag-and-drop tool, which historically locked out AI agents. But an `.aia` file is just a zip: screens are JSON documents (`*.scm`), blocks are XML (`*.bky`), assets are plain files. This server exposes those facts as tools any MCP client can call, so an agent can scaffold an entire multi-screen app for you before you ever open the designer.

## Setup

Requires Node 18+.

```bash
npm install
node server.mjs
```

Add to your MCP client config (Claude Desktop, opencode, etc.):

```json
{
  "mcpServers": {
    "app-inventor": {
      "command": "node",
      "args": ["/absolute/path/to/app-inventor-mcp/server.mjs"]
    }
  }
}
```

## Tools

| Tool | What it does |
|---|---|
| `aia_create_project` | New `.aia` with a `Screen1`, valid properties |
| `aia_add_screen` | Add a screen |
| `aia_inspect` | List screens, components, assets, properties |
| `aia_get_screen` | Read one screen's components, properties and blocks XML |
| `aia_add_component` | Add a component, optionally nested in a parent arrangement |
| `aia_set_property` | Set a property on the screen or a component |
| `aia_set_blocks` | Replace a screen's blocks XML |
| `aia_add_event_handlers` | Generate event handlers (when Click do...) without knowing Blockly XML |
| `aia_add_asset` | Embed a local file (image, sound) into the project |
| `aia_merge` | Merge multiple `.aia` files into one |

## Testing

```bash
node test.mjs    # library roundtrip: create, author, merge
node smoke.mjs   # full MCP protocol handshake + tool calls over stdio
node stress.mjs  # scale (25 screens / 120 components), concurrency, abuse, recovery
```

## Honest limits

Components and screen properties are fully supported. Blocks authoring works at two levels: generated event handlers via `aia_add_event_handlers` (property setters and screen navigation), or raw Blockly XML via `aia_get_screen` / `aia_set_blocks`. There is no high-level vocabulary for every block type yet. UI-first apps work end to end today; exotic logic may want finishing touches inside App Inventor.

All file operations are serialized per path inside the process, so pipelined/concurrent calls from an agent are safe. Cross-process access to the same `.aia` at the same time is not guarded; don't edit one file from two servers at once.