Dungeon MCP Server

🚀 Dungeon MCP Server

The Dungeon MCP Server is a Model Context Protocol (MCP) server that offers a text - based dungeon crawling adventure system. Through a set of MCP tools, players can explore mystical dungeons, interact with NPCs, collect treasures, and battle monsters.

🚀 Quick Start

To start using the Dungeon MCP Server, you can run the server with default settings using the following command:

./mcp-dungeon

✨ Features

• Dungeon Exploration: Navigate through interconnected rooms and corridors.
• Interactive Elements: Encounter NPCs, treasures, and monsters in various locations.
• Player Management: Load/save player data from YAML files.
• Visual Map Display: View an ASCII art representation of the entire dungeon.
• RESTful API: An HTTP server with MCP protocol support.
• Customizable: Support for custom dungeon and player configurations.

📦 Installation

There is no specific installation process described in the original document. If you have the source code, you can run the server directly following the usage instructions.

💻 Usage Examples

Command Line Interface

The server supports several CLI parameters using the Fang library for enhanced user experience:

./mcp-dungeon [OPTIONS]

CLI Parameters

Examples

# Start server with default settings
./mcp-dungeon

# Start with custom player and port
./mcp-dungeon --player-file my_player.yaml --port 8080

# Use a different dungeon file
./mcp-dungeon --dungeon-file my_dungeon.yaml

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

# Show help
./mcp-dungeon --help

Server Endpoints

Once started, the server provides the following endpoints:

• MCP Endpoint: http://localhost:PORT/mcp - Main MCP protocol endpoint
• Health Check: http://localhost:PORT/health - Server health status

📚 Documentation

Player Configuration

Player YAML Format

Look for the player configuration in templates/player_sample.yaml.

Generating Sample Player

To create a sample player configuration:

./mcp-dungeon --generate-player

This creates player_sample.yaml with default values.

Dungeon Configuration

Dungeon YAML Format

The dungeon configuration is defined in a YAML file, typically templates/crystal_caverns.yaml.

MCP Tools

The server provides the following MCP tools:

Basic Usage

1. say_hello

Say hello to a user.

{
  "name": "say_hello",
  "arguments": {
    "name": "Alice"
  }
}

Parameters:

• name (string, required): The name of the user to greet

Advanced Usage

2. get_room_details_by_name

Get detailed information about a room by its name/ID.

{
  "name": "get_room_details_by_name",
  "arguments": {
    "room_name": "entrance_cave"
  }
}

Parameters:

• room_name (string, required): The name/ID of the room

3. get_room_details_by_coordinates

Get detailed information about a room by its coordinates.

{
  "name": "get_room_details_by_coordinates",
  "arguments": {
    "x": 2,
    "y": 5
  }
}

Parameters:

• x (number, required): The X coordinate
• y (number, required): The Y coordinate

4. move_to_room_by_name

Move the player to a specified room by name. Only allows movement to connected rooms.

{
  "name": "move_to_room_by_name",
  "arguments": {
    "target_room": "corridor_1"
  }
}

Parameters:

• target_room (string, required): The name/ID of the target room

5. get_player_status

Get the current status and information of the player.

{
  "name": "get_player_status",
  "arguments": {}
}

Parameters: None

6. display_dungeon_map

Display an ASCII map of the entire dungeon showing rooms, corridors, and the player's current position.

{
  "name": "display_dungeon_map",
  "arguments": {}
}

Parameters: None

🔧 Technical Details

Game Mechanics

Movement Rules

• Players can only move to rooms that are directly connected to their current location.
• Movement is validated against the dungeon's connection graph.
• Player coordinates are automatically updated when moving.

Room Types

1. Rooms: Can contain NPCs, treasures, monsters, or items.
2. Corridors: Connecting passages between rooms.
3. Entrance: Starting location for players.
4. Exit: Goal location to complete the dungeon.

Location Elements

• NPCs: Non - player characters with names and descriptions.
• Treasures: Valuable items with gold values.
• Monsters: Enemies with difficulty levels and hit points.
• Items: Consumables like healing potions.

Testing

Test scripts are provided for manual testing:

cd tests
# Test room details
./room.tool.call.sh

# Test player movement
./move.tool.call.sh

# Test player status
./status.tool.call.sh

📄 Troubleshooting

Common Issues

1. Session ID Missing: Ensure you include the Mcp - Session - Id header.
2. Invalid Room Movement: Check room connections in dungeon YAML.
3. Port Already in Use: Change the port with --port parameter.
4. File Not Found: Verify file paths for dungeon and player files.

Health Check

Verify the server is running:

curl http://localhost:9090/health

Expected response:

{
  "status": "healthy",
  "dungeon_name": "Dungeon of Crystal Caverns"
}