@chessceo/mcp 0.49.3 → 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,11 +379,15 @@ 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),
+                ...(typeof args.engine_type === "string" ? { engineType: args.engine_type } : {}),
             });
         case "list_cloud_engines":
             return authedRequest("GET", "/api/agent/cloud-engines");

package/dist/tools.js

@@ -258,20 +258,25 @@ export const TOOLS = [
     },
     {
         name: "list_cloud_machine_options",
-        description: "Returns the catalog of combo cloud-engine machine types the user can start (SKU, 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. 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: {} },
     },
     {
         name: "start_cloud_engine",
-        description: "Rent a combo GPU instance (Stockfish + Lc0 in the same container) on the user's chess.ceo account. Real money — billed per second while running.\n\n" +
-            "CRITICAL: `machine_type` must be an exact SKU from `list_cloud_machine_options` (e.g. 'rtx-5090-64', NOT 'rtx-5090'). Guessing SKUs will fail. Call list_cloud_machine_options first, show the user the display names + prices, get their confirmation, then pass the SKU here.\n\n" +
-            "Use list_cloud_engines first to check if the user already has one running; don't start a second combo unless the user asked for it. Requires an MCP token with agent access.",
+        description: "Rent a GPU/CPU instance on the user's chess.ceo account — stockfish-only, lc0-only, or combo (both in one container), whichever the chosen SKU provides. Real money — billed per second while running.\n\n" +
+            "CRITICAL: `machine_type` must be an exact SKU from `list_cloud_machine_options` (e.g. 'rtx-5090-64', NOT 'rtx-5090'). Guessing SKUs will fail. Call list_cloud_machine_options first, show the user the display names + prices, get their confirmation, then pass the SKU here. `engine_type` must match what that SKU actually provides (its `engine` field from the catalog) — omit it to default to whatever the SKU is (a combo SKU defaults to \"combo\").\n\n" +
+            "Use list_cloud_engines first to check if the user already has one running; don't start a second instance unless the user asked for it. Requires an MCP token with agent access.",
         inputSchema: {
             type: "object",
             properties: {
                 machine_type: {
                     type: "string",
-                    description: "SKU from list_cloud_machine_options (e.g. 'rtx-5090-64', 'rtx-5090-dual-64'). MUST be the exact SKU, not the display name and not a guess.",
+                    description: "SKU from list_cloud_machine_options (e.g. 'rtx-5090-64', 'rtx-5090', 'epyc-256'). MUST be the exact SKU, not the display name and not a guess.",
+                },
+                engine_type: {
+                    type: "string",
+                    enum: ["stockfish", "lc0", "combo"],
+                    description: "Which engine(s) to run. Must match the SKU's own `engine` field from list_cloud_machine_options — e.g. a stockfish-only SKU can only be started as \"stockfish\". Optional; defaults to \"combo\".",
                 },
             },
             required: ["machine_type"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chessceo/mcp",
-  "version": "0.49.3",
+  "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": {