# Board SDK MCP Server

MCP server that gives AI assistants structured access to the [Board SDK](https://board.fun) (`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](https://github.com/CoplayDev/unity-mcp), 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

```bash
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):

```json
{
  "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:

```json
{
  "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`:

```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`:

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

### Claude Code (CLI)

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

### From source (development)

```bash
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](https://github.com/CoplayDev/unity-mcp) 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](https://github.com/CoplayDev/unity-mcp) 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

```bash
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`                  |