Board Mcp

Board SDK MCP 服务

为 AI 助手提供对 Board SDK（fun.board v3.3.0）的结构化访问，用于 Unity 游戏开发。你的 AI 不再臆测 SDK API，而是能一次性生成正确的 C# 代码，并妥善处理平台守卫、异步模式和注意事项。

当 Unity Editor 与 MCP for Unity 同时运行时，此服务会自动发现并代理 Unity 的工具和资源——一个 MCP 服务即可同时提供 Board SDK 知识和对 Unity Editor 的实时控制。

包含内容

• 27 个工具，涵盖 4 个 SDK 领域（输入、会话、存档、应用程序）
• 7 套棋子——完整的实体游戏棋子模型目录（arcade、chop_chop、mushka、omakase、save_the_bloogs、thrasos_arcade，以及组合套装 chop_chop_mushka）
• 8 个资源，包含类型架构、棋子套装目录、更新日志、错误目录和平台守卫参考
• Unity Editor 集成——Unity 运行时自动代理 Unity MCP 工具和资源
• 每个工具响应均包含：API 签名、完整的 C# 代码示例、参数文档、注意事项和相关工具

安装

npx board-sdk-mcp-server

无需构建，也无需克隆。只需将以下配置添加到你的 AI Agent，即可自动运行。

先决条件

• Node.js 20+

---

添加到你的 AI Agent

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

重启 Claude Desktop。你会在工具选择器（锤子图标）中看到 Board SDK 工具。

Cursor

在项目根目录中创建或编辑 .cursor/mcp.json：

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

重启 Cursor。Agent 即可在 Composer 中使用 Board SDK 工具。

Windsurf

编辑 ~/.codeium/windsurf/mcp_config.json：

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

VS Code（Copilot）

将以下内容添加到 VS Code 的 settings.json 或 .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

从源码安装（开发）

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

然后在上述任意配置中使用 "command": "node", "args": ["/path/to/BoardMCP/dist/index.js"]。

---

验证是否正常运行

将服务添加到你的 Agent 后，可以向它提问，例如：

“如何检测 Board 上实体棋子的接触？”

Agent 应调用 board_input_get_contacts，并返回包含完整 C# 代码示例、平台守卫和注意事项的结构化响应，而不是泛泛猜测。

其他适合测试的提示词：

提示词	预期调用的工具
“设置带封面图片的存档”	board_save_create、board_save_cover_image
“向会话中添加第二位玩家”	board_session_add_player、board_session_player_types
“为什么我的接触检测结果为空？”	board_input_get_contacts、board_input_simulator_setup
“有哪些可用的棋子套装？”	board_input_list_piece_sets
“设置 Chop Chop 棋子检测”	board_input_glyph_setup、board_input_list_piece_sets
“配置暂停屏幕”	board_app_pause_screen、board_app_pause_events
“存档文件的最大大小是多少？”	board_save_storage_info
“添加一个简单难度的 AI 对手”	board_session_ai_players、board_session_add_player
“修复相互冲突的输入模块”	board_app_input_module

可用工具

输入（board_input_*）

工具	返回内容
board_input_get_contacts	带平台保护的 GetActiveContacts() 轮询模式
board_input_contact_lifecycle	BoardContactPhase 状态机（Began → Moved → Ended）
board_input_configure_settings	BoardInputSettings 平滑处理和棋子集配置
board_input_simulator_setup	用于无硬件测试的编辑器模拟器激活
board_input_glyph_setup	使用模型文件设置检测实体游戏棋子
board_input_list_piece_sets	可用棋子集模型及其对应游戏的目录
board_input_debug_view	显示触点位置和边界的可视化调试叠加层

会话（board_session_*）

工具	返回内容
board_session_get_players	玩家名单访问方式和 playersChanged 事件模式
board_session_add_player	带 async/await 模式的 PresentAddPlayerSelector()
board_session_replace_player	PresentReplacePlayerSelector() 及 IL2CPP 说明
board_session_reset_players	用于恢复初始状态的 ResetPlayers()
board_session_player_types	BoardPlayerType（Profile、Guest、AI）说明
board_session_active_profile	activeProfile 与 players[] 的区别
board_session_ai_players	用于注册 AI 对手类型的 SetAIPlayerTypes()

存档（board_save_*）

工具	返回内容
board_save_create	CreateSaveGame() 并自动关联玩家
board_save_update	UpdateSaveGame() 并重新生成校验和
board_save_load	LoadSaveGame() 及玩家激活副作用警告
board_save_list	GetSaveGamesMetadata() 并包含已填充的玩家信息
board_save_cover_image	封面图片加载（432x243 PNG）
board_save_storage_info	存储限制（16MB 负载，64MB 总量）
board_save_remove_players	移除玩家时的自动删除行为
board_save_remove_profile	从存档中移除活动档案

