MCP B4A

English · [Español](README.es.md)

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

| Tool | Description | |------|-------------| | b4a_get_config | Returns current paths and config sources (auto-detected vs explicit) | | b4a_set_config | Updates a configuration value |

Build & Deploy

| Tool | Description | |------|-------------| | b4a_build | Compiles a B4A project via B4ABuilder.exe (release/debug/bundle) | | b4a_build_and_install | Compiles and installs in one step — equivalent to b4a_build + b4a_install_apk | | b4a_get_build_log | Returns the log from the last build | | b4a_get_signing_info | Returns keystore path, alias, and signing status (passwords are never exposed) | | b4a_install_apk | Installs an APK on a connected device via ADB |

Project

| Tool | Description | |------|-------------| | b4a_read_project | Reads project metadata: libraries, modules, build configs | | b4a_list_project_files | Lists source files, layouts, and assets | | b4a_project_context | Single-call overview: app info, libraries, modules, and last build error | | b4a_list_recent_projects | Lists recently opened projects from the B4A IDE history |

Layouts

| Tool | Description | |------|-------------| | b4a_read_layout | Converts binary .bal/.bil to JSON | | b4a_write_layout | Writes JSON back to .bal/.bil (with validation and backup) | | b4a_list_layouts | Lists all layout files in a project directory |

Libraries

| Tool | Description | |------|-------------| | b4a_list_libraries | Lists available B4A libraries with version info | | b4a_get_library_docs | Returns formatted method/property/event documentation for a library | | b4a_search_library | Searches across all library documentation |

Source Modules

| Tool | Description | |------|-------------| | b4a_read_bas | Reads a .bas source module and returns its content with line numbers | | b4a_edit_bas | Search-and-replace edit on a .bas file. Matches exact text (including indentation), normalises line endings, creates .bak backup. Rejects ambiguous matches unless replace_all=true. |

Manifest

| Tool | Description | |------|-------------| | b4a_read_manifest | Extracts the Manifest Editor block from a .b4a file | | b4a_write_manifest | Updates the Manifest Editor block |

Device Interaction

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

| Tool | Description | |------|-------------| | b4a_screenshot | Captures a PNG from the device. Optional cropX/Y/W/H for sub-regions, optional delayMs to wait before capture | | b4a_pixel_scan | Reads RGB values from a saved PNG — individual points (x,y pairs) or a full region grid | | b4a_tap | Sends a tap event at (x, y) device coordinates | | b4a_swipe | Sends a swipe gesture from (x1,y1) to (x2,y2) with configurable duration | | b4a_launch_app | Launches an installed app via adb shell am start | | b4a_key_event | Sends an Android key event (BACK=4, HOME=3, MENU=82, ENTER=66, …) | | b4a_input_text | Types text into the focused input field (spaces as %s) |

Sprite Tools

| Tool | Description | |------|-------------| | b4a_sprite_cleanup | Cleans sprite PNG files generated by Gemini: removes white/gray border artifacts (residual dividing lines, anti-aliasing), optionally auto-crops transparent padding. Creates .bak backup before overwriting. Supports single file or *.png batch. Use autoCrop=false for game sprites — auto-crop changes canvas dimensions and deforms sprites when the game scales them to a fixed display size. |

ADB / Debugging

| Tool | Description | |------|-------------| | b4a_get_logcat | Returns logcat output filtered by the B4A tag. Shows [showing last N of M lines] prefix when output is truncated. | | b4a_list_devices | Lists connected ADB devices |

---

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. Get the binary

Recommended — download the prebuilt executable: grab B4aMcp.exe from the Releases page. It is a self-contained Windows build — no .NET runtime required.

Alternative — build from source:

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\B4aMcp.exe

Or add manually to your MCP settings:

{
  "mcpServers": {
    "b4a": {
      "command": "C:\\path\\to\\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.

| Property | Type | Required | Default | Notes | |----------|------|----------|---------|-------| | inputType | string | Yes | — | TEXT, NUMBERS, DECIMAL_NUMBERS, PHONE, NONE | | password | boolean | Yes | — | No null guard in B4A runtime — crashes if missing | | hint | string | No | "" | Placeholder text | | hintColor | color | No | 0xFFF0F0F0 | Uses ValueType: 6 format | | singleLine | boolean | No | true | Text wrapping behavior | | wrap | boolean | No | true | Has default in runtime | | forceDone | boolean | No | false | Has default in runtime |

> 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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: unmateria
• Source: unmateria/MCP-B4A
• License: MIT

Install and usage instructions live in the source repository linked above.