Dungeon

You can run a text-based dungeon adventure server that exposes an MCP interface for clients to explore rooms, interact with NPCs, find treasures, and battle monsters. It includes an ASCII dungeon map, YAML-based player and dungeon configurations, and RESTful MCP endpoints you can query from any MCP client.

How to use

Start the server using the built-in CLI. The MCP endpoint is available at the MCP URL, and a health check endpoint lets you verify the server is running. You can interact with the dungeon and player data through the provided MCP tools and endpoints.

How to install

Prerequisites: ensure you have a runtime capable of executing the server binary. No additional runtime installation steps are shown here.

1. Download or build the dungeon MCP server binary if you have a prebuilt artifact. 2) Place your dungeon YAML file in an accessible location. 3) Place your player YAML file if you have a custom player profile. 4) Run the server CLI to start the MCP server.

./mcp-dungeon

# Start with a custom dungeon file and port, if desired
./mcp-dungeon --dungeon-file my_dungeon.yaml --port 8080

# Generate a sample player file for quick starts
./mcp-dungeon --generate-player --player-file hero.yaml

# Start with a custom player file as well
./mcp-dungeon --player-file hero.yaml --port 8080

Additional configuration and endpoints

Server endpoints you can query from clients are available after the server starts. Use the MCP endpoint for protocol requests and the health endpoint to verify status.

MCP Endpoint: http://localhost:9090/mcp
Health Check: http://localhost:9090/health

Available tools

say_hello

Say hello to a user with a simple greeting and optional name. Useful for testing connectivity and basic interaction.

get_room_details_by_name

Fetch detailed information about a specific room by its name or ID to present to the player.

get_room_details_by_coordinates

Retrieve room details based on x and y coordinates to support map exploration and location recall.

move_to_room_by_name

Move the player to a connected room by specifying the target room name or ID, enforcing dungeon connectivity rules.

get_player_status

Obtain the current status and attributes of the controlled player, including position and health.

display_dungeon_map

Render an ASCII map showing all rooms, corridors, and the player's current position for quick orientation.