appinventor-claude-mcp

MCP server for MIT App Inventor .aia projects. It reads and writes screen .scm and .bky files inside the project zip so agents can modify UI and blocks.

Features

• Validate .aia projects
• List screens
• Read and write screen .scm / .bky
• REST + MCP stdio transport

Requirements

• Node.js 18+

Installation

Global install:

npm install -g appinventor-claude-mcp

Local dev:

npm install
npm run build
npm run build:mcp

Usage

Run the REST server

appinventor-claude-mcp

Defaults to port 3070. Override with:

$env:PORT=3071
appinventor-claude-mcp

Run the MCP stdio server

node build/mcp.js

MCP client config

{
  "mcpServers": {
    "appinventor-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/build/mcp.js"]
    }
  }
}

Tutorial (10 minutes)

1. Choose a .aia file on disk.
2. Validate it:
   • POST /validate
   • Body: { "aiaPath": "/path/to/project.aia" }
3. List screens:
   • POST /list_screens
   • Body: { "aiaPath": "/path/to/project.aia" }
4. Read a screen:
   • POST /read_screen
   • Body: { "aiaPath": "/path/to/project.aia", "screenName": "Screen1" }
5. Write an update to a new file:
   • POST /write_screen
   • Body: { "aiaPath": "/path/to/project.aia", "screenName": "Screen1", "scm": "<xml>...</xml>", "outputPath": "/path/to/project-out.aia" }

REST API

Health

• GET /health -> { status: "ok" }

Validate

• POST /validate body: { aiaPath: string }
• Returns { valid, screens }

List screens

• POST /list_screens body: { aiaPath: string }
• Returns { screens }

Read screen

• POST /read_screen body: { aiaPath: string, screenName?: string }
• Returns { screenName, scm, bky }

Write screen

• POST /write_screen body: { aiaPath: string, screenName?: string, scm?: string, bky?: string, outputPath?: string }
• Returns { success, outputPath }
• If outputPath is not set, a .bak is created before overwrite

Clawdbot / Moltbot compatibility

This repo ships a skill at skills/appinventor-mcp/SKILL.md.

Enable it in Moltbot:

{
  "skills": {
    "load": {
      "extraDirs": ["~/.clawdbot/skills"],
      "watch": true,
      "watchDebounceMs": 250
    },
    "entries": {
      "appinventor-mcp": {
        "enabled": true,
        "env": {}
      }
    }
  }
}

Example prompts

• "Open this .aia file and add a Button labeled Start to Screen1."
• "List all screens and summarize their components."
• "Update Screen1 blocks to log when a button is clicked."

Testing

npm test

Tests generate temporary .aia fixtures on the fly.

Publishing

1. Update package.json version
2. Build:

   npm run build
   npm run build:mcp

3. Publish:

   npm publish --access public

4. Tag and push to trigger .github/workflows/publish.yml

Project structure

• src/index.ts REST API
• src/mcp.ts MCP stdio bridge
• skills/appinventor-mcp/SKILL.md agent skill
• server.json MCP registry metadata

Contributing

PRs welcome. Please keep changes small and include tests where possible.

License

MIT