应用（board_app_*）

工具	返回内容
board_app_pause_screen	SetPauseScreenContext() 与 UpdatePauseScreenContext() 的区别
board_app_profile_switcher	控制档案切换器叠加层的可见性
board_app_exit	正常退出及不同平台的行为差异
board_app_pause_events	暂停界面事件订阅模式
board_app_input_module	BoardUIInputModule 自动管理输入模块

棋盘棋子

棋盘游戏使用实体游戏棋子（称为“glyph”），由 Board 内置摄像头识别。每款游戏都有自己的棋子集——一种 TensorFlow Lite 识别模型，可将实体棋子映射到唯一的 glyphId 整数。

可用的棋子集

棋子集	模型文件	版本	游戏
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（组合）
omakase	omakase.bytes	1.3.2	Omakase
save_the_bloogs	save_the_bloogs.bytes	1.3.2	Save the Bloogs

棋子的工作方式

1. 将 .bytes 模型文件放入 Unity 项目中的 Assets/StreamingAssets/Board/PieceSets/
2. 在运行时将 BoardInputSettings.pieceSetModelFilename 设置为该模型文件
3. 每帧调用 BoardInput.GetActiveContacts(BoardContactType.Glyph) 来检测棋子

每个检测到的棋子都会提供：

• glyphId — 用于识别棋子的唯一整数（同一模型版本在不同会话中保持稳定）
• screenPosition — 棋子在表面上的位置
• orientation — 以弧度表示的旋转角度（从垂直方向起顺时针计算）
• isTouched — 是否有手指同时触碰棋子
• bounds — 用于命中测试的屏幕空间边界框

一次只能启用一个棋子集。若要同时识别多个游戏中的棋子，请使用组合棋子集（例如，chop_chop_mushka 可在同一会话中识别 Chop Chop 和 Mushka 棋子）。

相关工具

工具	用途
board_input_list_piece_sets	浏览完整目录，可选按游戏筛选
board_input_glyph_setup	配置棋子集并开始检测棋子
board_input_configure_settings	设置平滑处理和棋子集模型文件名
board_input_get_contacts	每帧轮询检测到的棋子（以及手指触碰）

可用资源

资源	内容
board://sdk/overview	SDK 描述、版本、命名空间映射
board://sdk/types/contact	BoardContact 结构体 — 全部 10 个字段
board://sdk/types/player	BoardPlayer + BoardSessionPlayer 架构
board://sdk/types/savegame	BoardSaveGameMetadata — 全部 11 个字段
board://sdk/piece-sets	棋子集目录，包含模型、版本和游戏
board://sdk/changelog	v2.0 → v3.3.0 更新日志
board://sdk/errors	常见错误及解决方法
board://sdk/platform-guards	#if UNITY_ANDROID 守卫参考

Unity Editor 集成

此服务充当 MCP 网关。它始终提供 Board SDK 工具（文档和代码示例）；当 Unity Editor 与 MCP for Unity 包同时运行时，它会自动连接，并通过同一服务代理 Unity 的工具和资源。

无需额外配置。 如果 Unity 正在运行且 MCP 桥接已启动，Unity 工具就会自动显示。如果 Unity 未运行，Board SDK 工具仍可正常使用。

工作方式

1. 启动时，服务会尝试连接到 Unity MCP：http://127.0.0.1:8090/mcp
2. 如果 Unity 可用，服务会发现所有 Unity 工具和资源，并将它们提供给你的 AI Agent
3. 如果 Unity 断开连接（编辑器关闭、域重载），Unity 工具会被移除，服务会在后台重试
4. 无论 Unity 处于何种状态，Board SDK 工具始终可用

要求

• 在 Unity 项目中安装 MCP for Unity 包
• 打开 Window > MCP for Unity，然后点击 Start Bridge
• 默认情况下，桥接运行于 http://127.0.0.1:8090/mcp

禁用 Unity 集成

将 UNITY_MCP_ENABLED=false 设置为跳过 Unity 代理，或者在 Unity 桥接运行于其他端口时，通过 UNITY_MCP_URL 更改 URL。

开发

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

环境变量

变量	默认值	描述
MCP_TRANSPORT	stdio	传输模式：stdio 或 sse
MCP_SSE_PORT	3000	SSE 服务端口（仅当 MCP_TRANSPORT=sse 时）
UNITY_MCP_URL	http://127.0.0.1:8090/mcp	Unity MCP 端点 URL
UNITY_MCP_ENABLED	true	设置为 false 可完全禁用 Unity 代理
LOG_LEVEL	info	日志级别：debug、info、warn、error