Skip to main content

MCP Servers

Number Guessing Game

Overview

The Guessing Game Server is a lightweight, interactive MCP server that enables AI agents and users to play a classic number guessing game. It’s designed for quick, turn-based fun and as a demonstration of stateful, multi-turn interactions between agents and users.

The server manages game sessions, tracks attempts, and provides real-time feedback on each guess, making it ideal for both entertainment and algorithmic experimentation (e.g., binary search, ternary search).

Key Features

  • Session Management: Each player can start a new game session, with the server tracking the secret number and remaining attempts.
  • Dynamic Resources: Tracks high scores by player name and number of attempts.
  • Dynamic Tools: Instantly tells you if your guess is too high, too low, or correct.
  • Error Handling: Clear messages for invalid guesses, out-of-range numbers, or session errors.

Use Cases

  • Algorithm Demos: Test and compare search strategies (binary, ternary, interpolation, etc.).
  • AI Training: Teach agents to reason, update state, and optimize guessing strategies.
  • Entertainment: Quick, competitive games for users or bots.
  • Leaderboard Challenges: Compete for the fewest attempts and top the high score list.

Server Details

Tools

1. start_game

Starts a new guessing game session for a player.

ParameterTypeRequiredDefaultDescription
playerNamestringYes-The name of the player starting the session

Example Request:

json

{
  "playerName": "alice"
}

Example Response:

json

{
  "content": [
    {
      "text": "Welcome, alice! Guess 1-100. 10 attempts.",
      "type": "text"
    }
  ]
}

2. guess_number

Submit a guess for the current game session.

ParameterTypeRequiredDefaultDescription
guessintYes-The number you want to guess

Example Request:

json

{
  "guess": 42
}

Example Response:

json

{
  "content": [
    {
      "text": "Too high! 9 attempts left.",
      "type": "text"
    }
  ]
}

3. give_up

Return to the lobby.

Example Request:

json

{}

Example Response:

json

{
  "content": [
    {
      "type": "text",
      "text": "Game over. Alice gave up. Number was 53."
    }
  ]
}

Example Workflow

Scenario: A user wants to play a game and try to get on the leaderboard.

  1. Repeat guesses until correct.

Make a Guess:

json

{
  "tool": "guess_number",
  "args": { "guess": 50 }
}

Response: "Too low! 9 attempts left."

Start a Game:

json

{
  "tool": "start_game",
  "args": { "playerName": "Jesse" }
}

Response: "Welcome, Jesse! Guess 1-100. 10 attempts."

Error Handling

  • If a guess is out of range:
    "Invalid guess. Please enter a number between 1 and 100."
  • If no active session:
    "No active game session. Please start a new game."
  • If attempts run out:
    "Game over! The correct number was 73."