bga-mcp

An unofficial Model Context Protocol (MCP) server for Board Game Arena Studio development.

bga-mcp aims to give MCP-compatible coding agents structured, safe access to the information and workflows needed to build and maintain games for Board Game Arena (BGA). The goal is not to generate an entire game autonomously. The goal is to make an experienced developer faster and help a new BGA developer avoid framework-specific mistakes.

Why this exists

BGA development spans local PHP, JavaScript or TypeScript, SQL, BGA's state machine, SFTP synchronization, browser-based testing, and Studio logs. General-purpose coding agents can edit the files, but they do not automatically understand how those pieces relate.

This server will focus on the gaps that benefit from structured BGA knowledge and purpose-built operations:

• Inspecting a project and explaining its BGA-specific structure.

• Validating state definitions, transitions, actions, notifications, and database usage across files.

• Searching curated, version-aware BGA development documentation.

• Running repeatable project and pre-release checks.

• Previewing and synchronizing changes to BGA Studio safely.

• Reading and filtering Studio diagnostics without pasting logs into an agent conversation.

Related MCP server: @lex-tools/codebase-context-dumper

Capabilities

Available now, local and read-only:

• inspect_project — detects the project layout, reports metadata, components, and the state machine where it can be read, and returns explicit findings for anything missing, uncertain, or unsupported. Every validator reads both the legacy forms (states.inc.php, <game>.action.php, notifyAllPlayers) and the modern ones (state classes, autowired act… methods, bga->notify), and reads each file in whichever form it is actually in. BGA migrates a project one file at a time, so most projects are part-way between; metadata, game logic, states, and client logic are each detected on their own, and a state machine split across states.inc.php and modules/php/States is read as one machine.

• validate_state_machine — checks the entry state, duplicate identifiers and names, unknown state types, transition targets, unreachable states, dead ends, and whether the methods a state names exist in readable PHP source. Structural findings are facts; cross-file handler findings are heuristics that carry their known limitations.

• validate_action_contracts — traces each player action from the client call, to the entry point in the action class, to the game method, and reports actions no state allows, missing entry points and methods, and arguments the two sides disagree about.

• validate_notifications — compares the notifications the server sends with the handlers the client declares, including payload keys. A notification nobody handles fails silently at runtime; this finds it before a player does.

• audit_database_usage — compares dbmodel.sql with the queries the PHP sources run, reporting undeclared tables and columns, unused columns, and queries that interpolate a value instead of escaping it.

• validate_project — runs every validator, or the groups you select, and combines the results. A validator that fails is reported as failed and makes the run incomplete rather than leaving it looking clean.

It also serves three read-only resources describing the single configured project: bga://project/summary, bga://project/states, and bga://project/diagnostics.

• run_pre_release_audit — runs the catalogued pre-release checks and reports passed, failed, unsupported, and manual-required separately. It never counts a check it could not run, or one that needs a human, as passed.

Planned for the first useful release:

• search_bga_docs

Later releases may add authenticated Studio operations:

• preview_studio_sync

• sync_to_studio

• read_studio_logs

• Test-table and saved-state workflows where they can be implemented reliably and responsibly.

The names above are proposals, not a stable API.

Design principles

• Verified, not assumed: no tool or resource is complete until its public behavior passes end-to-end tests through a real MCP client.

• Local first: source code and credentials stay on the developer's machine by default.

• Read-only by default: inspection and validation should not change a project or Studio state.

• Preview before mutation: uploads and other state-changing operations expose an exact dry run first.

• Structured results: tools return actionable findings with locations, evidence, and severity.

• Agent neutral: any client with suitable MCP support should be able to use the server.

• Current, attributable guidance: documentation results retain their source and update metadata.

• Narrow permissions: project roots and remote targets are explicitly configured and allowlisted.

Project status

Seven tools and three resources are live and verified against the legacy, modern, and part-migrated layouts, and Phase 0 and Phase 1 are complete. inspect_project describes a project; validate_state_machine and validate_action_contracts find real cross-file defects in it — a transition to a state that does not exist, an unreachable state, an action the client sends that no state allows, a notification nobody handles, a query against a table the schema never declares. All seven run against the packed and installed artifact through a real MCP client and prove the project directory is unchanged after every call. See the first capability, state-machine validation, action contract, notification contract, database audit, aggregate validation, project resource, and read-only and network-off records.

Underneath it: a strict TypeScript package that builds and packs, a versioned diagnostic contract and public error contract, the policy boundary every capability routes through, a threat model and compatibility matrix enforced by CI gates, and a verification evidence artifact each run emits and checks.

See the executable implementation backlog, testing policy, threat model, compatibility matrix, conformance coverage, roadmap, and architecture notes.

Develop locally

Requirements: Node.js 22.13 or newer on the Node 22 line, or Node.js 24 LTS or newer; Corepack; and Git.

corepack pnpm install --frozen-lockfile
corepack pnpm check

Build and inspect the local executable:

corepack pnpm build
node dist/cli.js --help
node dist/cli.js --version

An MCP client can launch a development checkout after it has been built:

{
  "command": "node",
  "args": [
    "/absolute/path/to/bga-mcp/dist/cli.js",
    "--project-root",
    "/absolute/path/to/a/bga-project"
  ]
}

Configuration is the policy boundary. Defaults are local, read-only, and network-off, and every relaxation is an explicit flag:

Every tool reads only from the roots given here. projectRoot may be omitted when exactly one root is configured, and then means that root; with none or several configured, the call is refused with a stable error code rather than guessing which project was meant.

The server writes only MCP frames to stdout, and every stderr line is redacted before it is written.

Verification commands

• pnpm format:check, pnpm lint, and pnpm typecheck enforce source quality.

• pnpm test:coverage runs unit, integration, fixture-integrity, harness self-tests, and packed-server E2E with coverage thresholds.

• pnpm check:package builds, packs, and checks package metadata.

• pnpm test:conformance proves the official suite rejects a seeded violation and accepts the candidate for its supported scenario.

• pnpm evidence and pnpm verify:evidence write and check .artifacts/verification-evidence.json, which records what the run actually proved: see docs/TESTING.md.

• pnpm verify:threat-model, pnpm verify:compatibility, and pnpm verify:scenarios prove the threat model, the compatibility matrix, and every claimed scenario stay consistent with the code and the tests. Each seeds its own defect first and fails on it.

• pnpm verify:safety-gates proves the secret scanner detects a seeded credential without printing it, then scans the repository and every retained CI artifact.

• pnpm check is the complete local gate.

Contributing

Early feedback from active BGA developers is particularly valuable. Please read CONTRIBUTING.md before opening an issue or pull request.

Security-sensitive reports should follow SECURITY.md.

License

Licensed under the Apache License 2.0.

Unofficial project

bga-mcp is an independent, unofficial community project. It is not affiliated with, endorsed by, or operated by Board Game Arena or its owners. Board Game Arena, BGA, and related names and marks belong to their respective owners.