AI导哈

国际象棋分析平台

一个基于AI的国际象棋分析平台，通过Lichess API和Playwright MCP自动分析棋局并提供可视化报告。

  • by Lim-Dong-Kyu
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Lim-Dong-Kyu/LichessAnalyzer_with_PlaywrightMCP

使用说明

带有Playwright MCP的Liches回放分析器

基于AI的分析平台，集成Lichess官方API和Playwright Model Context Protocol（MCP），自动分析国际象棋棋谱并可视化报告每个棋谱的评估。

功能

  1. Lichess API集成

    • 收集游戏数据（PGN、开场、玩家信息）
    • 通过Cloud Eval获取每个评估数据

  2. 基于AI的分析

    • 每个数字的评估差异（Δcp/mate）计算
    • 类别分类（Accurate/Good/Inaccuratic/Mistake/Blunder）
    • 通过OpenAI GPT生成游戏总生命周期
    • 通过OpenAI GPT分析特定数量的AI

  3. Playwright MCP自动化

    • 在应用程序启动时全局管理MCP会话（高效地重新使用连接）
    • 通过浏览器自动打开Lichess分析工具
    • 将分析工具设置为当前棋谱状态

  4. Web UI

    • 总结和可视化分析结果
    • 游戏统计（白/黑各统计）
    • 棋谱导航（1步，10步移动支持）
    • 每个数字的详细评估信息
    • 显示AI分析结果

项目结构

lichess_analyzer/
├── backend/          # Python FastAPI 백엔드
├── mcp-client/       # Node.js MCP 클라이언트
└── frontend/         # Next.js 프론트엔드

快速入门

要想最快地开始 QUICKSTART.md 请参考文件。

在Windows上快速运行

# 1. Backend 설정
cd backend
pip install -r requirements.txt

# 2. Frontend 설정
cd ../frontend
npm install

# 3. 환경 변수 설정 (선택사항)
cd ..
# .env 파일 생성 (LICHESS_API_TOKEN, OPENAI_API_KEY 등)

# 4. 실행
start.bat

start.bat运行时，后端和前端将自动启动。

手动运行

# 1. Backend 설정
cd backend
pip install -r requirements.txt

# 2. 환경 변수 설정 (선택사항)
cd ..
# .env 파일 생성 (LICHESS_API_TOKEN, OPENAI_API_KEY 등)

# 3. Backend 실행 (터미널 1)
cd backend
uvicorn main:app --reload --port 8000

# 4. Frontend 설정 및 실행 (터미널 2)
cd frontend
npm install
npm run dev

# 5. 브라우저에서 http://localhost:3000 접속

安装和运行

前提条件

  • Python 3.9+
  • Node.js 18+（前端용)
  • 必须安装pip和npm

设置环境变量

在项目根目录中 .env 通过创建文件，可以设置以下环境变量：

项目根目录 .env 文件（用于Backend/MCP客户端）

# Lichess API 토큰 (선택사항, rate limit 완화를 위해 권장)
# 토큰 생성: https://lichess.org/account/oauth/token/create
LICHESS_API_TOKEN=your_lichess_api_token_here

# OpenAI API 키 (AI 분석 기능 사용 시 필요)
# API 키 생성: https://platform.openai.com/api-keys
OPENAI_API_KEY=your_openai_api_key_here

# MCP 서버 설정 (선택사항, Cursor 설정 파일에서 자동 읽기 가능)
# MCP 서버 명령어 (기본값: "npx")
MCP_SERVER_COMMAND=npx

# MCP 서버 인자 (기본값: "-y @playwright/mcp")
# 공백으로 구분된 인자들을 하나의 문자열로 입력
MCP_SERVER_ARGS=-y @playwright/mcp

前端 .env.local 文件（可选）

# API 베이스 URL (기본값: "http://localhost:8000")
# Backend가 다른 포트나 도메인에서 실행되는 경우에만 설정
NEXT_PUBLIC_API_BASE=http://localhost:8000

参考:

  • 项目根目录： backend/env.example 请参见文件 .env 创建文件
  • Frontend：必要时 frontend/.env.local 直接创建文件 NEXT_PUBLIC_API_BASE 设置
  • 所有环境变量都是可选的，如果未设置，则使用默认值。

1.Backend设置

cd backend
pip install -r requirements.txt

参考:

  • MCP SDK包含在requirements.txt中
  • OpenAI SDK也包含在requirements.txt中。
  • 需要设置Cursor的MCP服务器（在Cursor IDE中设置）
  • MCP会话在应用程序启动时自动初始化

