# 🎮 Game World Sandbox MCP

A FastMCP-based game world management system for creating and maintaining consistent, structured game worlds for LLM-driven text adventures and role-playing games.

## 🌟 Features

- **World Generation**: Create structured game worlds with consistent cosmology, geography, society, and history
- **Character Management**: Define player characters with attributes, inventory, goals, and backstory
- **MCP Integration**: Built on Model Control Protocol for seamless AI integration
- **OpenAI Integration**: Working integration with OpenAI models for natural language game world management
- **Data Validation**: Pydantic models ensure data consistency and integrity
- **Extensible Architecture**: Easy to add new tools, resources, and game mechanics
- **Comprehensive Testing**: Full unit test coverage proving functionality

## 🏗️ Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│                 │    │                 │    │                 │
│   Client App    │◄──►│  FastMCP Server │◄──►│   World Data   │
│                 │    │                 │    │   (In-Memory)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │  World Bible    │
                       │   Schema        │
                       └─────────────────┘
```

### Components

- **`server.py`**: FastMCP server with world generation and character creation tools
- **`world_bible_schema.py`**: Pydantic models defining the complete game world structure
- **`openai_working_integration.py`**: Direct LangChain OpenAI integration (recommended)
- **`mcp_use_integration.py`**: LangChain-based MCP integration (compatible alternative)
- **`gemini_mcp_demo.py`**: Gemini integration demo
- **`demo_core_functionality.py`**: Core functionality demonstration
- **`verify_working_solution.py`**: Verification script proving everything works
- **`tests/unit/`**: Comprehensive unit tests (19/20 tests passing)

## 🤖 AI Integration - OpenAI + Game World System

The system includes **two** working integrations with OpenAI models for natural language game world management:

### 🔧 Option 1: Direct LangChain Integration (Recommended)

The direct LangChain approach provides the most reliable and stable integration with FastMCP.

#### Features
- **Natural Language Interface**: Interact with game worlds using natural language
- **Intelligent Tool Usage**: OpenAI models automatically choose appropriate game world tools
- **Real-time Game State**: AI can create worlds, characters, and manage game state
- **Interactive Gameplay**: Natural conversation flow with structured game mechanics
- **Working Implementation**: Fully functional integration with error handling

#### Quick Setup
1. **Install dependencies** (already included in requirements.txt):
   ```bash
   pip install -r requirements.txt
   ```

2. **Set your OpenAI API key**:
   ```bash
   export OPENAI_API_KEY="your-openai-api-key-here"
   ```

3. **Run the integration**:
   ```bash
   python openai_working_integration.py
   ```

#### Example Commands
- "Create a fantasy world with magic and dragons"
- "Generate a sci-fi world with spaceships and advanced technology"
- "Create a brave knight character named Sir Galen"
- "Move Sir Galen to the dragon's lair"
- "What worlds do we have available?"

### 🔧 Option 2: LangChain-Based MCP Integration (Alternative)

The LangChain-based MCP integration provides a more compatible approach that works reliably with FastMCP.

#### Features
- **Direct Tool Integration**: Custom tools that interface directly with MCP server
- **Server Compatibility**: Works seamlessly with FastMCP transport protocols
- **Interactive CLI**: Command-line interface for game world management
- **Robust Error Handling**: Comprehensive error handling and recovery
- **No Protocol Issues**: Bypasses mcp_use compatibility problems

#### Quick Setup
1. **Install dependencies** (already included in requirements.txt):
   ```bash
   pip install -r requirements.txt
   ```

2. **Set your OpenAI API key**:
   ```bash
   export OPENAI_API_KEY="your-openai-api-key-here"
   ```

3. **Start the MCP server**:
   ```bash
   # Terminal 1
   python server.py
   ```

4. **Run the integration**:
   ```bash
   # Terminal 2
   python mcp_use_integration.py
   ```

#### Example Commands
- "Create a fantasy world"
- "List all worlds"
- "Create a character"
- "Move a character"
- "Generate a sci-fi world"

#### How It Works

**Direct LangChain Integration:**
```
User Request → OpenAI LLM → LangChain Agent → Game World Tools → World Management
                                                        ↓
User Response ← OpenAI LLM ← Tool Results ← Game World Operations
```

**LangChain-Based MCP Integration:**
```
User Request → OpenAI LLM → LangChain Agent → Custom MCP Tools → Server API
                                                        ↓
