This MCP server is a chess analysis and personalized training platform that connects to Lichess, analyzes games with Stockfish, detects behavioral patterns, and helps players improve through structured diagnostics.
Fetch Games: Retrieve recent games from Lichess or Chess.com for a given username (up to 50 at a time).
Analyze a Game: Perform move-by-move Stockfish analysis on a game (by Lichess ID or PGN), calculating centipawn loss, blunders, and phase-level statistics at configurable depth (8–24).
Analyze a Position: Evaluate any FEN position using local Stockfish or Lichess cloud eval, with multi-PV support.
Opening Explorer: Look up positions in the Lichess public games or Masters (OTB) database for opening statistics.
Player Profile: Retrieve a Lichess player's profile, ratings across time controls, and game statistics.
Diagnose Player Weaknesses: Analyze multiple games to identify recurring tactical blind spots, phase weaknesses (opening/middlegame/endgame), problematic openings, and average centipawn loss per phase.
Detect Behavioral Patterns: Match games against a library of 14+ known playing patterns (A–S), providing confidence scores, evidence, and mitigation advice.
Import PGN: Import and analyze any chess game from a PGN string (from any platform or custom source) through the Stockfish pipeline.
Generate Coaching Reports: Create personalized natural language coaching reports based on analysis and detected patterns.
Spaced Repetition Training: Support spaced repetition (FSRS/SM-2) for effective learning from detected errors and patterns.
Workspace Info: Return server context including Stockfish status, Python version, and registered tool count.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@lichess-mcp-analyzer analyze my last 10 games and find my pattern errors"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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."
Related MCP server: chess-coach-mcp
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 |
| Stáhne recentní partie hráče z Lichess (max 999, berserk pagination fix) |
| Vrátí cache index her dle resultu (win/loss/draw) |
| Analyzuje jednu partii Stockfishem (depth 8-24, per-move cp_loss, BlunderFactSheet) |
| Analyzuje FEN pozici (depth 8-24, multipv 3, cloud eval optional) |
| Prozkoumá zahájení v Lichess / Masters databázi |
| Vrátí profil, ratingy a statistiky hráče |
| Diagnostikuje slabiny přes více partii (fáze, openings, ACPL) |
| Detekuje vzorové chyby A–S + podpora game_ids pro anonymní hry |
| Batch analýza nezpracovaných her (pending detection consistency) |
| Dávková analýza anonymních her (URL/ID/txt, label support, agregace) |
| Importuje PGN z libovolného zdroje do analyzy |
| Vrátí kontext pracovního prostoru |
L2 Resources:
lichess://analysis/{key} — uložené výsledky analýzy
lichess://patterns/{key} — uložené výsledky detekce patternů
lichess://analysis/list — seznam všech analýz
lichess://patterns/list — seznam všech pattern detekcí
models/analysis.py)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
services/narrative_validator.py)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}.mdPřepíná se env var DEFAULT_PROVIDER:
"" (nezadáno) → NVIDIA → Cerebras → DS V4 Flash
cerebras → Cerebras → NVIDIA → DS V4 Flash
deepseek → DeepSeek V4 Flash → NVIDIA → Cerebras
run_coaching_pipeline(mode="auto") volí architekturu dle golden rules:
Mode | Kdy | Co dělá |
| default | N≤30 → monolit, N>30 → inkrementální |
| rychlá analýza | 1 LLM call, raw data v promptu |
| 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 4000git clone https://github.com/outpost2026/lichess-mcp-analyzer.git
cd lichess-mcp-analyzerpowershell -File scripts\setup_stockfish.ps1Nebo 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_xxxToken vytvoříš na lichess.org/settings/oauth.
uv sync
uv run python -m lichess_analyzer_mcp.serverServer 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 ← MITVrstva | 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 | ⚠️ AUD-01 | Čeká na opravu |
C | ⚠️ AUD-02 | Čeká na opravu |
I | ✅ FIXED (concept, manual_only) | Code→I2 |
O | ✅ RESOLVED (rename → Stagnační panika) | Produkce |
P | ⚠️ AUD-06 | Č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án
00_STRATEGIE/DALSI_KROKY_po_RUN_003.md — 15-commit follow-up checklist
docs/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ýza
data/runs/RUN_005_DBCL_v3_2026-07-27.md — RUN_005 report (ACPL=46.1)
docs/MIKOLOV_KOMPRESE_V_PATTERN_ARCHITEKTURE.md — LCP formalizace
B2B-KB/05_EPISTEMIKA/00_kompresni_realismus/Kompresni_modelovani_v_praxi_synteza_v1.md — syntéza
B2B-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 findings
docs/AUDIT_REPORT_lichess-analyzer-mcp_v2.md — interní audit
docs/CONTEXT_INJECT.md v3.2 — session timeline, anomaly log, next steps
docs/CONTEXT_A_ZAMER.md v1.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í |
lichess-org / Matt Harrison | Lichess API Python client | |
Niklas Fiekas | PGN/FEN parsing, UCI wrapper | |
The Stockfish team | Lokální šachový engine | |
Jeremiah Lowin | FastMCP framework | |
Open Spaced Repetition | FSRS algoritmus |
Server | Toolů | Klíčový pattern |
20 | Session state, caching, audit log | |
8 | FastMCP, KB write-back, EROI scoring | |
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)
Stahne recent hry hrace z Lichess/Chess.com.
Args:
username: Lichess nebo Chess.com username
max_games: Maximalni pocet her (1-50)
source: Platforma - 'lichess' nebo 'chesscom'
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | lichess | |
| username | Yes | ||
| max_games | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says it fetches recent games. It does not disclose behavioral traits like rate limits, authentication needs, error handling, or what happens if the user doesn't exist. For a tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear subject line and bullet arguments. It is front-loaded with the main purpose. However, it mixes languages (Czech description with English argument names), which slightly reduces clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should explain return values, but it does not. It also lacks context about data format, pagination, or limitations. For a tool with moderate complexity (3 parameters, no output schema), this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds value for all three parameters: username is clarified to accept both Lichess and Chess.com usernames, max_games bound is specified as 1-50, and source options are explicitly listed as 'lichess' or 'chesscom'. This goes beyond the schema's defaults and titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool downloads recent games of a player from Lichess or Chess.com. The verb 'stahne' (downloads) and resource 'recent hry hrace' (recent games of a player) are specific, and it distinguishes from sibling tools like lichess_import_pgn or lichess_player_profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention of prerequisites, contexts, or when not to use it. The description simply states what it does without any usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import and analyze a chess game from a PGN string.
Parses any PGN (lichess, chess.com, GM games, custom PGN) through the same
Stockfish pipeline used for online games. Returns per-move evaluation,
classification (blunder/mistake/inaccuracy/good/best), and phase detection.
Results are stored in L2 Resources for later retrieval.
Use this to:
- Analyze your own games from any platform
- Import GM games and compare against your patterns (via lichess_match_patterns)
- Analyze opponent games you have PGN for
- Build a custom game library from PGN files
Args:
pgn: Full PGN string of the game (including headers)
color: Your color ('white' or 'black', default 'white')
depth: Stockfish analysis depth (8-24, default 14)
game_id: Optional game identifier (auto-detected from PGN Site header if empty)
| Name | Required | Description | Default |
|---|---|---|---|
| pgn | Yes | ||
| color | No | white | |
| depth | No | ||
| game_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that PGN is parsed through a Stockfish pipeline, returns per-move evaluation and classification, and stores results in L2 Resources for later retrieval. This gives good insight into behavior without contradictions. It does not mention side effects like rate limits or authentication, but for a read-like import, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: 6 sentences plus a bullet list. The main action is front-loaded in the first sentence. Every sentence adds value: purpose, technical detail, use cases, and parameter explanation. No redundant or vague phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters (1 required) and no output schema, the description covers purpose, parameters, and usage guidelines well. It explains what results are returned (evaluation, classification, phase detection) and storage mechanism. However, it lacks details on how to retrieve the stored results or the exact format of the analysis, which would aid completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds full parameter details via an Args block: pgn (full PGN string), color (white/black, default white), depth (integer range 8-24, default 14), game_id (optional, auto-detected from PGN Site header). This adds significant meaning beyond the schema alone, providing defaults, ranges, and usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear action: 'Import and analyze a chess game from a PGN string.' It specifies the verb (import/analyze), resource (chess game), and input format (PGN string). The tool is distinct from siblings like lichess_fetch_games, which fetches from lichess, and lichess_match_patterns, which compares patterns. The resource scope is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists four specific use cases: analyze your own games, import GM games, analyze opponent games, and build a custom library. It also references sibling tool lichess_match_patterns for comparison. However, it does not explicitly state when not to use this tool or provide alternative tools for different scenarios, missing some guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detects known playing patterns (A-Q1) from the player's pattern library.
Analyzes recent games and matches them against the pattern library
imported from chess_pattern_v5.json. Returns detected patterns with
confidence scores, evidence, mitigation advice, and compression validation.
Args:
username: Lichess username
max_games: Number of games to analyze (5-50)
depth: Stockfish depth (8-18)
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | ||
| username | Yes | ||
| max_games | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains it returns confidence scores, evidence, mitigation advice, and compression validation, but does not explicitly state that it is read-only or requires prior library import.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, action details, and an Args section. It is somewhat verbose but not overly so.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, parameters, and return values. It could mention that the pattern library must be imported first, but overall it provides sufficient context for a 3-parameter tool without annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds value beyond the schema by explaining each parameter (username, max_games with range 5-50, depth with range 8-18) and their purpose, despite 0% schema coverage measurement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it detects known playing patterns from a pattern library, using a specific verb and resource. It distinguishes from sibling tools like lichess_fetch_games and lichess_opening_explorer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions analyzing recent games and matching against a pattern library, implying a prerequisite (library import), but gives no explicit when-to-use or when-not-to-use guidance compared to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Looks up a position in the Lichess Opening Explorer.
Args:
fen: FEN string of the position
source: Database - 'lichess' (public games) or 'masters' (OTB master games)
| Name | Required | Description | Default |
|---|---|---|---|
| fen | Yes | ||
| source | No | lichess |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states it looks up a position, without mentioning read-only behavior, authentication needs, rate limits, return structure, or side effects. The description adds minimal value beyond the basic purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences and a bullet list. It is front-loaded with the main purpose and efficiently explains both parameters. There is no wasteful or redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only 2 parameters, no output schema, and no annotations. The description covers the purpose and parameter meanings adequately. However, it omits any indication of return values (e.g., move statistics, games count) or error handling (e.g., invalid FEN). It is minimally viable but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the 'fen' parameter as a FEN string and the 'source' parameter as a choice between 'lichess' and 'masters', including the default. This adds meaningful context beyond the schema titles, though format details for FEN could be added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool looks up a position in the Lichess Opening Explorer, using a specific verb and resource. It is distinct from sibling tools like lichess_fetch_games or lichess_player_profile, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the basic functionality and the parameters, but does not provide explicit when-to-use or when-not-to-use guidance. The context is clear given the name and siblings, but no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a player's Lichess profile, ratings, and stats.
Args:
username: Lichess username
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It only states the return data type but does not mention rate limits, authentication, side effects, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and front-loaded. However, the 'Args' section is separate and could be integrated. Still, no wasted words, earning a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lacks output schema and annotations. The description does not explain what the returned profile contains, possible error conditions (e.g., invalid username), or any additional context like call limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'username' is described as 'Lichess username', which adds minimal meaning beyond the schema's type. With 0% schema coverage, the description does not sufficiently compensate to clarify the parameter's usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Returns' and the resource 'player's Lichess profile, ratings, and stats'. This distinguishes it from sibling tools like lichess_fetch_games which deals with games, or lichess_import_pgn for imports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like lichess_fetch_games. There is no mention of context, prerequisites, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0lichess_fetch_gameslichess_import_pgnlichess_match_patternslichess_opening_explorerlichess_player_profileScored across 5 tools
Each tool has a clearly distinct purpose: fetching games, importing PGN, matching patterns, opening explorer, and player profile. No overlap or ambiguity.
All tools share the 'lichess_' prefix and use snake_case, but verbs are not uniformly applied: 'fetch_games', 'import_pgn', 'match_patterns' are verb_noun, while 'opening_explorer' and 'player_profile' are noun phrases. Minor inconsistency.
Five tools is well-scoped for a chess analysis server. Each tool earns its place without being overwhelming or too sparse.
Covers core workflows: game retrieval, PGN import, pattern matching, opening lookup, and player stats. Missing a direct 'analyze game' tool that doesn't require separate PGN import, but the set is largely complete.
Pedagogical chess intelligence for AI agents: explain positions and games for a target Elo.
An MCP server that gives your AI access to the source code and docs of all public github repos
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
