AI 客户端集成（MCP）

MCP 是让 AI 客户端（Claude Desktop、Claude Code、Cursor、VS Code 中的 GitHub Copilot、Gemini CLI、Codex CLI 等）调用外部工具的通用规范。注册 ShogiBoardQ 的 MCP 服务器（shogiboardq-mcp）后，只需对 AI 客户端说“把这份棋谱转换为 CSA”“把这个局面分析 10 秒”“生成 5 道三手诘”，客户端就会调用 ShogiBoardQ 的功能来完成。

服务器同时支持 MCP 规范的最新版（2026-07-28）和以前的版本（2024-11-05〜2025-11-25），新旧客户端都可以连接。

以下工具在内部运行 shogiboardq-cli，无需打开窗口。

render_board_image 的输出示例：与 GUI 相同的棋子图片和配色，并可突出显示最后一手。“行棋方”等标签和段的坐标会按照 ShogiBoardQ 的界面语言和记法设置显示

以 --automation 启动 ShogiBoardQ 后，可以用以下工具读取和修改窗口中的局面和棋谱。

还以资源形式提供当前局面（shogiboardq://position/current，SFEN）、当前棋谱（shogiboardq://kifu/current，KIF 文本）和已注册的引擎（shogiboardq://engines）。

以下为 Linux 的示例，请把 /path/to/ShogiBoardQ 替换为仓库的位置。在 Windows 上，把 python3 改为 python，路径写成 C:\\Users\\...\\ShogiBoardQ\\build\\ShogiBoardQ.exe 这样的形式。修改配置后，请重新启动客户端（或重新加载 MCP 服务器）。

在项目中运行以下命令（加上 --scope user 可在所有项目中启用）。-- 之后是服务器的启动命令。

claude mcp add shogiboardq \
  --env SHOGIBOARDQ_EXECUTABLE=/path/to/ShogiBoardQ/build/ShogiBoardQ \
  --env PYTHONPATH=/path/to/ShogiBoardQ/mcp \
  -- python3 -m shogiboardq_mcp

claude mcp list      # 确认连接状态

把服务器添加到 claude_desktop_config.json（通过 Settings → Developer → Edit Config 打开。macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）。

{
  "mcpServers": {
    "shogiboardq": {
      "command": "python3",
      "args": ["-m", "shogiboardq_mcp"],
      "env": {
        "SHOGIBOARDQ_EXECUTABLE": "/path/to/ShogiBoardQ/build/ShogiBoardQ",
        "PYTHONPATH": "/path/to/ShogiBoardQ/mcp"
      }
    }
  }
}

写入项目的 .cursor/mcp.json（所有项目通用时写入 ~/.cursor/mcp.json）。

{
  "mcpServers": {
    "shogiboardq": {
      "command": "python3",
      "args": ["-m", "shogiboardq_mcp"],
      "env": {
        "SHOGIBOARDQ_EXECUTABLE": "/path/to/ShogiBoardQ/build/ShogiBoardQ",
        "PYTHONPATH": "/path/to/ShogiBoardQ/mcp"
      }
    }
  }
}

写入工作区的 .vscode/mcp.json。VS Code 的顶层键是 servers。要在整个用户范围内使用，请从命令面板执行“MCP: Open User Configuration”，并以相同格式添加。

{
  "servers": {
    "shogiboardq": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "shogiboardq_mcp"],
      "env": {
        "SHOGIBOARDQ_EXECUTABLE": "/path/to/ShogiBoardQ/build/ShogiBoardQ",
        "PYTHONPATH": "/path/to/ShogiBoardQ/mcp"
      }
    }
  }
}

用以下命令注册，或写入 ~/.gemini/settings.json（项目则为 .gemini/settings.json）的 mcpServers。

gemini mcp add -s user \
  -e SHOGIBOARDQ_EXECUTABLE=/path/to/ShogiBoardQ/build/ShogiBoardQ \
  -e PYTHONPATH=/path/to/ShogiBoardQ/mcp \
  shogiboardq python3 -m shogiboardq_mcp

