English

Lichess MCP Analyzer

MCP server pro analyzu sachovych partii, detekci vzorovych chyb (pattern library jako kompresni model dle Mikolova) a spaced repetition trening (FSRS/SM-2 — algoritmy pro optimalni casovani opakovani uceni).

Proc?

Tento repozitar vznika se dvojim ucelem:

1. Sachovy analyzator — personalizovany treninkovy nastroj, ktery stahne tvoje partie z Lichess, analyzuje kazdy tah Stockfishem, detekuje 17 vzorovych patternu (A-Q1) z tve vlastni herni historie, diagnostikuje fazove slabiny a pomaha se z nich ucit pomoci spaced repetition.

2. MCP stavebnice — demonstracni projekt, na kterem si overuji principy tvorby MCP serveru v praxi. Kazda komponenta (Lichess API, Stockfish engine, pattern detection engine, SRS, B2B-Knowledge-Base persistence) je samostatne pouzitelna a prenositelna do jine domeny.

"Build tools for yourself first. If they solve a real problem, they solve a general one."

Jak to funguje?

Tvoje otazka (v opencode)  
       |  
       v JSON-RPC 2.0 (stdio)  
       |  
lichess-analyzer-mcp (Python FastMCP)  
       |  
       +--- Lichess API (berserk) -------- lichess.org  
       +--- Stockfish 18 (UCI) ----------- lokalni binary  
       +--- Pattern detector ------------- kompresni model (Mikolov)  
       +--- LLM reasoning (cascade) ------ NVIDIA / Cerebras / DeepSeek V4  
       +--- FSRS/SM-2 engine ------------- spaced repetition  
       +--- KB writer -------------------- B2B-Knowledge-Base  
       +--- MD reporter ------------------ docs/ coaching reports

Pattern detection jako kompresni model

"Reprezentace reality minimalizujici komplexitu, predikcni chybu a vypocetni naklady."

Chess pattern artifact je kompresni model hrace: minimalizuje komplexitu (9 patternu namisto 1000+ tahu), predikcni chybu (Stochastic cp_loss jako ground truth) a vypocetni naklady (2s cached runtime).

Overeni validity (MSE — Mean Squared Error, stredni kvadraticka chyba)

• MSE zprava: predikce tahu na zaklade patternu vs realita (Stockfish hodnoceni)
• Pokud MSE(pattern) < MSE(prumer), model je validni
• Pokud MSE(pattern) ≈ MSE(prumer), pattern je noise

Ztratova komprese

"Odstraneni informace s nizkou prediktivni hodnotou."

Pattern library ignoruje jednotlive tahy (sum) a extrahuje behavioralni vzory (signal). Ztratova komprese = ztratit detaily (presna hodnota cp_loss) kvuli zachyceni vzoru (hra preferuje X).

Pravidlo: Pattern je dobry, pokud:

• zachycuje chovani (signal)
• odstranuje jednotlive chyby (sum)
• neodstranuje strukturu (trendy, fazove slabiny)

Occamova britva

"Preferovani nejjednodussiho dostatecne presneho modelu."

Kompresni pomer (compression_ratio = raw_cost / pattern_cost) je meritko Occamovy britvy. Ze dvou patternu, ktere stejne dobre vysvetluji data, je ten s vyssim kompresnim pomerem spravnejsi.

Prakticky problem: Pattern H (Matematicka neznalost) a Pattern I (Material before initiative) se mohou prekryvat. Occam pres kompresi rekne:

• Ktery ma vyssi kompresni pomer?
• Ktery vyzaduje mene vyjimek pro stejne vysvetleni?

Confidence vzorec (Mikolov)

final_confidence = 0.5 × compression_score + 0.3 × entropy_score + 0.2 × sample_score

Resi small-N authority problem: pattern je validni i pri N < 25, pokud dobre komprimuje (compression_ratio > 1.5 = signal, > 10 = silny signal, < 1.0 = noise).

LLM Reasoning Pipeline

Deterministicky vystup (patterny + weakness report) je transformovan do prirozeneho treninkoveho reportu pomoci kaskady LLM provideru.

Architektura

Pipeline data (patterns + weakness)
       |
       v build_coaching_prompt()
       |
       v LLM cascade (prvni uspesny vyhrava)
       |
       +--- NVIDIA (free) ............ nemotron-3-super-120b
       +--- Cerebras (free) .......... gpt-oss-120b
       +--- DeepSeek V4 Flash ($) .... deepseek-v4-flash ($0.14/$0.28 per 1M tok)
       |
       v generate_md_report()
       |
       v docs/coaching_report_{user}_{ts}.md

Prepina se env var DEFAULT_PROVIDER:

