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。