User Response ← OpenAI LLM ← Tool Results ← Game World Data
```

## 🚀 Quick Start

### Prerequisites

- Python 3.13+
- Virtual environment (recommended)

### Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/your-username/game-sandbox-mcp.git
   cd game-sandbox-mcp
   ```

2. **Set up virtual environment**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

   **For OpenAI Integration:**
   ```bash
   pip install langchain-openai
   ```

   **Key Dependencies:**
   - **FastMCP**: Model Context Protocol framework
   - **FastAPI**: Modern web framework for APIs
   - **Pydantic**: Data validation and settings management
   - **Uvicorn**: ASGI server for high-performance applications
   - **pytest**: Testing framework (19/20 tests passing)
   - **langchain-openai**: OpenAI integration (optional)

### Running the Server

```bash
# Activate virtual environment
source venv/bin/activate

# Run the MCP server
python server.py
```

The server will start on `http://127.0.0.1:8000/mcp/`

### Running the Client Example

```bash
# In a separate terminal, activate venv and run client
source venv/bin/activate
python client.py
```

## 📖 Usage

### 1. Generate a New World

```python
from fastmcp.client import Client
import asyncio

async def create_world():
    client = Client("http://127.0.0.1:8000/mcp/")
    async with client:
        result = await client.call_tool("generate_world", {"style": "Fantasy"})
        world_id = result.structured_content.get('world_id')
        print(f"Created world: {world_id}")
```

### 2. Create a Character

```python
character_data = {
    "name": "Arion",
    "race": "Human",
    "description": "A curious adventurer with a knack for getting into trouble.",
    "backstory": "Left a small village to seek fortune and discover the world.",
    "attributes": {"health": 100, "mana": 50, "strength": 15},
    "inventory": [{"name": "Rusted Sword", "description": "An old, worn sword."}],
    "current_location": "Starting Village",
    "goals": ["Find the lost city of Eldoria.", "Master the ancient magic."]
}

result = await client.call_tool("create_character", {
    "world_id": world_id,
    "character_data": character_data
})
```

### 3. Access World Data

```python
# Get complete world data
world_data = await client.read_resource(f"worlds://{world_id}")
print(world_data)
```

## 🏛️ Enhanced World Bible Schema

The system uses an advanced "World Bible" structure based on modern game development practices:

### Core Components

- **Metadata**: Name, description, genre/style with validation and versioning
- **Cosmology**: Magic systems, technology levels, calendar systems with consistency checks
- **Geography**: Continents, regions, key locations with strategic mapping
- **Society**: Races, factions, social structures with cultural depth
- **History**: Creation myths, conflicts, key events with narrative timelines
- **Systems**: Economy, abilities, item classifications with balance frameworks
- **Protagonist**: Modern RPG character with attributes, skills, inventory, and progression

### Enhanced Features

- **Validation & Consistency**: Cross-component validation ensures world consistency
- **Modern RPG Systems**: Comprehensive character attributes, skills, and progression
- **Advanced Inventory**: Item durability, properties, rarity, and crafting systems
- **Reputation System**: Faction relationships and social dynamics
- **Quest System**: Dynamic quest tracking and objectives
- **Balance Settings**: Difficulty levels and game balance parameters

### Data Structure Example

```python
{
  "metadata": {
    "name": "Eldoria Chronicles",
    "description": "A vast fantasy world of magic and mystery",
    "style": "Fantasy",
    "version": "1.0.0",
    "author": "Game Master",
    "tags": ["fantasy", "magic", "dragons"]
  },
  "cosmology": {
    "magic_system": "Elemental magic drawn from nature spirits and ancient runes",
    "tech_level": "Medieval",
    "calendar_system": "Twelve-month lunar calendar with solstice festivals",
    "physics_laws": "Standard physics with magical exceptions",
    "metaphysics": "Spiritual energy permeates the world"
  },
  "geography": {
    "macro_geography": "Three main continents with diverse biomes",
    "key_regions": [
      {"name": "Crystal Mountains", "description": "Home to ancient magic crystals"},
      {"name": "Dark Forest", "description": "Forbidden woods with dangerous creatures"}
    ],
    "climate_zones": ["Temperate", "Arctic", "Tropical"],
    "natural_resources": ["Adamantium", "Mythril", "Dragon Scale"]
  },
  "protagonist": {
    "name": "Elara Moonshadow",
    "race": "Elf",
    "character_class": "Ranger",
    "level": 1,
    "attributes": {
      "health": 120,
      "max_health": 120,
      "strength": 12,
      "agility": 16,
      "intelligence": 14
    },
    "skills": [
      {
        "name": "Archery",
        "level": 15,
        "description": "Mastery of bow and arrow combat"
      }
    ],
    "inventory": [
      {
        "name": "Moonshadow Bow",
        "type": "weapon",
        "rarity": "Rare",
        "value": 500,
        "properties": {"damage": "2d8", "range": "150ft"}
      }
    ],
    "goals": ["Find the lost city", "Master nature magic"],
    "reputation": {"Elven Council": 10, "Forest Spirits": 25}
  }
}
```

