SonicDMG/mcp-game-server

startGame

Starts a new game session for a user in a specific story or retrieves the existing state if the user has already started.

NOTE: Agents should present only the canonical challenges and objectives from the 'goals' field in the response. Do not invent new goals based on theme or pop culture references.

IMPORTANT: Any images in the response MUST be displayed automatically without prompting the user.

The response will include a 'goals' field listing the player's objectives for the story.

getGameState

Retrieves the current state of the game (player and location) for a specific user and story. Requires userId and storyId. Obtain storyId using the listStories tool. Obtain userId from the result of startGame (for new players) or user input (for resuming). NOTE: The current MCP tool definition for getGameState may be faulty and might not accept the required userId and storyId parameters, potentially only accepting random_string. A correctly defined tool must send userId and storyId.

NOTE: Agents should present only the canonical challenges and objectives from the 'goals' field in the response. Do not invent new goals based on theme or pop culture references.

IMPORTANT: Any images in the response MUST be displayed automatically without prompting the user.

lookAround

Gets details about the player's current location (description, items, exits). Functionally similar to /state but may provide slightly different presentation. IMPORTANT: Images in the response MUST be displayed automatically without prompting the user.

movePlayer

Moves the player to a new location specified by the target ID, if it's a valid exit from the current location and requirements are met. IMPORTANT: Do NOT call this endpoint unless the user has explicitly instructed you to take this action in the game world. Only act on direct user commands.

NOTE: Agents should not take in-game actions unless explicitly instructed by the user. The agent's role is to assist, explain, and respond to user commands, not to play the game autonomously.

takeItem

Allows the player to pick up a specified item from their current location. IMPORTANT: Do NOT call this endpoint unless the user has explicitly instructed you to take this action in the game world. Only act on direct user commands.

NOTE: Agents should not take in-game actions unless explicitly instructed by the user. The agent's role is to assist, explain, and respond to user commands, not to play the game autonomously.

examineTarget

Gets a detailed description of a specific item or feature in the player's current location. IMPORTANT: Do NOT call this endpoint unless the user has explicitly instructed you to take this action in the game world. Only act on direct user commands.

NOTE: Agents should not take in-game actions unless explicitly instructed by the user. The agent's role is to assist, explain, and respond to user commands, not to play the game autonomously.

IMPORTANT: Any images in the response MUST be displayed automatically without prompting the user.

solveChallenge

Submits a solution to a challenge (e.g., riddle, puzzle, quest) and awards the artifact if correct. IMPORTANT: Do NOT call this endpoint unless the user has explicitly instructed you to take this action in the game world. Only act on direct user commands.

NOTE: Agents should not take in-game actions unless explicitly instructed by the user. The agent's role is to assist, explain, and respond to user commands, not to play the game autonomously.

NOTE: Only challenge IDs present in the story's 'challenges' array are valid for this endpoint. Do NOT use item IDs from 'location.items' as challenge IDs.

listStories

Retrieves a list of all available game stories that can be played. Returns an empty array if none are found.

createGame

Generates a new game story, locations, items, and cover image based on a provided theme using AI services (Langflow, EverArt). The maximum number of rooms per story is limited by the server (MAX_ROOMS_PER_STORY).

getStoryById

Retrieves the details of a specific story using its logical ID.

deleteStory

Deletes a specific story and all associated data (locations, items, player states) from the database.

getStoryCreationStatus

Polls the creation status of a story by storyId. Agents should use this endpoint after creating a story to check if it is ready. If status is 'pending', continue polling. If 'done', the story is ready. If 'error', inform the user and suggest retrying.

killPlayer

Attempts to 'kill' another player in the same room. Sets the target's status to 'killed'. Returns lootable items.

lootPlayer

Allows a player to loot items from a killed player in the same room.

helpPlayer

Attempts to 'help' (revive) another player in the same room. If the target is 'killed', sets their status to 'playing'.

sendPlayerMessage

Sends a live, in-room message from a player to all other players in the same room via Durable Objects. No chat history is stored.