Skip to content

seeincodes/BoardMCP

BranchesTags

Repository files navigation

Board SDK MCP Server

MCP server that gives AI assistants structured access to the Board SDK (fun.board v3.3.0) for Unity game development. Instead of hallucinating SDK APIs, your AI generates correct C# code with proper platform guards, async patterns, and caveats — on the first attempt.

When Unity Editor is running with MCP for Unity, this server automatically discovers and proxies Unity's tools and resources too — one MCP server for both Board SDK knowledge and live Unity Editor control.

What's included

  • 27 tools across 4 SDK domains (Input, Session, Save Game, Application)
  • 7 piece sets — full catalog of physical game piece models (arcade, chop_chop, mushka, omakase, save_the_bloogs, thrasos_arcade, and the combined chop_chop_mushka set)
  • 8 resources with type schemas, piece set catalog, changelog, error catalog, and platform guard reference
  • Unity Editor integration — automatically proxies Unity MCP tools/resources when Unity is running
  • Every tool response includes: API signature, complete C# code example, parameter docs, caveats, and related tools

Install

npx board-sdk-mcp-server

No build step, no cloning. Just add the config below to your AI agent and it runs automatically.

Prerequisites

  • Node.js 20+

Adding to your AI agent

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "board-sdk": {
      "command": "npx",
      "args": ["-y", "board-sdk-mcp-server"]
    }
  }
}

Restart Claude Desktop. You'll see the Board SDK tools appear in the tool picker (hammer icon).

Cursor

Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "board-sdk": {
      "command": "npx",
      "args": ["-y", "board-sdk-mcp-server"]
    }
  }
}

Restart Cursor. The Board SDK tools will be available to the agent in Composer.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "board-sdk": {
      "command": "npx",
      "args": ["-y", "board-sdk-mcp-server"]
    }
  }
}

VS Code (Copilot)

Add to your VS Code settings.json or .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "board-sdk": {
        "command": "npx",
        "args": ["-y", "board-sdk-mcp-server"]
      }
    }
  }
}

Claude Code (CLI)

claude mcp add board-sdk -- npx -y board-sdk-mcp-server

From source (development)

git clone <repo-url> && cd BoardMCP
npm install
npm run build

Then use "command": "node", "args": ["/path/to/BoardMCP/dist/index.js"] in any config above.

Verifying it works

After adding the server to your agent, ask it something like:

"How do I detect physical piece contacts on a Board?"

The agent should call board_input_get_contacts and return a structured response with a complete C# code example, platform guards, and caveats — not a generic guess.

Other good test prompts:

Prompt Expected tools called
"Set up save games with cover images" board_save_create, board_save_cover_image
"Add a second player to the session" board_session_add_player, board_session_player_types
"Why are my contacts returning empty?" board_input_get_contacts, board_input_simulator_setup
"What piece sets are available?" board_input_list_piece_sets
"Set up Chop Chop piece detection" board_input_glyph_setup, board_input_list_piece_sets
"Configure the pause screen" board_app_pause_screen, board_app_pause_events
"What's the max save file size?" board_save_storage_info
"Add an Easy AI opponent" board_session_ai_players, board_session_add_player
"Fix my input modules conflicting" board_app_input_module

Available tools

Input (board_input_*)

Tool What it returns
board_input_get_contacts GetActiveContacts() polling pattern with platform guards
board_input_contact_lifecycle BoardContactPhase state machine (Began → Moved → Ended)
board_input_configure_settings BoardInputSettings smoothing and piece set configuration
board_input_simulator_setup Editor simulator activation for testing without hardware
board_input_glyph_setup Physical game piece detection with model file setup
board_input_list_piece_sets Catalog of available piece set models and their games
board_input_debug_view Visual debug overlay for contact positions and bounds

Session (board_session_*)

Tool What it returns
board_session_get_players Player roster access and playersChanged event pattern
board_session_add_player PresentAddPlayerSelector() with async/await pattern
board_session_replace_player PresentReplacePlayerSelector() with IL2CPP notes
board_session_reset_players ResetPlayers() for returning to initial state
board_session_player_types BoardPlayerType (Profile, Guest, AI) explanation
board_session_active_profile activeProfile vs players[] distinction
board_session_ai_players SetAIPlayerTypes() for registering AI opponent types

Save Game (board_save_*)

Tool What it returns
board_save_create CreateSaveGame() with auto player association
board_save_update UpdateSaveGame() with checksum regeneration
board_save_load LoadSaveGame() with player activation side-effect warning
board_save_list GetSaveGamesMetadata() with hydrated player info
board_save_cover_image Cover image loading (432x243 PNG)
board_save_storage_info Storage limits (16MB payload, 64MB total)
board_save_remove_players Player removal with auto-delete behavior
board_save_remove_profile Active profile removal from save

