llm-chess-mcp

LLM이 모든 결정을 엔진에 위임하지 않고 체스를 두고, 분석하며, 자신의 실력을 조절할 수 있게 해주는 MCP 체스 런타임입니다.

단일 최선의 수를 반환하는 대신, 객관적 강도(Stockfish), 인간의 수 선택 확률(Maia3), 실제 경기 통계(Lichess)를 노출하여 LLM이 자신이 원하는 방식으로 플레이할 수 있도록 합니다. 전략과 판단은 LLM이 담당하고, 모든 계산은 MCP 서버가 처리합니다.

엔진

모든 것은 Node 프로세스 내부에서 실행됩니다. 배포 시 외부 엔진 프로세스나 Python 런타임이 필요하지 않습니다. 게시된 패키지에는 Maia3 5M 모델이 번들로 포함되어 있습니다. 다른 내보내기 변형은 ONNX 파일을 별도로 제공하지 않는 한 런타임 옵션이 아닙니다.

Related MCP server: Chess MCP

설치

Node.js 20 이상이 필요합니다.

설치가 필요 없습니다. npx로 직접 실행하세요:

npx -y llm-chess-mcp

Maia3 모델은 이미 번들로 포함되어 있으므로 Python, torch 또는 엔진 바이너리를 설치할 필요가 없습니다. npx는 첫 실행 시 패키지를 가져와 캐시합니다.

영구적으로 설치하려면:

npm install -g llm-chess-mcp

소스에서 빌드

pnpm install
pnpm build
pnpm test

pnpm test:unit은 단위 테스트 스위트를 실행합니다. pnpm test:e2e는 먼저 빌드한 후 MCP 전송 테스트를 실행합니다. pnpm check는 전체 로컬 게이트를 실행하며, 게시 전에는 pnpm release:check를 사용하세요.

관리자

아키텍처는 런타임 및 서비스 경계를 설명합니다.

로컬 품질 명령:

pnpm typecheck
pnpm test:coverage
pnpm contract:check
pnpm check
pnpm test:package

pnpm test:stress는 짧은 실제 엔진 동시성 검사를 실행합니다. pnpm test:live는 LICHESS_TOKEN이 설정된 경우에만 Lichess를 조회하며, 그렇지 않으면 네트워크 요청 없이 건너뜁니다.

Maia3를 ONNX로 내보내기 (빌드 시에만)

이 단계는 Python + PyTorch가 한 번 필요합니다. Maia3 체크포인트를 다운로드하고, 재구현을 원본과 검증한 후 models/maia3-5m.onnx를 내보냅니다.

uv venv .venv-maia3 --python 3.13
uv pip install --python .venv-maia3/bin/python -r scripts/requirements.txt
uv pip install --python .venv-maia3/bin/python "maia3 @ git+https://github.com/CSSLab/maia3.git@1e13597c42d4858b7cfd7cfdae01e297263364b2"
pnpm export:maia3            # -> models/maia3-5m.onnx

결과 .onnx 파일은 커밋/번들되며, 최종 사용자는 Python이나 torch가 필요 없습니다.

Lichess 토큰 (선택 사항)

오프닝 익스플로러는 이제 인증이 필요합니다. https://lichess.org/account/oauth/token/create에서 개인 액세스 토큰을 생성하고 .env에 설정하세요:

cp .env.example .env
# set LICHESS_TOKEN=...

토큰이 없으면 opening_explorer는 비활성화 알림을 반환하며, 다른 모든 도구는 정상 작동합니다.

익스플로러 필터는 엄격합니다. 속도는 ultraBullet, bullet, blitz, rapid, classical, correspondence이며, 레이팅 구간은 0, 1000, 1200, 1400, 1600, 1800, 2000, 2200, 2500입니다. masters는 두 필터 모두 허용하지 않습니다. 잘못된 필터는 로컬에서 실패합니다. 일시적 오류(네트워크, 타임아웃, 429, 5xx)는 12초 총 예산 내에서 한 번 재시도되며, 잘못된 요청 및 기타 4xx 응답은 재시도되지 않습니다.