{
  "mcpServers": {
    "shogiboardq": {
      "command": "python3",
      "args": ["-m", "shogiboardq_mcp"],
      "env": {
        "SHOGIBOARDQ_EXECUTABLE": "/path/to/ShogiBoardQ/build/ShogiBoardQ",
        "PYTHONPATH": "/path/to/ShogiBoardQ/mcp"
      }
    }
  }
}

同一台主机上的 Codex 客户端共用 ~/.codex/config.toml。请用以下命令注册，或写入下面的配置。python3 需指定安装了 mcp 包的 Python；使用虚拟环境时，请改为该 Python 的绝对路径。

codex mcp add shogiboardq \
  --env SHOGIBOARDQ_EXECUTABLE=/path/to/ShogiBoardQ/build/ShogiBoardQ \
  --env PYTHONPATH=/path/to/ShogiBoardQ/mcp \
  -- python3 -m shogiboardq_mcp

[mcp_servers.shogiboardq]
command = "python3"
args = ["-m", "shogiboardq_mcp"]
startup_timeout_sec = 30
env_vars = ["DISPLAY", "WAYLAND_DISPLAY", "XDG_RUNTIME_DIR", "XAUTHORITY", "DBUS_SESSION_BUS_ADDRESS", "XDG_CONFIG_HOME"]

[mcp_servers.shogiboardq.env]
SHOGIBOARDQ_EXECUTABLE = "/path/to/ShogiBoardQ/build/ShogiBoardQ"
PYTHONPATH = "/path/to/ShogiBoardQ/mcp"

在 Linux 上自动启动 GUI 时，即使用命令注册，也请在 [mcp_servers.shogiboardq] 中加入上面的 env_vars。它用于传递显示、会话的环境变量和配置目录。请编辑已有的表，不要重复创建。

用 codex mcp get shogiboardq 确认注册内容，然后重新启动 Codex 并开始新的对话。在 CLI 中可以用 /mcp 确认连接。请求“用 ShogiBoardQ 的 validate_sfen 验证 startpos”，返回合法着法数 30 即表示工具可以运行。codex mcp list 只显示注册内容。

在没有显示器的环境中试用应用操作工具时，请在 [mcp_servers.shogiboardq.env] 中加入 QT_QPA_PLATFORM = "offscreen"。此时窗口不会显示在屏幕上。配置的详情请参阅 OpenAI 官方 MCP 文档。

自动化 API 默认关闭。加上 --automation 启动后，ShogiBoardQ 会在只有本用户可以访问的本地套接字上接收请求，并在标准输出中显示 automation: listening on ...。设置了 SHOGIBOARDQ_EXECUTABLE 时，服务器会在第一次调用应用操作工具时自动启动应用（已启动则直接连接）。

./build/ShogiBoardQ --automation
# 指定套接字位置时
./build/ShogiBoardQ --automation --automation-socket /tmp/shogiboardq.sock

在有未保存更改的状态下读取棋谱或设置局面的请求，除非明确指定 discard_unsaved，否则会被拒绝。菜单操作采用允许列表，无法执行退出和覆盖保存。可以切换语言，重新启动应用后生效。可执行的操作可用 list_actions 确认。

所有工具都用 target（objectName、selector 或标题的一部分）指定要操作的窗口或对话框，省略时为主窗口。没有名称的控件，可以把 get_widget_text 或 list_dialogs 返回的 selector 指定给 widget 或 target 来操作。重新打开对话框或重新启动应用后请重新获取。set_widget_value 也支持滑块、列表、带勾选的组和颜色。菜单可以用 list_menu_actions 查询层级索引，再指定给 select_menu_action 的 path。

操作画面的工具会等待应用执行完操作后才返回；执行时无法操作（例如目标被隐藏、被禁用或被其他对话框遮挡）时返回错误。结果中的 state 用于区分已执行（done）、操作打开的模态对话框仍在显示（running）和等待期间未执行（pending）。工具失败时，消息以与 CLI、自动化 API 共用的错误分类词开头，例如 invalid_argument、not_found、file_exists、parse_error。