blueprism-mcp

Build, run and diagnose Blue Prism browser automations through a local MCP server. An LLM observes the requested website, proposes a typed plan, and gets native Blue Prism objects and processes with dynamic XPath, state-based Waits and business assertions.

Présentation courte en français

This is an original implementation started from scratch, not a fork of another Blue Prism MCP server. Blue Prism remains the execution engine; the model does not write arbitrary XML or Code Stages. The project is independent of SS&C.

Experimental preview: Windows, Blue Prism Enterprise 7.5.1 and Chrome with the official BP extension in a dedicated robot profile. Tested on a local trial environment with synthetic data; this is not a production qualification.

Recorded native-log demonstration · Detailed evidence and limitations · Template design and SS&C sources

The demonstration is an interactive replay of recorded native events, not a browser video. Download the repository and open the HTML locally to use its playback controls.

Implemented

• Typed objects with shared Attach/helpers, dynamic selectors and bounded Waits.

• DOM observation and XPath prevalidation in a separate temporary Chrome session.

• Native XML and offline expression checks, guarded import/publish, persistent launch keys and run tracking.

• Status, bounded logs and scalar assertions: Completed alone is not business success.

• Local MCP stdio tools and a portable skill.

• Native queue creation, verified seeding and an original bounded processing loop.

Objects are ordinary, editable BP artifacts: separate lifecycle and screen objects, reusable Attach/field pages, meaningful stage names, and separate Wait-success/timeout branches. Their structure is designed for maintenance in Studio, without requiring the LLM at runtime.

Existing names are preserved; deploy a new version instead of overwriting a Studio object. Native XML and expression checks do not replace full Studio/dependency validation. DOM verification does not prove BP extension compatibility. Listener collection payloads are withheld until decoding is qualified. General API workflows, credential management, merging into existing objects, Citrix/SAP and a replacement RPA runtime are outside this first release.

Related MCP server: AI Web Tester

Local setup

1. Install Node 24, Blue Prism and Chrome. Configure a local BP connection and runtime.

2. Prepare a dedicated Chrome user-data directory with the official BP extension.

3. Clone this repository and run:

   npm ci
   npm run build
   powershell -File tools/bpprobe/build.ps1
   npm run catalog:extract -w @bpdev/catalog
   Copy-Item .env.example .env

4. Fill .env locally: BP_USER, BP_PASSWORD, BP_RESOURCE_NAME, connection name and BP_ROBOT_PROFILE_DIR. The default listener is loopback port 8181. Keep the runtime idle before deployment; use a separate profile from normal browsing.

5. Configure a stdio MCP client: executable node, arguments containing the absolute path to packages/mcp/dist/cli.js and the absolute repository directory.

For clients using mcpServers JSON:

{
  "mcpServers": {
    "blueprism": {
      "command": "node",
      "args": ["C:/path/to/blueprism-mcp/packages/mcp/dist/cli.js", "C:/path/to/blueprism-mcp"]
    }
  }
}

The CLI loads .env; existing environment variables take precedence. No secret is needed in the MCP client configuration. Extracted AMI catalogues and BP binaries are local dependencies, not redistributed assets.

Workflow

Read bp_capabilities and bp_catalog. Observe with scan_open and verify candidate selectors with scan_verify. Use bp_prepare, bp_validate, bp_deploy, then bp_start with a stable request key. Poll bp_inspect for status, logs and assertions.

Reuse the same request key after a lost response. An unknown launch needs reconciliation. After a submission timeout, check the business effect before retrying. Stop acknowledgement does not mean the robot has stopped. Failed/stopped sessions and unverified business results block subsequent mutations until an operator records independent evidence with the runner's reconciliation API. This override is deliberately absent from the MCP tool surface. Queue loading is limited to one batch per queue created by this runner; a different request key does not permit reseeding it. The process itself consumes items until none is eligible or a stopping limit is reached: 100 items by default (maximum 1,000), three consecutive System Exceptions by default, or an operator stop request. It finalizes each item before continuing and performs no item retries. An empty Item ID means no eligible item now, not that the queue has no remaining rows.

Verification and demonstration

npm run lint
npm run typecheck
npm test
npm run build

Latest full suite: 823 passed, 14 optional tests skipped; lint, typecheck and build passed. The 14 real-Chrome scanner tests also passed in a separate targeted run. Native operator-stop and queue-finalization-failure injection remain explicit backlog items; their unit guards are covered, but no native pass is claimed. Exception screenshot retrieval is not implemented. See the qualification record for the fresh-agent trial and interventions.

CI runs without Blue Prism. The native demo imports new BPDEV versions and uses synthetic data on RPA Challenge. Enable it explicitly:

$env:BP_INTEGRATION = '1'
node tools/demo/run-rpa.js

It uses the public MCP protocol from generation through inspection. Local evidence goes to .bpdev/demo. Start the original service-request fixture with:

node tools/demo/site.js

With that local target running, node tools/demo/run-service-desk.js repeats the qualified browser scenario (BP_INTEGRATION=1 required). The queue scenario separates deployment for Studio inspection from execution. Choose a fresh suite ID once:

$env:BP_INTEGRATION = '1'
$env:BPDEMO_SCENARIO = 'mixed'
$env:BPDEMO_QUEUE_ID = $env:BPDEMO_SCENARIO + '-' + (Get-Date -Format 'yyyyMMddHHmmss')
$env:BPDEMO_PHASE = 'deploy'
node tools/demo/run-queue.js

This prepares, validates, imports and publishes the objects, consumer and seed when needed; it does not load or process queue items. Inspect the process and its objects in Studio and require zero errors before proceeding. Trial published-process limits can block this deployment phase. Choose BPDEMO_SCENARIO from mixed, empty, item-limit or system-limit (default: mixed). Use a fresh suite ID for each new scenario; IDs accept letters, digits and hyphens, up to 40 characters. empty creates no seed. Keep the same scenario, suite ID and local target running between deploy and run:

$env:BPDEMO_PHASE = 'run'
node tools/demo/run-queue.js
node tools/demo/export-queue.js

The run phase verifies the seed count when applicable and the expected aggregate results. The operator-only export uses native /exportqueue to save a CSV under .bpdev/demo/<suite-id>/; it does not modify or clear queue items. Review it alongside /records. Failed or uncertain runs need reconciliation; changing the suite ID or repeating a seed is not a recovery procedure. The qualification record identifies the passing mixed, empty, item-limit and system-limit scenarios, their evidence and the guard cases still to be tested.

Its input IDs/order change on each load, confirmation is delayed, and /records independently counts submissions. It binds only to 127.0.0.1:8931. Use synthetic demo-* case references.

Before publishing, run node tools/security/audit-public.js with any additional local .env paths as arguments. It checks public files and historical Git blobs without printing matched secret values. Review findings require inspection; a clean scan cannot prove the absence of every unknown secret. Local .env, .bpdev, reference releases and vendor catalogues stay out of Git.

Structure

Contributors and license

• Swih — project author, product direction and Blue Prism expertise.

• Codex — AI-assisted implementation, tests and integration.

• Claude — AI-assisted design review and strategic feedback.

MIT, copyright 2026 Swih. Third-party dependencies retain their own licenses. Blue Prism, its extension and its libraries are not included in this license or repository.