MCP 클라이언트에서 구성

opencode

opencode.json(프로젝트) 또는 ~/.config/opencode/opencode.json(전역)에 추가하세요:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "llm-chess-mcp": {
      "type": "local",
      "command": ["npx", "-y", "llm-chess-mcp"],
      "enabled": true,
      "environment": {
        "LICHESS_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

.mcp.json(프로젝트) 또는 ~/.claude.json(전역)에 추가하거나, 다음을 실행하세요:

claude mcp add llm-chess-mcp -- npx -y llm-chess-mcp

{
  "mcpServers": {
    "llm-chess-mcp": {
      "command": "npx",
      "args": ["-y", "llm-chess-mcp"],
      "env": {
        "LICHESS_TOKEN": "your-token"
      }
    }
  }
}

Codex CLI

~/.codex/config.toml에 추가하세요:

[mcp_servers.llm-chess-mcp]
command = "npx"
args = ["-y", "llm-chess-mcp"]

[mcp_servers.llm-chess-mcp.env]
LICHESS_TOKEN = "your-token"

또는 CLI를 통해:

codex mcp add llm-chess-mcp --command npx --args -y llm-chess-mcp --env LICHESS_TOKEN=your-token

도구

결과 형식

structuredContent는 표준 성공 결과입니다. 핸들러 수준의 실패는 isError를 설정하고 structuredContent.error를 제공합니다. 입력 스키마 실패는 핸들러 이전에 MCP SDK에 의해 생성되며, structuredContent 없이 표준 isError 텍스트 결과를 사용합니다. 그 외에는 content가 짧은 사람이 읽을 수 있는 요약일 뿐이며 데이터로 파싱해서는 안 됩니다.

점수 규칙

• Stockfish 점수는 수를 둘 측 기준: 양수 cp = 수를 두는 측이 유리함; mate N = 수를 두는 측이 N수 내에 메이트. wdl은 수를 두는 측 기준 [승, 무, 패]를 permille로 표시.

• move_candidates는 moverCp(수를 두는 측 기준 — 수를 선택하는 플레이어에게 높을수록 좋음)와 whiteCp(고정된 백 기준)를 제공하므로 부호가 뒤집히지 않습니다.

• move_evaluate는 수를 두는 측 기준 점수와 cpLoss(최선의 수 대비 센티폰 손실), 그리고 분류(best / excellent / good / inaccuracy / mistake / blunder)를 보고합니다.

• maia3Prob는 인간형 가능성이지 수의 품질이 아닙니다. 확률이 높은 수라도 객관적으로 나쁠 수 있습니다.

후보 구조

move_candidates는 각 후보를 세 가지 독립적인 측면으로 반환합니다:

{
  "uci": "g1f3",
  "san": "Nf3",
  "objective": { "rank": 1, "moverCp": 55, "whiteCp": 55, "cpLoss": 0, "moverMate": null, "wdl": [153, 844, 3] },
  "human": { "maia3Prob": 0.62, "selfElo": 1500, "opponentElo": 1500 },
  "opening": { "status": "available", "games": 18421, "frequency": 0.31 }
}

• objective — Stockfish: 엔진 강도, 인간형 가능성과 혼동되지 않음. moverCp는 수를 두는 측 기준(선택자에게 높을수록 좋음).

• human — 목표 Elo에서 Maia3 조건부 확률.

• opening — Lichess 경험적 빈도(Maia3와는 다른 신호).

opening.status는 available, no_data(API는 정상이나 해당 포지션에 게임 없음), unavailable(타임아웃/429/401), disabled(토큰 없음) 중 하나입니다. Stockfish + Maia3 결과는 항상 반환됩니다.

move_candidates는 또한 상위 엔진 라인 간 평가가 얼마나 급격히 변하는지 설명하는 moveSensitivity를 반환합니다:

{ "moveSensitivity": { "level": "high", "topMoveSpreadCp": 245 } }

level은 low(<80cp 스프레드), medium(80–200cp), high(≥200cp)입니다. 높은 민감도는 그럴듯한 대안 중에서 선택하는 것이 평가를 실질적으로 바꿀 수 있음을 의미합니다. 이는 힘을 빼거나 정확하게 둘지 결정하는 데 유용합니다.

분석 레벨

Stockfish 도구는 원시 UCI 설정 대신 analysis_level 프리셋을 허용합니다:

고급 사용을 위해 명시적 depth/multipv 오버라이드도 계속 사용할 수 있습니다.

Stale-position 가드

모든 상태 읽기는 revision을 반환합니다. game_play_move는 expected_revision을 요구합니다. 마지막 읽기 이후 게임이 진행되었다면 수가 거부됩니다:

{ "error": { "code": "STALE_POSITION", "message": "position changed: expected revision 2, current 3" } }

런타임 제한

• 최대 1,000개의 게임 세션이 유지되며, 유휴 세션은 1시간 후 만료됩니다.

• move_evaluate는 호출당 최대 10개의 수를 허용합니다.

• 가져온 PGN은 1MiB 및 4,096플라이로 제한됩니다.

• Stockfish는 최대 32개의 활성 또는 대기 분석을 허용합니다.

의도

move_candidates_by_intent는 선택한 의도에 따라 후보의 순위를 매깁니다. 이는 move_candidates 위의 편의 계층이며, 아래 고정 임계값은 휴리스틱 기본값이지 진리의 원천이 아닙니다:

이 도구는 후보의 순위를 매기지만 수를 선택하지는 않습니다. 반환된 신호와 대화 맥락을 사용하여 최종 결정을 내리세요. 사용자 실력을 기계적으로 의도에 매핑하지 마세요.

예시 흐름

일반적인 플레이 루프는 세 번의 호출입니다:

1. create_game → game_id

2. move_candidates → 수 선택

3. game_play_move(expected_revision 포함) → 수를 둠

필요할 때만 더 깊이 들어가세요:

• position_analyze — 객관적 최선 라인

• human_move_distribution — 특정 Elo의 인간이 둘 수

• opening_explorer — 실제 경기 통계

• move_evaluate — 특정 수의 점수(또는 여러 수 비교)

Maia3 ONNX 검증

내보낸 ONNX 모델은 고정 포지션과 Elo 쌍에 걸쳐 업스트림 Maia3 구현과 회귀 테스트됩니다:

.venv-maia3/bin/python scripts/verify_maia3.py --model 5m

top-1/top-k 수 일치와 최대 확률 오차를 확인하여 내보내기/런타임 회귀를 감지합니다. 번들된 maia3-5m.onnx는 100% top-1 및 top-5 일치, 최대 확률 오차 < 1e-4로 통과합니다.

패키지 검증

패키지 아티팩트는 로컬에서 검증됩니다. 이 프로젝트는 의도적으로 호스팅된 CI 워크플로가 없습니다.

결정적 오프라인 게이트에는 pnpm check를 실행하세요. pnpm test:package를 사용하여 프로젝트를 패킹하고, 깨끗한 임시 디렉터리에 tarball을 설치한 후, 설치된 llm-chess-mcp 바이너리를 실제 Stockfish 및 Maia 런타임으로 실행합니다. pnpm release:check는 두 검사에 더해 프로덕션 의존성 감사와 패키지 매니페스트 드라이 런을 실행합니다.

라이선스 및 귀속

이 프로젝트는 AGPL-3.0 라이선스입니다(LICENSE 참조).

타사 구성 요소를 번들 및 의존합니다:

번들로 제공되는 Maia3 모델(models/maia3-5m.onnx)은 UofTCSSLab/Maia3-5M의 b6559de2398d7140b985f28fd2c19fb5e47ddabe에서 파생되었습니다. ONNX 내보내기는 빌드 시 단계(scripts/export_maia3.py)이며, 런타임은 Maia3 Python 코드를 실행하지 않습니다.