@chessceo/mcp 0.49.4 → 0.49.5

package/dist/index.js

@@ -114,6 +114,18 @@ const SUMMARY_AUTHORING_DOC = loadBundledDoc("summary-authoring.md", "Summary au
 // all intact) — not summarised into English.
 const EXAMPLE_OVERVIEW_PGN = loadBundledDoc("examples/italian-fried-liver.pgn", "Italian Fried Liver overview example");
 const EXAMPLE_REPERTOIRE_PGN = loadBundledDoc("examples/najdorf-6-f4-white.pgn", "Najdorf 6.f4 White repertoire example");
+// Per-engine guidance surfaced in list_cloud_machine_options' RESPONSE only
+// (an AUTHED_TOOLS-gated call, both transports — see authedRequest's
+// missing-token check and isAuthedToolCall's 401+WWW-Authenticate
+// pre-check). Deliberately NOT in this tool's static `description` in
+// tools.ts, since tools/list itself is reachable without authentication —
+// 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.",
+    combo: "Runs Stockfish and Lc0 together — use when you want both the objective read and the practical/human-feel read on the same position.",
+};
 // v0.48: consolidated the five `read_*_guide` / `read_example_prep_files`
 // tools into ONE `read_docs`. LLM lists what it wants; we return them
 // in a single response. Also cleaner: enumerating available docs in one
@@ -367,8 +379,11 @@ async function callToolInner(name, args) {
         case "list_player_live_tournaments":
             // Note: snake_case fide_id, unlike the prep endpoints. Documented quirk.
             return get("/api/chess/live/player", { fide_id: Number(args.fide_id) });
-        case "list_cloud_machine_options":
-            return authedRequest("GET", "/api/agent/cloud-engines/options");
+        case "list_cloud_machine_options": {
+            const raw = await authedRequest("GET", "/api/agent/cloud-engines/options");
+            const resp = raw;
+            return { ...(resp && typeof resp === "object" ? resp : { options: [] }), engine_guide: ENGINE_GUIDE };
+        }
         case "start_cloud_engine":
             return authedRequest("POST", "/api/agent/cloud-engines", {
                 machineType: String(args.machine_type),

package/dist/tools.js

@@ -258,7 +258,7 @@ export const TOOLS = [
     },
     {
         name: "list_cloud_machine_options",
-        description: "Returns the catalog of cloud-engine machine types the user can start — every engine shape (stockfish-only, lc0-only, and combo) they're entitled to, same visibility rules as the chess.ceo app (SKU, which engine(s) it runs, human display name, cost per hour, availability). ALWAYS call this before start_cloud_engine — SKU strings like 'rtx-5090-64' do not match the display names ('Stockfish 32 CPUs + Lc0 1× RTX 5090') and are NOT guessable, and a given SKU only supports the engine(s) shown in its `engine` field (a stockfish-only SKU cannot be started as lc0 or combo). Present the user the display names + prices; pass the SKU to start_cloud_engine.",
+        description: "Returns the catalog of cloud-engine machine types the user can start — every engine shape (stockfish-only, lc0-only, and combo) they're entitled to, same visibility rules as the chess.ceo app (SKU, which engine(s) it runs, human display name, cost per hour, availability), plus an `engine_guide` explaining what each engine type is actually good/bad for so you can pick the right one for the task, not just the cheapest. ALWAYS call this before start_cloud_engine — SKU strings like 'rtx-5090-64' do not match the display names ('Stockfish 32 CPUs + Lc0 1× RTX 5090') and are NOT guessable, and a given SKU only supports the engine(s) shown in its `engine` field (a stockfish-only SKU cannot be started as lc0 or combo). Present the user the display names + prices; pass the SKU to start_cloud_engine.",
         inputSchema: { type: "object", properties: {} },
     },
     {

package/package.json

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