mcp-eregistrations-bpa 0.4.0

MCP server for eRegistrations BPA platform

MCP eRegistrations BPA

AI-powered Service Design for Government Digital Transformation

An MCP server that enables AI assistants like Claude to design, configure, and deploy government services on the eRegistrations BPA platform using natural language.

What It Does

Design and configure BPA services through conversation:

You: Create a "Business License" service
Claude: Created service with registration. Service ID: abc-123

You: Add a reviewer role
Claude: Added "Reviewer" role to the service

You: Set a $50 processing fee
Claude: Created fixed cost of $50 attached to the registration

Each step uses the right MCP tool. Full audit trail. Rollback if needed.

Prerequisites

Install uv (includes uvx):

# macOS (recommended)
brew install uv

# Other platforms
curl -LsSf https://astral.sh/uv/install.sh | sh

Quick Install

For Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "BPA-elsalvador-dev": {
      "command": "uvx",
      "args": ["mcp-eregistrations-bpa"],
      "env": {
        "BPA_INSTANCE_URL": "https://bpa.dev.els.eregistrations.org",
        "KEYCLOAK_URL": "https://login.dev.els.eregistrations.org",
        "KEYCLOAK_REALM": "SV"
      }
    }
  }
}

Troubleshooting: If you get "command not found: uvx", you installed via curl which puts uvx in ~/.local/bin (not in GUI app PATH). Fix: either brew install uv, or use "command": "/bin/zsh", "args": ["-c", "$HOME/.local/bin/uvx mcp-eregistrations-bpa"]

For Claude Code — add to .mcp.json in your project:

{
  "mcpServers": {
    "BPA-elsalvador-dev": {
      "command": "uvx",
      "args": ["mcp-eregistrations-bpa"],
      "env": {
        "BPA_INSTANCE_URL": "https://bpa.dev.els.eregistrations.org",
        "KEYCLOAK_URL": "https://login.dev.els.eregistrations.org",
        "KEYCLOAK_REALM": "SV"
      }
    }
  }
}

That's it. On first use, a browser opens for Keycloak login. Your BPA permissions apply automatically.

Tip: Name each MCP after its instance (e.g., BPA-elsalvador-dev, BPA-kenya-test) to manage multiple environments.

69 MCP Tools

Category	Capabilities
Services	Create, read, update, copy, export, transform to YAML
Registrations	Full CRUD with parent service linking
Institutions	Assign/unassign institutions to registrations
Forms	Read/write Form.io components with container support
Roles	Create reviewer/approver/processor roles
Bots	Configure workflow automation
Determinants	Text and select conditional logic
Costs	Fixed fees and formula-based pricing
Documents	Link document requirements to registrations
Workflows	Intent-based natural language service design
Audit	Complete operation history with rollback
Analysis	Service inspection and dependency mapping

Natural Language Workflows

Ask Claude to design services using plain English:

What you say	What happens
"Create a permit service"	Creates service + registration with proper structure
"Add a reviewer role to this service"	Adds UserRole with 'processing' assignment
"Set a $75 application fee"	Creates fixed cost attached to registration
"Add document requirement for ID proof"	Links requirement to the registration

The workflow system extracts your intent, validates inputs, and executes multi-step operations with full audit trail.

Key Features

Audit Trail — Every operation logged (who, what, when). Query history with audit_list.

Rollback — Undo any write operation. Restore previous state with rollback.

Export — Get complete service definitions as clean YAML for review or version control.

Copy — Clone existing services with selective component inclusion.

Form MCP Tools

BPA uses Form.io for dynamic forms. These tools provide full CRUD operations on form components.

Available Tools

Tool	Purpose
form_get	Get form structure with simplified component list
form_component_get	Get full details of a specific component
form_component_add	Add new component to form
form_component_update	Update component properties
form_component_remove	Remove component from form
form_component_move	Move component to new position/parent
form_update	Replace entire form schema

Form Types

• applicant (default) - Main application form
• guide - Guidance/help form
• send_file - File submission form
• payment - Payment form

Property Availability

Properties vary by tool. Use form_get for overview, form_component_get for full details:

Property	form_get	form_component_get
key	Yes	Yes
type	Yes	Yes
label	Yes	Yes
path	Yes	Yes
is_container	Yes	No
children_count	For containers	No
required	When present	Yes (in validate)
validate	No	Yes
registrations	No	Yes
determinant_ids	No	Yes (in raw)
data	No	Yes
default_value	No	Yes
raw	No	Yes (complete object)

Container Types

Form.io uses containers to organize components. Each has different child accessors:

Container Type    Children Accessor
--------------    -----------------
tabs              components[] (tab panes)
panel             components[]
columns           columns[].components[] (2-level)
fieldset          components[]
editgrid          components[] (repeatable)
datagrid          components[]
table             rows[][] (HTML table)
well              components[]
container         components[]

Usage Examples

Get form overview:

form_get(service_id="abc-123", form_type="applicant")
# Returns: component_count, component_keys, simplified components list

Get specific component details:

form_component_get(service_id="abc-123", component_key="firstName")
# Returns: full component with validate, data, determinant_ids, raw object

Add component to form:

form_component_add(
    service_id="abc-123",
    component={"key": "email", "type": "email", "label": "Email Address"},
    parent_key="personalInfo",  # Optional: nest under panel
    position=0                   # Optional: insert at position
)

Update component:

form_component_update(
    service_id="abc-123",
    component_key="firstName",
    updates={"validate": {"required": True}, "label": "First Name *"}
)

Move component:

form_component_move(
    service_id="abc-123",
    component_key="phoneNumber",
    new_parent_key="contactPanel",
    new_position=1
)

All write operations include audit_id for rollback capability.

Example Session

You: List all services

Claude: Found 12 services. [displays table with IDs, names, status]

You: Analyze the "Business Registration" service

Claude: [shows registrations, roles, determinants, documents, costs]
        Found 3 potential issues: orphaned determinant, missing cost...

You: Create a copy called "Business Registration v2"

Claude: Created service with ID abc-123. Copied 2 registrations,
        4 roles, 8 determinants. Audit ID: xyz-789

Authentication

Uses Keycloak OIDC with Authorization Code + PKCE:

1. Browser opens automatically on first connection
2. Login with your BPA credentials
3. Tokens managed automatically with refresh
4. Your BPA permissions apply to all operations

Configuration

Variable	Description	Required
BPA_INSTANCE_URL	BPA server URL	Yes
KEYCLOAK_URL	Keycloak server URL	Yes
KEYCLOAK_REALM	Keycloak realm name	Yes
LOG_LEVEL	DEBUG, INFO, WARNING, ERROR	No

Logs: ~/.config/mcp-eregistrations-bpa/server.log

Development

# Clone and install
git clone https://github.com/unctad-ai/mcp-eregistrations-bpa.git
cd mcp-eregistrations-bpa
uv sync

# Run tests (800+ tests)
uv run pytest

# Lint and format
uv run ruff check . && uv run ruff format .

License

Copyright (c) 2025-2026 UN for Trade & Development (UNCTAD) Division on Investment and Enterprise (DIAE) Business Facilitation Section

All rights reserved. See LICENSE.

---

Part of eRegistrations