• "" (nezadano) → NVIDIA → Cerebras → DS V4 Flash
• cerebras → Cerebras → NVIDIA → DS V4 Flash
• deepseek → DeepSeek V4 Flash → NVIDIA → Cerebras

Pipeline mode (monolit vs inkrementalni)

run_coaching_pipeline(mode="auto") volí architekturu dle golden rules:

| Mode | Kdy | Co dela | |---|---|---|---| | auto | default | N≤30 → monolit, N>30 → inkrementalni | | mono | rychlá analýza | 1 LLM call, raw data v promptu | | incremental | stovky her, PGN import | per-game LLM cache + agregace se summaries |

Prepina se PIPELINE_MODE env var nebo parametrem funkce. Per-game LLM cache: data/game_cache/{game_id}_llm.json. Per-game analyza (inkrementalni) resi Stockfish → LLM mapping pres contract testy (tests/test_prompt_contract.py).

API klic (volitelny)

Do .env (vsechny jsou free krome DeepSeek):

NVIDIA_API_KEY=nvapi-...
CEREBRAS_API_KEY=csk-...
DEEPSEEK_API_KEY=sk-...       # spolecny pro DS Chat i V4 Flash
LLM_MAX_TOKENS=4000            # default 2000, pro plny report 4000

Porovnani provideru (5 her, stejna data)

Provider	Model	Tokens	Latence	Cena/5her	SNR
NVIDIA	nemotron-3-super-120b-a12b	2 597	17s	$0.000	57%
Cerebras	gpt-oss-120b	2 677	-	$0.000	54%
DeepSeek V4 Flash	deepseek-v4-flash	3 876	31s	$0.001	93%

SNR = semanticka vernost vuci vstupnim datum (konfidence %, phase ACPL, zadne inventovane patterny). ACPL = Average Centipawn Loss — prumerna ztrata v centipawnech (setinach pesce) na tah.

Analyza kvality

Kriterium	NVIDIA	Cerebras	DeepSeek V4
Grounding k patternum	✅ vsech 6	⚠️ inventuje 7. pattern	✅ vsech 6
Konfidence % z dat	❌ chybi	⚠️ castecne	✅ vsechny
Phase ACPL citace	❌ chybi	⚠️ priblizne	✅ presne
Halucinace	❌ zadne	⚠️ stredni	✅ minimalni
Koucovaci ton	formalni	stredni	prirozeny

Verdikt: DeepSeek V4 Flash = nejvyssi SNR (93%). Jediny, ktery konzistentne cituje konfidence a fázová data. NVIDIA = solidni fallback zdarma. Cerebras ma nejlepsi formatovani, ale inventuje patterny.

Cenova projekce (100 her)

Provider	Cena/100her	Pozn
NVIDIA	$0.00	Free tier, neomezeno
Cerebras	$0.00	Free tier, neomezeno
DeepSeek V4 Flash	~$0.07	~1 460 her za $1
DeepSeek Chat	~$0.24	ZAKAZAN — 3.6× drazsi nez V4 Flash

Nastroje (9 MCP toolu)

Tool	Co dela
lichess\_fetch\_games	Stahne recent partie hrace z Lichess
lichess\_analyze\_game	Analyzuje jednu partii Stockfishem (kazdy tah, centipawn loss)
lichess\_analyze\_position	Analyzuje FEN pozici (depth 8-24, multipv 3)
lichess\_opening\_explorer	Prozkuma zahajeni v Lichess databazi
lichess\_player\_profile	Vrati profil, ratingy a statistiky hrace
lichess\_diagnose\_player	Diagnostikuje slabiny pres vice partii (faze, otvoreni, ACPL)
lichess\_match\_patterns	Detekuje vzorove chyby A-Q1 z tve pattern library
lichess\_workspace\_info	Vrati kontext pracovniho prostoru (P17)
lichess\_import\_pgn	Importuje PGN soubor jako partii

L2 Resources:

• lichess://analysis/\{key\} — ulozene vysledky analyzy

• lichess://patterns/\{key\} — ulozene vysledky detekce patternu

• lichess://analysis/list — seznam vsech analyz

• lichess://patterns/list — seznam vsech pattern detekci

Rychly start

1. Stahnout repo

git clone https://github.com/outpost2026/lichess-mcp-analyzer.git  
cd lichess-mcp-analyzer

2. Stahnout Stockfish

powershell -File scripts\setup_stockfish.ps1

Nebo stahni rucne z official-stockfish/Stockfish a vloz stockfish.exe do stockfish/ adresare.

3. Nastavit LICHESS_TOKEN

Vytvor .env soubor v repo root:

LICHESS\_TOKEN=lip\_xxx

Token vytvoris na lichess.org/settings/oauth.

4. Spustit MCP server

uv sync  
uv run python -m src.server

