Shogi MCP Server

Instructions

Implementation Reference

• src/core/engine.js:134-156 (handler)

  The primary handler for the 'analyze' tool. This async method in the AIEngine class performs chess engine analysis on a given SFEN position, up to a specified depth and multipv variations, using a USI-compatible engine process. It handles mutex locking, option setting, position setup, search command issuance, and result parsing via callbacks.

  /**
   * @param {{sfen:string, depth:number, multipv:number, threads?:number, forceMove?:string}} params
   */
  async analyze({ sfen, depth, multipv, threads = this.defaultThreads, forceMove }) {
    return this.mutex.run(async () => {
      await this._waitReady();
      this._write(`setoption name MultiPV value ${multipv}`);
      if (threads && threads !== this.defaultThreads) this._write(`setoption name Threads value ${threads}`);
  
      this._writePosition(sfen, forceMove);
  
      const timeoutMs = Math.max(8000, 400 * depth);
      const results = {};
      const prom = new Promise((resolve, reject) => {
        const timer = setTimeout(() => {
          if (this.pending) { this.pending = null; reject(new Error("engine timeout (no bestmove)")); }
        }, timeoutMs);
        this.pending = { results, resolve: (v) => { clearTimeout(timer); resolve(v); } };
      });
      this._write(`go depth ${depth}`);
      return prom;
    });
  }

• src/core/engine.js:31-48 (helper)

  Helper function to parse 'info' output lines from the USI chess engine, extracting key metrics like depth, multipv, score (cp or mate), nodes, nps, and principal variation (pv). Used in _onLine to populate analysis results.

  function parseInfo(line) {
    const g = {};
    const mDepth = /(?:^| )depth (\d+)/.exec(line);
    const mMPV  = /(?:^| )multipv (\d+)/.exec(line);
    const mCp   = / score cp (-?\d+)/.exec(line);
    const mMate = / score mate (-?\d+)/.exec(line);
    const mNodes= / nodes (\d+)/.exec(line);
    const mNps  = / nps (\d+)/.exec(line);
    const mPv   = / pv (.+)$/.exec(line);
    if (mDepth) g.depth = Number(mDepth[1]);
    if (mMPV)   g.multipv = Number(mMPV[1]);
    if (mCp)    g.scoreCp = Number(mCp[1]);
    if (mMate)  g.mate    = Number(mate = mMate[1]);
    if (mNodes) g.nodes   = Number(mNodes[1]);
    if (mNps)   g.nps     = Number(mNps[1]);
    if (mPv)    g.pv      = mPv[1].trim().split(/\s+/);
    return g;
  }

• src/servers/bridge-server.js:14-35 (helper)

  HTTP endpoint '/analyze' that serves as a bridge to invoke the engine's analyze method, with input validation and parameter clamping for depth, multipv, threads.

  app.get("/analyze", async (req, res) => {
    try {
      const sfen = String(req.query.sfen || "");
      if (!sfen) return res.status(400).json({ error: "sfen required" });
  
      const depth = Math.min(Number(req.query.depth || MAX_DEPTH), MAX_DEPTH);
      const multipv = Math.min(Number(req.query.multipv || DEFAULT_MULTIPV), 10);
      const threads = Math.max(1, Math.min(Number(req.query.threads || 1), 8));
      const forceMove = req.query.forceMove ? String(req.query.forceMove) : undefined;
  
      const result = await engine.analyze({ sfen, depth, multipv, threads, forceMove });
      res.json({
        engine: "AI Engine",
        depth,
        multipv,
        threads,
        ...result,
      });
    } catch (e) {
      res.status(500).json({ error: String(e.message || e) });
    }
  });