2.设置Frontend

cd frontend
npm install
npm run dev

执行顺序

方法1:自动运行（Windows）

  1. 在Cursor中设置Playwright MCP服务器（如果已设置，则可省略）
  2. start.bat 运行—后端和前端将自动启动
  3. 在浏览器中 http://localhost:3000 连接

方法2：手动运行

  1. 在Cursor中设置Playwright MCP服务器（如果已设置，则可省略）
  2. Backend运行（端口8000）： cd backend && uvicorn main:app --reload --port 8000
  3. 启动Frontend（端口3000）： cd frontend && npm run dev
  4. 在浏览器中 http://localhost:3000 连接

参考:

  • 必须设置Cursor的Playwright MCP
  • MCP服务器在后端自动连接

使用方法

  1. 输入Lichess游戏链接（例如： https://lichess.org/ABC123)
  2. 单击开始分析按钮
  3. 在报告页面上，您可以看到：
    • 游戏信息（玩家、结果、开场）
    • 游戏统计（白/黑各统计）
    • AI游戏总评（基于OpenAI GPT）
    • 查看棋谱（通过棋谱导航依次移动）
      • 按上一个/下一个按钮移动一个数字
      • -按10/+10按钮移动10次
    • 每个数字的详细评估信息
    • AI数量分析功能（针对每个数量的GPT分析）
    • 研究功能（自动打开Lichess分析工具）

API端点

  • POST /api/analyze -开始游戏分析

    • 请求： { "gameUrl": "https://lichess.org/ABC123" }
    • 答复： { "gameId": "ABC123", "status": "started", "message": "..." }

  • GET /api/game/{gameId} -查询游戏数据

    • Response:游戏信息（玩家、棋谱、开场等）

  • GET /api/eval/{gameId}/{ply} -查看特定数量的评估信息

    • Response：评估信息（前/后评估，Δcp、类别等）

  • GET /api/stats/{gameId} -查看游戏统计

    • Response:白/黑统计信息

  • GET /api/analysis/{gameId} -生成AI游戏总计

    • Response:通过OpenAI进行游戏总结

  • GET /api/move-analysis/{gameId}/{ply} -生成AI数分析

    • Response：通过OpenAI分析特定数量

  • POST /api/research/{gameId}/{ply} -打开Lichess分析工具

    • Response:打开的浏览器URL

  • GET /api/capture/{gameId}/{ply} -查看电路板图像URL

    • Response:板映像URL

  • GET /api/status/{gameId} -检查分析状态

    • Response:关于分析状态

评估类别标准

  • 准确的：|Δcp|<10
  • 好：10≤|Δcp|<50
  • 不准确：50≤|Δcp|<100
  • 错误：100≤|Δcp|<300
  • 错误：|Δcp|≥300

技术堆栈

  • 后端:

    • FastAPI（Web框架）
    • Python 3.9+
    • httpx（异步HTTP客户端）
    • python-chess（棋谱处理）
    • MCP SDK（模型上下文协议）
    • OpenAI SDK（AI分析功能）

  • 前端:

    • Next.js 16.0.1
    • 反应19.2.0
    • TypeScript
    • Tailwind CSS

  • 外部API:

    • Licess Cloud Eval API公司
    • OpenAI API（ChatGPT）

  • 浏览器自动化:

    • Cursor Playwright MCP（通过Python MCP SDK连接，全局会话管理）

故障排除

MCP连接错误

  • 验证是否已安装MCP SDK： pip install mcp
  • 确保在Cursor中设置了Playwright MCP服务器
  • 环境变量 MCP_SERVER_COMMAND 和 MCP_SERVER_ARGS 验证设置
  • 检查MCP会话初始化日志（在后端启动时检查“MCP会话初始化成功”消息）
  • MCP默认值： MCP_SERVER_COMMAND=npx, MCP_SERVER_ARGS=-y @playwright/mcp

OpenAI API错误

  • 验证是否已设置OpenAI API密钥： .env 在文件中 OPENAI_API_KEY 设置
  • 生成API密钥：https://platform.openai.com/api-keys
  • 验证API密钥是否有效（验证是否为已充值帐户）
  • 检查API调用限制

API调用错误

  • 确认Backend正在运行（端口8000）
  • 确认CORS设置（前端必须在localhost:3000上运行）
  • 验证网络连接

前端错误

  • 检查Node.js版本（需要18+）： node --version
  • 重新安装依赖性： cd frontend && rm -rf node_modules && npm install
  • 端口冲突时使用其他端口： npm run dev -- -p 3001

相关 MCP