Shogi MCP

🚀 將棋MCP服務器

將棋MCP服務器是將棋AI引擎的HTTP API橋接器以及MCP（Model Context Protocol）服務器的實現。它將現有的LLM與USI形式的將棋AI進行整合，是一個用於讓AI給出指手說明的示例程序。

🚀 快速開始

這個項目將原生的將棋引擎二進制文件進行封裝，提供以下兩個接口：

• HTTP API橋接器：通過HTTP端點進行將棋局面分析。
• MCP服務器：用於AI代理集成的Model Context Protocol服務器。

✨ 主要特性

• 提供HTTP API和MCP協議兩種接口，方便不同場景使用。
• 可將LLM與USI形式的將棋AI進行整合，實現指手說明功能。

📦 安裝指南

必要條件

• Node.js 18.0.0及以上版本。
• 支持USI協議的將棋引擎。
• 評估函數文件（nn.bin）。

安裝步驟

# 克隆倉庫
git clone <repository-url>
cd shogi-mcp

# 安裝依賴
npm install

配置

1. 將將棋引擎二進制文件放置在 engine/engine 路徑下。
2. 將評估函數文件放置在 eval/nn.bin 路徑下。

💻 使用示例

Claude Desktop配置

在 claude_desktop_config.json 中添加以下內容：

  "mcpServers": {
    "shogi-mcp": {
      "command": "這裡添加node的完整路徑",
      "args": ["這裡添加mcp-server.mjs的完整路徑"],
      "env": {
        "REST_BASE": "http://localhost:8787"
      }
    }
  }

啟動橋接服務器

npm run start:bridge

默認在端口8787啟動。

API端點

• GET /health：用於健康檢查的端點。
• GET /analyze：局面分析端點。
  • 參數：
    • sfen（必需）：SFEN格式的局面。
    • depth：搜索深度（默認值：30，最大值：30）。
    • multipv：候選手的數量（默認值：10，最大值：10）。
    • threads：使用的線程數（默認值：1，最大值：8）。
    • forceMove：指定走某一步後分析局面。

示例：

curl "http://localhost:8787/analyze?sfen=lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL%20b%20-%201&depth=20&multipv=5"

啟動MCP服務器

npm run start:mcp

MCP服務器通過標準輸入輸出進行通信，提供以下工具：

• ping：用於連通性檢查。
• analyze：對局面進行全面分析（MultiPV）。
• eval_at：評估特定走法後的局面。

🔧 技術細節

環境變量

項目結構

shogi-mcp/
├── src/
│   ├── core/
│   │   └── engine.js         # USI協議引擎包裝器
│   └── servers/
│       ├── bridge-server.js  # Express HTTP API橋接服務器
│       └── mcp-server.mjs    # MCP服務器實現
├── engine/
│   └── engine                # 將棋引擎二進制文件
├── eval/
│   └── nn.bin               # 評估函數(NNUE實現)
├── package.json
└── README.md        

🚧 開發相關

測試

橋接API的測試示例：

# 健康檢查
curl http://localhost:8787/health

# 初始局面分析
curl "http://localhost:8787/analyze?sfen=startpos&depth=15&multipv=3"

故障排除

評估函數無法加載

請在環境變量中明確指定路徑：

EVAL_FILE=./eval/nn.bin EVAL_DIR=./eval npm run start:bridge

引擎無法啟動

1. 檢查引擎二進制文件的執行權限：

chmod +x engine/engine

2. 在環境變量中指定引擎路徑：

ENGINE_PATH=/path/to/engine npm run start:bridge

📄 許可證

本項目採用MIT許可證。