Shogi MCP

🚀 Shogi MCP Server

This is an HTTP API bridge and MCP (Model Context Protocol) server implementation for a Shogi AI engine, integrating the current LLM with a USI - format Shogi AI and providing a sample program for move explanations.

https://github.com/user-attachments/assets/cdff97b9-d60f-411b-b81f-9cabd8e62

🚀 Quick Start

This project wraps a native Shogi engine binary and provides the following two interfaces:

• HTTP API Bridge: Analyze Shogi game positions via HTTP endpoints.
• MCP Server: A Model Context Protocol server for AI agent integration.

✨ Features

• Integrate LLM with USI - format Shogi AI.
• Provide REST API and MCP server for Shogi analysis.

📦 Installation

# Clone the repository
git clone <repository-url>
cd shogi-mcp

# Install dependencies
npm install

🔧 Setup

1. Place the Shogi engine binary in engine/engine.
2. Place the evaluation function file in eval/nn.bin.

💻 Usage Examples

Claude Desktop

Add the following to claude_desktop_config.json:

  "mcpServers": {
    "shogi-mcp": {
      "command": "Add the full path of node here",
      "args": ["Add the full path of mcp-server.mjs here"],
      "env": {
        "REST_BASE": "http://localhost:8787"
      }
    }
  }

Start the Bridge Server

npm run start:bridge

It starts on port 8787 by default.

API Endpoints

GET /health

• An endpoint for health checks.

GET /analyze

• An endpoint for position analysis.

Parameters:

• sfen (required): A game position in SFEN format.
• depth: Search depth (default: 30, max: 30).
• multipv: Number of candidate moves (default: 10, max: 10).
• threads: Number of threads to use (default: 1, max: 8).
• forceMove: Analyze the position after making the specified move.

Example:

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

Start the MCP Server

npm run start:mcp

The MCP server communicates via stdio and provides the following tools:

• ping: Check connectivity.
• analyze: Complete analysis of a game position (MultiPV).
• eval_at: Evaluate a position after making a specific move.

🔧 Technical Details

Environment Variables

Project Structure

shogi-mcp/
├── src/
│   ├── core/
│   │   └── engine.js         # USI protocol engine wrapper
│   └── servers/
│       ├── bridge-server.js  # Express HTTP API bridge server
│       └── mcp-server.mjs    # MCP server implementation
├── engine/
│   └── engine                # Shogi engine binary
├── eval/
│   └── nn.bin               # Evaluation function (implemented in NNUE)
├── package.json
└── README.md        

Development

Testing

Examples of testing the bridge API:

# Health check
curl http://localhost:8787/health

# Analyze the initial position
curl "http://localhost:8787/analyze?sfen=startpos&depth=15&multipv=3"

Troubleshooting

If the evaluation function cannot be loaded

Explicitly specify the path using environment variables:

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

If the engine fails to start

1. Check the execution permissions of the engine binary.

chmod +x engine/engine

2. Specify the engine path using an environment variable.

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

📄 License

MIT