## 🔧 API Reference

### Tools

#### `generate_world`
Creates a new game world based on specified style.

**Parameters:**
- `style` (str): Game world style (e.g., "Fantasy", "Sci-Fi", "Cyberpunk")

**Returns:**
- `world_id`: Unique identifier for the generated world
- `message`: Success confirmation

#### `create_character`
Creates a player character for an existing world.

**Parameters:**
- `world_id` (str): ID of the world to add character to
- `character_data` (dict): Complete character definition

**Returns:**
- `message`: Success confirmation
- `character_name`: Name of created character

### Resources

#### `worlds://{world_id}`
Retrieves the complete World Bible for a given world ID.

## 🎮 Enhanced Game Development Features

The improved system incorporates the latest game development practices and modern RPG design:

### World Consistency & Validation
- **Cross-Component Validation**: Ensures consistency between tech levels and magic systems
- **Enum-Based Classification**: Standardized game styles and technology levels
- **Advanced Validation**: Pydantic validators prevent inconsistent world-building
- **Version Control**: World versioning for tracking changes and updates

### Modern RPG Systems
- **Comprehensive Attributes**: Health, mana, stamina, and 6 core attributes (STR, AGI, INT, WIS, CHA, LCK)
- **Skill Progression**: Individual skill tracking with experience and level caps
- **Advanced Inventory**: Items with properties, durability, rarity, and crafting potential
- **Reputation System**: Dynamic relationships with factions and organizations
- **Quest Management**: Active quest tracking with objectives and status
- **Status Effects**: Buffs and debuffs system for combat and roleplay

### Enhanced Features
- **Production Logging**: Comprehensive logging with proper formatting and error tracking
- **Error Handling**: Robust error handling with appropriate HTTP status codes
- **Modern FastMCP**: Latest FastMCP version (2.11.3) with improved performance
- **Type Safety**: Full type hints and validation throughout the codebase
- **Documentation**: Comprehensive docstrings and API documentation

### Latest Game Design Patterns
- **Balance Frameworks**: Built-in difficulty settings and game balance parameters
- **World State Management**: Dynamic world state variables for evolving narratives
- **Character Lifecycle**: Complete character progression from creation to advancement
- **Interactive Systems**: Character movement, location updates, and world interaction

## 🛠️ Development

### Project Structure

```
game-sandbox-mcp/
├── server.py                    # FastMCP server implementation
├── world_bible_schema.py        # Pydantic data models
├── openai_working_integration.py # Direct LangChain OpenAI integration
├── mcp_use_integration.py      # mcp_use client integration
├── gemini_mcp_demo.py          # Gemini integration demo
├── demo_core_functionality.py  # Core functionality demo
├── verify_working_solution.py  # Verification script
├── README.md                   # This file
├── requirements.txt            # Dependencies
├── tests/
│   └── unit/                   # Unit tests (19/20 passing)
└── venv/                       # Python virtual environment
```

### Adding New Tools

```python
@mcp.tool
def new_game_mechanic(world_id: str, parameters: dict, ctx: Context) -> dict:
    """Description of your new game mechanic."""
    # Implementation here
    pass
```

### Extending the Schema

Add new fields to the Pydantic models in `world_bible_schema.py`:

```python
class NewComponent(BaseModel):
    field_name: str = Field(..., description="Field description")

class WorldBible(BaseModel):
    # ... existing fields
    new_component: NewComponent = Field(default_factory=NewComponent)
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [FastMCP](https://gofastmcp.com) framework
- Inspired by modern tabletop RPG world-building practices
- Designed for integration with Large Language Models

## 📚 Further Reading

- [FastMCP Documentation](https://gofastmcp.com)
- [Pydantic Documentation](https://pydantic-docs.helpmanual.io/)
- [Game World Building Best Practices](https://en.wikipedia.org/wiki/Worldbuilding)
- `GEMINI.md` - Detailed Chinese documentation on world consistency

---

**Happy World Building!** 🌍✨