{"openapi":"3.1.0","info":{"title":"Mastermind Play API","version":"0.1.0","description":"A fully local, playable Mastermind-style code-breaking peg game, with an optional codebreaker mode where the engine guesses your secret using a real Knuth-style minimax strategy. Stateless: the caller holds the game state between calls.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://mastermindplay.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/mastermindplay/docs"},"termsOfService":"https://connectorbay.com/mastermindplay/terms"},"servers":[{"url":"https://mastermindplay.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/mastermindplay/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":"Start a new Mastermind game. 'guesser' mode generates a secret the engine holds for you to guess;","description":"Start a new Mastermind game. 'guesser' mode generates a secret the engine holds for you to guess;\n    'codebreaker' mode expects YOU to hold a secret for the engine to guess. Use for \"let's play mastermind\",\n    \"start a codebreaking game with 5 pegs and 8 colors\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"mode":{"default":"guesser","description":"'guesser' (engine holds the secret) or 'codebreaker' (you hold the secret).","title":"Mode","type":"string"},"code_length":{"default":4,"description":"Number of peg positions in the code.","maximum":8,"minimum":2,"title":"Code Length","type":"integer"},"colors":{"default":6,"description":"Number of distinct colors, numbered 1..colors.","maximum":10,"minimum":2,"title":"Colors","type":"integer"},"allow_repeats":{"default":true,"description":"Whether a color may appear more than once in the code.","title":"Allow Repeats","type":"boolean"},"max_attempts":{"default":10,"description":"Maximum number of guesses allowed.","maximum":20,"minimum":1,"title":"Max Attempts","type":"integer"}},"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/submit_guess":{"post":{"operationId":"submit_guess","summary":"Guesser mode only: submit a guess against the engine's secret and get black/white peg feedback.","description":"Guesser mode only: submit a guess against the engine's secret and get black/white peg feedback.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current game state, exactly as returned by a previous call.","title":"State","type":"object"},"guess":{"description":"Your guess: a list of colors (integers), one per peg position.","items":{"type":"integer"},"title":"Guess","type":"array"}},"required":["state","guess"],"title":"submit_guessArguments","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/codebreaker_guess":{"post":{"operationId":"codebreaker_guess","summary":"Codebreaker mode only: compute the engine's next guess against the human-held secret using a real","description":"Codebreaker mode only: compute the engine's next guess against the human-held secret using a real\n    Knuth-style minimax strategy over every code still consistent with feedback so far. Show the returned\n    guess to the human, collect their black/white peg count, and call provide_feedback with it.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current game state, exactly as returned by a previous call.","title":"State","type":"object"}},"required":["state"],"title":"codebreaker_guessArguments","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/provide_feedback":{"post":{"operationId":"provide_feedback","summary":"Codebreaker mode only: record the human's black/white peg feedback for the engine's most recent","description":"Codebreaker mode only: record the human's black/white peg feedback for the engine's most recent\n    guess, and report whether the engine solved it, ran out of attempts, or should guess again.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current game state, exactly as returned by a previous call.","title":"State","type":"object"},"black":{"description":"Number of black pegs (right color, right position) for the engine's last guess.","minimum":0,"title":"Black","type":"integer"},"white":{"description":"Number of white pegs (right color, wrong position) for the engine's last guess.","minimum":0,"title":"White","type":"integer"}},"required":["state","black","white"],"title":"provide_feedbackArguments","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_board":{"post":{"operationId":"render_board","summary":"Render the guess history as human-readable text with peg symbols. Never reveals the secret.","description":"Render the guess history as human-readable text with peg symbols. Never reveals the secret.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current game state, exactly as returned by a previous call.","title":"State","type":"object"}},"required":["state"],"title":"render_boardArguments","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/reveal_secret":{"post":{"operationId":"reveal_secret","summary":"Reveal the secret code for a 'guesser'-mode game -- use for a clean end-of-game reveal, or if the","description":"Reveal the secret code for a 'guesser'-mode game -- use for a clean end-of-game reveal, or if the\n    human wants to give up. Not applicable to 'codebreaker' mode (the human already knows their own secret).","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current game state, exactly as returned by a previous call.","title":"State","type":"object"}},"required":["state"],"title":"reveal_secretArguments","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/game_info":{"post":{"operationId":"game_info","summary":"Report attempts used/remaining, guess count, and (in codebreaker mode) how many codes are still","description":"Report attempts used/remaining, guess count, and (in codebreaker mode) how many codes are still\n    logically consistent with feedback so far.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current game state, exactly as returned by a previous call.","title":"State","type":"object"}},"required":["state"],"title":"game_infoArguments","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/rules_info":{"post":{"operationId":"rules_info","summary":"Explain the rules of Mastermind Play, both modes, and the codebreaker's minimax strategy.","description":"Explain the rules of Mastermind Play, both modes, and the codebreaker's minimax strategy.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"rules_infoArguments","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}}}}