金大哥 - shogi-mcp MCP 详情

article

README

🚀 将棋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

配置

将将棋引擎二进制文件放置在 engine/engine 路径下。
将评估函数文件放置在 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：评估特定走法后的局面。

🔧 技术细节

环境变量

| 属性 | 详情 | |------|------| | ENGINE_PATH | 将棋引擎的路径，默认值为 ./engine/engine | | PORT | 桥接服务器的端口，默认值为 8787 | | REST_BASE | MCP服务器使用的桥接API的基础URL，默认值为 http://localhost:8787 | | DEBUG | 启用引擎通信的调试日志（"1"表示启用） | | EVAL_FILE | 评估函数文件的路径 | | EVAL_DIR | 评估函数目录的路径 |

项目结构

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

引擎无法启动

检查引擎二进制文件的执行权限：

chmod +x engine/engine

在环境变量中指定引擎路径：

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

📄 许可证

本项目采用MIT许可证。

shogi-mcp