bc-rig

bc-rig is a Linux-hosted Model Context Protocol server for driving two real Microsoft Dynamics 365 Business Central client surfaces:

• Business Central web through Playwright and a persistent, human-authenticated Chromium session.
• MobileNAV through an Android emulator, adb, and uiautomator.

It exposes both drivers through one stdio MCP server and can record exploratory runs, screenshots, and honest handover reports. The package does not contain credentials, customer data, MobileNAV, or an Android system image.

Install

Requirements:

• Linux and Node.js 22 or newer.
• Playwright Chromium: npx playwright install chromium.
• For mobile tools: KVM access, Android command-line tools, and an x86_64 Android system image.
• A valid Business Central account and MobileNAV licence/configuration for the environments you test.

Install the tagged GitHub release globally:

npm install --global github:Brad-Fullwood/bc-rig#v3.0.0
bc-rig init
bc-rig doctor

bc-rig init creates a commented config from .env.example. By default the config is ~/.config/bc-rig/.env; runtime data is kept under ~/.local/share/bc-rig. Both locations can be overridden—see Configuration.

To use the package without a global install, replace bc-rig with:

npx -y github:Brad-Fullwood/bc-rig#v3.0.0

MCP configuration

The repository's .mcp.json is portable and contains no checkout-specific cwd:

{
  "mcpServers": {
    "bc-rig": {
      "command": "npx",
      "args": ["-y", "github:Brad-Fullwood/bc-rig#v3.0.0"]
    }
  }
}

The CLI starts the MCP server when no subcommand is given. A global installation can instead use "command": "bc-rig-mcp".

The old checkout-relative form—npx tsx src/mcp/server.ts plus an absolute cwd—is deliberately not used. Renaming or moving a source folder therefore cannot break the published MCP command.

First run

Every browser is initialized from the AL project's .vscode/launch.json; there is no global tenant, environment, profile, or CDP setting. From an MCP client, start a session with:

{
  "operation": "start",
  "launchJson": "/absolute/path/to/project/.vscode/launch.json",
  "configuration": "Microsoft cloud sandbox"
}

configuration is optional and selects the first AL launch entry when omitted. Comments and trailing commas are supported. Tenant and environment come from that entry; omitted fields use Business Central's normal cloud defaults. A headed window opens for interactive sign-in and MFA.

The equivalent operator CLI is:

bc-rig browser start --launch /absolute/path/to/project/.vscode/launch.json \
  --configuration "Microsoft cloud sandbox"
bc-rig browser list
bc-rig bc-check --session <session-id>

Every start creates a new random session ID, persistent profile, headed Chromium process, and OS-assigned CDP port. Two agents—even against the same launch configuration—therefore cannot share or redirect each other's tabs. Each MCP process binds its browser tools to the session it starts or explicitly selects.

For MobileNAV:

bc-rig avd setup
bc-rig avd start
bc-rig mobile-install
bc-rig mobile-connect /path/to/environment.mnlc

The APK is downloaded from the vendor at setup time and checksum-verified. It is not redistributed by this project. Microsoft/MobileNAV authentication may still require interactive user action.

Efficient agent workflow

The MCP surface is built around project session → observe → referenced action:

1. Call browser_session with operation=start and the current project's launch.json.
2. Call browser_observe or mobile_observe in compact mode.
3. Act on the returned stable ref, such as @b7a12f or @m20c9e.
4. Read the changed state returned by browser_act / mobile_act; do not immediately observe again.
5. Use query to find page data that compact mode intentionally omitted.
6. When polling, pass the previous rev as since; unchanged state costs one short line.
7. Use full mode only for diagnosis. It is capped and explicitly marked as costly.

Refs are derived from role, accessible name, and occurrence in the existing ARIA/UI dump. Creating them requires no extra Playwright/ADB lookup calls. Browser actions accept an exact accessible name when a ref is unavailable, but the MCP surface does not expose raw CSS/Playwright selectors.

MCP tools

Tool	Purpose
doctor	Report host, Android, Playwright, and project-session readiness.
browser_session	Start/use/status/list/stop isolated browsers from AL launch configurations.
browser_observe	Return compact referenced state, focused query matches, or a capped full snapshot.
browser_act	Navigate/click/fill/press and return semantic changes or resulting compact state.
browser_screenshot	Save visual evidence only when text state is insufficient.
mobile_observe	Return compact referenced native state, optionally filtered or full.
mobile_act	Launch/stop/connect/tap/type/back/reset/wait and return resulting compact state.
mobile_screenshot	Save emulator visual evidence.
run	Start/status/annotate/finish an exploratory evidence manifest.

Connections are lazy: browser tools do not boot Android, and mobile tools do not require a browser. A mobile lease prevents two MCP processes from interleaving taps on the same emulator. Browser sessions are horizontally isolated and support concurrent agents.

Compared with v1, the advertised interface remains compact despite adding browser concurrency: 9 tools / 5,563 JSON bytes versus 18 tools / 7,663 bytes. Page responses shrink further because compact mode omits grid/text noise, actions return diffs, and unchanged polling returns only the revision marker.

Browser lifecycle change in v3

The singleton BC_BASE_URL, CDP_URL, and BC_PROFILE_DIR model was removed. Browser tools now reject calls until browser_session start or browser_session use binds that MCP process to an explicit project session. There is no implicit shared-browser fallback.

Reports

Start and finish a run through MCP, then generate its report:

bc-rig handover --run latest

Manifests and screenshots live in ~/.local/share/bc-rig/artifacts and generated reports in ~/.local/share/bc-rig/handover by default. The generator calls out read-only runs, missing client surfaces, absent failure probes, and missing screenshots instead of overstating coverage.

Configuration

Configuration precedence is:

1. Existing process environment variables.
2. BC_RIG_CONFIG_FILE.
3. .env in the process launch directory.
4. ~/.config/bc-rig/.env (or $XDG_CONFIG_HOME/bc-rig/.env).

Important overrides:

Variable	Default
BC_RIG_DATA_DIR	$XDG_DATA_HOME/bc-rig or ~/.local/share/bc-rig
BC_RIG_ARTIFACTS_DIR	<data>/artifacts
BC_RIG_HANDOVER_DIR	<data>/handover
ANDROID_HOME / ANDROID_SDK_ROOT	~/Android/Sdk
ANDROID_USER_HOME	~/.android
ANDROID_AVD_HOME	<ANDROID_USER_HOME>/avd
ANDROID_AVD_NAME	bcrig

Browser session records live under <data>/browser-sessions; isolated profiles live under <data>/browser-profiles/<session-id>. Chromium chooses each CDP port dynamically.

Run bc-rig paths to see the resolved locations.

Development

git clone https://github.com/Brad-Fullwood/bc-rig.git
cd bc-rig
npm ci
cp .env.example .env
npm run check
npm run mcp

npm run check compiles TypeScript, runs unit tests, performs a real MCP initialize/list-tools handshake, and inspects the publish tarball. See docs/architecture.md for the design and CONTRIBUTING.md for contribution guidance.

Security and privacy

Run artifacts can contain page text, company names, record data, screenshots, and target URLs. Connection files can identify tenants and users. They are excluded from git, but you are responsible for protecting the runtime data directory and reviewing every change before publishing. See SECURITY.md.

Licence

MIT. MobileNAV, Business Central, Android, Chromium, and Playwright retain their respective licences and trademarks.