Server se pripoji pres stdio. Pro opencode ho registruj v opencode.jsonc:

"lichess-analyzer": {
    "type": "local",
    "command": ["cesta\\k\\repo\\.venv\\Scripts\\python.exe", "-X", "utf8", "-m", "src.server"],
    "enabled": true,
    "timeout": 60000
}

5. Nebo pouzit CLI pipeline

# Analyzuj vlastni profil (poslednich 20 partii)  
uv run python scripts\run_pipeline.py outpost2026 --games 20 --depth 12  
   
# Analyzuj + zapis do KB (bez --no-kb)  
uv run python scripts\run_pipeline.py outpost2026 --games 10

Ukazka pouziti

"Co je za hrace?"

> lichess_player_profile("outpost2026")
  
{
  "username": "outpost2026",
  "ratings": {
    "blitz": {"rating": 1950, "games": 342},
    "rapid": {"rating": 1880, "games": 156}
  },
  "total_games": 523
}

"Analyza posledni partie"

> lichess_analyze_game("abc12345")
  
{
  "game": {"opening": "Sicilian Defense", "result": "1-0"},
  "stats": {"total_acpl": 45.2, "blunders": 1, "total_moves": 42},
  "blunders": ["Move 28: Nxe5 (loss 450cp)"]
}

"Diagnoza slabin"

> lichess_diagnose_player("outpost2026", max_games=15)
  
{
  "total_acpl": 62.3,
  "phase_weaknesses": {
    "middlegame": {"acpl": 78.1, "blunders": 4},
    "endgame": {"acpl": 45.0, "blunders": 1}
  },
  "top_weaknesses": [
    "Tactical awareness in middlegame transitions",
    "Opening preparation: Sicilian Defense"
  ]
}

"Najdi vzorove chyby"

> lichess_match_patterns("outpost2026")
  
{
  "patterns_detected": [
    {
      "pattern_id": "B",
      "pattern_name": "Automatic grab",
      "confidence": 85,
      "severity": "high",
      "mitigation": "3-sec pause + 'A CO ON?' before every capture"
    }
  ]
}

Struktura repozitare

lichess-analyzer-mcp/  
├── stockfish/               ← Stockfish 18 binary (necommitovano)  
├── src/  
│   ├── app.py               ← FastMCP instance  
│   ├── server.py            ← Entry point + workspace context  
│   ├── models/              ← Datove modely (dataclasses)  
│   ├── services/  
│   │   ├── llm_client.py    ← Multi-provider LLM cascade (NVIDIA/Cerebras/DeepSeek)  
│   │   └── ...              ← Lichess, Stockfish, SRS, diagnostika  
│   ├── tools/               ← 9 MCP toolu  
│   ├── resources/           ← L2 Resources  
│   └── kb/  
│       ├── md_reporter.py   ← Generovani MD reportu do docs/  
│       └── ...              ← KB persistence (B2B-Knowledge-Base)  
├── scripts/  
│   ├── run\_pipeline.py      ← CLI batch pipeline  
│   └── setup\_stockfish.ps1  ← Automaticke stazeni Stockfish  
├── tests/  
│   ├── test\_services.py       ← 15 unit testu (modely, komprese, validace)  
│   ├── test\_prompt\_contract.py ← 13 contract testu (schema, mapping, noise-floor)  
│   └── test\_engine\_client.py  ← 5 unit testu s mocknutym Stockfish  
├── docs/  
│   ├── CONTEXT\_A\_ZAMER.md   ← Kompletni kontext a zamer projektu  
│   └── PHASE2\_BUILD\_PLAN.md ← Build plan + MCP pitva pravidla  
├── lichess-mcp.bat          ← Cross-shell launcher (Windows)  
├── .env                     ← LICHESS\_TOKEN (necommitovat)  
├── README.md                ← Tento soubor  
└── LICENSE                  ← MIT

Stack

Vrstva	Technologie
Runtime	Python 3.12+, uv
Framework	FastMCP (mcp>=1.0.0)
Lichess API	berserk>=0.14.0
Sahovy engine	chess>=1.11.0 (python-chess) + Stockfish 18
Spaced repetition	fsrs>=4.0.0 (py-fsrs)
HTTP / LLM API	httpx>=0.28.0
LLM providers	NVIDIA (nemotron-3-super-120b), Cerebras (gpt-oss-120b), DeepSeek (deepseek-v4-flash)
LLM cascade	prvni uspesny vyhrava, prepinaci DEFAULT_PROVIDER env var
Persistence	B2B-Knowledge-Base (JSON + Markdown)

Inspirace a zdroje

Tento projekt neni fork — je vlastni architekturou, ale cenna inspirace a infrastrukturni komponenty pochazeji z nasledujicich open-source projektu. Dekujeme autorum.

