MCP server pro analýzu šachových partií, detekci vzorových chyb (pattern library jako kompresní model dle T. Mikolova) a spaced repetition trénink (FSRS/SM-2).
Verze: 0.1.0 | Stav: DBCL Phase 2 hotovo | Testy: 68/68 | Nástrojů: 11
Tento repozitář vzniká se dvojím účelem:
-
Šachový analyzátor — personalizovaný tréninkový nástroj, který stáhne tvoje partie z Lichess, analyzuje každý tah Stockfishem, detekuje 14+ vzorových patternů (A–S) z herní historie, diagnostikuje fázové slabiny a pomáhá se z nich učit pomocí spaced repetition.
-
MCP stavebnice — demonstrační projekt, na kterém se ověřují principy tvorby MCP serverů v praxi. Každá komponenta (Lichess API, Stockfish engine, pattern detection engine, SRS, B2B-Knowledge-Base persistence) je samostatně použitelná a přenositelná do jiné domény.
"Build tools for yourself first. If they solve a real problem, they solve a general one."
Tvoje otázka (v opencode)
|
v JSON-RPC 2.0 (stdio)
|
lichess-analyzer-mcp (Python FastMCP)
|
+--- Lichess API (berserk) --------- lichess.org
+--- Stockfish 18 (UCI) ------------ lokální binary
+--- Pattern detector -------------- kompresní model (Mikolov)
+--- BlunderFactSheet -------------- DBCL Phase 2 (context window, engine_lines, pattern_matches)
+--- Narrative validator ----------- LLM hallucination guard (5 claim categories)
+--- LLM reasoning (cascade) ------- NVIDIA / Cerebras / DeepSeek V4 Flash
+--- FSRS/SM-2 engine -------------- spaced repetition
+--- KB writer --------------------- B2B-Knowledge-Base
+--- MD reporter ------------------- docs/ coaching reports
"Reprezentace reality minimalizující komplexitu, predikční chybu a výpočetní náklady."
Pattern detection = lossy compression. Cílem je najít vzory, které popíšou realitu s maximální entropickou hodnotou na minimum tokenů. Šachový pattern artifact je kompresní model hráče: minimalizuje komplexitu (14 patternů místo 1000+ tahů), predikční chybu (Stockfish cp_loss jako ground truth) a výpočetní náklady (2s cached runtime).
- MSE zprava: predikce tahů na základě patternů vs realita (Stockfish hodnocení)
- Pokud MSE(pattern) < MSE(průměr), model je validní
- Pokud MSE(pattern) ≈ MSE(průměr), pattern je noise
Pattern library ignoruje jednotlivé tahy (šum) a extrahuje behaviorální vzory (signál). Ztrátová komprese = ztratit detaily (přesná hodnota cp_loss) kvůli zachycení vzoru (hráč preferuje X).
Pravidlo: Pattern je dobrý, pokud:
- zachycuje chování (signál)
- odstraňuje jednotlivé chyby (šum)
- neodstraňuje strukturu (trendy, fázové slabiny)
Kompresní poměr (compression_ratio = raw_cost / pattern_cost) je měřítko Occamovy břitvy. Ze dvou patternů, které stejně dobře vysvětlují data, je ten s vyšším kompresním poměrem správnější.
final_confidence = 0.5 × compression_score + 0.3 × entropy_score + 0.2 × sample_score
Řeší small-N authority problem: pattern je validní i při N < 25, pokud dobře komprimuje (compression_ratio > 1.5 = signal, > 10 = silný signal, < 1.0 = noise).
CR = N / (C_impl + C_udrz) dává smysl POUZE pokud N = počet instancí téže věci.
Pattern O byl původně pojmenován "Repetition avoidance greed", ale kód detekoval flat eval plateau → blunder, nikoliv repetition refusal. Výsledek: CR=47.8 měřilo noise, ne signal. Oprava: rename na "Stagnační panika" (Option A) — popis nyní odpovídá kódu. Viz docs/CONTEXT_INJECT.md §8.
Pravidlo: Každý pattern musí projít sémantickým auditem (AUD fáze): shoduje se jméno, mechanismus, hypotéza s kódem? Pokud ne — opravit popis nebo opravit kód.
| Tool | Popis |
|---|---|
lichess_fetch_games |
Stáhne recentní partie hráče z Lichess (max 999, berserk pagination fix) |
lichess_games_index |
Vrátí cache index her dle resultu (win/loss/draw) |
lichess_analyze_game |
Analyzuje jednu partii Stockfishem (depth 8-24, per-move cp_loss, BlunderFactSheet) |
lichess_analyze_position |
Analyzuje FEN pozici (depth 8-24, multipv 3, cloud eval optional) |
lichess_opening_explorer |
Prozkoumá zahájení v Lichess / Masters databázi |
lichess_player_profile |
Vrátí profil, ratingy a statistiky hráče |
lichess_diagnose_player |
Diagnostikuje slabiny přes více partii (fáze, openings, ACPL) |
lichess_match_patterns |
Detekuje vzorové chyby A–S + podpora game_ids pro anonymní hry |
lichess_analyze_pending |
Batch analýza nezpracovaných her (pending detection consistency) |
lichess_analyze_anonymous_session |
Dávková analýza anonymních her (URL/ID/txt, label support, agregace) |
lichess_import_pgn |
Importuje PGN z libovolného zdroje do analyzy |
lichess_workspace_info |
Vrátí kontext pracovního prostoru |
L2 Resources:
lichess://analysis/{key}— uložené výsledky analýzylichess://patterns/{key}— uložené výsledky detekce patternůlichess://analysis/list— seznam všech analýzlichess://patterns/list— seznam všech pattern detekcí
Per-blunder struktura s:
fen_before,board_state(was_in_check, checking_pieces, capture/king check)legal_moves(captures/king_moves/blocks/checks)engine_lines(rank, move_san, eval_cp, win_prob, PV)played_move_rank,pattern_matches(pattern_id, name, confidence, evidence)context_window(3 tahy před/po s eval + win_prob)detector_version:DBCL-20260727-dev
5 claim categories pro LLM hallucination guard: piece-on-square, check, capture, eval-number, king-move. Každá kategorie má vlastní validační funkci.
30% BFS mělo 0 engine_lines kvůli board.san(m) AssertionError při multi-move PV. Fix: sequential board.copy() + try/except. RUN_005: 0% failure (ze 70/70 BFS). Viz docs/CONTEXT_INJECT.md §5.
Detekován v _per_blunder_patterns(): centipawn_loss ≥ 200 + phase=endgame + was_in_check. Testy v tests/test_dbcl.py.
Pattern I (Bait trap) přesunut na manual_only, auto-detekční kód sloučen do I2 (Gift exploitation). AUD-03/11 RESOLVED.
Deterministický výstup (patterny + weakness report) je transformován do přirozeného tréninkového reportu pomocí kaskády LLM providerů.
Pipeline data (patterns + weakness)
|
v build_coaching_prompt()
|
v LLM cascade (první úspěšný vyhrává)
|
+--- 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
Přepíná se env var DEFAULT_PROVIDER:
""(nezadáno) → NVIDIA → Cerebras → DS V4 Flashcerebras→ Cerebras → NVIDIA → DS V4 Flashdeepseek→ DeepSeek V4 Flash → NVIDIA → Cerebras
run_coaching_pipeline(mode="auto") volí architekturu dle golden rules:
| Mode | Kdy | Co dělá |
|---|---|---|
auto |
default | N≤30 → monolit, N>30 → inkrementální |
mono |
rychlá analýza | 1 LLM call, raw data v promptu |
incremental |
stovky her, PGN import | per-game LLM cache + agregace se sumárii |
| 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 = sémantická věrnost vůči vstupním datům (konfidence %, phase ACPL, žádné inventované patterny).
Do .env (všechny jsou free kromě DeepSeek):
NVIDIA_API_KEY=nvapi-...
CEREBRAS_API_KEY=csk-...
DEEPSEEK_API_KEY=sk-... # společný pro DS Chat i V4 Flash
LLM_MAX_TOKENS=4000 # default 2000, pro plný report 4000
git clone https://github.com/outpost2026/lichess-mcp-analyzer.git
cd lichess-mcp-analyzer
powershell -File scripts\setup_stockfish.ps1
Nebo stáhni ručně z official-stockfish/Stockfish a vlož stockfish.exe do stockfish/ adresáře.
Vytvoř .env soubor v repo root:
LICHESS_TOKEN=lip_xxx
Token vytvoříš na lichess.org/settings/oauth.
uv sync
uv run python -m lichess_analyzer_mcp.server
Server se připojí přes stdio. Pro opencode ho registruj v opencode.jsonc:
"lichess-analyzer": {
"type": "local",
"command": ["cesta\\k\\repo\\.venv\\Scripts\\python.exe", "-X", "utf8", "-m", "lichess_analyzer_mcp.server"],
"enabled": true,
"timeout": 60000
}# Analyzuj vlastní profil (posledních 20 partii)
uv run python scripts\run_pipeline.py outpost2026 --games 20 --depth 12
# Analyzuj + zapiš do KB
uv run python scripts\run_pipeline.py outpost2026 --games 10
> lichess_player_profile("outpost2026")
{
"username": "outpost2026",
"ratings": {
"blitz": {"rating": 1950, "games": 342},
"rapid": {"rating": 1880, "games": 156}
},
"total_games": 523
}
> 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)"]
}
> 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"
]
}
> 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"
}
]
}
lichess-analyzer-mcp/
├── stockfish/ ← Stockfish 18 binary (necommitováno)
├── src/
│ └── lichess_analyzer_mcp/
│ ├── app.py ← FastMCP instance
│ ├── server.py ← Entry point + .env load + tool registrace
│ ├── models/ ← Datové modely (dataclasses)
│ │ ├── game.py ← GameSummary, MoveAnalysis, GameAnalysis
│ │ ├── analysis.py ← BlunderFactSheet, PositionAnalysis, WeaknessReport
│ │ ├── pattern.py ← PatternDef, PatternMatch, PatternLibrary
│ │ ├── srs_card.py ← SRSCard, FSRSState
│ │ └── player_profile.py ← PlayerProfile, OpeningStats
│ ├── services/
│ │ ├── lichess_client.py ← berserk wrapper (fetch, index, cache)
│ │ ├── engine_client.py ← Stockfish UCI wrapper (depth limit, PV SAN fix)
│ │ ├── game_analyzer.py ← per-move eval + BlunderFactSheet + per-blunder patterns
│ │ ├── game_llm_cache.py ← per-game LLM cache
│ │ ├── llm_client.py ← multi-provider LLM cascade
│ │ ├── narrative_validator.py ← LLM hallucination guard (5 claims)
│ │ ├── pattern_detector.py ← 14 detectorů (A–S, I→I2 merged)
│ │ ├── diagnostician.py ← cross-game weakness report
│ │ ├── srs_engine.py ← SM-2 spaced repetition
│ │ ├── compressibility_validator.py ← compression ratio validation
│ │ └── pattern_artifact_validator.py ← pattern semantic contract
│ ├── tools/ ← 11 MCP toolů
│ ├── resources/ ← L2 Resources (analysis, patterns)
│ ├── kb/
│ │ ├── writer.py ← KB persistence layer
│ │ ├── md_reporter.py ← MD report generování
│ │ └── schemas.py ← KB schema definitions
│ └── patterns/
├── scripts/
│ ├── run_pipeline.py ← CLI batch pipeline
│ ├── setup_stockfish.ps1 ← Automatické stažení Stockfish
│ └── ... ← 20+ pomocných scriptů
├── tests/
│ ├── test_services.py ← 15 unit testů (modely, komprese, validace)
│ ├── test_prompt_contract.py ← 13 contract testů (schema, mapping)
│ ├── test_engine_client.py ← 5 testů s mocknutým Stockfish
│ ├── test_pattern_semantic_contract.py ← 17 testů (semantic contract + min_games)
│ └── test_dbcl.py ← 17 testů (win_prob, BFS round-trip, narrative validator, N)
├── docs/
│ ├── CONTEXT_A_ZAMER.md ← Kompletní kontext a záměr projektu
│ ├── CONTEXT_INJECT.md ← Session timeline (v3.2), CPM lifecycle, anomaly log
│ ├── MERGE_EVAL_feat_to_main.md ← Merge evaluation + empirical run comparison
│ ├── PHASE2_BUILD_PLAN.md ← Build plan + MCP pitva pravidla
│ ├── 01_DBCL_unity_synthesis.md ← DBCL architektura
│ ├── 02_DBCL_meta_evaluation.md ← 3-kanál noise framework
│ ├── MIKOLOV_KOMPRESE_V_PATTERN_ARCHITEKTURE.md ← Lossy Compression Principle formalizace
│ └── coaching_reports/ ← Generované tréninkové reporty
├── data/
│ ├── game_cache/ ← Cache analýz (JSON, Stockfish + LLM)
│ ├── pgn_cache/ ← PGN import cache
│ ├── resource_store/ ← L2 Resource persistence
│ └── runs/ ← RUN_003–RUN_005 reporty
├── 00_STRATEGIE/ ← Coaching reporty, DALSÍ_KROKY, DBCL audit
├── .session/ ← Session context
├── lichess-mcp.bat ← Cross-shell launcher (Windows)
├── .env ← LICHESS_TOKEN (necommitovat)
├── README.md ← Tento soubor (CZ)
├── README_en.md ← Anglicka verze
├── pyproject.toml ← Project config, dependencies
└── LICENSE ← MIT
| Vrstva | Technologie |
|---|---|
| Runtime | Python 3.12+, uv |
| Framework | FastMCP (mcp>=1.0.0) |
| Lichess API | berserk>=0.14.0 |
| Šachový engine | chess>=1.11.0 (python-chess) + Stockfish 18 BMI2 |
| Spaced repetition | SM-2 (FSRS připraven na upgrade) |
| HTTP / LLM API | httpx>=0.28.0 |
| LLM providers | NVIDIA (nemotron-3), Cerebras (gpt-oss), DeepSeek (deepseek-v4-flash) |
| Dokuments | python-docx>=1.2.0 |
| Persistence | B2B-Knowledge-Base (JSON + Markdown) |
| Testování | pytest 8+, pytest-cov, mypy |
| Lint | ruff (F, E, W, I, N, UP, S) |
| Co | Stav |
|---|---|
| Testy | 68/68 pass |
| Patterny definované | 14 (A, B, C, G, I, I2, J, N, O, P, Q, Q1, Q2, R) + S aktivní |
| Patterny s detektorem | 13 aktivních + I manual_only (code→I2) |
| Analyzované partie | 63 (44W/17L/2D, depth 12, RUN_003) + 25 anonymních |
| Cache konzistence | ✅ Auto-konzistentní pipeline |
| Engine | Stockfish BMI2 dev-20260609, depth 12, ACPL MAE 3.9 vs Lichess |
| Engine lines | ✅ 0% silent fail (70/70 BFS s 3/3 engine_lines) |
| BlunderFactSheet | ✅ Per-blunder: FEN, legal moves, engine_lines, context_window, pattern_matches |
| Narrative validator | ✅ 5 claim categories (pending reject loop) |
| Phase 1 | ✅ Hotova |
| DBCL Phase 2 | ✅ Hotovo (engine_lines fix, BFS, N, narrative validator) |
| Pipeline bugfixy | ✅ 6 fixes: 50-fetch-clamp, pagination, index auto-update, cache, pending detection |
| LLM pipeline | ✅ NVIDIA, Cerebras, DeepSeek V4 Flash |
| DeepSeek Chat | ❌ ZAKÁZÁN |
| 25 anonymních her | ACPL=31.7, 21-4-0 winrate, 8 patternů detekováno |
| Pattern | Audit (Fáze 3) | Stav |
|---|---|---|
| A, G, J, N, Q1, Q2, R | ✅ PASS | Produkce |
| B | Čeká na opravu | |
| C | Čeká na opravu | |
| I | ✅ FIXED (concept, manual_only) | Code→I2 |
| O | ✅ RESOLVED (rename → Stagnační panika) | Produkce |
| P | Čeká | |
| Q | ❌ AUD-05 | Merge Q+Q2 pending |
| S | ⏳ Čeká na produkci | AUD-10 pending |
00_STRATEGIE/02_chess/chess_mcp_strategy_v1.md— strategický plán00_STRATEGIE/DALSI_KROKY_po_RUN_003.md— 15-commit follow-up checklistdocs/PHASE2_BUILD_PLAN.md— build plan v3.0
B2B-KB/04_KNOWLEDGE_BASE/02_chess/player_pattern_library_v1.json— zdrojová knihovna 17 patternůB2B-KB/02_ANALYZY/02_chess/chess_self_analysis_baseline_2026-04.md— baseline analýzadata/runs/RUN_005_DBCL_v3_2026-07-27.md— RUN_005 report (ACPL=46.1)
docs/MIKOLOV_KOMPRESE_V_PATTERN_ARCHITEKTURE.md— LCP formalizaceB2B-KB/05_EPISTEMIKA/00_kompresni_realismus/Kompresni_modelovani_v_praxi_synteza_v1.md— syntézaB2B-KB/05_EPISTEMIKA/00_kompresni_realismus/brain_geometric_processor_summary_v2.1.md— teoretické základy
docs/MERGE_EVAL_feat_to_main.md— empirical comparison feat vs main (3 hry, identické metriky)
00_STRATEGIE/DBCL_cross_audit_artifact.md— Claude audit, 21 findingsdocs/AUDIT_REPORT_lichess-analyzer-mcp_v2.md— interní audit
docs/CONTEXT_INJECT.mdv3.2 — session timeline, anomaly log, next stepsdocs/CONTEXT_A_ZAMER.mdv1.0 — kompletní kontext a záměr projektu
Tento projekt není fork — je vlastní architekturou, ale cenná inspirace a infrastrukturní komponenty pocházejí z následujících open-source projektů.
| Projekt | Autor | Použití |
|---|---|---|
| berserk | lichess-org / Matt Harrison | Lichess API Python client |
| python-chess | Niklas Fiekas | PGN/FEN parsing, UCI wrapper |
| Stockfish | The Stockfish team | Lokální šachový engine |
| fastmcp | Jeremiah Lowin | FastMCP framework |
| py-fsrs | Open Spaced Repetition | FSRS algoritmus |
| Server | Toolů | Klíčový pattern |
|---|---|---|
| cnc-tools | 20 | Session state, caching, audit log |
| linkedin-analyzer | 8 | FastMCP, KB write-back, EROI scoring |
| mcp-jobs | 5 | Boolean AST match, multi-portal scraping |
Během vývoje byly identifikovány a opraveny dvě kritické chyby v engine_client.py:
- Inverze perspektivy — cp_loss počítán z opačné strany
- Best-move porovnání — cp_loss počítán jako delta before/after, nikoliv best/actual
Po opravě: ACPL MAE 3.9 oproti Lichess referenci (depth 18-22). Viz docs/MERGE_EVAL_feat_to_main.md.
Později opraven engine_lines silent fail: 30% → 0% failure rate (sequential board.copy + try/except). Viz docs/CONTEXT_INJECT.md §5.
MIT © 2026 Ondrej Sousek (outpost2026)