MCP Server for B4A

Bridges Claude Code (and any MCP-compatible client) with the B4A (Basic4Android) ecosystem.

Exposes 31 tools for compiling projects, reading/editing source modules, reading/modifying layouts, exploring libraries, deploying APKs, debugging via ADB, doing live visual UI verification directly on the device, and cleaning up sprite PNG artifacts — all without leaving your AI coding assistant.

Tools

Configuration

Build & Deploy

Project

Layouts

Libraries

Source Modules

Manifest

Device Interaction

Enables visual UI verification and device control without leaving Claude Code. Replaces the manual Bash + PIL screenshot workflow.

Sprite Tools

ADB / Debugging

Prerequisites

• .NET 8 Runtime (or use the self-contained build)
• B4A IDE installed (required for compilation)
• Android SDK Platform Tools (required for ADB tools)

Installation

1. Build

cd B4aMcp
dotnet publish -c Release -r win-x64 --self-contained -p:PublishSingleFile=true -o ../publish

2. Configure Claude Code

claude mcp add b4a C:\path\to\publish\B4aMcp.exe

Or add manually to your MCP settings:

{
  "mcpServers": {
    "b4a": {
      "command": "C:\\path\\to\\publish\\B4aMcp.exe",
      "args": []
    }
  }
}

3. First-time setup

Run b4a_get_config to check auto-detected paths. If B4A is installed in a non-standard location, configure manually:

b4a_set_config(key="b4aPath", value="C:\\B4A")
b4a_set_config(key="additionalLibrariesPath", value="C:\\B4A\\SharedLibs")

The server auto-detects paths from the B4A IDE settings file (b4xV5.ini) when possible. Config is stored at %APPDATA%\mcp-b4a\config.json.

Layout Files (.bal / .bil)

B4A stores UI layouts in a proprietary binary format. This server includes a full port of the official BalConverter to VB.NET, providing lossless binary-to-JSON roundtrip conversion.

• .bal — standard layout (Activity layouts)
• .bil — internal layout variant (RECT32/CNULL entries stripped on write)

Roundtrip safety: b4a_write_layout validates JSON structure and always creates a .bak backup before writing.

EditText Required Properties

EditText controls in layout JSON require specific properties that differ from other control types. The B4A runtime does not null-guard all of them, so missing properties cause runtime crashes.

inputType values must be string constants, NOT integers. B4A uses Java reflection (getField("INPUT_TYPE_" + value)) internally, so numeric values like 1 or 129 will crash at runtime with NoSuchFieldException.

b4a_write_layout automatically injects missing password and singleLine with safe defaults, and converts numeric inputType values to their named equivalents when possible. Warnings are included in the response.

Common B4A Pitfall: DrawText Font Size is dp, Not Pixels

Canvas.DrawText in B4A interprets the font size parameter as dp (density-independent pixels). Android multiplies by deviceDpi / 160 internally, so the same numeric font size renders at very different pixel sizes across devices. If UI containers (bitmaps, rects) use hardcoded pixel dimensions but fonts scale with DPI, text will overflow on low-DPI devices.

Rule of thumb: every UI dimension — container sizes, font sizes, positions, and touch zones — should be proportional to 100%x / 100%y (screen width/height in pixels). Never use hardcoded pixel values like Dim btnW As Int = 200.

See b4a_language_gotchas for more B4A-specific pitfalls.

Notable Implementation Details

• b4a_build WorkingDirectory: B4ABuilder.exe is invoked with WorkingDirectory = baseFolder. Without this, the builder cannot locate the .b4a file even when -BaseFolder is passed, because it resolves the project filename against the current working directory of the calling process.

• Manifest write safety: b4a_write_manifest uses a MatchEvaluator lambda instead of a string replacement to prevent Regex.Replace from interpreting $0/\1-style backreferences in the manifest content. A .bak backup is always written before modifying the file.

• Config resilience: If %APPDATA%\mcp-b4a\config.json is malformed, the server falls back to an empty config and auto-detects paths from b4xV5.ini rather than crashing at startup.

Security

• b4a_build only accepts paths to existing .b4a files — no arbitrary command execution.
• All file writes create .bak backups first.
• ADB tools that modify device state (b4a_tap, b4a_swipe, b4a_launch_app, b4a_key_event, b4a_input_text, b4a_install_apk) only interact with the connected Android device, not the host filesystem.
• Signing passwords from b4xV5.ini are never exposed through b4a_get_signing_info.

Caching

The server caches results to avoid redundant I/O:

• File-based cache (mtime-invalidated): layout conversions, project parsing, library docs
• TTL cache (60s): device list, library listings
• Simple store: last build log (no expiry, replaced on each build)

Cache is invalidated automatically when source files change.

Development

cd B4aMcp
dotnet build
dotnet run

The server communicates via stdio (MCP standard). It does not open any network ports.

Project Structure

B4aMcp/
├── Program.vb              # Server entry point
├── Models/
│   ├── B4aProject.vb       # Project metadata model
│   └── McpConfig.vb        # Configuration model
├── Tools/
│   ├── AdbTools.vb          # logcat, devices, install APK
│   ├── BuildTools.vb        # compile, build+install combo, build log, signing info
│   ├── ConfigTools.vb       # get/set configuration
│   ├── DeviceTools.vb       # screenshot, tap, swipe, launch app, pixel scan, key event, input text
│   ├── LayoutTools.vb       # read/write/list layouts + EditText validation
│   ├── LibraryTools.vb      # list, docs, search libraries
│   ├── BasTools.vb           # read/edit .bas source modules
│   ├── ManifestTools.vb     # read/write manifest block
│   ├── ProjectTools.vb      # project metadata, file listing, context
│   └── SpriteTools.vb       # sprite PNG cleanup: edge artifact removal + auto-crop
└── Utils/
    ├── AppConfig.vb          # Config management + B4A IDE auto-detection
    ├── B4aParser.vb          # .b4a project file parser
    ├── BalConverter.vb        # Binary .bal/.bil ↔ JSON converter
    └── CacheManager.vb       # Mtime-based + TTL caching

Tech Stack

• VB.NET targeting .NET 8
• ModelContextProtocol SDK (0.9.0-preview.2)
• Newtonsoft.Json for serialization
• System.Drawing.Common for PNG pixel reading (Windows only)

License

MIT