Primarni zdroje (knihovny)

Projekt	Autor	Pouziti
berserk	lichess-org / Matt Harrison	Lichess API Python client — auth, rate limiting, streaming
python-chess	Niklas Fiekas (niklasf)	PGN/FEN parsing, UCI engine wrapper, game tree, move validation
Stockfish	The Stockfish team	Lokalni sachovy engine (UCI protokol), evaluace kazdeho tahu
fastmcp	Jeremiah Lowin	FastMCP framework — usnadnuje tvorbu MCP serveru
py-fsrs	Open Spaced Repetition	FSRS algoritmus pro spaced repetition

Sekundarni inspirace (MCP servery pro sachy)

Pri navrhu architektury jsme zkoumali 10+ existujicich chess MCP serveru na GitHubu. Ponauceni z TOP 4:

Repozitar	Hvezdy	Co nas inspirovalo
chess-coach-mcp	~50	Analyza partii + treninkovy feedback
chessagine-mcp	~30	Multi-engine analyza, viceserverova architektura
chess-rocket	~80	Spaced repetition na sachove chyby (SM-2)
chess-com-lichess-org-mcp	~120	Siroky Lichess API wrapper (54 toolu) — inspirace pro tool design

Co nasi architekturu odlisuje: kombinace pattern detection library jako kompresniho modelu hrace (viz sekce "Pattern detection jako kompresni model" — MSE overeni, ztratova komprese, Occamova britva, confidence pres compression_ratio), FSRS spaced repetition na osobni chyby, cross-game diagnostiky a KB persistence v jednom MCP serveru.

Stavba a debug engine integrace

Behem vyvoje byly identifikovany a opraveny dve kriticke chyby v engine\_client.py:

• Inverze perspektivy — cp_loss pocitan z opacne strany (board.push() meni side-to-move)

• Best-move porovnani — cp_loss pocitan jako delta before/after, nikoliv best/actual

Po oprave probehla diferencialni analyza proti Lichess GUI (Stockfish dev-20260609-415ff793, depth 18-22). Vysledek: ACPL MAE (Mean Absolute Error — stredni absolutni chyba) 3.9 oproti lichess referenci — engine je po fixu funkcne ekvivalentni.

Dalsi zdroje pouzite pri debugu:

• stockfish-web — Lichess patch pro Stockfish WASM (sf_dev build)

• lila — Lichess platform (klasifikacni thresholds: 50/150/300 centipawn)

Sourozenecke MCP servery v portfoliu

Architektonicke vzory (tools-of-tools, KB write-back, L2 Resources, session state) byly overeny na:

Server	Toolu	Klicovy pattern
cnc-tools	20	Session state, caching, audit log
linkedin-analyzer	8	FastMCP framework, KB write-back, EROI scoring
mcp-jobs	5	Boolean AST match, multi-portal scraping, L2+ Resources

Souvislosti

• Pattern library: 9 definovanych (A-R), 7 s detektory — analyza 13 partii, Phase 1 hotova (commit a536845)

• Pozadi: docs/CONTEXT\_A\_ZAMER.md — kompletni kontext, reserse a architektura

• MCP pravidla: Aplikovano P1-P45 z agregovane pitevni knihy (timeout guard, structured logging, L2 Resources, encoding triad, contract testing, API key health check)

• KB modul: B2B-Knowledge-Base/02_ANALYZY/02_chess/ + 04_KNOWLEDGE_BASE/02_chess/

Stav (2026-07-20)

Co	Stav
Tests	33/33 pass (15 unit + 13 contract + 5 engine mock)
Patterny definovane	9 (A, B, C, G, I, O, P, Q, R)
Patterny s detektorem	7 (A, B, G, O, P, Q, R)
Cached games	18 (depth 12-14)
Phase 1	Hotova
LLM pipeline	✅ NVIDIA, Cerebras, DeepSeek V4 Flash funkcni
LLM reporting	✅ MD reporty do docs/ (truncating, signal, priorita, trening)
Provider switch	✅ DEFAULT_PROVIDER env var (nvidia/cerebras/deepseek)
Pipeline mode	✅ PIPELINE_MODE env var (mono/incremental/auto)
Contract tests	✅ 13 testu — Stockfish→LLM mapping, schema, noise-floor
Low SNR fix	✅ GT-059 — accuracy, phase_stats, key mapping opraveny
DeepSeek Chat	❌ ZAKAZAN — prilis drahy ($0.27/$1.10 per 1M)

Kalibracni plan: docs/KALIBRACE_PLAN_2026-07-19.md (v2.3, ~600 lines). Session state: .ai_state.json

License

MIT 2026 Ondrej Sousek (outpost2026)