{"openapi":"3.1.0","info":{"title":"Klondike Solitaire API","version":"0.1.0","description":"A real, stateless, playable single-player card game: genuine shuffle and deal, tableau/foundation move validation, draw-1/draw-3 stock handling, win detection, and a real deadlock check. Every tool call takes the full game state and returns the new state; nothing is stored server-side.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://solitaireklondike.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/solitaireklondike/docs"},"termsOfService":"https://connectorbay.com/solitaireklondike/terms"},"servers":[{"url":"https://solitaireklondike.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/solitaireklondike/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/new_game":{"post":{"operationId":"new_game","summary":"Shuffles a real 52-card deck and deals standard Klondike (7 tableau piles sized 1-7, top","description":"Shuffles a real 52-card deck and deals standard Klondike (7 tableau piles sized 1-7, top\n    card of each face up; remaining 24 to the stock). Use for \"let's play solitaire/klondike\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"draw_mode":{"default":"draw1","description":"'draw1' (default) or 'draw3'.","title":"Draw Mode","type":"string"},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Optional integer seed for a reproducible shuffle (testing/demos). Omit for a real random shuffle.","title":"Seed"}},"title":"new_gameArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/make_move":{"post":{"operationId":"make_move","summary":"Validates and applies one move per real Klondike rules, returning the new state with an","description":"Validates and applies one move per real Klondike rules, returning the new state with an\n    informative message (or a rejection reason for an illegal move). Use for any single move.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game or make_move. Carry it forward between calls; there is no server-side session.","title":"State","type":"object"},"move":{"additionalProperties":true,"description":"{'action': 'draw'|'tableau_to_tableau'|'waste_to_tableau'|'tableau_to_foundation'|'waste_to_foundation', 'from_pile': int (0-6), 'to_pile': int (0-6), 'count': int (cards to move as a unit, tableau_to_tableau only, default 1)}.","examples":[{"action":"draw"},{"action":"tableau_to_tableau","count":1,"from_pile":2,"to_pile":5},{"action":"waste_to_foundation"}],"title":"Move","type":"object"}},"required":["state","move"],"title":"make_moveArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/draw":{"post":{"operationId":"draw","summary":"Draws 1 or 3 cards (per draw_mode) from the stock to the waste; recycles the waste back","description":"Draws 1 or 3 cards (per draw_mode) from the stock to the waste; recycles the waste back\n    into the stock if the stock is empty. Use for \"draw a card\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game or make_move. Carry it forward between calls; there is no server-side session.","title":"State","type":"object"}},"required":["state"],"title":"drawArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/move_tableau_to_tableau":{"post":{"operationId":"move_tableau_to_tableau","summary":"Moves a valid descending, alternating-color run of `count` face-up cards from one tableau","description":"Moves a valid descending, alternating-color run of `count` face-up cards from one tableau\n    pile to another. Use for \"move the red 6 (and what's on it) onto the black 7\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game or make_move. Carry it forward between calls; there is no server-side session.","title":"State","type":"object"},"from_pile":{"description":"Source tableau pile, 0-6.","title":"From Pile","type":"integer"},"to_pile":{"description":"Destination tableau pile, 0-6.","title":"To Pile","type":"integer"},"count":{"default":1,"description":"How many cards to move as one run, starting from the top. Default 1.","title":"Count","type":"integer"}},"required":["state","from_pile","to_pile"],"title":"move_tableau_to_tableauArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/move_waste_to_tableau":{"post":{"operationId":"move_waste_to_tableau","summary":"Moves the top waste card onto a tableau pile if it fits. Use for \"play the waste card onto","description":"Moves the top waste card onto a tableau pile if it fits. Use for \"play the waste card onto\n    pile 3\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game or make_move. Carry it forward between calls; there is no server-side session.","title":"State","type":"object"},"to_pile":{"description":"Destination tableau pile, 0-6.","title":"To Pile","type":"integer"}},"required":["state","to_pile"],"title":"move_waste_to_tableauArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/move_tableau_to_foundation":{"post":{"operationId":"move_tableau_to_foundation","summary":"Moves a tableau pile's top card to its suit foundation if it's the next rank needed. Use","description":"Moves a tableau pile's top card to its suit foundation if it's the next rank needed. Use\n    for \"send that ace up to the foundation\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game or make_move. Carry it forward between calls; there is no server-side session.","title":"State","type":"object"},"from_pile":{"description":"Source tableau pile, 0-6.","title":"From Pile","type":"integer"}},"required":["state","from_pile"],"title":"move_tableau_to_foundationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/move_waste_to_foundation":{"post":{"operationId":"move_waste_to_foundation","summary":"Moves the top waste card to its suit foundation if it's the next rank needed. Use for","description":"Moves the top waste card to its suit foundation if it's the next rank needed. Use for\n    \"send the waste card to the foundation\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game or make_move. Carry it forward between calls; there is no server-side session.","title":"State","type":"object"}},"required":["state"],"title":"move_waste_to_foundationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_valid_moves":{"post":{"operationId":"get_valid_moves","summary":"Lists every currently legal move (tableau/waste to tableau/foundation, plus draw) as","description":"Lists every currently legal move (tableau/waste to tableau/foundation, plus draw) as\n    ready-to-use move objects with descriptions. Use for \"what can I do\", \"what moves do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game or make_move. Carry it forward between calls; there is no server-side session.","title":"State","type":"object"}},"required":["state"],"title":"get_valid_movesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/hint":{"post":{"operationId":"hint","summary":"A real hint: the best legal move available (foundation moves first), or a genuine deadlock","description":"A real hint: the best legal move available (foundation moves first), or a genuine deadlock\n    report when the stock, waste, and every tableau/foundation move are all exhausted. Use for\n    \"give me a hint\", \"am I stuck\", \"is there any move left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game or make_move. Carry it forward between calls; there is no server-side session.","title":"State","type":"object"}},"required":["state"],"title":"hintArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/render":{"post":{"operationId":"render","summary":"A human-readable text rendering of the whole board: foundations, stock/waste, and every","description":"A human-readable text rendering of the whole board: foundations, stock/waste, and every\n    tableau pile (face-down cards shown as '??'). Use for \"show me the board\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game or make_move. Carry it forward between calls; there is no server-side session.","title":"State","type":"object"}},"required":["state"],"title":"renderArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}