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许可证。