Application (board_app_*)

Tool What it returns
board_app_pause_screen SetPauseScreenContext() vs UpdatePauseScreenContext()
board_app_profile_switcher Profile switcher overlay visibility control
board_app_exit Clean exit with platform behavior differences
board_app_pause_events Pause screen event subscription pattern
board_app_input_module BoardUIInputModule automatic input module management

Board pieces

Board games use physical game pieces (called "glyphs") that are recognized by the Board's built-in camera. Each game has its own piece set — a TensorFlow Lite recognition model that maps physical pieces to unique glyphId integers.

Available piece sets

Piece Set Model File Version Game
arcade arcade.bytes 1.3.7 Board Arcade
thrasos_arcade thrasos_arcade.bytes 1.0.2 Thrasos Arcade
chop_chop chop_chop.bytes 1.3.0 Chop Chop
mushka mushka.bytes 1.3.1 Mushka
chop_chop_mushka chop_chop_mushka.bytes 1.0.0 Chop Chop + Mushka (combined)
omakase omakase.bytes 1.3.2 Omakase
save_the_bloogs save_the_bloogs.bytes 1.3.2 Save the Bloogs

How pieces work

  1. Place the .bytes model file in Assets/StreamingAssets/Board/PieceSets/ in your Unity project
  2. Set BoardInputSettings.pieceSetModelFilename to the model file at runtime
  3. Call BoardInput.GetActiveContacts(BoardContactType.Glyph) to detect pieces each frame

Each detected piece provides:

  • glyphId — unique integer identifying which piece it is (stable across sessions for the same model version)
  • screenPosition — where on the surface the piece is located
  • orientation — rotation in radians (clockwise from vertical)
  • isTouched — whether a finger is simultaneously touching the piece
  • bounds — screen-space bounding box for hit-testing

Only one piece set can be active at a time. To recognize pieces from multiple games simultaneously, use a combined set (e.g., chop_chop_mushka recognizes both Chop Chop and Mushka pieces in one session).

Related tools

Tool Use it to...
board_input_list_piece_sets Browse the full catalog with optional game filtering
board_input_glyph_setup Configure a piece set and start detecting pieces
board_input_configure_settings Set smoothing and piece set model filename
board_input_get_contacts Poll detected pieces (and finger touches) each frame

Available resources

Resource Contents
board://sdk/overview SDK description, version, namespace map
board://sdk/types/contact BoardContact struct — all 10 fields
board://sdk/types/player BoardPlayer + BoardSessionPlayer schemas
board://sdk/types/savegame BoardSaveGameMetadata — all 11 fields
board://sdk/piece-sets Piece set catalog with models, versions, games
board://sdk/changelog Changelog v2.0 → v3.3.0
board://sdk/errors Common errors and resolutions
board://sdk/platform-guards #if UNITY_ANDROID guard reference

Unity Editor integration

This server acts as an MCP gateway. It always serves Board SDK tools (documentation and code examples), and when Unity Editor is running with the MCP for Unity package, it automatically connects and proxies Unity's tools and resources through the same server.

No extra configuration needed. If Unity is running with the MCP bridge started, Unity tools appear automatically. If Unity isn't running, Board SDK tools still work normally.

How it works

  1. On startup, the server attempts to connect to Unity MCP at http://127.0.0.1:8090/mcp
  2. If Unity is available, it discovers all Unity tools and resources and makes them available to your AI agent
  3. If Unity disconnects (editor closed, domain reload), Unity tools are removed and the server retries in the background
  4. Board SDK tools are always available regardless of Unity's state

Requirements

  • Install the MCP for Unity package in your Unity project
  • Open Window > MCP for Unity and click Start Bridge
  • The bridge runs on http://127.0.0.1:8090/mcp by default

Disabling Unity integration

Set UNITY_MCP_ENABLED=false to skip the Unity proxy entirely, or change the URL with UNITY_MCP_URL if your Unity bridge runs on a different port.

Development

npm run dev          # Run server with tsx (no build step)
npm run build        # Compile TypeScript to dist/
npm run typecheck    # Type-check without emitting
npm test             # Run tests

Environment variables

Variable Default Description
MCP_TRANSPORT stdio Transport mode: stdio or sse
MCP_SSE_PORT 3000 SSE server port (only when MCP_TRANSPORT=sse)
UNITY_MCP_URL http://127.0.0.1:8090/mcp Unity MCP endpoint URL
UNITY_MCP_ENABLED true Set to false to disable Unity proxy entirely
LOG_LEVEL info Logging: debug, info, warn, error

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages