MCP MUD Game

A classic Multi-User Dungeon (MUD) game designed specifically for AI agent interaction through the Model Context Protocol (MCP). This project allows AI agents to play characters in a dynamically generated dungeon environment, complete with RPG mechanics, combat, and exploration.

Features

Core Game Systems

• Full RPG Character System: Classes (Warrior, Mage, Rogue, Cleric) with stats, levels, and progression
• Dynamic Dungeon Generation: AI-powered Dungeon Master creates rooms, encounters, and puzzles
• Turn-based Combat: D&D-style combat with dice rolling, attack rolls, and damage calculation
• Spell System: Class-specific spells with mana costs and various effects
• Skill Checks: Strength, Dexterity, Intelligence checks for interacting with the environment
• Inventory Management: Equipment, weapons, armor, and consumable items

Technical Architecture

• MCP Server: Provides tools for AI agents to interact with the game
• RabbitMQ: Message queue system for turn-based action processing
• DynamoDB: Persistent storage for characters, rooms, and game state
• n8n Agents: AI agents running in Docker containers as players and DM
• Ollama: Local LLM for AI decision making

Quick Start

Prerequisites

• Docker and Docker Compose
• Git

Installation

1. Clone the repository

   git clone <repository-url>
   cd mcp-mud-game

2. Run the setup script

   chmod +x scripts/setup.sh
   ./scripts/setup.sh

3. Start the game server

   docker-compose up -d mcp-mud-server

4. Start AI agents

   docker-compose up -d n8n-player1 n8n-player2 n8n-dm

Access Points

• MCP Server: localhost:8080
• RabbitMQ Management: http://localhost:15672 (guest/guest)
• n8n Player 1: http://localhost:5679 (player1/player1)
• n8n Player 2: http://localhost:5680 (player2/player2)
• n8n Dungeon Master: http://localhost:5681 (dm/dm)
• Ollama API: http://localhost:11434

Game Mechanics

Character Classes

Warrior

• Primary Stat: Strength
• Skills: Melee Combat, Shield Bash, Intimidate
• Starting Equipment: Iron Sword, Leather Armor, Wooden Shield

Mage

• Primary Stat: Intelligence
• Skills: Fireball, Magic Missile, Arcane Knowledge
• Starting Equipment: Wooden Staff, Mage Robes, Spell Components

Rogue

• Primary Stat: Dexterity
• Skills: Lockpicking, Stealth, Backstab
• Starting Equipment: Dagger, Lockpicks, Leather Armor

Cleric

• Primary Stat: Wisdom
• Skills: Heal, Turn Undead, Divine Favor
• Starting Equipment: Mace, Chain Mail, Holy Symbol

Combat System

Combat uses D&D-style mechanics:

• Attack Rolls: d20 + attack bonus vs. armor class
• Damage: Weapon damage dice + stat modifier
• Critical Hits: Natural 20 doubles damage
• Critical Misses: Natural 1 always misses

Skill Checks

Skill checks use the following difficulty classes:

• Trivial: DC 5
• Easy: DC 10
• Medium: DC 15
• Hard: DC 20
• Epic: DC 25
• Legendary: DC 30

MCP Tools

Player Actions

Character Management

• create_character(player_id, name, character_class) - Create a new character
• get_character_status(player_id) - Get character stats and status
• rest_character(player_id) - Rest to recover health and mana

Movement and Exploration

• move_character(player_id, direction) - Move in a direction
• examine_object(player_id, target) - Examine rooms, items, or creatures

Combat and Actions

• attack_target(player_id, target, weapon?) - Attack a monster
• cast_spell(player_id, spell_name, target?) - Cast a spell
• use_item(player_id, item_name, target?) - Use an inventory item
• attempt_skill_check(player_id, skill_type, target?) - Perform skill checks

Dungeon Master Tools

• generate_room(theme, difficulty, connections?) - Create new rooms
• add_encounter(room_id, encounter_type) - Add monsters, traps, or puzzles
• update_room_description(room_id, new_description) - Modify room descriptions
• create_custom_ability(name, description, mechanics) - Create new abilities
• get_dungeon_overview() - View current dungeon state

Architecture Details

Database Schema (DynamoDB)

Players Table

• player_id (Hash Key)
• Character data, stats, inventory, location

Rooms Table

• room_id (Hash Key)
• Room description, exits, items, monsters, puzzles

Game State Table

• game_id (Hash Key)
• Turn order, active sessions, global state

Action Queue Table

• action_id (Hash Key)
• timestamp (GSI)
• Pending actions with priorities

Message Queues (RabbitMQ)

• Actions Queue: Player actions waiting for processing
• DM Queue: Requests for content generation
• Events Queue: Game events and notifications
• Turn Resolution: Ordered action processing

Development

Project Structure

mcp-mud-game/
├── mcp_server.py          # Main MCP server
├── game_engine.py         # Core game logic
├── character_system.py    # RPG character mechanics
├── dungeon_manager.py     # Dynamic content generation
├── action_processor.py    # RabbitMQ action handling
├── database_manager.py    # DynamoDB operations
├── dice_system.py         # Dice rolling and skill checks
├── config.py             # Game configuration
├── docker-compose.yml    # Full stack deployment
├── workflows/            # n8n workflow templates
├── scripts/              # Setup and utility scripts
└── docker/              # Docker configurations

Adding New Features

1. New MCP Tools: Add to mcp_server.py and implement in game_engine.py
2. New Character Classes: Update config.py and character_system.py
3. New Room Types: Add to dungeon_manager.py room templates
4. New Spells/Abilities: Update spell databases in game_engine.py

Configuration

Edit config.py to modify:

• Character class definitions
• Difficulty classes
• Room themes and generation parameters
• Database and queue settings

AI Agent Integration

n8n Workflows

The project includes pre-built n8n workflows for:

• Player Agents: Autonomous character control
• Dungeon Master: Dynamic content generation
• Shared Nodes: Reusable MCP communication components

Ollama Integration

AI agents use local Ollama models for decision making:

• Character action selection
• Dungeon Master creativity
• Narrative generation
• Problem solving

Troubleshooting

Common Issues

1. Services not starting: Check Docker daemon and port availability
2. Database connection errors: Ensure DynamoDB Local is running
3. RabbitMQ connection issues: Verify RabbitMQ container status
4. Ollama model not found: Run docker exec ollama ollama pull llama3.2

Logs

View logs for debugging:

docker-compose logs mcp-mud-server
docker-compose logs rabbitmq
docker-compose logs ollama

Contributing

1. Fork the repository
2. Create a feature branch
3. Implement changes with tests
4. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with the Model Context Protocol (MCP)
• Inspired by classic MUD games
• Uses D&D-style mechanics for familiarity
• Designed for AI agent interaction and automation