@chessceo/mcp 0.49.7 → 0.49.9

package/dist/index.js

@@ -122,8 +122,9 @@ const EXAMPLE_REPERTOIRE_PGN = loadBundledDoc("examples/najdorf-6-f4-white.pgn",
 // putting it there would surface this to any caller who can list tools,
 // not just ones who actually hold a token.
 const ENGINE_GUIDE = {
-    stockfish: "Objective calculation — the ground truth for whether a line is actually winning/drawn/losing with best play, whether a tactic is real, whether a defense holds. Gives 0.00 to a large share of normal positions even when one side is much harder to play for a human — that means 'drawn with best play,' not 'trivial' or 'nothing to look for.'",
-    lc0: "Neural-net engine trained on human-style play, roughly 3500-strength. Its evaluation approximates how a strong human judges the position (practical chances, initiative, structure) rather than pure objective truth — good for finding ideas and gauging which side is easier to play over the board. Has real weaknesses in unconventional/irregular positions outside its training distribution: evals there can be unstable or it can miss a deep concrete tactic. When it disagrees sharply with Stockfish, look for the tactical justification before trusting its read.",
+    stockfish: "Objective calculation, the default cloud engine at about 100 million nodes per second. A few seconds gives a very strong view of the position. Use it on every position, including when steering by lc0 or human. Its score is the objective value with best defense: 0.00 means objectively a draw with best play, not that nothing is happening or that neither side has chances. Many positions that are very hard to play for a human score 0.00. Scores drift toward 0.00 as the search deepens, especially in drawn positions. Use it to check whether a tactic is real, whether a defense holds, and whether a move loses material or the game.",
+    lc0: "Neural-net engine trained on self-play games, not human games. It is better than Stockfish at long-term ideas and at judging which side is practically on top. Never gives 0.00: it always says which side prefers the position, at least a little. Use it when Stockfish gives 0.00 to see who still has the practical edge, and to find where the long-term ideas are. Contempt changes how it values a draw and which side it plays for: contempt at -20 makes Black play for a win, which is useful for finding ideas, including in openings. It is much weaker tactically than Stockfish, so confirm any concrete line with Stockfish.",
+    human: "Neural net trained only on human games, about 11 million rated games. Its moves and evaluations are practical, not objective: the moves it suggests are the ones a human would find and play. It punishes dubious moves less than Stockfish, because human games contain many imperfect moves that still work in practice, so a move with a sound idea behind it can score well here. Use it to predict how a person will respond to an idea, to find ideas (it may like a move that only fails to a refutation no human would find; Stockfish shows whether that refutation exists), and to see how a human would evaluate a position, especially positional or unclear ones. Like lc0 it is weaker in very unusual positions, and its evaluations there can be trusted much less. Stockfish remains the check on tactics and on whether a practical idea is objectively sound.",
     combo: "Runs Stockfish and Lc0 together — use when you want both the objective read and the practical/human-feel read on the same position.",
 };
 // Modern engines give equality very often, so small numbers are not "equal".

package/docs/engine-usage.md

@@ -34,7 +34,7 @@ Concrete failure this rule blocks: the LLM says *"9...Bb7: both engines 0.00"* a
 
 ### Stockfish — objective source of truth
 
-Stockfish is calculation. Its evaluation is objective: *"is this position a draw, a win, or a loss with best play from both sides?"*
+Stockfish is the default cloud engine, searching about 100 million nodes per second. A few seconds gives a very strong view of the position. Use it on every position, including when steering by Lc0 or the human engine. Its score is objective: *"is this position a draw, a win, or a loss with best play from both sides?"* 0.00 means objectively a draw with best play, not that nothing is happening.
 
 Trust Stockfish for questions like:
 - Does this defensive line actually hold?
@@ -44,11 +44,11 @@ Trust Stockfish for questions like:
 
 **Watch out for:** Stockfish gives 0.00 to a *lot* of positions in the opening and early middlegame. 0.00 does not mean "trivial draw" — it means "objectively drawn with best play." Practically, one side can still be much harder to defend for a human. Every top-level classical game past move 8 typically shows 0.00 in Stockfish's eyes, yet real players win and lose those games all the time.
 
-### Lc0 — practical eval, human-like feel
+### Lc0 — practical eval, long-term ideas
 
-Lc0 is a neural net trained on self-play games. Its evaluation is closer to how a strong human sees the position — it weighs long-term positional factors, piece activity, space, and initiative in a way Stockfish's fixed search often can't reach.
+Lc0 is a neural net trained on self-play games, not human games. It is better than Stockfish at long-term ideas and at judging which side is practically on top. It never gives 0.00: it always says which side prefers the position, at least a little.
 
-Where Stockfish says 0.00, Lc0 might say +0.15 — meaning *"White still has a small but real practical edge over the board."* That's exactly the signal you want for opening prep, where 95% of positions are within the objective drawing margin and the real question is *"which side is easier to play?"*
+Use it when Stockfish gives 0.00 to see who still has the practical edge, and to find where the long-term ideas are. Contempt changes how it values a draw and which side it plays for: contempt at -20 makes Black play for a win, which is useful for finding ideas, including in openings.
 
 Trust Lc0 for:
 - Which side has practical chances in an opening structure
@@ -56,7 +56,20 @@ Trust Lc0 for:
 - Whether a slow positional idea has long-term venom
 - Ranking candidate moves when Stockfish sees several as equal
 
-**Watch out for:** Lc0 can miss very deep tactical shots — its search is guided by intuition, not depth. If Lc0 loves a line but Stockfish doesn't, look for a concrete tactical justification (or a refutation).
+**Watch out for:** Lc0 is much weaker tactically than Stockfish. If Lc0 loves a line but Stockfish doesn't, look for a concrete tactical justification (or a refutation). Confirm any concrete line with Stockfish.
+
+### Human engine — the practical read
+
+The human engine is a neural net trained only on human games, about 11 million rated games. Its moves and evaluations are practical, not objective: the moves it suggests are the ones a human would find and play.
+
+It punishes dubious moves less than Stockfish. Human games contain many imperfect moves that still work in practice, so a move with a sound idea behind it can score well here.
+
+Use it to:
+- Predict how a person will respond to an idea.
+- Find ideas. It may like a move that only fails to a refutation no human would find. Stockfish shows whether that refutation exists.
+- See how a human would evaluate a position, especially positional or unclear ones.
+
+**Watch out for:** like Lc0, it is weaker in very unusual positions, and its evaluations there can be trusted much less. Stockfish remains the check on tactics and on whether a practical idea is objectively sound.
 
 ### Rule of thumb
 
@@ -192,6 +205,25 @@ Override the defaults with `stockfish_multipv` / `lc0_multipv` when a specific p
 
 The skipped engine's field is omitted from the response (not present as an empty object).
 
+## Renting and choosing engines
+
+Analysis needs a running rental. Start one with `start_cloud_engine`, using a `machine_type` SKU from `list_cloud_machine_options`. Each SKU provides one of three shapes, shown in its `engine` field:
+
+- **`stockfish`**: Stockfish only. Fits when the question is objective (is this tactic real, does this defense hold).
+- **`lc0`**: Lc0 only. Fits the practical, human-feel read, or running alongside a `deep_analyse` that holds the Stockfish side.
+- **`combo`**: both engines in one container. The default, and the right choice for prep decisions, where both reads are needed on the same position.
+
+Rule of thumb: start a `combo` rental unless the task only needs one engine. A single-engine rental gives one read per position, so a prep walk that needs both reads on a single-engine rental takes two passes.
+
+`list_cloud_machine_options` returns the price for each SKU. Show the user the price and get their confirmation before starting a rental; every rental bills per second until `stop_cloud_engine`.
+
+Routing to a rental:
+
+- `cloud_analyse`, `auto_evaluate`, and `deep_analyse` each take an optional `contract_id` (from `list_cloud_engines`).
+- Without `contract_id`, the call uses the only running rental that can serve the request. If several can, the error lists their contract ids, and you pick one.
+- Any shape works. With `engines` set, the rental must provide those engines: asking for `engines: ["lc0"]` on a stockfish-only rental fails.
+- Do not guess contract ids. Call `list_cloud_engines` first if more than one rental is running.
+
 ## Worked example
 
 User is preparing Black against a 2600 opponent who plays 1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6 6.Be3 e5. You want to know if 7.Nb3 or 7.Nf3 is more testing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chessceo/mcp",
-  "version": "0.49.7",
+  "version": "0.49.9",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {