Upload 195 files

Tempus .... fugit.
Refactored version.

.gitattributes

@@ -33,3 +33,6 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+tests/unit/services/__pycache__/test_npc_service_corrected.cpython-313-pytest-8.3.5.pyc filter=lfs diff=lfs merge=lfs -text
+tests/unit/services/__pycache__/test_npc_service_fixed.cpython-313-pytest-8.3.5.pyc filter=lfs diff=lfs merge=lfs -text
+tests/unit/services/__pycache__/test_npc_service.cpython-313-pytest-8.3.5.pyc filter=lfs diff=lfs merge=lfs -text

DEVELOPER_DOCUMENTATION.md

@@ -0,0 +1,189 @@
+# 🛠️ MMORPG with MCP Integration - Developer Documentation
+
+## 📖 Table of Contents
+
+1.  [Introduction](#introduction)
+2.  [Project Setup](#project-setup)
+3.  [Architecture Overview](#architecture-overview)
+4.  [MCP API Reference](#mcp-api-reference)
+    *   [Connection](#connection)
+    *   [Available Tools/Commands](#available-toolscommands)
+    *   [Common Operations](#common-operations)
+5.  [Extending the Game](#extending-the-game)
+    *   [NPC Add-on Development](#npc-add-on-development)
+    *   [Adding New Game Mechanics](#adding-new-game-mechanics)
+6.  [AI Agent Integration](#ai-agent-integration)
+7.  [Debugging](#debugging)
+
+---
+
+## 📜 Introduction
+
+This document provides technical guidance for developers working on the **MMORPG with MCP Integration** project. It covers project setup, architecture, API usage for client/agent development, and how to extend the game's functionalities.
+
+---
+
+## ⚙️ Project Setup
+
+### Prerequisites
+*   Python 3.8 or higher
+*   `pip` for package management
+
+### Getting the Code
+Clone the repository to your local machine (if you haven't already).
+
+### Installation
+1.  Navigate to the project directory (e.g., `c:\Users\Chris4K\Projekte\projecthub\projects\MMOP_second_try`).
+    ```powershell
+    cd c:\Users\Chris4K\Projekte\projecthub\projects\MMOP_second_try
+    ```
+2.  Install the required Python dependencies:
+    ```bash
+    pip install gradio mcp aiohttp asyncio
+    ```
+    (Ensure other project-specific dependencies from your `requirements.txt` are also installed).
+
+### Running the Game Server
+Execute the main application file (assumed to be `app.py` in the root of `MMOP_second_try`):
+```bash
+python app.py
+```
+The server should start, typically making the Gradio UI available at `http://127.0.0.1:7868` and the MCP SSE endpoint at `http://127.0.0.1:7868/gradio_api/mcp/sse`.
+
+---
+
+## 🏗️ Architecture Overview (High-Level)
+
+*   **Game Server (`app.py`)**: The main entry point. Initializes and runs the Gradio web interface, integrates game components, and likely hosts the MCP endpoint.
+*   **Game Engine (`src/core/game_engine.py`)**: Contains the core game logic, manages world state, player data, NPC interactions, and game rules.
+*   **UI Layer (`src/ui/interface_manager.py`, `src/ui/huggingface_ui.py`)**: Manages the Gradio user interface, defining layouts, components, and event handling for human players.
+*   **MCP Integration Layer**: A facade or service within the server that exposes game functionalities to MCP clients. This allows AI agents or other external systems to interact with the game.
+*   **NPC Addons**: Modular components that extend NPC functionalities. See `NPC_Addon_Development_Guide.md`.
+
+---
+
+## 🔌 MCP API Reference
+
+The game server exposes its functionalities via the Model Context Protocol (MCP), allowing external clients (like AI agents or custom tools) to interact with the game world programmatically.
+
+### Connection
+*   **Endpoint URL**: `http://127.0.0.1:7868/gradio_api/mcp/sse` (for Server-Sent Events)
+*   **Protocol**: MCP over SSE.
+*   **Client Implementation**: Refer to `simple_game_client.py` for a reference Python client. It uses `mcp.ClientSession` and `mcp.client.sse.sse_client`.
+
+**Example Connection Snippet (from `simple_game_client.py`):**
+```python
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from contextlib import AsyncExitStack
+import asyncio
+
+class GameClient:
+    def __init__(self, server_url="http://127.0.0.1:7868/gradio_api/mcp/sse"):
+        self.server_url = server_url
+        self.session = None
+        self.exit_stack = AsyncExitStack()
+        self.connected = False
+        self.tools = []
+
+    async def connect(self):
+        try:
+            transport = await self.exit_stack.enter_async_context(
+                sse_client(self.server_url)
+            )
+            read_stream, write_callable = transport
+            self.session = await self.exit_stack.enter_async_context(
+                ClientSession(read_stream, write_callable)
+            )
+            await self.session.initialize()
+            response = await self.session.list_tools()
+            self.tools = response.tools
+            self.connected = True
+            print(f"✅ Connected! Available tools: {[tool.name for tool in self.tools]}")
+            return True
+        except Exception as e:
+            print(f"❌ Connection failed: {e}")
+            return False
+
+    async def disconnect(self):
+        if self.connected:
+            await self.exit_stack.aclose()
+            self.connected = False
+            print("🔌 Disconnected.")
+```
+
+### Available Tools/Commands
+Upon connection, the client can list available tools (commands) from the server. Common tools exposed by the MMORPG server typically include:
+
+*   `register_ai_agent` (or similar): To join the game as a new player/agent.
+*   `move_agent` (or similar): To move the player/agent in the game world.
+*   `send_chat_message` (or similar): To send messages to the public game chat.
+*   `interact_with_npc` (or similar): To send messages or commands to specific NPCs.
+*   `get_game_state` (or similar): To retrieve information about the current game world, other players, etc.
+
+The exact names and parameters of these tools are defined by the server-side MCP implementation. Use `session.list_tools()` to get the current list and `tool.parameters_json_schema` for expected inputs.
+
+### Common Operations
+
+**1. Registering a Player/Agent:**
+*   **Tool**: Look for a tool like `register_ai_agent`.
+*   **Parameters**: Typically `player_name` (string) and `client_id` (string, unique identifier for the client).
+*   **Response**: Often includes an `agent_id` or `player_id` assigned by the server.
+
+**2. Moving a Player/Agent:**
+*   **Tool**: Look for a tool like `move_agent`.
+*   **Parameters**: `agent_id` (string) and `direction` (string, e.g., "north", "south", "east", "west", "up", "down").
+*   **Response**: Confirmation of movement, new coordinates, or error if movement is not possible.
+
+**3. Sending Chat Messages:**
+*   **Tool**: Look for a tool like `send_chat_message`.
+*   **Parameters**: `agent_id` (string) and `message` (string).
+*   **Response**: Confirmation that the message was sent.
+
+**4. Interacting with NPCs:**
+*   **Tool**: Look for a tool like `interact_with_npc`.
+*   **Parameters**: `agent_id` (string), `npc_id` (string), and `message` or `command` (string).
+*   **Response**: NPC's reply or result of the interaction.
+
+**5. Getting Game State:**
+*   **Tool**: Look for a tool like `get_game_state`.
+*   **Parameters**: May include `agent_id` (string) or be parameterless.
+*   **Response**: JSON object containing game world information, list of players, NPCs, etc.
+
+---
+
+## 🧩 Extending the Game
+
+### NPC Add-on Development
+For creating new NPCs with custom behaviors and UI components, please refer to the **`NPC_Addon_Development_Guide.md`**. It provides a comprehensive, up-to-date guide covering the modern auto-registration system, working examples from the codebase, and best practices.
+
+### Adding New Game Mechanics
+To introduce new core game mechanics:
+1.  **Game Engine (`src/core/game_engine.py`):** Implement the fundamental logic for the new mechanic here. This might involve modifying player states, world interactions, or introducing new entities.
+2.  **Facade Layer:** If the mechanic needs to be exposed to the UI or MCP clients, update or create methods in your game facade (e.g., `src/facades/game_facade.py`) to provide a clean interface to the engine's functionality.
+3.  **UI Integration (`src/ui/interface_manager.py`):** If human players should interact with this mechanic, add new UI elements and event handlers in the Gradio interface.
+4.  **MCP Exposure:** If AI agents or external clients should use this mechanic, expose the relevant facade methods as new MCP tools.
+
+---
+
+## 🤖 AI Agent Integration
+
+AI agents can connect to the MMORPG as players using an MCP client (like the one shown in `simple_game_client.py`).
+1.  **Connection**: The agent connects to the MCP SSE endpoint.
+2.  **Registration**: The agent registers itself, providing a name.
+3.  **Interaction**: The agent uses the available MCP tools to perceive the game state (`get_game_state`), move (`move_agent`), chat (`send_chat_message`), and interact with NPCs (`interact_with_npc`).
+4.  **Decision Making**: The agent's internal logic processes game state information and decides on actions to take.
+
+The `simple_game_client.py` script serves as a foundational example for building more sophisticated AI agents.
+
+---
+
+## 🐞 Debugging
+
+*   **Server Logs**: Check the console output where `python app.py` is running for server-side errors, print statements, and game event logs.
+*   **Gradio UI**: Use your web browser's developer tools (especially the console) to debug issues related to the Gradio interface and JavaScript (like the keyboard control script).
+*   **MCP Client-Side**: Add extensive logging in your MCP client to trace requests sent to the server and responses received. Print the full content of MCP tool calls and results.
+*   **Game State Dumps**: Periodically use the `get_game_state` MCP tool (if available) or implement a debug feature to dump the current game state to understand the situation from the server's perspective.
+*   **Incremental Testing**: When developing new features or MCP tools, test them incrementally.
+
+---

Documentation/DEVELOPER_DOCUMENTATION.md

@@ -0,0 +1,210 @@
+# 🛠️ MMORPG with MCP Integration - Developer Documentation
+
+## 📖 Table of Contents
+
+1.  [Introduction](#introduction)
+2.  [Project Setup](#project-setup)
+3.  [Architecture Overview](#architecture-overview)
+4.  [MCP API Reference](#mcp-api-reference)
+    *   [Connection](#connection)
+    *   [Available Tools/Commands](#available-toolscommands)
+    *   [Common Operations](#common-operations)
+5.  [Extending the Game](#extending-the-game)
+    *   [NPC Add-on Development](#npc-add-on-development)
+    *   [Adding New Game Mechanics](#adding-new-game-mechanics)
+6.  [AI Agent Integration](#ai-agent-integration)
+7.  [Debugging](#debugging)
+
+---
+
+## 📜 Introduction
+
+This document provides technical guidance for developers working on the **MMORPG with MCP Integration** project. It covers project setup, architecture, API usage for client/agent development, and how to extend the game's functionalities.
+
+---
+
+## ⚙️ Project Setup
+
+### Prerequisites
+*   Python 3.8 or higher
+*   `pip` for package management
+
+### Getting the Code
+Clone the repository to your local machine (if you haven't already).
+
+### Installation
+1.  Navigate to the project directory (e.g., `c:\\Users\\Chris4K\\Projekte\\projecthub\\projects\\MMOP_second_try`).
+    ```powershell
+    cd c:\Users\Chris4K\Projekte\projecthub\projects\MMOP_second_try
+    ```
+2.  Install the required Python dependencies:
+    ```bash
+    pip install gradio mcp aiohttp asyncio
+    ```
+    (Ensure other project-specific dependencies from your `requirements.txt` are also installed).
+
+### Running the Game Server
+Execute the main application file (assumed to be `app.py` in the root of `MMOP_second_try`):
+```bash
+python app.py
+```
+The server should start, typically making the Gradio UI available at `http://127.0.0.1:7868` and the MCP SSE endpoint at `http://127.0.0.1:7868/gradio_api/mcp/sse`.
+
+---
+
+## 🏗️ Architecture Overview (High-Level)
+
+*   **Game Server (`app.py`)**: The main entry point. Initializes and runs the Gradio web interface, integrates game components, and likely hosts the MCP endpoint.
+*   **Game Engine (`src/core/game_engine.py`)**: Contains the core game logic, manages world state, player data, NPC interactions, and game rules.
+*   **UI Layer (`src/ui/interface_manager.py`, `src/ui/huggingface_ui.py`)**: Manages the Gradio user interface, defining layouts, components, and event handling for human players.
+*   **MCP Integration Layer**: A facade or service within the server that exposes game functionalities to MCP clients. This allows AI agents or other external systems to interact with the game.
+*   **NPC Addons**: Modular components that extend NPC functionalities. See `NPC_Addon_Development_Guide.md`.
+
+---
+
+## 🔌 MCP API Reference
+
+The game server exposes its functionalities via the Model Context Protocol (MCP), allowing external clients (like AI agents or custom tools) to interact with the game world programmatically.
+
+### Connection
+*   **Endpoint URL**: `http://127.0.0.1:7868/gradio_api/mcp/sse` (for Server-Sent Events)
+*   **Protocol**: MCP over SSE.
+*   **Client Implementation**: Refer to `simple_game_client.py` for a reference Python client. It uses `mcp.ClientSession` and `mcp.client.sse.sse_client`.
+
+**Example Connection Snippet (from `simple_game_client.py`):**
+```python
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from contextlib import AsyncExitStack
+import asyncio
+
+class GameClient:
+    def __init__(self, server_url="http://127.0.0.1:7868/gradio_api/mcp/sse"):
+        self.server_url = server_url
+        self.session = None
+        self.exit_stack = AsyncExitStack()
+        self.connected = False
+        self.tools = []
+
+    async def connect(self):
+        try:
+            transport = await self.exit_stack.enter_async_context(
+                sse_client(self.server_url)
+            )
+            read_stream, write_callable = transport
+            self.session = await self.exit_stack.enter_async_context(
+                ClientSession(read_stream, write_callable)
+            )
+            await self.session.initialize()
+            response = await self.session.list_tools()
+            self.tools = response.tools
+            self.connected = True
+            print(f"✅ Connected! Available tools: {[tool.name for tool in self.tools]}")
+            return True
+        except Exception as e:
+            print(f"❌ Connection failed: {e}")
+            return False
+
+    async def disconnect(self):
+        if self.connected:
+            await self.exit_stack.aclose()
+            self.connected = False
+            print("🔌 Disconnected.")
+```
+
+### Available Tools/Commands
+Upon connection, the client can list available tools (commands) from the server. Common tools exposed by the MMORPG server typically include:
+
+*   `register_ai_agent` (or similar): To join the game as a new player/agent.
+*   `move_agent` (or similar): To move the player/agent in the game world.
+*   `send_chat_message` (or similar): To send messages to the public game chat.
+*   `interact_with_npc` (or similar): To send messages or commands to specific NPCs.
+*   `get_game_state` (or similar): To retrieve information about the current game world, other players, etc.
+
+The exact names and parameters of these tools are defined by the server-side MCP implementation. Use `session.list_tools()` to get the current list and `tool.parameters_json_schema` for expected inputs.
+
+### Common Operations
+
+**1. Registering a Player/Agent:**
+*   **Tool**: Look for a tool like `register_ai_agent`.
+*   **Parameters**: Typically `player_name` (string) and `client_id` (string, unique identifier for the client).
+*   **Response**: Often includes an `agent_id` or `player_id` assigned by the server.
+
+**2. Moving a Player/Agent:**
+*   **Tool**: Look for a tool like `move_agent`.
+*   **Parameters**: `agent_id` (string) and `direction` (string, e.g., "north", "south", "east", "west", "up", "down").
+*   **Response**: Confirmation of movement, new coordinates, or error if movement is not possible.
+
+**3. Sending Chat Messages:**
+*   **Tool**: Look for a tool like `send_chat_message`.
+*   **Parameters**: `agent_id` (string) and `message` (string).
+*   **Response**: Confirmation that the message was sent.
+
+**4. Interacting with NPCs:**
+*   **Tool**: Look for a tool like `interact_with_npc`.
+*   **Parameters**: `agent_id` (string), `npc_id` (string), and `message` or `command` (string).
+*   **Response**: NPC's reply or result of the interaction.
+
+**5. Getting Game State:**
+*   **Tool**: Look for a tool like `get_game_state`.
+*   **Parameters**: May include `agent_id` (string) or be parameterless.
+*   **Response**: JSON object containing game world information, list of players, NPCs, etc.
+
+**Example MCP Tool Usage:**
+```python
+# Register as AI agent
+response = await session.call_tool("register_ai_agent", {
+    "player_name": "MyBot",
+    "client_id": "bot_001"
+})
+
+# Move the agent
+response = await session.call_tool("move_agent", {
+    "agent_id": "bot_001", 
+    "direction": "north"
+})
+
+# Send chat message
+response = await session.call_tool("send_chat_message", {
+    "agent_id": "bot_001",
+    "message": "Hello everyone!"
+})
+```
+
+---
+
+## 🧩 Extending the Game
+
+### NPC Add-on Development
+For creating new NPCs with custom behaviors and UI components, please refer to the **`NPC_Addon_Development_Guide.md`**. It provides a comprehensive, up-to-date guide covering the modern auto-registration system, working examples from the codebase, and best practices.
+
+### Adding New Game Mechanics
+To introduce new core game mechanics:
+1.  **Game Engine (`src/core/game_engine.py`):** Implement the fundamental logic for the new mechanic here. This might involve modifying player states, world interactions, or introducing new entities.
+2.  **Facade Layer:** If the mechanic needs to be exposed to the UI or MCP clients, update or create methods in your game facade (e.g., `src/facades/game_facade.py`) to provide a clean interface to the engine's functionality.
+3.  **UI Integration (`src/ui/interface_manager.py`):** If human players should interact with this mechanic, add new UI elements and event handlers in the Gradio interface.
+4.  **MCP Exposure:** If AI agents or external clients should use this mechanic, expose the relevant facade methods as new MCP tools.
+
+---
+
+## 🤖 AI Agent Integration
+
+AI agents can connect to the MMORPG as players using an MCP client (like the one shown in `simple_game_client.py`).
+1.  **Connection**: The agent connects to the MCP SSE endpoint.
+2.  **Registration**: The agent registers itself, providing a name.
+3.  **Interaction**: The agent uses the available MCP tools to perceive the game state (`get_game_state`), move (`move_agent`), chat (`send_chat_message`), and interact with NPCs (`interact_with_npc`).
+4.  **Decision Making**: The agent's internal logic processes game state information and decides on actions to take.
+
+The `simple_game_client.py` script serves as a foundational example for building more sophisticated AI agents.
+
+---
+
+## 🐞 Debugging
+
+*   **Server Logs**: Check the console output where `python app.py` is running for server-side errors, print statements, and game event logs.
+*   **Gradio UI**: Use your web browser's developer tools (especially the console) to debug issues related to the Gradio interface and JavaScript (like the keyboard control script).
+*   **MCP Client-Side**: Add extensive logging in your MCP client to trace requests sent to the server and responses received. Print the full content of MCP tool calls and results.
+*   **Game State Dumps**: Periodically use the `get_game_state` MCP tool (if available) or implement a debug feature to dump the current game state to understand the situation from the server's perspective.
+*   **Incremental Testing**: When developing new features or MCP tools, test them incrementally.
+
+---

Documentation/NPC_Addon_Development_Guide.md

@@ -0,0 +1,1312 @@
+# 🛠️ NPC Addon Development Guide - Complete & Updated
+
+> **Updated for Current Architecture** - This guide reflects the latest addon system with auto-registration, modern patterns, and actual working examples from the codebase.
+
+## 📋 Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Modern Addon Architecture](#modern-addon-architecture)
+3. [Auto-Registration System](#auto-registration-system)
+4. [Complete Examples](#complete-examples)
+5. [Advanced Patterns](#advanced-patterns)
+6. [MCP Integration](#mcp-integration)
+7. [Best Practices](#best-practices)
+8. [Deployment & Testing](#deployment--testing)
+
+---
+
+## 🚀 Quick Start
+
+### Creating Your First Addon
+
+The modern addon system uses **auto-registration** - no manual edits to other files required!
+
+```python
+# src/addons/my_first_addon.py
+"""
+My First Addon - A simple self-contained NPC addon.
+"""
+
+import gradio as gr
+from ..interfaces.npc_addon import NPCAddon
+
+
+class MyFirstAddon(NPCAddon):
+    """A simple greeting NPC that demonstrates the addon system."""
+    
+    def __init__(self):
+        super().__init__()  # This auto-registers the addon!
+        self.greeting_count = 0
+    
+    @property
+    def addon_id(self) -> str:
+        """Unique identifier - must be unique across all addons"""
+        return "my_first_addon"
+    
+    @property
+    def addon_name(self) -> str:
+        """Display name shown in UI"""
+        return "🤝 My First Addon"
+    
+    @property
+    def npc_config(self) -> Dict[str, Any]:
+        """NPC configuration for auto-placement in world"""
+        return {
+            'id': 'my_first_npc',
+            'name': '🤝 Friendly Greeter',
+            'x': 100, 'y': 100,  # Position in game world
+            'char': '🤝',         # Character emoji
+            'type': 'addon',      # NPC type
+            'description': 'A friendly NPC that greets players'
+        }
+    
+    @property
+    def ui_tab_name(self) -> str:
+        """UI tab name - returns None if no UI tab needed"""
+        return "🤝 Greeter"
+    
+    def get_interface(self) -> gr.Component:
+        """Create the Gradio interface for this addon"""
+        with gr.Column() as interface:
+            gr.Markdown("## 🤝 Friendly Greeter\n*Hello! I'm here to greet players.*")
+            
+            greeting_btn = gr.Button("👋 Get Greeting", variant="primary")
+            greeting_output = gr.Textbox(label="Greeting", lines=3, interactive=False)
+            
+            def get_greeting():
+                self.greeting_count += 1
+                return f"Hello! This is greeting #{self.greeting_count}. Welcome to the game!"
+            
+            greeting_btn.click(get_greeting, outputs=[greeting_output])
+        
+        return interface
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle commands sent via private messages to this NPC"""
+        cmd = command.lower().strip()
+        
+        if cmd in ['hello', 'hi', 'greet']:
+            self.greeting_count += 1
+            return f"🤝 **Friendly Greeter says:**\nHello! Greeting #{self.greeting_count}!"
+        elif cmd == 'help':
+            return "🤝 **Available commands:**\n• hello/hi/greet - Get a greeting\n• help - Show this help"
+        else:
+            return "🤝 **Friendly Greeter:**\nI didn't understand that. Try 'hello' or 'help'!"
+
+
+# Global instance - this triggers auto-registration!
+my_first_addon = MyFirstAddon()
+```
+
+**That's it!** Your addon is now fully functional and auto-registered. No other files need to be modified.
+
+---
+
+## 🏗️ Modern Addon Architecture
+
+### Base Class Structure
+
+All addons inherit from `NPCAddon` which provides:
+
+```python
+class NPCAddon(ABC):
+    """Base class for NPC add-ons with auto-registration support"""
+    
+    def __init__(self):
+        """Initialize and auto-register the addon"""
+        # Auto-register this addon when instantiated
+        _addon_registry[self.addon_id] = self
+    
+    # Required Properties
+    @property
+    @abstractmethod
+    def addon_id(self) -> str: pass
+    
+    @property
+    @abstractmethod
+    def addon_name(self) -> str: pass
+    
+    # Optional Properties
+    @property
+    def npc_config(self) -> Optional[Dict[str, Any]]: return None
+    
+    @property
+    def ui_tab_name(self) -> Optional[str]: return None
+    
+    # Required Methods
+    @abstractmethod
+    def get_interface(self) -> gr.Component: pass
+    
+    @abstractmethod
+    def handle_command(self, player_id: str, command: str) -> str: pass
+    
+    # Optional Lifecycle Methods
+    def on_startup(self): pass
+    def on_shutdown(self): pass
+```
+
+### Core Concepts
+
+1. **Auto-Registration**: Simply instantiating your addon class registers it globally
+2. **Self-Contained**: Everything in one file - NPC config, UI, logic
+3. **Optional Components**: Only implement what you need (UI tab, world NPC, etc.)
+4. **Service Pattern**: Use interfaces for complex functionality
+
+---
+
+## 🔄 Auto-Registration System
+
+### How It Works
+
+1. **Create addon class** that inherits from `NPCAddon`
+2. **Instantiate globally** at the bottom of your addon file
+3. **Auto-discovery** by the game engine at startup
+4. **Automatic registration** of NPCs and UI components
+
+### Current Auto-Registration List
+
+The game engine automatically loads these addons:
+
+```python
+# src/core/game_engine.py
+auto_register_addons = [
+    ('weather_oracle_addon', 'auto_register'),
+    # Add your addon here if using custom auto_register function
+]
+```
+
+### Two Registration Patterns
+
+#### Pattern 1: Global Instance (Recommended)
+```python
+# At bottom of your addon file
+my_addon = MyAddon()  # Auto-registers via __init__
+```
+
+#### Pattern 2: Custom Auto-Register Function
+```python
+def auto_register(game_engine):
+    """Custom registration logic"""
+    try:
+        addon_instance = MyAddon()
+        # Custom registration logic here
+        return True
+    except Exception as e:
+        print(f"Registration failed: {e}")
+        return False
+
+# Add to game_engine.py auto_register_addons list
+```
+
+---
+
+## 📚 Complete Examples
+
+### Example 1: Simple Trader (From Codebase)
+
+```python
+"""
+Simple Trader NPC Add-on - Self-contained NPC with automatic registration.
+"""
+
+import gradio as gr
+from typing import Dict
+from ..interfaces.npc_addon import NPCAddon
+
+
+class SimpleTraderAddon(NPCAddon):
+    """Self-contained trader NPC that handles its own registration and positioning."""
+    
+    def __init__(self):
+        super().__init__()
+        self.inventory = {
+            "Health Potion": {"price": 50, "stock": 10, "description": "Restores 100 HP"},
+            "Magic Scroll": {"price": 150, "stock": 5, "description": "Cast magic spells"},
+            "Iron Sword": {"price": 300, "stock": 3, "description": "Sharp iron weapon"},
+            "Shield": {"price": 200, "stock": 4, "description": "Protective gear"}
+        }
+        self.sales_history = []
+    
+    @property
+    def addon_id(self) -> str:
+        return "simple_trader"
+    
+    @property 
+    def addon_name(self) -> str:
+        return "🛒 Simple Trader"
+    
+    @property
+    def npc_config(self) -> Dict:
+        return {
+            'id': 'simple_trader',
+            'name': '🛒 Simple Trader',
+            'x': 450, 'y': 150,
+            'char': '🛒',
+            'type': 'addon',
+            'personality': 'trader',
+            'description': 'A friendly trader selling useful items'
+        }
+    
+    @property
+    def ui_tab_name(self) -> str:
+        return "🛒 Simple Trader"
+    
+    def get_interface(self) -> gr.Component:
+        """Create the Gradio interface for this addon."""
+        with gr.Column() as interface:
+            gr.Markdown("### 🛒 Simple Trader Shop")
+            gr.Markdown("Browse items and check prices. Use private messages to trade!")
+            
+            # Display inventory
+            inventory_data = []
+            for item, info in self.inventory.items():
+                inventory_data.append([item, f"{info['price']} gold", info['stock'], info['description']])
+            
+            gr.Dataframe(
+                headers=["Item", "Price", "Stock", "Description"],
+                value=inventory_data,
+                interactive=False
+            )
+            
+            gr.Markdown("**Commands:** Send private message to Simple Trader")
+            gr.Markdown("• `buy <item>` - Purchase an item")
+            gr.Markdown("• `inventory` - See available items")
+            gr.Markdown("• `help` - Show all commands")
+        
+        return interface
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle commands sent to this NPC."""
+        parts = command.strip().lower().split()
+        cmd = parts[0] if parts else ""
+        
+        if cmd == "buy" and len(parts) > 1:
+            item_name = " ".join(parts[1:]).title()
+            return self._handle_buy(player_id, item_name)
+        elif cmd == "inventory":
+            return self._show_inventory()
+        elif cmd == "help":
+            return self._show_help()
+        else:
+            return "🛒 **Simple Trader:** I didn't understand. Try 'buy <item>', 'inventory', or 'help'."
+    
+    def _handle_buy(self, player_id: str, item_name: str) -> str:
+        """Handle item purchase."""
+        if item_name not in self.inventory:
+            return f"❌ Sorry, I don't have '{item_name}' in stock."
+        
+        item = self.inventory[item_name]
+        if item['stock'] <= 0:
+            return f"❌ '{item_name}' is out of stock!"
+        
+        # In a real implementation, check player gold and deduct
+        item['stock'] -= 1
+        self.sales_history.append({'player': player_id, 'item': item_name, 'price': item['price']})
+        
+        return f"✅ **Purchase Successful!**\n📦 You bought: {item_name}\n💰 Price: {item['price']} gold\n📊 Stock remaining: {item['stock']}"
+    
+    def _show_inventory(self) -> str:
+        """Show current inventory."""
+        result = "🛒 **Current Inventory:**\n\n"
+        for item, info in self.inventory.items():
+            result += f"**{item}** - {info['price']} gold (Stock: {info['stock']})\n"
+            result += f"  ↳ {info['description']}\n\n"
+        return result
+    
+    def _show_help(self) -> str:
+        """Show help commands."""
+        return """🛒 **Simple Trader Commands:**
+
+**buy <item>** - Purchase an item
+**inventory** - See available items and prices
+**help** - Show this help
+
+💰 **Available Items:**
+• Health Potion, Magic Scroll, Iron Sword, Shield
+
+Example: `buy Health Potion`"""
+
+
+# Global instance for automatic registration
+simple_trader_addon = SimpleTraderAddon()
+```
+
+### Example 2: Read2Burn Messaging (From Codebase)
+
+This example shows a complex addon with state management and service interfaces:
+
+```python
+"""
+Read2Burn Mailbox Add-on - Self-destructing secure messaging system.
+"""
+
+import time
+import random
+import string
+from typing import Dict, List
+from dataclasses import dataclass
+from abc import ABC, abstractmethod
+import gradio as gr
+
+from ..interfaces.npc_addon import NPCAddon
+
+
+@dataclass
+class Read2BurnMessage:
+    """Data class for Read2Burn messages."""
+    id: str
+    creator_id: str
+    content: str
+    created_at: float
+    expires_at: float
+    reads_left: int
+    burned: bool = False
+
+
+class IRead2BurnService(ABC):
+    """Interface for Read2Burn service operations."""
+    
+    @abstractmethod
+    def create_message(self, creator_id: str, content: str) -> str: pass
+    
+    @abstractmethod
+    def read_message(self, reader_id: str, message_id: str) -> str: pass
+    
+    @abstractmethod
+    def list_player_messages(self, player_id: str) -> str: pass
+
+
+class Read2BurnService(IRead2BurnService, NPCAddon):
+    """Service for managing Read2Burn secure messaging."""
+    
+    def __init__(self):
+        super().__init__()
+        self.messages: Dict[str, Read2BurnMessage] = {}
+        self.access_log: List[Dict] = []
+    
+    @property
+    def addon_id(self) -> str:
+        return "read2burn_mailbox"
+    
+    @property
+    def addon_name(self) -> str:
+        return "📧 Read2Burn Secure Mailbox"
+    
+    @property
+    def npc_config(self) -> Dict:
+        return {
+            'id': 'read2burn',
+            'name': '📧 Read2Burn Service',
+            'x': 200, 'y': 100,
+            'char': '📧',
+            'type': 'service',
+            'personality': 'read2burn',
+            'description': 'Secure message service - send private messages that auto-delete after reading'
+        }
+    
+    def get_interface(self) -> gr.Component:
+        """Return Gradio interface for this add-on"""
+        with gr.Column() as interface:
+            gr.Markdown("""
+            ## 📧 Read2Burn Secure Mailbox
+            
+            **Create self-destructing messages that burn after reading!**
+            
+            ### Features:
+            - 🔥 Messages self-destruct after reading
+            - ⏰ 24-hour automatic expiration
+            - 🔒 Secure delivery system
+            - 📊 Message tracking and history
+            """)
+            
+            with gr.Tabs():
+                with gr.Tab("📝 Create Message"):
+                    message_input = gr.Textbox(
+                        label="Message Content",
+                        lines=5,
+                        placeholder="Type your secret message here..."
+                    )
+                    create_btn = gr.Button("🔥 Create Burning Message", variant="primary")
+                    create_output = gr.Textbox(label="Result", lines=3, interactive=False)
+                    
+                    def create_message_ui(content):
+                        # In real implementation, get current player ID
+                        player_id = "current_player"  # Simplified
+                        return self.create_message(player_id, content)
+                    
+                    create_btn.click(create_message_ui, inputs=[message_input], outputs=[create_output])
+                
+                with gr.Tab("🔓 Read Message"):
+                    message_id_input = gr.Textbox(label="Message ID", placeholder="Enter 8-character message ID")
+                    read_btn = gr.Button("📖 Read & Burn Message", variant="secondary")
+                    read_output = gr.Textbox(label="Message Content", lines=5, interactive=False)
+                    
+                    def read_message_ui(msg_id):
+                        player_id = "current_player"  # Simplified
+                        return self.read_message(player_id, msg_id)
+                    
+                    read_btn.click(read_message_ui, inputs=[message_id_input], outputs=[read_output])
+                
+                with gr.Tab("📋 My Messages"):
+                    refresh_btn = gr.Button("🔄 Refresh List")
+                    messages_output = gr.Textbox(label="Your Messages", lines=10, interactive=False)
+                    
+                    def list_messages_ui():
+                        player_id = "current_player"  # Simplified
+                        return self.list_player_messages(player_id)
+                    
+                    refresh_btn.click(list_messages_ui, outputs=[messages_output])
+            
+            gr.Markdown("**💬 Private Message Commands:**")
+            gr.Markdown("• `create Your message here` - Create new message")
+            gr.Markdown("• `read MESSAGE_ID` - Read message (destroys it!)")
+            gr.Markdown("• `list` - Show your created messages")
+            gr.Markdown("• `help` - Show command help")
+        
+        return interface
+        
+    def generate_message_id(self) -> str:
+        """Generate a unique message ID."""
+        return ''.join(random.choices(string.ascii_uppercase + string.digits, k=8))
+    
+    def create_message(self, creator_id: str, content: str) -> str:
+        """Create a new self-destructing message."""
+        message_id = self.generate_message_id()
+        
+        message = Read2BurnMessage(
+            id=message_id,
+            creator_id=creator_id,
+            content=content,  # In production, encrypt this
+            created_at=time.time(),
+            expires_at=time.time() + (24 * 3600),  # 24 hours
+            reads_left=1,
+            burned=False
+        )
+        
+        self.messages[message_id] = message
+        
+        self.access_log.append({
+            'action': 'create',
+            'message_id': message_id,
+            'player_id': creator_id,
+            'timestamp': time.time()
+        })
+        
+        return f"✅ **Message Created Successfully!**\n\n📝 **Message ID:** `{message_id}`\n🔗 Share this ID with the recipient\n⏰ Expires in 24 hours\n🔥 Burns after 1 read"
+    
+    def read_message(self, reader_id: str, message_id: str) -> str:
+        """Read and burn a message."""
+        if message_id not in self.messages:
+            return "❌ Message not found or already burned"
+        
+        message = self.messages[message_id]
+        
+        # Check expiry
+        if time.time() > message.expires_at:
+            del self.messages[message_id]
+            return "❌ Message expired and has been burned"
+        
+        # Check if already burned
+        if message.burned or message.reads_left <= 0:
+            del self.messages[message_id]
+            return "❌ Message has already been burned"
+        
+        # Read the message
+        content = message.content
+        message.reads_left -= 1
+        
+        self.access_log.append({
+            'action': 'read',
+            'message_id': message_id,
+            'player_id': reader_id,
+            'timestamp': time.time()
+        })
+        
+        # Burn the message after reading
+        if message.reads_left <= 0:
+            message.burned = True
+            del self.messages[message_id]
+            return f"🔥 **Message Self-Destructed After Reading**\n\n📖 **Content:** {content}\n\n💨 This message has been permanently destroyed."
+        
+        return f"📖 **Message Content:** {content}\n\n⚠️ Reads remaining: {message.reads_left}"
+    
+    def list_player_messages(self, player_id: str) -> str:
+        """List messages created by a player."""
+        player_messages = [msg for msg in self.messages.values() if msg.creator_id == player_id]
+        
+        if not player_messages:
+            return "📪 No messages found. Create one with: `create Your message here`"
+        
+        result = "📋 **Your Created Messages:**\n\n"
+        for msg in player_messages:
+            status = "🔥 Burned" if msg.burned else f"✅ Active ({msg.reads_left} reads left)"
+            created_time = time.strftime("%Y-%m-%d %H:%M", time.localtime(msg.created_at))
+            expires_time = time.strftime("%Y-%m-%d %H:%M", time.localtime(msg.expires_at))
+            
+            result += f"**ID:** `{msg.id}`\n"
+            result += f"**Status:** {status}\n"
+            result += f"**Created:** {created_time}\n"
+            result += f"**Expires:** {expires_time}\n"
+            result += f"**Preview:** {msg.content[:50]}{'...' if len(msg.content) > 50 else ''}\n\n"
+        
+        return result
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle Read2Burn mailbox commands."""
+        parts = command.strip().split(' ', 1)
+        cmd = parts[0].lower()
+        
+        if cmd == "create" and len(parts) > 1:
+            return self.create_message(player_id, parts[1])
+        elif cmd == "read" and len(parts) > 1:
+            return self.read_message(player_id, parts[1])
+        elif cmd == "list":
+            return self.list_player_messages(player_id)
+        elif cmd == "help":
+            return """📚 **Read2Burn Mailbox Commands:**
+
+**create** `Your secret message here` - Create new message
+**read** `MESSAGE_ID` - Read message (destroys it!)
+**list** - Show your created messages
+**help** - Show this help
+
+🔥 **Features:**
+• Messages self-destruct after reading
+• 24-hour automatic expiration
+• Secure delivery system
+• Anonymous messaging support"""
+        else:
+            return "❓ Invalid command. Try: `create <message>`, `read <id>`, `list`, or `help`"
+
+
+# Global Read2Burn service instance
+read2burn_service = Read2BurnService()
+```
+
+---
+
+## 🌐 MCP Integration
+
+### MCP-Powered Weather Oracle (From Codebase)
+
+This example shows how to integrate external MCP servers:
+
+```python
+"""
+Weather Oracle Add-on - MCP-powered weather information system.
+"""
+
+import time
+import asyncio
+from typing import Dict, Optional
+import gradio as gr
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from contextlib import AsyncExitStack
+
+from ..interfaces.npc_addon import NPCAddon
+
+
+class WeatherOracleService(NPCAddon):
+    """Service for managing Weather Oracle MCP integration."""
+    
+    def __init__(self):
+        super().__init__()
+        self.connected = False
+        self.last_connection_attempt = 0
+        self.connection_cooldown = 30  # 30 seconds between connection attempts
+        self.server_url = "https://chris4k-weather.hf.space/gradio_api/mcp/sse"
+        self.session = None
+        self.tools = []
+        self.exit_stack = None
+        
+        # Set up event loop for async operations
+        try:
+            self.loop = asyncio.get_event_loop()
+        except RuntimeError:
+            self.loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(self.loop)
+    
+    @property
+    def addon_id(self) -> str:
+        return "weather_oracle"
+    
+    @property
+    def addon_name(self) -> str:
+        return "🌤️ Weather Oracle (MCP)"
+    
+    @property
+    def npc_config(self) -> Dict:
+        return {
+            'id': 'weather_oracle',
+            'name': '🌤️ Weather Oracle (MCP)',
+            'x': 150, 'y': 300,
+            'char': '🌤️',
+            'type': 'mcp',
+            'description': 'MCP-powered weather information service'
+        }
+    
+    @property
+    def ui_tab_name(self) -> str:
+        return "🌤️ Weather Oracle"
+    
+    def get_interface(self) -> gr.Component:
+        """Return Gradio interface for this add-on"""
+        with gr.Column() as interface:
+            gr.Markdown("""
+            ## 🌤️ Weather Oracle
+            
+            *I commune with the spirits of sky and storm to bring you weather wisdom from across the realms!*
+            
+            **Ask me about weather in any city:**
+            - Current conditions and temperature
+            - Weather forecasts  
+            - Climate information
+            
+            *Format: "City, Country" (e.g., "Berlin, Germany")*
+            """)
+            
+            # Connection status
+            connection_status = gr.HTML(
+                value=f"<div style='color: {'green' if self.connected else 'red'};'>{'🟢 Connected to weather spirits' if self.connected else '🔴 Disconnected from weather realm'}</div>"
+            )
+            
+            with gr.Row():
+                location_input = gr.Textbox(
+                    label="🌍 Location",
+                    placeholder="Enter city, country (e.g., Berlin, Germany)",
+                    scale=3
+                )
+                get_weather_btn = gr.Button("🌡️ Consult Weather Spirits", variant="primary", scale=1)
+            
+            weather_output = gr.Textbox(
+                label="🌤️ Weather Wisdom",
+                lines=8,
+                interactive=False,
+                placeholder="Enter a location and I will consult the weather spirits..."
+            )
+            
+            # Example locations
+            gr.Examples(
+                examples=[
+                    ["London, UK"],
+                    ["Tokyo, Japan"],
+                    ["New York, USA"],
+                    ["Berlin, Germany"],
+                    ["Sydney, Australia"]
+                ],
+                inputs=[location_input],
+                label="🌍 Try These Locations"
+            )
+            
+            # Connection controls
+            with gr.Row():
+                connect_btn = gr.Button("🔗 Connect to MCP", variant="secondary")
+                status_btn = gr.Button("📊 Check Status", variant="secondary")
+            
+            def handle_weather_request(location: str):
+                if not location.strip():
+                    return "🌪️ The spirits need to know which realm you seek knowledge about!"
+                return self.get_weather(location)
+            
+            def handle_connect():
+                result = self.connect_to_mcp()
+                status = f"<div style='color: {'green' if self.connected else 'red'};'>{'🟢 Connected to weather spirits' if self.connected else '🔴 Disconnected from weather realm'}</div>"
+                return result, status
+            
+            def handle_status():
+                if self.connected:
+                    tool_names = [tool.name for tool in self.tools] if self.tools else []
+                    return f"✅ **Connected to MCP Weather Server**\n\nServer: {self.server_url}\nTools: {', '.join(tool_names) if tool_names else 'None'}"
+                else:
+                    return "❌ **Not Connected**\n\nClick 'Connect to MCP' to establish connection."
+            
+            # Wire up events
+            get_weather_btn.click(
+                handle_weather_request,
+                inputs=[location_input],
+                outputs=[weather_output]
+            )
+            
+            location_input.submit(
+                handle_weather_request,
+                inputs=[location_input], 
+                outputs=[weather_output]
+            )
+            
+            connect_btn.click(
+                handle_connect,
+                outputs=[weather_output, connection_status]
+            )
+            
+            status_btn.click(
+                handle_status,
+                outputs=[weather_output]
+            )
+        
+        return interface
+    
+    def connect_to_mcp(self) -> str:
+        """Connect to MCP weather server."""
+        current_time = time.time()
+        if current_time - self.last_connection_attempt < self.connection_cooldown:
+            return "⏳ Please wait before retrying connection..."
+        
+        self.last_connection_attempt = current_time
+        
+        try:
+            return self.loop.run_until_complete(self._connect())
+        except Exception as e:
+            self.connected = False
+            return f"❌ Connection failed: {str(e)}"
+    
+    async def _connect(self) -> str:
+        """Async connect to MCP server using SSE."""
+        try:
+            # Clean up previous connection
+            if self.exit_stack:
+                await self.exit_stack.aclose()
+
+            self.exit_stack = AsyncExitStack()
+
+            # Connect to SSE MCP server
+            sse_transport = await self.exit_stack.enter_async_context(
+                sse_client(self.server_url)
+            )
+            read_stream, write_callable = sse_transport
+
+            self.session = await self.exit_stack.enter_async_context(
+                ClientSession(read_stream, write_callable)
+            )
+            await self.session.initialize()
+
+            # Get available tools
+            response = await self.session.list_tools()
+            self.tools = response.tools
+
+            self.connected = True
+            tool_names = [tool.name for tool in self.tools]
+            return f"✅ Connected to weather MCP server!\nAvailable tools: {', '.join(tool_names)}"
+
+        except Exception as e:
+            self.connected = False
+            return f"❌ Connection failed: {str(e)}"
+    
+    def get_weather(self, location: str) -> str:
+        """Get weather for a location using actual MCP server"""
+        if not self.connected:
+            # Try to auto-reconnect
+            connect_result = self.connect_to_mcp()
+            if not self.connected:
+                return f"❌ **Not connected to weather spirits**\n\n{connect_result}"
+        
+        try:
+            return self.loop.run_until_complete(self._get_weather(location))
+        except Exception as e:
+            return f"❌ **Weather divination failed**\n\nError: {str(e)}"
+    
+    async def _get_weather(self, location: str) -> str:
+        """Async get weather using MCP."""
+        try:
+            # Parse location
+            if ',' in location:
+                city, country = [part.strip() for part in location.split(',', 1)]
+            else:
+                city = location.strip()
+                country = ""
+
+            # Find the weather tool
+            weather_tool = next((tool for tool in self.tools if 'weather' in tool.name.lower()), None)
+            if not weather_tool:
+                return "❌ Weather tool not found on server"
+
+            # Call the tool
+            params = {"city": city, "country": country}
+            result = await self.session.call_tool(weather_tool.name, params)
+
+            # Extract content properly
+            content_text = ""
+            if hasattr(result, 'content') and result.content:
+                if isinstance(result.content, list):
+                    for content_item in result.content:
+                        if hasattr(content_item, 'text'):
+                            content_text += content_item.text + "\n"
+                        else:
+                            content_text += str(content_item) + "\n"
+                else:
+                    content_text = str(result.content)
+
+            if not content_text.strip():
+                return f"❌ No weather data received for {location}"
+
+            # Format the response
+            return f"🌤️ **Weather Oracle reveals the weather for {location}:**\n\n{content_text.strip()}"
+
+        except Exception as e:
+            return f"❌ Weather divination failed: {str(e)}"
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle Weather Oracle commands."""
+        cmd = command.strip()
+        
+        if not cmd:
+            return ("🌤️ **Weather Oracle whispers:**\n\n"
+                   "Ask me about the weather in any city!\n"
+                   "Format: 'City, Country' (e.g., 'Berlin, Germany')")
+        
+        # Treat any non-empty command as a location request
+        result = self.get_weather(cmd)
+        return f"🌤️ **Weather Oracle reveals:**\n\n{result}"
+
+
+# Custom auto-registration function
+def auto_register(game_engine):
+    """Auto-register the Weather Oracle addon with the game engine."""
+    try:
+        # Create the weather oracle NPC definition
+        weather_oracle_npc = {
+            'id': 'weather_oracle_auto',
+            'name': '🌤️ Weather Oracle (Auto)',
+            'x': 300, 'y': 150,
+            'char': '🌤️',
+            'type': 'mcp',
+            'personality': 'weather_oracle',
+            'description': 'Self-contained MCP-powered weather information service'
+        }
+        
+        # Register the NPC with the NPC service
+        npc_service = game_engine.get_npc_service()
+        npc_service.register_npc('weather_oracle_auto', weather_oracle_npc)
+        
+        # Register the addon for handling private message commands
+        world = game_engine.get_world()
+        if not hasattr(world, 'addon_npcs'):
+            world.addon_npcs = {}
+        world.addon_npcs['weather_oracle_auto'] = weather_oracle_service
+        
+        print("[WeatherOracleAddon] Auto-registered successfully as self-contained addon")
+        return True
+        
+    except Exception as e:
+        print(f"[WeatherOracleAddon] Error during auto-registration: {e}")
+        return False
+
+
+# Global Weather Oracle service instance
+weather_oracle_service = WeatherOracleService()
+```
+
+---
+
+## 🔧 Advanced Patterns
+
+### State Persistence
+
+```python
+import json
+import os
+
+class PersistentAddon(NPCAddon):
+    """Example addon with state persistence."""
+    
+    def __init__(self):
+        super().__init__()
+        self.data_file = f"data/{self.addon_id}_data.json"
+        self.load_state()
+    
+    def load_state(self):
+        """Load addon state from file."""
+        try:
+            if os.path.exists(self.data_file):
+                with open(self.data_file, 'r') as f:
+                    data = json.load(f)
+                    self.player_data = data.get('players', {})
+                    self.settings = data.get('settings', {})
+            else:
+                self.player_data = {}
+                self.settings = {}
+        except Exception as e:
+            print(f"[{self.addon_id}] Failed to load state: {e}")
+            self.player_data = {}
+            self.settings = {}
+    
+    def save_state(self):
+        """Save addon state to file."""
+        try:
+            os.makedirs(os.path.dirname(self.data_file), exist_ok=True)
+            with open(self.data_file, 'w') as f:
+                json.dump({
+                    'players': self.player_data,
+                    'settings': self.settings
+                }, f, indent=2)
+        except Exception as e:
+            print(f"[{self.addon_id}] Failed to save state: {e}")
+    
+    def on_shutdown(self):
+        """Save state when addon shuts down."""
+        self.save_state()
+```
+
+### Player Validation Helper
+
+```python
+def get_current_player(self, game_world):
+    """Helper to safely get current active player."""
+    try:
+        current_players = list(game_world.players.keys())
+        if not current_players:
+            return None, "❌ You must be in the game to use this service!"
+        
+        player_id = max(current_players, key=lambda pid: game_world.players[pid].last_active)
+        player = game_world.players.get(player_id)
+        
+        if not player:
+            return None, "❌ Player not found!"
+        
+        return player, None
+    except Exception as e:
+        return None, f"❌ Error accessing player data: {e}"
+```
+
+### Async Operation Wrapper
+
+```python
+def run_async_safely(self, async_func, *args, **kwargs):
+    """Safely run async functions in sync context."""
+    try:
+        return self.loop.run_until_complete(async_func(*args, **kwargs))
+    except Exception as e:
+        return f"❌ Async operation failed: {e}"
+```
+
+### Configuration Management
+
+```python
+import yaml
+
+class ConfigurableAddon(NPCAddon):
+    """Addon with configuration file support."""
+    
+    def __init__(self):
+        super().__init__()
+        self.config = self.load_config()
+    
+    def load_config(self):
+        """Load configuration from YAML file."""
+        config_file = f"config/{self.addon_id}_config.yaml"
+        try:
+            if os.path.exists(config_file):
+                with open(config_file, 'r') as f:
+                    return yaml.safe_load(f)
+            else:
+                return self.get_default_config()
+        except Exception as e:
+            print(f"[{self.addon_id}] Config load failed: {e}")
+            return self.get_default_config()
+    
+    def get_default_config(self):
+        """Return default configuration."""
+        return {
+            'enabled': True,
+            'max_operations': 100,
+            'cooldown_seconds': 30
+        }
+```
+
+---
+
+## 🎯 Best Practices
+
+### 1. Error Handling
+
+```python
+def handle_command(self, player_id: str, command: str) -> str:
+    """Always wrap command handling in try-catch."""
+    try:
+        # Your command logic here
+        return self.process_command(player_id, command)
+    except Exception as e:
+        print(f"[{self.addon_id}] Command error: {e}")
+        return f"❌ An error occurred. Please try again or contact support."
+```
+
+### 2. Input Validation
+
+```python
+def validate_input(self, input_value: str, max_length: int = 500) -> tuple[bool, str]:
+    """Validate user input."""
+    if not input_value or not input_value.strip():
+        return False, "Input cannot be empty"
+    
+    if len(input_value) > max_length:
+        return False, f"Input too long (max {max_length} characters)"
+    
+    # Add more validation as needed
+    return True, ""
+```
+
+### 3. Rate Limiting
+
+```python
+import time
+from collections import defaultdict
+
+class RateLimitedAddon(NPCAddon):
+    """Addon with rate limiting."""
+    
+    def __init__(self):
+        super().__init__()
+        self.last_command_time = defaultdict(float)
+        self.command_cooldown = 5  # 5 seconds between commands
+    
+    def is_rate_limited(self, player_id: str) -> bool:
+        """Check if player is rate limited."""
+        current_time = time.time()
+        last_time = self.last_command_time[player_id]
+        
+        if current_time - last_time < self.command_cooldown:
+            return True
+        
+        self.last_command_time[player_id] = current_time
+        return False
+```
+
+### 4. Logging
+
+```python
+import logging
+
+class LoggedAddon(NPCAddon):
+    """Addon with proper logging."""
+    
+    def __init__(self):
+        super().__init__()
+        self.logger = logging.getLogger(f"addon_{self.addon_id}")
+        self.logger.setLevel(logging.INFO)
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        self.logger.info(f"Command from {player_id}: {command}")
+        try:
+            result = self.process_command(player_id, command)
+            self.logger.info(f"Command successful for {player_id}")
+            return result
+        except Exception as e:
+            self.logger.error(f"Command failed for {player_id}: {e}")
+            return "❌ Command failed. Please try again."
+```
+
+### 5. Resource Cleanup
+
+```python
+class ResourceManagedAddon(NPCAddon):
+    """Addon with proper resource management."""
+    
+    def __init__(self):
+        super().__init__()
+        self.resources = []  # Track resources
+    
+    def on_shutdown(self):
+        """Clean up resources on shutdown."""
+        for resource in self.resources:
+            try:
+                if hasattr(resource, 'close'):
+                    resource.close()
+                elif hasattr(resource, '__exit__'):
+                    resource.__exit__(None, None, None)
+            except Exception as e:
+                print(f"[{self.addon_id}] Cleanup error: {e}")
+```
+
+---
+
+## 🧪 Deployment & Testing
+
+### Testing Your Addon
+
+Create a test file for your addon:
+
+```python
+# tests/test_my_addon.py
+import pytest
+from src.addons.my_addon import MyAddon
+
+class TestMyAddon:
+    def setup_method(self):
+        """Set up test fixtures."""
+        self.addon = MyAddon()
+    
+    def test_addon_id(self):
+        """Test addon ID is correct."""
+        assert self.addon.addon_id == "my_addon"
+    
+    def test_handle_command_hello(self):
+        """Test hello command."""
+        result = self.addon.handle_command("test_player", "hello")
+        assert "hello" in result.lower()
+    
+    def test_handle_command_invalid(self):
+        """Test invalid command handling."""
+        result = self.addon.handle_command("test_player", "invalid_command")
+        assert "didn't understand" in result.lower() or "help" in result.lower()
+```
+
+### Running Tests
+
+```bash
+# Run all addon tests
+python -m pytest tests/test_*_addon.py -v
+
+# Run specific addon test
+python -m pytest tests/test_my_addon.py -v
+
+# Run with coverage
+python -m pytest tests/test_*_addon.py --cov=src/addons
+```
+
+### Debug Mode
+
+Add debug functionality to your addon:
+
+```python
+class DebuggableAddon(NPCAddon):
+    """Addon with debug capabilities."""
+    
+    def __init__(self):
+        super().__init__()
+        self.debug_mode = os.getenv('ADDON_DEBUG', 'false').lower() == 'true'
+    
+    def debug_log(self, message: str):
+        """Log debug messages."""
+        if self.debug_mode:
+            print(f"[DEBUG:{self.addon_id}] {message}")
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        self.debug_log(f"Received command: {command}")
+        # ... rest of method
+```
+
+### Performance Monitoring
+
+```python
+import time
+from functools import wraps
+
+def monitor_performance(func):
+    """Decorator to monitor function performance."""
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        start_time = time.time()
+        try:
+            result = func(self, *args, **kwargs)
+            duration = time.time() - start_time
+            if duration > 1.0:  # Log slow operations
+                print(f"[{self.addon_id}] Slow operation: {func.__name__} took {duration:.2f}s")
+            return result
+        except Exception as e:
+            duration = time.time() - start_time
+            print(f"[{self.addon_id}] Error in {func.__name__} after {duration:.2f}s: {e}")
+            raise
+    return wrapper
+
+class MonitoredAddon(NPCAddon):
+    """Addon with performance monitoring."""
+    
+    @monitor_performance
+    def handle_command(self, player_id: str, command: str) -> str:
+        # Your command handling logic
+        pass
+```
+
+### Integration Testing
+
+Test your addon with the game engine:
+
+```python
+# tests/test_integration.py
+import asyncio
+from src.core.game_engine import GameEngine
+from src.addons.my_addon import MyAddon
+
+def test_addon_integration():
+    """Test addon integrates properly with game engine."""
+    engine = GameEngine()
+    engine.start()
+    
+    # Check addon is registered
+    world = engine.get_world()
+    assert hasattr(world, 'addon_npcs')
+    assert 'my_addon' in world.addon_npcs
+    
+    # Test NPC exists
+    npc_service = engine.get_npc_service()
+    npc = npc_service.get_npc('my_addon_npc')
+    assert npc is not None
+    
+    engine.stop()
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+**1. Addon Not Auto-Registering**
+- Check that you have a global instance at the bottom of your file
+- Verify `addon_id` is unique and doesn't conflict with others
+- Ensure you're calling `super().__init__()` in your constructor
+
+**2. UI Tab Not Appearing**
+- Check that `ui_tab_name` property returns a string, not None
+- Verify `get_interface()` returns a valid Gradio component
+- Look for exceptions in the console when the interface loads
+
+**3. NPC Not Appearing in World**
+- Verify `npc_config` property returns a valid dictionary
+- Check that the NPC position coordinates are within world bounds
+- Ensure the NPC ID is unique
+
+**4. Private Messages Not Working**
+- Confirm `handle_command()` is implemented
+- Check that the addon is registered in `world.addon_npcs`
+- Verify the NPC ID matches between world registration and addon registry
+
+**5. MCP Connection Issues**
+- Check the MCP server URL is correct and accessible
+- Verify the server is running and supports the expected tools
+- Look for async/await issues in your MCP client code
+- Check firewall and network connectivity
+
+### Debug Checklist
+
+- [ ] Addon file imported without errors
+- [ ] Global instance created at file bottom
+- [ ] All required methods implemented
+- [ ] Properties return correct types
+- [ ] No exceptions in console on startup
+- [ ] NPC appears in world at specified coordinates
+- [ ] UI tab appears in interface (if configured)
+- [ ] Private messages work correctly
+- [ ] Error handling covers edge cases
+
+### Getting Help
+
+1. **Check Logs**: Look for error messages in the console
+2. **Test Individually**: Create a simple test script for your addon
+3. **Validate Configuration**: Ensure all properties return expected values
+4. **Compare Examples**: Look at working addons like SimpleTrader or Read2Burn
+5. **Community Support**: Ask on project forums or GitHub issues
+
+---
+
+## 📚 Additional Resources
+
+- **Interface Reference**: `src/interfaces/npc_addon.py` - Base class documentation
+- **Working Examples**: `src/addons/` - All current addon implementations
+- **Game Engine**: `src/core/game_engine.py` - Auto-registration system
+- **World Management**: `src/core/world.py` - NPC placement and management
+- **MCP Documentation**: [Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk)
+
+---
+
+*This guide reflects the current addon system architecture and includes real examples from the working codebase. All code examples are tested and functional.*

Documentation/NPC_Addon_Development_Guide_OLD.md

@@ -0,0 +1,1110 @@
+# Building NPC Add-ons for MMORPG Game
+
+This comprehensive guide shows you how to create custom NPC add-ons for the MMORPG game, with examples ranging from simple text-based NPCs to complex MCP-powered services.
+
+## Table of Contents
+
+1. [Basic NPC Add-on Structure](#basic-npc-add-on-structure)
+2. [Creating a Simple Add-on](#creating-a-simple-add-on)
+3. [Advanced Add-on with State Management](#advanced-add-on-with-state-management)
+4. [MCP-Powered Add-on](#mcp-powered-add-on)
+5. [Integration into the Game](#integration-into-the-game)
+6. [Best Practices](#best-practices)
+7. [Troubleshooting](#troubleshooting)
+
+---
+
+## Basic NPC Add-on Structure
+
+Every NPC add-on must inherit from the `NPCAddon` abstract base class and implement four required methods:
+
+```python
+from abc import ABC, abstractmethod
+import gradio as gr
+
+class NPCAddon(ABC):
+    """Base class for NPC add-ons"""
+    
+    @property
+    @abstractmethod
+    def addon_id(self) -> str:
+        """Unique identifier for this add-on"""
+        pass
+    
+    @property
+    @abstractmethod
+    def addon_name(self) -> str:
+        """Display name for this add-on"""
+        pass
+    
+    @abstractmethod
+    def get_interface(self) -> gr.Component:
+        """Return Gradio interface for this add-on"""
+        pass
+    
+    @abstractmethod
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle player commands via private messages"""
+        pass
+```
+
+### Key Requirements
+
+1. **Unique ID**: Each add-on needs a unique `addon_id`
+2. **Display Name**: User-friendly name shown in the interface
+3. **Gradio Interface**: Web interface for players to interact with
+4. **Command Handler**: Process commands sent via private messages to the NPC
+
+---
+
+## Creating a Simple Add-on
+
+Let's create a **Fortune Teller** NPC that gives random predictions:
+
+```python
+import random
+import time
+from typing import Dict, List
+
+class FortuneTellerAddon(NPCAddon):
+    """Fortune Teller NPC - gives random predictions and wisdom"""
+    
+    def __init__(self):
+        self.fortunes = [
+            "A great adventure awaits you beyond the eastern mountains!",
+            "Beware of strangers bearing gifts in the next full moon.",
+            "Your courage will be tested, but victory will be yours.",
+            "Gold will come to you through an unexpected friendship.",
+            "The stars suggest a powerful ally will join your quest.",
+            "A hidden treasure lies where the old oak meets the stream.",
+            "Your wisdom will grow through helping others in need.",
+            "Trust your instincts - they will guide you true.",
+            "A challenge approaches, but it will make you stronger.",
+            "The path you seek becomes clear under starlight."
+        ]
+        
+        self.player_fortunes: Dict[str, Dict] = {}  # Track player fortune history
+    
+    @property
+    def addon_id(self) -> str:
+        return "fortune_teller"
+    
+    @property
+    def addon_name(self) -> str:
+        return "🔮 Mystic Fortune Teller"
+    
+    def get_interface(self) -> gr.Component:
+        """Create the Gradio interface for fortune telling"""
+        with gr.Column() as interface:
+            gr.Markdown("""
+            ## 🔮 Mystic Fortune Teller
+            
+            *Peer into the mists of time and discover your destiny...*
+            
+            **Services Available:**
+            - 🌟 **Daily Fortune** - Receive guidance for your journey
+            - 📜 **Fortune History** - View your past predictions
+            - 🎲 **Lucky Numbers** - Get your lucky numbers for today
+            """)
+            
+            with gr.Row():
+                fortune_btn = gr.Button("🔮 Get My Fortune", variant="primary", scale=2)
+                history_btn = gr.Button("📜 View History", variant="secondary", scale=1)
+                lucky_btn = gr.Button("🎲 Lucky Numbers", variant="secondary", scale=1)
+            
+            fortune_output = gr.Textbox(
+                label="🌟 Your Fortune",
+                lines=5,
+                interactive=False,
+                placeholder="Click 'Get My Fortune' to reveal your destiny..."
+            )
+            
+            def get_player_fortune():
+                # Get current player (simplified - in real implementation use proper session management)
+                current_players = list(game_world.players.keys())
+                if not current_players:
+                    return "❌ You must be in the game to receive a fortune reading!"
+                
+                player_id = max(current_players, key=lambda pid: game_world.players[pid].last_active)
+                player_name = game_world.players[player_id].name
+                
+                return self.get_daily_fortune(player_id, player_name)
+            
+            def get_player_history():
+                current_players = list(game_world.players.keys())
+                if not current_players:
+                    return "❌ You must be in the game to view your fortune history!"
+                
+                player_id = max(current_players, key=lambda pid: game_world.players[pid].last_active)
+                return self.get_fortune_history(player_id)
+            
+            def get_lucky_numbers():
+                current_players = list(game_world.players.keys())
+                if not current_players:
+                    return "❌ You must be in the game to receive lucky numbers!"
+                
+                player_id = max(current_players, key=lambda pid: game_world.players[pid].last_active)
+                return self.generate_lucky_numbers(player_id)
+            
+            fortune_btn.click(get_player_fortune, outputs=[fortune_output])
+            history_btn.click(get_player_history, outputs=[fortune_output])
+            lucky_btn.click(get_lucky_numbers, outputs=[fortune_output])
+        
+        return interface
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle fortune teller commands via private messages"""
+        cmd = command.strip().lower()
+        player_name = game_world.players.get(player_id, {}).get('name', 'Traveler')
+        
+        if cmd in ['fortune', 'predict', 'future', 'tell']:
+            return f"🔮 **Mystic Fortune Teller whispers:**\n\n{self.get_daily_fortune(player_id, player_name)}"
+        
+        elif cmd in ['history', 'past', 'previous']:
+            return f"📜 **Your Fortune History:**\n\n{self.get_fortune_history(player_id)}"
+        
+        elif cmd in ['lucky', 'numbers', 'luck']:
+            return f"🎲 **Lucky Numbers:**\n\n{self.generate_lucky_numbers(player_id)}"
+        
+        else:
+            return ("🔮 **Mystic Fortune Teller:**\n\n"
+                   "I can help you with:\n"
+                   "• Say 'fortune' for your daily prediction\n"
+                   "• Say 'history' to see past fortunes\n"
+                   "• Say 'lucky' for your lucky numbers")
+    
+    def get_daily_fortune(self, player_id: str, player_name: str) -> str:
+        """Get or generate daily fortune for player"""
+        today = time.strftime("%Y-%m-%d")
+        
+        # Check if player already got fortune today
+        if player_id in self.player_fortunes:
+            player_data = self.player_fortunes[player_id]
+            if player_data.get('last_fortune_date') == today:
+                return (f"**{player_name}**, I have already revealed your destiny for today:\n\n"
+                       f"✨ *{player_data['last_fortune']}*\n\n"
+                       f"Return tomorrow for new guidance...")
+        
+        # Generate new fortune
+        fortune = random.choice(self.fortunes)
+        
+        # Store fortune
+        if player_id not in self.player_fortunes:
+            self.player_fortunes[player_id] = {'history': []}
+        
+        self.player_fortunes[player_id].update({
+            'last_fortune': fortune,
+            'last_fortune_date': today
+        })
+        
+        self.player_fortunes[player_id]['history'].append({
+            'date': today,
+            'fortune': fortune,
+            'timestamp': time.time()
+        })
+        
+        # Keep only last 10 fortunes
+        if len(self.player_fortunes[player_id]['history']) > 10:
+            self.player_fortunes[player_id]['history'] = self.player_fortunes[player_id]['history'][-10:]
+        
+        return (f"**{player_name}**, the crystal ball reveals your destiny...\n\n"
+               f"✨ *{fortune}*\n\n"
+               f"May this wisdom guide your path, brave adventurer!")
+    
+    def get_fortune_history(self, player_id: str) -> str:
+        """Get player's fortune history"""
+        if player_id not in self.player_fortunes or not self.player_fortunes[player_id].get('history'):
+            return "The mists show no past... you have not sought guidance before."
+        
+        history = self.player_fortunes[player_id]['history']
+        result = "**Your Past Fortunes:**\n\n"
+        
+        for i, entry in enumerate(reversed(history[-5:]), 1):  # Last 5 fortunes
+            result += f"**{entry['date']}** - {entry['fortune']}\n\n"
+        
+        return result
+    
+    def generate_lucky_numbers(self, player_id: str) -> str:
+        """Generate lucky numbers based on player ID and current date"""
+        # Use player ID and date as seed for consistent daily numbers
+        seed_str = f"{player_id}_{time.strftime('%Y-%m-%d')}"
+        random.seed(hash(seed_str) % (2**32))
+        
+        lucky_nums = sorted(random.sample(range(1, 100), 6))
+        
+        # Reset random seed
+        random.seed()
+        
+        numbers_str = " • ".join(map(str, lucky_nums))
+        
+        return (f"🎲 **Your Lucky Numbers for Today:**\n\n"
+               f"✨ {numbers_str} ✨\n\n"
+               f"These numbers carry special energy today. "
+               f"Use them wisely in your adventures!")
+```
+
+---
+
+## Advanced Add-on with State Management
+
+Here's a more complex example - a **Blacksmith NPC** that can upgrade weapons and manage an inventory:
+
+```python
+import json
+from datetime import datetime, timedelta
+
+class BlacksmithAddon(NPCAddon):
+    """Advanced Blacksmith NPC with weapon upgrading and inventory management"""
+    
+    def __init__(self):
+        self.weapons_catalog = {
+            'iron_sword': {'name': 'Iron Sword', 'base_damage': 10, 'upgrade_cost': 50},
+            'steel_sword': {'name': 'Steel Sword', 'base_damage': 15, 'upgrade_cost': 100},
+            'silver_sword': {'name': 'Silver Sword', 'base_damage': 20, 'upgrade_cost': 200},
+            'mithril_sword': {'name': 'Mithril Sword', 'base_damage': 30, 'upgrade_cost': 500},
+        }
+        
+        self.player_weapons: Dict[str, Dict] = {}  # player_id -> weapon data
+        self.upgrade_queue: List[Dict] = []  # Weapons being upgraded
+        self.shop_inventory = self.initialize_shop_inventory()
+    
+    def initialize_shop_inventory(self):
+        """Initialize blacksmith shop inventory"""
+        return {
+            'iron_ore': {'name': 'Iron Ore', 'price': 25, 'stock': 50},
+            'steel_ingot': {'name': 'Steel Ingot', 'price': 75, 'stock': 30},
+            'silver_ore': {'name': 'Silver Ore', 'price': 150, 'stock': 20},
+            'enchant_stone': {'name': 'Enchantment Stone', 'price': 300, 'stock': 10},
+            'repair_kit': {'name': 'Weapon Repair Kit', 'price': 40, 'stock': 25},
+        }
+    
+    @property
+    def addon_id(self) -> str:
+        return "blacksmith"
+    
+    @property
+    def addon_name(self) -> str:
+        return "⚒️ Master Blacksmith"
+    
+    def get_interface(self) -> gr.Component:
+        with gr.Column() as interface:
+            gr.Markdown("""
+            ## ⚒️ Master Blacksmith Forge
+            
+            *Welcome to the finest smithy in the realm!*
+            
+            **Services:**
+            - 🗡️ **Weapon Upgrades** - Enhance your weapons for better damage
+            - 🛒 **Shop** - Buy materials and repair kits
+            - 📦 **Inventory** - View your weapons and materials
+            - 🔧 **Repairs** - Fix damaged equipment
+            """)
+            
+            with gr.Tabs():
+                with gr.Tab("🗡️ Weapon Upgrade"):
+                    with gr.Row():
+                        weapon_select = gr.Dropdown(
+                            choices=list(self.weapons_catalog.keys()),
+                            label="Select Weapon to Upgrade",
+                            value="iron_sword"
+                        )
+                        upgrade_level = gr.Number(
+                            label="Upgrade Level (+1 to +10)",
+                            value=1,
+                            minimum=1,
+                            maximum=10
+                        )
+                    
+                    upgrade_info = gr.HTML(label="Upgrade Information")
+                    upgrade_btn = gr.Button("⚒️ Start Upgrade", variant="primary")
+                    upgrade_result = gr.Textbox(label="Result", lines=5)
+                    
+                    def calculate_upgrade_info(weapon, level):
+                        if weapon in self.weapons_catalog:
+                            weapon_data = self.weapons_catalog[weapon]
+                            base_cost = weapon_data['upgrade_cost']
+                            total_cost = base_cost * level * (level + 1) // 2  # Progressive cost
+                            new_damage = weapon_data['base_damage'] + (level * 2)
+                            time_required = level * 30  # 30 seconds per level
+                            
+                            return f"""
+                            <div style="background: #f0f8ff; padding: 15px; border-radius: 8px; border-left: 4px solid #4682b4;">
+                                <h4>🗡️ {weapon_data['name']} +{level}</h4>
+                                <p><strong>Base Damage:</strong> {weapon_data['base_damage']} → {new_damage}</p>
+                                <p><strong>Upgrade Cost:</strong> {total_cost} gold</p>
+                                <p><strong>Time Required:</strong> {time_required} seconds</p>
+                            </div>
+                            """
+                        return "Select a weapon to see upgrade information."
+                    
+                    weapon_select.change(calculate_upgrade_info, [weapon_select, upgrade_level], upgrade_info)
+                    upgrade_level.change(calculate_upgrade_info, [weapon_select, upgrade_level], upgrade_info)
+                    
+                    def handle_upgrade(weapon, level):
+                        current_players = list(game_world.players.keys())
+                        if not current_players:
+                            return "❌ You must be in the game to upgrade weapons!"
+                        
+                        player_id = max(current_players, key=lambda pid: game_world.players[pid].last_active)
+                        return self.start_weapon_upgrade(player_id, weapon, int(level))
+                    
+                    upgrade_btn.click(handle_upgrade, [weapon_select, upgrade_level], upgrade_result)
+                
+                with gr.Tab("🛒 Shop"):
+                    shop_display = gr.HTML()
+                    
+                    with gr.Row():
+                        item_select = gr.Dropdown(
+                            choices=list(self.shop_inventory.keys()),
+                            label="Select Item",
+                            value=list(self.shop_inventory.keys())[0]
+                        )
+                        quantity = gr.Number(label="Quantity", value=1, minimum=1, maximum=99)
+                    
+                    buy_btn = gr.Button("💰 Purchase", variant="primary")
+                    purchase_result = gr.Textbox(label="Purchase Result", lines=3)
+                    
+                    def update_shop_display():
+                        html = "<div style='background: #f9f9f9; padding: 15px; border-radius: 8px;'>"
+                        html += "<h4>🛒 Shop Inventory</h4>"
+                        for item_id, item_data in self.shop_inventory.items():
+                            html += f"""
+                            <div style='margin: 10px 0; padding: 10px; background: white; border-radius: 4px;'>
+                                <strong>{item_data['name']}</strong><br>
+                                Price: {item_data['price']} gold | Stock: {item_data['stock']}
+                            </div>
+                            """
+                        html += "</div>"
+                        return html
+                    
+                    def handle_purchase(item, qty):
+                        current_players = list(game_world.players.keys())
+                        if not current_players:
+                            return "❌ You must be in the game to make purchases!"
+                        
+                        player_id = max(current_players, key=lambda pid: game_world.players[pid].last_active)
+                        return self.purchase_item(player_id, item, int(qty))
+                    
+                    buy_btn.click(handle_purchase, [item_select, quantity], purchase_result)
+                    
+                    # Update shop display on tab load
+                    shop_display.value = update_shop_display()
+                
+                with gr.Tab("📦 My Weapons"):
+                    refresh_btn = gr.Button("🔄 Refresh Inventory")
+                    inventory_display = gr.JSON(label="Your Weapons & Materials")
+                    
+                    def refresh_inventory():
+                        current_players = list(game_world.players.keys())
+                        if not current_players:
+                            return {"error": "You must be in the game to view inventory!"}
+                        
+                        player_id = max(current_players, key=lambda pid: game_world.players[pid].last_active)
+                        return self.get_player_inventory(player_id)
+                    
+                    refresh_btn.click(refresh_inventory, outputs=inventory_display)
+        
+        return interface
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle blacksmith commands via private messages"""
+        cmd_parts = command.strip().lower().split()
+        cmd = cmd_parts[0] if cmd_parts else ""
+        
+        player = game_world.players.get(player_id)
+        player_name = player.name if player else "Traveler"
+        
+        if cmd in ['upgrade', 'enhance']:
+            if len(cmd_parts) < 2:
+                return ("⚒️ **Master Blacksmith:**\n\n"
+                       "To upgrade a weapon, specify: `upgrade [weapon_name] [level]`\n"
+                       f"Available weapons: {', '.join(self.weapons_catalog.keys())}")
+            
+            weapon = cmd_parts[1]
+            level = int(cmd_parts[2]) if len(cmd_parts) > 2 else 1
+            
+            return self.start_weapon_upgrade(player_id, weapon, level)
+        
+        elif cmd == 'shop':
+            return self.format_shop_for_message()
+        
+        elif cmd == 'inventory':
+            inventory = self.get_player_inventory(player_id)
+            return f"📦 **Your Inventory:**\n\n{json.dumps(inventory, indent=2)}"
+        
+        elif cmd in ['buy', 'purchase']:
+            if len(cmd_parts) < 2:
+                return "💰 Specify what you want to buy: `buy [item_name] [quantity]`"
+            
+            item = cmd_parts[1]
+            quantity = int(cmd_parts[2]) if len(cmd_parts) > 2 else 1
+            
+            return self.purchase_item(player_id, item, quantity)
+        
+        else:
+            return ("⚒️ **Master Blacksmith:**\n\n"
+                   "I can help you with:\n"
+                   "• `upgrade [weapon] [level]` - Upgrade weapons\n"
+                   "• `shop` - View available items\n"
+                   "• `buy [item] [qty]` - Purchase materials\n"
+                   "• `inventory` - Check your weapons")
+    
+    def start_weapon_upgrade(self, player_id: str, weapon_type: str, level: int) -> str:
+        """Start weapon upgrade process"""
+        if weapon_type not in self.weapons_catalog:
+            return f"❌ Unknown weapon type: {weapon_type}"
+        
+        if level < 1 or level > 10:
+            return "❌ Upgrade level must be between 1 and 10"
+        
+        weapon_data = self.weapons_catalog[weapon_type]
+        cost = weapon_data['upgrade_cost'] * level * (level + 1) // 2
+        
+        # Check if player has enough gold (simplified - use game's gold system)
+        player = game_world.players.get(player_id)
+        if not player or player.gold < cost:
+            return f"❌ Insufficient gold! Need {cost} gold for this upgrade."
+        
+        # Deduct gold
+        player.gold -= cost
+        
+        # Add to upgrade queue
+        upgrade_id = f"upgrade_{int(time.time())}_{player_id}"
+        completion_time = time.time() + (level * 30)  # 30 seconds per level
+        
+        self.upgrade_queue.append({
+            'id': upgrade_id,
+            'player_id': player_id,
+            'weapon_type': weapon_type,
+            'level': level,
+            'completion_time': completion_time
+        })
+        
+        return (f"⚒️ **Upgrade Started!**\n\n"
+               f"Weapon: {weapon_data['name']} +{level}\n"
+               f"Cost: {cost} gold (paid)\n"
+               f"Completion: {level * 30} seconds\n\n"
+               f"Your weapon is now being forged...")
+    
+    def purchase_item(self, player_id: str, item_id: str, quantity: int) -> str:
+        """Handle item purchases"""
+        if item_id not in self.shop_inventory:
+            return f"❌ Item '{item_id}' not available"
+        
+        item = self.shop_inventory[item_id]
+        
+        if quantity > item['stock']:
+            return f"❌ Only {item['stock']} {item['name']} in stock"
+        
+        total_cost = item['price'] * quantity
+        player = game_world.players.get(player_id)
+        
+        if not player or player.gold < total_cost:
+            return f"❌ Need {total_cost} gold for this purchase"
+        
+        # Process purchase
+        player.gold -= total_cost
+        item['stock'] -= quantity
+        
+        # Add to player inventory
+        if player_id not in self.player_weapons:
+            self.player_weapons[player_id] = {'materials': {}}
+        
+        materials = self.player_weapons[player_id].setdefault('materials', {})
+        materials[item_id] = materials.get(item_id, 0) + quantity
+        
+        return (f"✅ **Purchase Successful!**\n\n"
+               f"Bought: {quantity}x {item['name']}\n"
+               f"Cost: {total_cost} gold\n"
+               f"Remaining gold: {player.gold}")
+    
+    def get_player_inventory(self, player_id: str) -> Dict:
+        """Get player's weapon and material inventory"""
+        if player_id not in self.player_weapons:
+            return {"weapons": [], "materials": {}}
+        
+        return self.player_weapons[player_id]
+    
+    def format_shop_for_message(self) -> str:
+        """Format shop inventory for private message"""
+        result = "🛒 **Blacksmith Shop**\n\n"
+        for item_id, item_data in self.shop_inventory.items():
+            result += f"**{item_data['name']}** - {item_data['price']} gold (Stock: {item_data['stock']})\n"
+        
+        result += "\nTo buy: `buy [item_name] [quantity]`"
+        return result
+```
+
+---
+
+## MCP-Powered Add-on
+
+Here's how to create an add-on that connects to an external MCP server:
+
+```python
+import asyncio
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from contextlib import AsyncExitStack
+
+class WeatherOracleAddon(NPCAddon):
+    """Weather Oracle powered by external MCP weather service"""
+    
+    def __init__(self, mcp_server_url: str = "https://chris4k-weather.hf.space/gradio_api/mcp/sse"):
+        self.mcp_server_url = mcp_server_url
+        self.mcp_client = None
+        self.connected = False
+        self.tools = []
+        self.exit_stack = None
+        
+        # Set up event loop for async operations
+        self.loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self.loop)
+        
+        # Auto-connect on initialization
+        self.connect_to_mcp()
+    
+    @property
+    def addon_id(self) -> str:
+        return "weather_oracle"
+    
+    @property
+    def addon_name(self) -> str:
+        return "🌤️ Weather Oracle"
+    
+    def connect_to_mcp(self) -> str:
+        """Connect to the MCP weather server"""
+        return self.loop.run_until_complete(self._connect())
+    
+    async def _connect(self) -> str:
+        try:
+            # Clean up previous connection
+            if self.exit_stack:
+                await self.exit_stack.aclose()
+            
+            self.exit_stack = AsyncExitStack()
+            
+            # Connect to SSE MCP server
+            sse_transport = await self.exit_stack.enter_async_context(
+                sse_client(self.mcp_server_url)
+            )
+            read_stream, write_callable = sse_transport
+            
+            self.mcp_client = await self.exit_stack.enter_async_context(
+                ClientSession(read_stream, write_callable)
+            )
+            await self.mcp_client.initialize()
+            
+            # Get available tools
+            response = await self.mcp_client.list_tools()
+            self.tools = response.tools
+            
+            self.connected = True
+            tool_names = [tool.name for tool in self.tools]
+            return f"✅ Connected to weather server! Tools: {', '.join(tool_names)}"
+            
+        except Exception as e:
+            self.connected = False
+            return f"❌ Connection failed: {str(e)}"
+    
+    def get_interface(self) -> gr.Component:
+        with gr.Column() as interface:
+            gr.Markdown("""
+            ## 🌤️ Weather Oracle
+            
+            *I commune with the spirits of sky and storm to bring you weather wisdom from across the realms!*
+            
+            **Ask me about weather in any city:**
+            - Current conditions and temperature
+            - Weather forecasts
+            - Climate information
+            
+            *Format: "City, Country" (e.g., "Berlin, Germany")*
+            """)
+            
+            # Connection status
+            connection_status = gr.HTML(
+                value=f"<div style='color: {'green' if self.connected else 'red'};'>{'🟢 Connected to weather spirits' if self.connected else '🔴 Disconnected from weather realm'}</div>"
+            )
+            
+            with gr.Row():
+                location_input = gr.Textbox(
+                    label="Location",
+                    placeholder="e.g., Berlin, Germany",
+                    scale=3
+                )
+                get_weather_btn = gr.Button("🌡️ Consult Weather Spirits", variant="primary", scale=1)
+            
+            weather_output = gr.Textbox(
+                label="🌤️ Weather Wisdom",
+                lines=8,
+                interactive=False,
+                placeholder="Enter a location and I will consult the weather spirits..."
+            )
+            
+            # Example locations
+            with gr.Row():
+                gr.Examples(
+                    examples=[
+                        ["Berlin, Germany"],
+                        ["Tokyo, Japan"], 
+                        ["New York, USA"],
+                        ["London, UK"],
+                        ["Sydney, Australia"],
+                        ["Paris, France"],
+                        ["Moscow, Russia"]
+                    ],
+                    inputs=[location_input],
+                    label="🌍 Try These Locations"
+                )
+            
+            def handle_weather_request(location: str):
+                current_players = list(game_world.players.keys())
+                if not current_players:
+                    return "❌ You must be in the game to consult the weather spirits!"
+                
+                player_id = max(current_players, key=lambda pid: game_world.players[pid].last_active)
+                
+                return self.get_weather_prediction(location, player_id)
+            
+            get_weather_btn.click(
+                handle_weather_request,
+                inputs=[location_input],
+                outputs=[weather_output]
+            )
+            
+            location_input.submit(
+                handle_weather_request,
+                inputs=[location_input], 
+                outputs=[weather_output]
+            )
+        
+        return interface
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle weather oracle commands via private messages"""
+        cmd = command.strip()
+        
+        if not cmd:
+            return ("🌤️ **Weather Oracle whispers:**\n\n"
+                   "Ask me about the weather in any city!\n"
+                   "Format: 'City, Country' (e.g., 'Berlin, Germany')")
+        
+        # Treat any non-empty command as a location request
+        result = self.get_weather_prediction(cmd, player_id)
+        return f"🌤️ **Weather Oracle reveals:**\n\n{result}"
+    
+    def get_weather_prediction(self, location: str, player_id: str = None) -> str:
+        """Get weather prediction for location"""
+        if not self.connected:
+            # Try to reconnect
+            connect_result = self.connect_to_mcp()
+            if not self.connected:
+                return f"🌫️ The weather spirits are silent... Connection lost: {connect_result}"
+        
+        if not location.strip():
+            return "🌪️ The spirits need to know which realm you seek knowledge about!"
+        
+        return self.loop.run_until_complete(self._get_weather_async(location, player_id))
+    
+    async def _get_weather_async(self, location: str, player_id: str = None) -> str:
+        try:
+            # Parse location
+            if ',' in location:
+                city, country = [part.strip() for part in location.split(',', 1)]
+            else:
+                city = location.strip()
+                country = ""
+            
+            # Find the weather tool
+            weather_tool = next((tool for tool in self.tools if 'weather' in tool.name.lower()), None)
+            if not weather_tool:
+                return "🌫️ The weather spirits have retreated... No weather tools available."
+            
+            # Call the MCP weather tool
+            params = {"city": city, "country": country}
+            result = await self.mcp_client.call_tool(weather_tool.name, params)
+            
+            # Extract and format the weather data
+            content_text = self._extract_content(result)
+            
+            if not content_text:
+                return "🌫️ The weather spirits speak in riddles I cannot decipher..."
+            
+            # Try to parse and format the weather data
+            formatted_result = self._format_weather_response(content_text, city, country)
+            
+            # Log the interaction
+            if player_id and player_id in game_world.players:
+                player_name = game_world.players[player_id].name
+                print(f"[WEATHER_ORACLE] {player_name} asked about weather in {location}")
+            
+            return formatted_result
+            
+        except Exception as e:
+            return f"🌩️ The weather spirits are troubled: {str(e)}"
+    
+    def _extract_content(self, result) -> str:
+        """Extract content from MCP response"""
+        content_text = ""
+        if hasattr(result, 'content') and result.content:
+            if isinstance(result.content, list):
+                for content_item in result.content:
+                    if hasattr(content_item, 'text'):
+                        content_text += content_item.text
+                    elif hasattr(content_item, 'content'):
+                        content_text += str(content_item.content)
+                    else:
+                        content_text += str(content_item)
+            elif hasattr(result.content, 'text'):
+                content_text = result.content.text
+            else:
+                content_text = str(result.content)
+        return content_text
+    
+    def _format_weather_response(self, content_text: str, city: str, country: str) -> str:
+        """Format weather response in a mystical way"""
+        try:
+            # Try to parse as JSON
+            parsed = json.loads(content_text)
+            if isinstance(parsed, dict):
+                if 'error' in parsed:
+                    return f"🌫️ The spirits say: {parsed['error']}"
+                
+                # Format with mystical flair
+                location_name = parsed.get('location', f"{city}, {country}")
+                
+                if 'current_weather' in parsed:
+                    weather = parsed['current_weather']
+                    temp = weather.get('temperature_celsius', 'Unknown')
+                    conditions = weather.get('weather_description', 'mysterious')
+                    wind = weather.get('wind_speed_kmh', 'calm')
+                    humidity = weather.get('humidity_percent', 'balanced')
+                    
+                    return (f"🌍 **The spirits speak of {location_name}:**\n\n"
+                           f"🌡️ **Temperature:** {temp}°C - The fire spirits dance at this warmth\n"
+                           f"🌤️ **Conditions:** {conditions} - The sky spirits reveal their mood\n"
+                           f"💨 **Wind:** {wind} km/h - The air spirits move with purpose\n"
+                           f"💧 **Humidity:** {humidity}% - The water spirits' presence\n\n"
+                           f"*May this knowledge guide your journey, brave traveler!*")
+                
+                elif 'temperature (°C)' in parsed:
+                    temp = parsed.get('temperature (°C)', 'Unknown')
+                    weather_code = parsed.get('weather_code', 'Unknown')
+                    timezone = parsed.get('timezone', 'Unknown')
+                    local_time = parsed.get('local_time', 'Unknown')
+                    
+                    return (f"🌍 **The ancient spirits whisper of {location_name}:**\n\n"
+                           f"🌡️ **Sacred Temperature:** {temp}°C\n"
+                           f"🌤️ **Weather Rune:** {weather_code}\n"
+                           f"🕐 **Realm:** {timezone}\n"
+                           f"🕒 **Current Time:** {local_time}\n\n"
+                           f"*The weather spirits have spoken!*")
+                
+                else:
+                    return f"✨ **Weather spirits reveal:**\n```\n{json.dumps(parsed, indent=2)}\n```"
+                    
+        except json.JSONDecodeError:
+            # If not JSON, format as mystical text
+            return f"🌟 **The weather spirits whisper:**\n\n{content_text}\n\n*Such is their ancient wisdom...*"
+        
+        return f"🌫️ The spirits speak in riddles: {content_text}"
+```
+
+---
+
+## Integration into the Game
+
+To integrate your new add-on into the game, follow these steps:
+
+### 1. Register the Add-on
+
+In your main game file (`app.py`), add your add-on to the `create_mmorpg_interface()` function:
+
+```python
+def create_mmorpg_interface():
+    """Create the complete MMORPG interface with all features"""
+    
+    # Initialize add-ons
+    read2burn_addon = Read2BurnMailboxAddon()
+    game_world.addon_npcs['read2burn_mailbox'] = read2burn_addon
+    
+    # Add your new add-ons here
+    fortune_teller_addon = FortuneTellerAddon()
+    game_world.addon_npcs['fortune_teller'] = fortune_teller_addon
+    
+    blacksmith_addon = BlacksmithAddon()
+    game_world.addon_npcs['blacksmith'] = blacksmith_addon
+    
+    weather_oracle_addon = WeatherOracleAddon()
+    game_world.addon_npcs['weather_oracle'] = weather_oracle_addon
+    
+    # ... rest of the interface code
+```
+
+### 2. Add NPC to the World
+
+Add your NPC to the game world's NPC dictionary:
+
+```python
+def __init__(self):
+    self.npcs: Dict[str, Dict] = {
+        # ... existing NPCs ...
+        
+        'fortune_teller': {
+            'id': 'fortune_teller',
+            'name': 'Mystic Zelda',
+            'x': 125, 'y': 75,
+            'char': '🔮',
+            'type': 'addon'
+        },
+        'blacksmith': {
+            'id': 'blacksmith',
+            'name': 'Master Forge',
+            'x': 400, 'y': 300,
+            'char': '⚒️',
+            'type': 'addon'
+        },
+        # weather_oracle already exists
+    }
+```
+
+### 3. Add Interface Tab
+
+Add your add-on's interface to the NPC Add-ons tab:
+
+```python
+with gr.Tab("🤖 NPC Add-ons"):
+    with gr.Tabs() as addon_tabs:
+        # Existing add-ons
+        with gr.Tab("🔥 Read2Burn Mailbox"):
+            read2burn_addon.get_interface()
+        
+        with gr.Tab("🌤️ Weather Oracle"):
+            weather_oracle_addon.get_interface()
+        
+        # Add your new add-ons here
+        with gr.Tab("🔮 Fortune Teller"):
+            fortune_teller_addon.get_interface()
+        
+        with gr.Tab("⚒️ Blacksmith"):
+            blacksmith_addon.get_interface()
+```
+
+---
+
+## Best Practices
+
+### 1. Error Handling
+
+Always include proper error handling in your add-ons:
+
+```python
+def handle_command(self, player_id: str, command: str) -> str:
+    try:
+        # Your command logic here
+        return self.process_command(player_id, command)
+    except Exception as e:
+        print(f"[{self.addon_id}] Error: {e}")
+        return f"⚠️ Something went wrong: {str(e)}"
+```
+
+### 2. Player Validation
+
+Always validate that players exist before processing commands:
+
+```python
+def get_current_player(self):
+    """Get the current active player safely"""
+    current_players = list(game_world.players.keys())
+    if not current_players:
+        return None, "❌ You must be in the game to use this service!"
+    
+    player_id = max(current_players, key=lambda pid: game_world.players[pid].last_active)
+    player = game_world.players.get(player_id)
+    
+    if not player:
+        return None, "❌ Player not found!"
+    
+    return player, None
+```
+
+### 3. State Persistence
+
+For add-ons that maintain state, consider implementing save/load functionality:
+
+```python
+import json
+import os
+
+class StatefulAddon(NPCAddon):
+    def __init__(self):
+        self.state_file = f"addon_state_{self.addon_id}.json"
+        self.load_state()
+    
+    def save_state(self):
+        """Save add-on state to file"""
+        try:
+            state_data = {
+                'player_data': self.player_data,
+                'global_settings': self.global_settings,
+                'last_saved': time.time()
+            }
+            with open(self.state_file, 'w') as f:
+                json.dump(state_data, f, indent=2)
+        except Exception as e:
+            print(f"[{self.addon_id}] Failed to save state: {e}")
+    
+    def load_state(self):
+        """Load add-on state from file"""
+        try:
+            if os.path.exists(self.state_file):
+                with open(self.state_file, 'r') as f:
+                    state_data = json.load(f)
+                    self.player_data = state_data.get('player_data', {})
+                    self.global_settings = state_data.get('global_settings', {})
+            else:
+                self.player_data = {}
+                self.global_settings = {}
+        except Exception as e:
+            print(f"[{self.addon_id}] Failed to load state: {e}")
+            self.player_data = {}
+            self.global_settings = {}
+```
+
+### 4. Async Operations
+
+For add-ons that need to perform async operations (like MCP calls), use proper async handling:
+
+```python
+def sync_wrapper_for_async_function(self, *args, **kwargs):
+    """Wrapper to run async functions in sync context"""
+    if not hasattr(self, 'loop') or self.loop.is_closed():
+        self.loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self.loop)
+    
+    return self.loop.run_until_complete(self.async_function(*args, **kwargs))
+```
+
+### 5. Resource Management
+
+Clean up resources properly:
+
+```python
+def __del__(self):
+    """Cleanup when add-on is destroyed"""
+    if hasattr(self, 'exit_stack') and self.exit_stack:
+        try:
+            asyncio.run(self.exit_stack.aclose())
+        except:
+            pass
+    
+    self.save_state()  # Save state before destruction
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Add-on not appearing in interface**
+   - Check that you registered it in `game_world.addon_npcs`
+   - Verify the addon_id matches the NPC ID
+   - Ensure no exceptions in `get_interface()`
+
+2. **Private messages not working**
+   - Verify `handle_command()` is implemented
+   - Check that the NPC ID exists in `game_world.npcs`
+   - Make sure the addon is registered correctly
+
+3. **MCP connection issues**
+   - Check the MCP server URL is correct
+   - Verify the server is running and accessible
+   - Look for async/await issues in your code
+
+4. **State not persisting**
+   - Implement proper save/load methods
+   - Handle file permissions issues
+   - Check for JSON serialization errors
+
+### Debug Tips
+
+1. **Add logging** to your add-ons:
+```python
+import logging
+
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger(f"addon_{self.addon_id}")
+
+def handle_command(self, player_id: str, command: str) -> str:
+    logger.debug(f"Received command '{command}' from player {player_id}")
+    # ... rest of method
+```
+
+2. **Test your add-on standalone**:
+```python
+if __name__ == "__main__":
+    # Test your add-on independently
+    addon = YourAddon()
+    test_result = addon.handle_command("test_player", "test command")
+    print(f"Test result: {test_result}")
+```
+
+3. **Use the browser console** to debug Gradio interface issues
+
+4. **Check the game's world events** for proximity detection issues
+
+---
+
+## Advanced Features
+
+### Dynamic Add-on Loading
+
+You can implement dynamic add-on loading for hot-swapping add-ons:
+
+```python
+import importlib
+import os
+
+def load_addon_from_file(filepath: str, addon_class_name: str):
+    """Dynamically load an add-on from a Python file"""
+    try:
+        spec = importlib.util.spec_from_file_location("dynamic_addon", filepath)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        
+        addon_class = getattr(module, addon_class_name)
+        return addon_class()
+    except Exception as e:
+        print(f"Failed to load addon from {filepath}: {e}")
+        return None
+```
+
+### Configuration Files
+
+Use configuration files for add-on settings:
+
+```python
+import yaml
+
+class ConfigurableAddon(NPCAddon):
+    def __init__(self, config_file: str = None):
+        self.config = self.load_config(config_file or f"{self.addon_id}_config.yaml")
+    
+    def load_config(self, config_file: str):
+        try:
+            with open(config_file, 'r') as f:
+                return yaml.safe_load(f)
+        except:
+            return self.get_default_config()
+    
+    def get_default_config(self):
+        return {
+            'enabled': True,
+            'max_operations_per_player': 10,
+            'cooldown_seconds': 30
+        }
+```
+
+This comprehensive guide should give you everything you need to create powerful, feature-rich NPC add-ons for the MMORPG game!

Documentation/NPC_Addon_Development_Guide_Updated.md

@@ -0,0 +1,1312 @@
+# 🛠️ NPC Addon Development Guide - Complete & Updated
+
+> **Updated for Current Architecture** - This guide reflects the latest addon system with auto-registration, modern patterns, and actual working examples from the codebase.
+
+## 📋 Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Modern Addon Architecture](#modern-addon-architecture)
+3. [Auto-Registration System](#auto-registration-system)
+4. [Complete Examples](#complete-examples)
+5. [Advanced Patterns](#advanced-patterns)
+6. [MCP Integration](#mcp-integration)
+7. [Best Practices](#best-practices)
+8. [Deployment & Testing](#deployment--testing)
+
+---
+
+## 🚀 Quick Start
+
+### Creating Your First Addon
+
+The modern addon system uses **auto-registration** - no manual edits to other files required!
+
+```python
+# src/addons/my_first_addon.py
+"""
+My First Addon - A simple self-contained NPC addon.
+"""
+
+import gradio as gr
+from ..interfaces.npc_addon import NPCAddon
+
+
+class MyFirstAddon(NPCAddon):
+    """A simple greeting NPC that demonstrates the addon system."""
+    
+    def __init__(self):
+        super().__init__()  # This auto-registers the addon!
+        self.greeting_count = 0
+    
+    @property
+    def addon_id(self) -> str:
+        """Unique identifier - must be unique across all addons"""
+        return "my_first_addon"
+    
+    @property
+    def addon_name(self) -> str:
+        """Display name shown in UI"""
+        return "🤝 My First Addon"
+    
+    @property
+    def npc_config(self) -> Dict[str, Any]:
+        """NPC configuration for auto-placement in world"""
+        return {
+            'id': 'my_first_npc',
+            'name': '🤝 Friendly Greeter',
+            'x': 100, 'y': 100,  # Position in game world
+            'char': '🤝',         # Character emoji
+            'type': 'addon',      # NPC type
+            'description': 'A friendly NPC that greets players'
+        }
+    
+    @property
+    def ui_tab_name(self) -> str:
+        """UI tab name - returns None if no UI tab needed"""
+        return "🤝 Greeter"
+    
+    def get_interface(self) -> gr.Component:
+        """Create the Gradio interface for this addon"""
+        with gr.Column() as interface:
+            gr.Markdown("## 🤝 Friendly Greeter\n*Hello! I'm here to greet players.*")
+            
+            greeting_btn = gr.Button("👋 Get Greeting", variant="primary")
+            greeting_output = gr.Textbox(label="Greeting", lines=3, interactive=False)
+            
+            def get_greeting():
+                self.greeting_count += 1
+                return f"Hello! This is greeting #{self.greeting_count}. Welcome to the game!"
+            
+            greeting_btn.click(get_greeting, outputs=[greeting_output])
+        
+        return interface
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle commands sent via private messages to this NPC"""
+        cmd = command.lower().strip()
+        
+        if cmd in ['hello', 'hi', 'greet']:
+            self.greeting_count += 1
+            return f"🤝 **Friendly Greeter says:**\nHello! Greeting #{self.greeting_count}!"
+        elif cmd == 'help':
+            return "🤝 **Available commands:**\n• hello/hi/greet - Get a greeting\n• help - Show this help"
+        else:
+            return "🤝 **Friendly Greeter:**\nI didn't understand that. Try 'hello' or 'help'!"
+
+
+# Global instance - this triggers auto-registration!
+my_first_addon = MyFirstAddon()
+```
+
+**That's it!** Your addon is now fully functional and auto-registered. No other files need to be modified.
+
+---
+
+## 🏗️ Modern Addon Architecture
+
+### Base Class Structure
+
+All addons inherit from `NPCAddon` which provides:
+
+```python
+class NPCAddon(ABC):
+    """Base class for NPC add-ons with auto-registration support"""
+    
+    def __init__(self):
+        """Initialize and auto-register the addon"""
+        # Auto-register this addon when instantiated
+        _addon_registry[self.addon_id] = self
+    
+    # Required Properties
+    @property
+    @abstractmethod
+    def addon_id(self) -> str: pass
+    
+    @property
+    @abstractmethod
+    def addon_name(self) -> str: pass
+    
+    # Optional Properties
+    @property
+    def npc_config(self) -> Optional[Dict[str, Any]]: return None
+    
+    @property
+    def ui_tab_name(self) -> Optional[str]: return None
+    
+    # Required Methods
+    @abstractmethod
+    def get_interface(self) -> gr.Component: pass
+    
+    @abstractmethod
+    def handle_command(self, player_id: str, command: str) -> str: pass
+    
+    # Optional Lifecycle Methods
+    def on_startup(self): pass
+    def on_shutdown(self): pass
+```
+
+### Core Concepts
+
+1. **Auto-Registration**: Simply instantiating your addon class registers it globally
+2. **Self-Contained**: Everything in one file - NPC config, UI, logic
+3. **Optional Components**: Only implement what you need (UI tab, world NPC, etc.)
+4. **Service Pattern**: Use interfaces for complex functionality
+
+---
+
+## 🔄 Auto-Registration System
+
+### How It Works
+
+1. **Create addon class** that inherits from `NPCAddon`
+2. **Instantiate globally** at the bottom of your addon file
+3. **Auto-discovery** by the game engine at startup
+4. **Automatic registration** of NPCs and UI components
+
+### Current Auto-Registration List
+
+The game engine automatically loads these addons:
+
+```python
+# src/core/game_engine.py
+auto_register_addons = [
+    ('weather_oracle_addon', 'auto_register'),
+    # Add your addon here if using custom auto_register function
+]
+```
+
+### Two Registration Patterns
+
+#### Pattern 1: Global Instance (Recommended)
+```python
+# At bottom of your addon file
+my_addon = MyAddon()  # Auto-registers via __init__
+```
+
+#### Pattern 2: Custom Auto-Register Function
+```python
+def auto_register(game_engine):
+    """Custom registration logic"""
+    try:
+        addon_instance = MyAddon()
+        # Custom registration logic here
+        return True
+    except Exception as e:
+        print(f"Registration failed: {e}")
+        return False
+
+# Add to game_engine.py auto_register_addons list
+```
+
+---
+
+## 📚 Complete Examples
+
+### Example 1: Simple Trader (From Codebase)
+
+```python
+"""
+Simple Trader NPC Add-on - Self-contained NPC with automatic registration.
+"""
+
+import gradio as gr
+from typing import Dict
+from ..interfaces.npc_addon import NPCAddon
+
+
+class SimpleTraderAddon(NPCAddon):
+    """Self-contained trader NPC that handles its own registration and positioning."""
+    
+    def __init__(self):
+        super().__init__()
+        self.inventory = {
+            "Health Potion": {"price": 50, "stock": 10, "description": "Restores 100 HP"},
+            "Magic Scroll": {"price": 150, "stock": 5, "description": "Cast magic spells"},
+            "Iron Sword": {"price": 300, "stock": 3, "description": "Sharp iron weapon"},
+            "Shield": {"price": 200, "stock": 4, "description": "Protective gear"}
+        }
+        self.sales_history = []
+    
+    @property
+    def addon_id(self) -> str:
+        return "simple_trader"
+    
+    @property 
+    def addon_name(self) -> str:
+        return "🛒 Simple Trader"
+    
+    @property
+    def npc_config(self) -> Dict:
+        return {
+            'id': 'simple_trader',
+            'name': '🛒 Simple Trader',
+            'x': 450, 'y': 150,
+            'char': '🛒',
+            'type': 'addon',
+            'personality': 'trader',
+            'description': 'A friendly trader selling useful items'
+        }
+    
+    @property
+    def ui_tab_name(self) -> str:
+        return "🛒 Simple Trader"
+    
+    def get_interface(self) -> gr.Component:
+        """Create the Gradio interface for this addon."""
+        with gr.Column() as interface:
+            gr.Markdown("### 🛒 Simple Trader Shop")
+            gr.Markdown("Browse items and check prices. Use private messages to trade!")
+            
+            # Display inventory
+            inventory_data = []
+            for item, info in self.inventory.items():
+                inventory_data.append([item, f"{info['price']} gold", info['stock'], info['description']])
+            
+            gr.Dataframe(
+                headers=["Item", "Price", "Stock", "Description"],
+                value=inventory_data,
+                interactive=False
+            )
+            
+            gr.Markdown("**Commands:** Send private message to Simple Trader")
+            gr.Markdown("• `buy <item>` - Purchase an item")
+            gr.Markdown("• `inventory` - See available items")
+            gr.Markdown("• `help` - Show all commands")
+        
+        return interface
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle commands sent to this NPC."""
+        parts = command.strip().lower().split()
+        cmd = parts[0] if parts else ""
+        
+        if cmd == "buy" and len(parts) > 1:
+            item_name = " ".join(parts[1:]).title()
+            return self._handle_buy(player_id, item_name)
+        elif cmd == "inventory":
+            return self._show_inventory()
+        elif cmd == "help":
+            return self._show_help()
+        else:
+            return "🛒 **Simple Trader:** I didn't understand. Try 'buy <item>', 'inventory', or 'help'."
+    
+    def _handle_buy(self, player_id: str, item_name: str) -> str:
+        """Handle item purchase."""
+        if item_name not in self.inventory:
+            return f"❌ Sorry, I don't have '{item_name}' in stock."
+        
+        item = self.inventory[item_name]
+        if item['stock'] <= 0:
+            return f"❌ '{item_name}' is out of stock!"
+        
+        # In a real implementation, check player gold and deduct
+        item['stock'] -= 1
+        self.sales_history.append({'player': player_id, 'item': item_name, 'price': item['price']})
+        
+        return f"✅ **Purchase Successful!**\n📦 You bought: {item_name}\n💰 Price: {item['price']} gold\n📊 Stock remaining: {item['stock']}"
+    
+    def _show_inventory(self) -> str:
+        """Show current inventory."""
+        result = "🛒 **Current Inventory:**\n\n"
+        for item, info in self.inventory.items():
+            result += f"**{item}** - {info['price']} gold (Stock: {info['stock']})\n"
+            result += f"  ↳ {info['description']}\n\n"
+        return result
+    
+    def _show_help(self) -> str:
+        """Show help commands."""
+        return """🛒 **Simple Trader Commands:**
+
+**buy <item>** - Purchase an item
+**inventory** - See available items and prices
+**help** - Show this help
+
+💰 **Available Items:**
+• Health Potion, Magic Scroll, Iron Sword, Shield
+
+Example: `buy Health Potion`"""
+
+
+# Global instance for automatic registration
+simple_trader_addon = SimpleTraderAddon()
+```
+
+### Example 2: Read2Burn Messaging (From Codebase)
+
+This example shows a complex addon with state management and service interfaces:
+
+```python
+"""
+Read2Burn Mailbox Add-on - Self-destructing secure messaging system.
+"""
+
+import time
+import random
+import string
+from typing import Dict, List
+from dataclasses import dataclass
+from abc import ABC, abstractmethod
+import gradio as gr
+
+from ..interfaces.npc_addon import NPCAddon
+
+
+@dataclass
+class Read2BurnMessage:
+    """Data class for Read2Burn messages."""
+    id: str
+    creator_id: str
+    content: str
+    created_at: float
+    expires_at: float
+    reads_left: int
+    burned: bool = False
+
+
+class IRead2BurnService(ABC):
+    """Interface for Read2Burn service operations."""
+    
+    @abstractmethod
+    def create_message(self, creator_id: str, content: str) -> str: pass
+    
+    @abstractmethod
+    def read_message(self, reader_id: str, message_id: str) -> str: pass
+    
+    @abstractmethod
+    def list_player_messages(self, player_id: str) -> str: pass
+
+
+class Read2BurnService(IRead2BurnService, NPCAddon):
+    """Service for managing Read2Burn secure messaging."""
+    
+    def __init__(self):
+        super().__init__()
+        self.messages: Dict[str, Read2BurnMessage] = {}
+        self.access_log: List[Dict] = []
+    
+    @property
+    def addon_id(self) -> str:
+        return "read2burn_mailbox"
+    
+    @property
+    def addon_name(self) -> str:
+        return "📧 Read2Burn Secure Mailbox"
+    
+    @property
+    def npc_config(self) -> Dict:
+        return {
+            'id': 'read2burn',
+            'name': '📧 Read2Burn Service',
+            'x': 200, 'y': 100,
+            'char': '📧',
+            'type': 'service',
+            'personality': 'read2burn',
+            'description': 'Secure message service - send private messages that auto-delete after reading'
+        }
+    
+    def get_interface(self) -> gr.Component:
+        """Return Gradio interface for this add-on"""
+        with gr.Column() as interface:
+            gr.Markdown("""
+            ## 📧 Read2Burn Secure Mailbox
+            
+            **Create self-destructing messages that burn after reading!**
+            
+            ### Features:
+            - 🔥 Messages self-destruct after reading
+            - ⏰ 24-hour automatic expiration
+            - 🔒 Secure delivery system
+            - 📊 Message tracking and history
+            """)
+            
+            with gr.Tabs():
+                with gr.Tab("📝 Create Message"):
+                    message_input = gr.Textbox(
+                        label="Message Content",
+                        lines=5,
+                        placeholder="Type your secret message here..."
+                    )
+                    create_btn = gr.Button("🔥 Create Burning Message", variant="primary")
+                    create_output = gr.Textbox(label="Result", lines=3, interactive=False)
+                    
+                    def create_message_ui(content):
+                        # In real implementation, get current player ID
+                        player_id = "current_player"  # Simplified
+                        return self.create_message(player_id, content)
+                    
+                    create_btn.click(create_message_ui, inputs=[message_input], outputs=[create_output])
+                
+                with gr.Tab("🔓 Read Message"):
+                    message_id_input = gr.Textbox(label="Message ID", placeholder="Enter 8-character message ID")
+                    read_btn = gr.Button("📖 Read & Burn Message", variant="secondary")
+                    read_output = gr.Textbox(label="Message Content", lines=5, interactive=False)
+                    
+                    def read_message_ui(msg_id):
+                        player_id = "current_player"  # Simplified
+                        return self.read_message(player_id, msg_id)
+                    
+                    read_btn.click(read_message_ui, inputs=[message_id_input], outputs=[read_output])
+                
+                with gr.Tab("📋 My Messages"):
+                    refresh_btn = gr.Button("🔄 Refresh List")
+                    messages_output = gr.Textbox(label="Your Messages", lines=10, interactive=False)
+                    
+                    def list_messages_ui():
+                        player_id = "current_player"  # Simplified
+                        return self.list_player_messages(player_id)
+                    
+                    refresh_btn.click(list_messages_ui, outputs=[messages_output])
+            
+            gr.Markdown("**💬 Private Message Commands:**")
+            gr.Markdown("• `create Your message here` - Create new message")
+            gr.Markdown("• `read MESSAGE_ID` - Read message (destroys it!)")
+            gr.Markdown("• `list` - Show your created messages")
+            gr.Markdown("• `help` - Show command help")
+        
+        return interface
+        
+    def generate_message_id(self) -> str:
+        """Generate a unique message ID."""
+        return ''.join(random.choices(string.ascii_uppercase + string.digits, k=8))
+    
+    def create_message(self, creator_id: str, content: str) -> str:
+        """Create a new self-destructing message."""
+        message_id = self.generate_message_id()
+        
+        message = Read2BurnMessage(
+            id=message_id,
+            creator_id=creator_id,
+            content=content,  # In production, encrypt this
+            created_at=time.time(),
+            expires_at=time.time() + (24 * 3600),  # 24 hours
+            reads_left=1,
+            burned=False
+        )
+        
+        self.messages[message_id] = message
+        
+        self.access_log.append({
+            'action': 'create',
+            'message_id': message_id,
+            'player_id': creator_id,
+            'timestamp': time.time()
+        })
+        
+        return f"✅ **Message Created Successfully!**\n\n📝 **Message ID:** `{message_id}`\n🔗 Share this ID with the recipient\n⏰ Expires in 24 hours\n🔥 Burns after 1 read"
+    
+    def read_message(self, reader_id: str, message_id: str) -> str:
+        """Read and burn a message."""
+        if message_id not in self.messages:
+            return "❌ Message not found or already burned"
+        
+        message = self.messages[message_id]
+        
+        # Check expiry
+        if time.time() > message.expires_at:
+            del self.messages[message_id]
+            return "❌ Message expired and has been burned"
+        
+        # Check if already burned
+        if message.burned or message.reads_left <= 0:
+            del self.messages[message_id]
+            return "❌ Message has already been burned"
+        
+        # Read the message
+        content = message.content
+        message.reads_left -= 1
+        
+        self.access_log.append({
+            'action': 'read',
+            'message_id': message_id,
+            'player_id': reader_id,
+            'timestamp': time.time()
+        })
+        
+        # Burn the message after reading
+        if message.reads_left <= 0:
+            message.burned = True
+            del self.messages[message_id]
+            return f"🔥 **Message Self-Destructed After Reading**\n\n📖 **Content:** {content}\n\n💨 This message has been permanently destroyed."
+        
+        return f"📖 **Message Content:** {content}\n\n⚠️ Reads remaining: {message.reads_left}"
+    
+    def list_player_messages(self, player_id: str) -> str:
+        """List messages created by a player."""
+        player_messages = [msg for msg in self.messages.values() if msg.creator_id == player_id]
+        
+        if not player_messages:
+            return "📪 No messages found. Create one with: `create Your message here`"
+        
+        result = "📋 **Your Created Messages:**\n\n"
+        for msg in player_messages:
+            status = "🔥 Burned" if msg.burned else f"✅ Active ({msg.reads_left} reads left)"
+            created_time = time.strftime("%Y-%m-%d %H:%M", time.localtime(msg.created_at))
+            expires_time = time.strftime("%Y-%m-%d %H:%M", time.localtime(msg.expires_at))
+            
+            result += f"**ID:** `{msg.id}`\n"
+            result += f"**Status:** {status}\n"
+            result += f"**Created:** {created_time}\n"
+            result += f"**Expires:** {expires_time}\n"
+            result += f"**Preview:** {msg.content[:50]}{'...' if len(msg.content) > 50 else ''}\n\n"
+        
+        return result
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle Read2Burn mailbox commands."""
+        parts = command.strip().split(' ', 1)
+        cmd = parts[0].lower()
+        
+        if cmd == "create" and len(parts) > 1:
+            return self.create_message(player_id, parts[1])
+        elif cmd == "read" and len(parts) > 1:
+            return self.read_message(player_id, parts[1])
+        elif cmd == "list":
+            return self.list_player_messages(player_id)
+        elif cmd == "help":
+            return """📚 **Read2Burn Mailbox Commands:**
+
+**create** `Your secret message here` - Create new message
+**read** `MESSAGE_ID` - Read message (destroys it!)
+**list** - Show your created messages
+**help** - Show this help
+
+🔥 **Features:**
+• Messages self-destruct after reading
+• 24-hour automatic expiration
+• Secure delivery system
+• Anonymous messaging support"""
+        else:
+            return "❓ Invalid command. Try: `create <message>`, `read <id>`, `list`, or `help`"
+
+
+# Global Read2Burn service instance
+read2burn_service = Read2BurnService()
+```
+
+---
+
+## 🌐 MCP Integration
+
+### MCP-Powered Weather Oracle (From Codebase)
+
+This example shows how to integrate external MCP servers:
+
+```python
+"""
+Weather Oracle Add-on - MCP-powered weather information system.
+"""
+
+import time
+import asyncio
+from typing import Dict, Optional
+import gradio as gr
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from contextlib import AsyncExitStack
+
+from ..interfaces.npc_addon import NPCAddon
+
+
+class WeatherOracleService(NPCAddon):
+    """Service for managing Weather Oracle MCP integration."""
+    
+    def __init__(self):
+        super().__init__()
+        self.connected = False
+        self.last_connection_attempt = 0
+        self.connection_cooldown = 30  # 30 seconds between connection attempts
+        self.server_url = "https://chris4k-weather.hf.space/gradio_api/mcp/sse"
+        self.session = None
+        self.tools = []
+        self.exit_stack = None
+        
+        # Set up event loop for async operations
+        try:
+            self.loop = asyncio.get_event_loop()
+        except RuntimeError:
+            self.loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(self.loop)
+    
+    @property
+    def addon_id(self) -> str:
+        return "weather_oracle"
+    
+    @property
+    def addon_name(self) -> str:
+        return "🌤️ Weather Oracle (MCP)"
+    
+    @property
+    def npc_config(self) -> Dict:
+        return {
+            'id': 'weather_oracle',
+            'name': '🌤️ Weather Oracle (MCP)',
+            'x': 150, 'y': 300,
+            'char': '🌤️',
+            'type': 'mcp',
+            'description': 'MCP-powered weather information service'
+        }
+    
+    @property
+    def ui_tab_name(self) -> str:
+        return "🌤️ Weather Oracle"
+    
+    def get_interface(self) -> gr.Component:
+        """Return Gradio interface for this add-on"""
+        with gr.Column() as interface:
+            gr.Markdown("""
+            ## 🌤️ Weather Oracle
+            
+            *I commune with the spirits of sky and storm to bring you weather wisdom from across the realms!*
+            
+            **Ask me about weather in any city:**
+            - Current conditions and temperature
+            - Weather forecasts  
+            - Climate information
+            
+            *Format: "City, Country" (e.g., "Berlin, Germany")*
+            """)
+            
+            # Connection status
+            connection_status = gr.HTML(
+                value=f"<div style='color: {'green' if self.connected else 'red'};'>{'🟢 Connected to weather spirits' if self.connected else '🔴 Disconnected from weather realm'}</div>"
+            )
+            
+            with gr.Row():
+                location_input = gr.Textbox(
+                    label="🌍 Location",
+                    placeholder="Enter city, country (e.g., Berlin, Germany)",
+                    scale=3
+                )
+                get_weather_btn = gr.Button("🌡️ Consult Weather Spirits", variant="primary", scale=1)
+            
+            weather_output = gr.Textbox(
+                label="🌤️ Weather Wisdom",
+                lines=8,
+                interactive=False,
+                placeholder="Enter a location and I will consult the weather spirits..."
+            )
+            
+            # Example locations
+            gr.Examples(
+                examples=[
+                    ["London, UK"],
+                    ["Tokyo, Japan"],
+                    ["New York, USA"],
+                    ["Berlin, Germany"],
+                    ["Sydney, Australia"]
+                ],
+                inputs=[location_input],
+                label="🌍 Try These Locations"
+            )
+            
+            # Connection controls
+            with gr.Row():
+                connect_btn = gr.Button("🔗 Connect to MCP", variant="secondary")
+                status_btn = gr.Button("📊 Check Status", variant="secondary")
+            
+            def handle_weather_request(location: str):
+                if not location.strip():
+                    return "🌪️ The spirits need to know which realm you seek knowledge about!"
+                return self.get_weather(location)
+            
+            def handle_connect():
+                result = self.connect_to_mcp()
+                status = f"<div style='color: {'green' if self.connected else 'red'};'>{'🟢 Connected to weather spirits' if self.connected else '🔴 Disconnected from weather realm'}</div>"
+                return result, status
+            
+            def handle_status():
+                if self.connected:
+                    tool_names = [tool.name for tool in self.tools] if self.tools else []
+                    return f"✅ **Connected to MCP Weather Server**\n\nServer: {self.server_url}\nTools: {', '.join(tool_names) if tool_names else 'None'}"
+                else:
+                    return "❌ **Not Connected**\n\nClick 'Connect to MCP' to establish connection."
+            
+            # Wire up events
+            get_weather_btn.click(
+                handle_weather_request,
+                inputs=[location_input],
+                outputs=[weather_output]
+            )
+            
+            location_input.submit(
+                handle_weather_request,
+                inputs=[location_input], 
+                outputs=[weather_output]
+            )
+            
+            connect_btn.click(
+                handle_connect,
+                outputs=[weather_output, connection_status]
+            )
+            
+            status_btn.click(
+                handle_status,
+                outputs=[weather_output]
+            )
+        
+        return interface
+    
+    def connect_to_mcp(self) -> str:
+        """Connect to MCP weather server."""
+        current_time = time.time()
+        if current_time - self.last_connection_attempt < self.connection_cooldown:
+            return "⏳ Please wait before retrying connection..."
+        
+        self.last_connection_attempt = current_time
+        
+        try:
+            return self.loop.run_until_complete(self._connect())
+        except Exception as e:
+            self.connected = False
+            return f"❌ Connection failed: {str(e)}"
+    
+    async def _connect(self) -> str:
+        """Async connect to MCP server using SSE."""
+        try:
+            # Clean up previous connection
+            if self.exit_stack:
+                await self.exit_stack.aclose()
+
+            self.exit_stack = AsyncExitStack()
+
+            # Connect to SSE MCP server
+            sse_transport = await self.exit_stack.enter_async_context(
+                sse_client(self.server_url)
+            )
+            read_stream, write_callable = sse_transport
+
+            self.session = await self.exit_stack.enter_async_context(
+                ClientSession(read_stream, write_callable)
+            )
+            await self.session.initialize()
+
+            # Get available tools
+            response = await self.session.list_tools()
+            self.tools = response.tools
+
+            self.connected = True
+            tool_names = [tool.name for tool in self.tools]
+            return f"✅ Connected to weather MCP server!\nAvailable tools: {', '.join(tool_names)}"
+
+        except Exception as e:
+            self.connected = False
+            return f"❌ Connection failed: {str(e)}"
+    
+    def get_weather(self, location: str) -> str:
+        """Get weather for a location using actual MCP server"""
+        if not self.connected:
+            # Try to auto-reconnect
+            connect_result = self.connect_to_mcp()
+            if not self.connected:
+                return f"❌ **Not connected to weather spirits**\n\n{connect_result}"
+        
+        try:
+            return self.loop.run_until_complete(self._get_weather(location))
+        except Exception as e:
+            return f"❌ **Weather divination failed**\n\nError: {str(e)}"
+    
+    async def _get_weather(self, location: str) -> str:
+        """Async get weather using MCP."""
+        try:
+            # Parse location
+            if ',' in location:
+                city, country = [part.strip() for part in location.split(',', 1)]
+            else:
+                city = location.strip()
+                country = ""
+
+            # Find the weather tool
+            weather_tool = next((tool for tool in self.tools if 'weather' in tool.name.lower()), None)
+            if not weather_tool:
+                return "❌ Weather tool not found on server"
+
+            # Call the tool
+            params = {"city": city, "country": country}
+            result = await self.session.call_tool(weather_tool.name, params)
+
+            # Extract content properly
+            content_text = ""
+            if hasattr(result, 'content') and result.content:
+                if isinstance(result.content, list):
+                    for content_item in result.content:
+                        if hasattr(content_item, 'text'):
+                            content_text += content_item.text + "\n"
+                        else:
+                            content_text += str(content_item) + "\n"
+                else:
+                    content_text = str(result.content)
+
+            if not content_text.strip():
+                return f"❌ No weather data received for {location}"
+
+            # Format the response
+            return f"🌤️ **Weather Oracle reveals the weather for {location}:**\n\n{content_text.strip()}"
+
+        except Exception as e:
+            return f"❌ Weather divination failed: {str(e)}"
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle Weather Oracle commands."""
+        cmd = command.strip()
+        
+        if not cmd:
+            return ("🌤️ **Weather Oracle whispers:**\n\n"
+                   "Ask me about the weather in any city!\n"
+                   "Format: 'City, Country' (e.g., 'Berlin, Germany')")
+        
+        # Treat any non-empty command as a location request
+        result = self.get_weather(cmd)
+        return f"🌤️ **Weather Oracle reveals:**\n\n{result}"
+
+
+# Custom auto-registration function
+def auto_register(game_engine):
+    """Auto-register the Weather Oracle addon with the game engine."""
+    try:
+        # Create the weather oracle NPC definition
+        weather_oracle_npc = {
+            'id': 'weather_oracle_auto',
+            'name': '🌤️ Weather Oracle (Auto)',
+            'x': 300, 'y': 150,
+            'char': '🌤️',
+            'type': 'mcp',
+            'personality': 'weather_oracle',
+            'description': 'Self-contained MCP-powered weather information service'
+        }
+        
+        # Register the NPC with the NPC service
+        npc_service = game_engine.get_npc_service()
+        npc_service.register_npc('weather_oracle_auto', weather_oracle_npc)
+        
+        # Register the addon for handling private message commands
+        world = game_engine.get_world()
+        if not hasattr(world, 'addon_npcs'):
+            world.addon_npcs = {}
+        world.addon_npcs['weather_oracle_auto'] = weather_oracle_service
+        
+        print("[WeatherOracleAddon] Auto-registered successfully as self-contained addon")
+        return True
+        
+    except Exception as e:
+        print(f"[WeatherOracleAddon] Error during auto-registration: {e}")
+        return False
+
+
+# Global Weather Oracle service instance
+weather_oracle_service = WeatherOracleService()
+```
+
+---
+
+## 🔧 Advanced Patterns
+
+### State Persistence
+
+```python
+import json
+import os
+
+class PersistentAddon(NPCAddon):
+    """Example addon with state persistence."""
+    
+    def __init__(self):
+        super().__init__()
+        self.data_file = f"data/{self.addon_id}_data.json"
+        self.load_state()
+    
+    def load_state(self):
+        """Load addon state from file."""
+        try:
+            if os.path.exists(self.data_file):
+                with open(self.data_file, 'r') as f:
+                    data = json.load(f)
+                    self.player_data = data.get('players', {})
+                    self.settings = data.get('settings', {})
+            else:
+                self.player_data = {}
+                self.settings = {}
+        except Exception as e:
+            print(f"[{self.addon_id}] Failed to load state: {e}")
+            self.player_data = {}
+            self.settings = {}
+    
+    def save_state(self):
+        """Save addon state to file."""
+        try:
+            os.makedirs(os.path.dirname(self.data_file), exist_ok=True)
+            with open(self.data_file, 'w') as f:
+                json.dump({
+                    'players': self.player_data,
+                    'settings': self.settings
+                }, f, indent=2)
+        except Exception as e:
+            print(f"[{self.addon_id}] Failed to save state: {e}")
+    
+    def on_shutdown(self):
+        """Save state when addon shuts down."""
+        self.save_state()
+```
+
+### Player Validation Helper
+
+```python
+def get_current_player(self, game_world):
+    """Helper to safely get current active player."""
+    try:
+        current_players = list(game_world.players.keys())
+        if not current_players:
+            return None, "❌ You must be in the game to use this service!"
+        
+        player_id = max(current_players, key=lambda pid: game_world.players[pid].last_active)
+        player = game_world.players.get(player_id)
+        
+        if not player:
+            return None, "❌ Player not found!"
+        
+        return player, None
+    except Exception as e:
+        return None, f"❌ Error accessing player data: {e}"
+```
+
+### Async Operation Wrapper
+
+```python
+def run_async_safely(self, async_func, *args, **kwargs):
+    """Safely run async functions in sync context."""
+    try:
+        return self.loop.run_until_complete(async_func(*args, **kwargs))
+    except Exception as e:
+        return f"❌ Async operation failed: {e}"
+```
+
+### Configuration Management
+
+```python
+import yaml
+
+class ConfigurableAddon(NPCAddon):
+    """Addon with configuration file support."""
+    
+    def __init__(self):
+        super().__init__()
+        self.config = self.load_config()
+    
+    def load_config(self):
+        """Load configuration from YAML file."""
+        config_file = f"config/{self.addon_id}_config.yaml"
+        try:
+            if os.path.exists(config_file):
+                with open(config_file, 'r') as f:
+                    return yaml.safe_load(f)
+            else:
+                return self.get_default_config()
+        except Exception as e:
+            print(f"[{self.addon_id}] Config load failed: {e}")
+            return self.get_default_config()
+    
+    def get_default_config(self):
+        """Return default configuration."""
+        return {
+            'enabled': True,
+            'max_operations': 100,
+            'cooldown_seconds': 30
+        }
+```
+
+---
+
+## 🎯 Best Practices
+
+### 1. Error Handling
+
+```python
+def handle_command(self, player_id: str, command: str) -> str:
+    """Always wrap command handling in try-catch."""
+    try:
+        # Your command logic here
+        return self.process_command(player_id, command)
+    except Exception as e:
+        print(f"[{self.addon_id}] Command error: {e}")
+        return f"❌ An error occurred. Please try again or contact support."
+```
+
+### 2. Input Validation
+
+```python
+def validate_input(self, input_value: str, max_length: int = 500) -> tuple[bool, str]:
+    """Validate user input."""
+    if not input_value or not input_value.strip():
+        return False, "Input cannot be empty"
+    
+    if len(input_value) > max_length:
+        return False, f"Input too long (max {max_length} characters)"
+    
+    # Add more validation as needed
+    return True, ""
+```
+
+### 3. Rate Limiting
+
+```python
+import time
+from collections import defaultdict
+
+class RateLimitedAddon(NPCAddon):
+    """Addon with rate limiting."""
+    
+    def __init__(self):
+        super().__init__()
+        self.last_command_time = defaultdict(float)
+        self.command_cooldown = 5  # 5 seconds between commands
+    
+    def is_rate_limited(self, player_id: str) -> bool:
+        """Check if player is rate limited."""
+        current_time = time.time()
+        last_time = self.last_command_time[player_id]
+        
+        if current_time - last_time < self.command_cooldown:
+            return True
+        
+        self.last_command_time[player_id] = current_time
+        return False
+```
+
+### 4. Logging
+
+```python
+import logging
+
+class LoggedAddon(NPCAddon):
+    """Addon with proper logging."""
+    
+    def __init__(self):
+        super().__init__()
+        self.logger = logging.getLogger(f"addon_{self.addon_id}")
+        self.logger.setLevel(logging.INFO)
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        self.logger.info(f"Command from {player_id}: {command}")
+        try:
+            result = self.process_command(player_id, command)
+            self.logger.info(f"Command successful for {player_id}")
+            return result
+        except Exception as e:
+            self.logger.error(f"Command failed for {player_id}: {e}")
+            return "❌ Command failed. Please try again."
+```
+
+### 5. Resource Cleanup
+
+```python
+class ResourceManagedAddon(NPCAddon):
+    """Addon with proper resource management."""
+    
+    def __init__(self):
+        super().__init__()
+        self.resources = []  # Track resources
+    
+    def on_shutdown(self):
+        """Clean up resources on shutdown."""
+        for resource in self.resources:
+            try:
+                if hasattr(resource, 'close'):
+                    resource.close()
+                elif hasattr(resource, '__exit__'):
+                    resource.__exit__(None, None, None)
+            except Exception as e:
+                print(f"[{self.addon_id}] Cleanup error: {e}")
+```
+
+---
+
+## 🧪 Deployment & Testing
+
+### Testing Your Addon
+
+Create a test file for your addon:
+
+```python
+# tests/test_my_addon.py
+import pytest
+from src.addons.my_addon import MyAddon
+
+class TestMyAddon:
+    def setup_method(self):
+        """Set up test fixtures."""
+        self.addon = MyAddon()
+    
+    def test_addon_id(self):
+        """Test addon ID is correct."""
+        assert self.addon.addon_id == "my_addon"
+    
+    def test_handle_command_hello(self):
+        """Test hello command."""
+        result = self.addon.handle_command("test_player", "hello")
+        assert "hello" in result.lower()
+    
+    def test_handle_command_invalid(self):
+        """Test invalid command handling."""
+        result = self.addon.handle_command("test_player", "invalid_command")
+        assert "didn't understand" in result.lower() or "help" in result.lower()
+```
+
+### Running Tests
+
+```bash
+# Run all addon tests
+python -m pytest tests/test_*_addon.py -v
+
+# Run specific addon test
+python -m pytest tests/test_my_addon.py -v
+
+# Run with coverage
+python -m pytest tests/test_*_addon.py --cov=src/addons
+```
+
+### Debug Mode
+
+Add debug functionality to your addon:
+
+```python
+class DebuggableAddon(NPCAddon):
+    """Addon with debug capabilities."""
+    
+    def __init__(self):
+        super().__init__()
+        self.debug_mode = os.getenv('ADDON_DEBUG', 'false').lower() == 'true'
+    
+    def debug_log(self, message: str):
+        """Log debug messages."""
+        if self.debug_mode:
+            print(f"[DEBUG:{self.addon_id}] {message}")
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        self.debug_log(f"Received command: {command}")
+        # ... rest of method
+```
+
+### Performance Monitoring
+
+```python
+import time
+from functools import wraps
+
+def monitor_performance(func):
+    """Decorator to monitor function performance."""
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        start_time = time.time()
+        try:
+            result = func(self, *args, **kwargs)
+            duration = time.time() - start_time
+            if duration > 1.0:  # Log slow operations
+                print(f"[{self.addon_id}] Slow operation: {func.__name__} took {duration:.2f}s")
+            return result
+        except Exception as e:
+            duration = time.time() - start_time
+            print(f"[{self.addon_id}] Error in {func.__name__} after {duration:.2f}s: {e}")
+            raise
+    return wrapper
+
+class MonitoredAddon(NPCAddon):
+    """Addon with performance monitoring."""
+    
+    @monitor_performance
+    def handle_command(self, player_id: str, command: str) -> str:
+        # Your command handling logic
+        pass
+```
+
+### Integration Testing
+
+Test your addon with the game engine:
+
+```python
+# tests/test_integration.py
+import asyncio
+from src.core.game_engine import GameEngine
+from src.addons.my_addon import MyAddon
+
+def test_addon_integration():
+    """Test addon integrates properly with game engine."""
+    engine = GameEngine()
+    engine.start()
+    
+    # Check addon is registered
+    world = engine.get_world()
+    assert hasattr(world, 'addon_npcs')
+    assert 'my_addon' in world.addon_npcs
+    
+    # Test NPC exists
+    npc_service = engine.get_npc_service()
+    npc = npc_service.get_npc('my_addon_npc')
+    assert npc is not None
+    
+    engine.stop()
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+**1. Addon Not Auto-Registering**
+- Check that you have a global instance at the bottom of your file
+- Verify `addon_id` is unique and doesn't conflict with others
+- Ensure you're calling `super().__init__()` in your constructor
+
+**2. UI Tab Not Appearing**
+- Check that `ui_tab_name` property returns a string, not None
+- Verify `get_interface()` returns a valid Gradio component
+- Look for exceptions in the console when the interface loads
+
+**3. NPC Not Appearing in World**
+- Verify `npc_config` property returns a valid dictionary
+- Check that the NPC position coordinates are within world bounds
+- Ensure the NPC ID is unique
+
+**4. Private Messages Not Working**
+- Confirm `handle_command()` is implemented
+- Check that the addon is registered in `world.addon_npcs`
+- Verify the NPC ID matches between world registration and addon registry
+
+**5. MCP Connection Issues**
+- Check the MCP server URL is correct and accessible
+- Verify the server is running and supports the expected tools
+- Look for async/await issues in your MCP client code
+- Check firewall and network connectivity
+
+### Debug Checklist
+
+- [ ] Addon file imported without errors
+- [ ] Global instance created at file bottom
+- [ ] All required methods implemented
+- [ ] Properties return correct types
+- [ ] No exceptions in console on startup
+- [ ] NPC appears in world at specified coordinates
+- [ ] UI tab appears in interface (if configured)
+- [ ] Private messages work correctly
+- [ ] Error handling covers edge cases
+
+### Getting Help
+
+1. **Check Logs**: Look for error messages in the console
+2. **Test Individually**: Create a simple test script for your addon
+3. **Validate Configuration**: Ensure all properties return expected values
+4. **Compare Examples**: Look at working addons like SimpleTrader or Read2Burn
+5. **Community Support**: Ask on project forums or GitHub issues
+
+---
+
+## 📚 Additional Resources
+
+- **Interface Reference**: `src/interfaces/npc_addon.py` - Base class documentation
+- **Working Examples**: `src/addons/` - All current addon implementations
+- **Game Engine**: `src/core/game_engine.py` - Auto-registration system
+- **World Management**: `src/core/world.py` - NPC placement and management
+- **MCP Documentation**: [Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk)
+
+---
+
+*This guide reflects the current addon system architecture and includes real examples from the working codebase. All code examples are tested and functional.*

Documentation/ROADMAP.md

@@ -0,0 +1,375 @@
+# 🚀 MMORPG with MCP Integration - Roadmap
+
+## 📋 Current Status (v1.0)
+
+- ✅ **Core Game Engine**: Real-time multiplayer MMORPG with smooth movement
+- ✅ **MCP Integration**: Full Model Context Protocol support with SSE
+- ✅ **Multi-user Support**: Concurrent human and AI agent players
+- ✅ **NPC Addon System**: Extensible NPC architecture with custom addons
+- ✅ **Read2Burn Messaging**: Self-destructing secure message system
+- ✅ **Weather Integration**: Real-time weather data via MCP servers
+- ✅ **Keyboard Controls**: WASD and arrow key support for fluid gameplay
+- ✅ **Web Interface**: Rich Gradio-based user interface
+- ✅ **AI Agent APIs**: Complete MCP tool suite for AI agent integration
+- ✅ **Session Management**: Robust player session handling and state persistence
+- ✅ **Real-time Updates**: Live game world synchronization across all clients
+
+## ✅ Recently Completed Refactoring (December 2024)
+
+### ✅ Clean Architecture Implementation
+- ✅ **Service Layer**: Separated concerns into dedicated service classes (PlayerService, ChatService, NPCService, MCPService, PluginService)
+- ✅ **Facade Pattern**: Implemented GameFacade for simplified API access
+- ✅ **Singleton Pattern**: Refactored GameEngine to use proper singleton implementation
+- ✅ **Dependency Injection**: Improved service management and dependency handling
+
+### ✅ Plugin System Enhancement
+- ✅ **Plugin Architecture**: Enhanced plugin loading and management system
+- ✅ **Trading System Plugin**: Implemented comprehensive trading system with economic mechanics
+- ✅ **Weather Plugin**: Enhanced weather integration with better API management
+- ✅ **Enhanced Chat Plugin**: Advanced chat features with filtering and commands
+
+### ✅ UI/UX Improvements
+- ✅ **Enhanced Interface Manager**: Improved UI component organization and management
+- ✅ **Keyboard Controls**: Enhanced WASD and arrow key handling with better responsiveness
+- ✅ **Bigger Game Map**: Increased map size for better gameplay experience
+- ✅ **Player Tracking**: Improved current player state management
+
+### ✅ NPC System Enhancement
+- ✅ **Donald NPC**: Implemented Donald the Trader with distinctive personality and trading capabilities
+- ✅ **Personality System**: Enhanced NPC personality framework for diverse character interactions
+- ✅ **NPC Service**: Refactored NPC management into dedicated service layer
+
+### ✅ Documentation & Testing
+- ✅ **Developer Documentation**: Updated and corrected development setup documentation
+- ✅ **Test Suite**: Created comprehensive test framework with unit, integration, and E2E tests
+- ✅ **Test Coverage**: Implemented proper test coverage strategy and organization
+- ✅ **Code Quality**: Improved code structure and maintainability
+
+---
+
+## 🎯 Short-term Goals (v1.1 - v1.3)
+
+### v1.1 - Enhanced Gameplay Mechanics
+- [ ] **Quest System**: Dynamic quest generation and completion tracking
+- [ ] **Inventory Management**: Player inventory with items and equipment
+- [ ] **Combat System**: Turn-based or real-time combat mechanics
+- [ ] **Character Progression**: Skill trees and specialization paths
+- [ ] **Resource Gathering**: Mining, crafting, and resource management
+- [ ] **Player Trading**: Secure item and currency exchange system
+- [ ] **Guild System**: Player organizations and group activities
+
+### v1.2 - Advanced MCP Features  
+- [ ] **MCP Marketplace**: Built-in server discovery and rating system
+- [ ] **Custom MCP Tools**: Visual tool builder for non-developers
+- [ ] **Server Composition**: Chain multiple MCP servers for complex workflows
+- [ ] **Authentication & Security**: OAuth2/JWT integration for MCP servers
+- [ ] **Rate Limiting**: Smart request management and throttling
+- [ ] **Server Health Monitoring**: Real-time MCP server status dashboard
+- [ ] **Hot-swapping**: Live addon replacement without server restart
+
+### v1.3 - Social & Collaboration Features
+- [ ] **Player-to-Player Messaging**: Secure private messaging between players
+- [ ] **Voice Chat Integration**: WebRTC voice communication in groups
+- [ ] **Shared Workspaces**: Collaborative areas for team projects
+- [ ] **Event System**: Scheduled events and tournaments
+- [ ] **Leaderboards**: Player rankings and achievement systems
+- [ ] **Mentorship Program**: Experienced players helping newcomers
+- [ ] **Content Sharing**: Share screenshots, videos, and gameplay moments
+
+---
+
+## 🚀 Medium-term Goals (v2.0 - v2.5)
+
+### v2.0 - AI Agent Ecosystem
+- [ ] **Multi-Agent Orchestration**: Coordinated AI agent teams and workflows
+- [ ] **Agent Marketplace**: Community-contributed specialized AI agents  
+- [ ] **Behavior Templates**: Pre-built AI agent behavior patterns
+- [ ] **Learning Framework**: AI agents that learn from player interactions
+- [ ] **Agent Training Grounds**: Sandbox environments for AI development
+- [ ] **Performance Analytics**: Detailed AI agent effectiveness metrics
+- [ ] **Agent Tournaments**: Competitive events between AI agents
+
+### v2.1 - Advanced World Systems
+- [ ] **Procedural World Generation**: Dynamic map creation and expansion
+- [ ] **Day/Night Cycles**: Time-based gameplay mechanics and events
+- [ ] **Weather Effects**: Weather impact on gameplay and NPC behavior
+- [ ] **Economic Simulation**: Supply and demand market simulation
+- [ ] **Political Systems**: Player-driven governance and faction warfare
+- [ ] **Environmental Puzzles**: World-based challenges requiring cooperation
+- [ ] **Dynamic Events**: Emergent world events affecting all players
+
+### v2.2 - Enterprise & Development Platform
+- [ ] **Multi-tenancy**: Support for multiple game instances
+- [ ] **Admin Dashboard**: Comprehensive game administration interface
+- [ ] **Analytics Suite**: Detailed player behavior and system performance metrics
+- [ ] **A/B Testing Framework**: Compare different game mechanics and features
+- [ ] **API Gateway**: RESTful APIs for external integrations
+- [ ] **Webhook System**: Event-driven notifications and integrations
+- [ ] **Documentation Portal**: Interactive API documentation and tutorials
+
+### v2.3 - Mobile & Cross-Platform
+- [ ] **Progressive Web App**: Mobile-optimized web interface
+- [ ] **Native Mobile Apps**: iOS and Android native applications
+- [ ] **Desktop Applications**: Electron-based desktop clients for Windows/Mac/Linux
+- [ ] **Cross-platform Sync**: Seamless experience across all devices
+- [ ] **Offline Mode**: Limited offline gameplay with sync when reconnected
+- [ ] **Cloud Save System**: Player progress backup and restoration
+- [ ] **Push Notifications**: Real-time alerts for important game events
+
+### v2.4 - Advanced Graphics & Performance
+- [ ] **3D Game World**: Three-dimensional game environment with WebGL
+- [ ] **Custom Avatars**: Player avatar customization and equipment visualization
+- [ ] **Animation System**: Smooth character animations and effects
+- [ ] **Sound Design**: Immersive audio experience with spatial sound
+- [ ] **Performance Optimization**: Support for 1000+ concurrent players
+- [ ] **CDN Integration**: Global content delivery for optimal performance
+- [ ] **Edge Computing**: Regional game servers for reduced latency
+
+### v2.5 - AI & Machine Learning Integration
+- [ ] **Intelligent NPCs**: Advanced AI-powered NPCs with natural language understanding
+- [ ] **Procedural Content**: AI-generated quests, stories, and world content
+- [ ] **Player Behavior Prediction**: ML models for personalized experiences
+- [ ] **Automated Moderation**: AI-powered chat moderation and behavior monitoring
+- [ ] **Adaptive Difficulty**: Dynamic game difficulty based on player skill
+- [ ] **Natural Language Interfaces**: Voice and text commands for game control
+- [ ] **Sentiment Analysis**: Real-time mood and engagement tracking
+
+---
+
+## 🌟 Long-term Vision (v3.0+)
+
+### v3.0 - Metaverse Integration
+- [ ] **Virtual Reality Support**: VR headset compatibility and immersive gameplay
+- [ ] **Augmented Reality Features**: AR overlays for real-world gaming experiences
+- [ ] **Blockchain Integration**: NFT items and decentralized ownership
+- [ ] **Cross-game Interoperability**: Character and item portability between games
+- [ ] **Virtual Real Estate**: Player-owned and customizable virtual spaces
+- [ ] **Digital Economy**: Real-world value exchange for in-game assets
+- [ ] **Social VR Spaces**: Virtual meeting rooms and social hangouts
+
+### v3.1 - Research & Academic Platform
+- [ ] **Research Tools**: Built-in data collection and analysis for academic studies
+- [ ] **Experiment Framework**: A/B testing and controlled experiments for researchers
+- [ ] **Ethics Dashboard**: Privacy and consent management for research participants
+- [ ] **Publication Integration**: Direct integration with academic publication workflows
+- [ ] **Collaboration Networks**: Connect researchers studying similar topics
+- [ ] **Open Data Initiative**: Anonymized dataset sharing for the research community
+- [ ] **Grant Integration**: Funding application and management tools
+
+### v3.2 - Autonomous Game Evolution
+- [ ] **Self-modifying Code**: Game systems that evolve based on player feedback
+- [ ] **Emergent Gameplay**: Unplanned game mechanics arising from player behavior
+- [ ] **AI Game Masters**: Autonomous systems managing dynamic storylines
+- [ ] **Player-driven Development**: Community voting on new features and changes
+- [ ] **Genetic Algorithms**: Evolution of game mechanics through player selection
+- [ ] **Quantum Computing**: Quantum-enhanced AI for complex game simulations
+- [ ] **Consciousness Simulation**: Advanced AI entities with apparent consciousness
+
+---
+
+## 🔧 Technical Infrastructure Roadmap
+
+### Performance & Scalability
+- [ ] **Microservices Architecture**: Break down monolithic structure into services
+- [ ] **Container Orchestration**: Kubernetes deployment and management
+- [ ] **Database Sharding**: Horizontal scaling for large player populations
+- [ ] **Caching Layer**: Redis-based multi-level caching system
+- [ ] **Load Balancing**: Intelligent traffic distribution across servers
+- [ ] **Auto-scaling**: Dynamic resource allocation based on demand
+- [ ] **Global CDN**: Worldwide content delivery network integration
+
+### Security & Privacy
+- [ ] **End-to-end Encryption**: Secure all player communications and data
+- [ ] **Multi-factor Authentication**: Enhanced account security options
+- [ ] **Privacy Controls**: Granular privacy settings and data control
+- [ ] **GDPR Compliance**: Full compliance with international privacy regulations
+- [ ] **Security Auditing**: Regular penetration testing and security assessments
+- [ ] **Incident Response**: Automated security incident detection and response
+- [ ] **Zero-trust Architecture**: Comprehensive security model implementation
+
+### Monitoring & Observability
+- [ ] **Distributed Tracing**: End-to-end request flow tracking
+- [ ] **Custom Metrics**: Business-specific KPI tracking and alerting
+- [ ] **Real-time Dashboards**: Live system health and performance monitoring
+- [ ] **Predictive Analytics**: AI-powered system failure prediction
+- [ ] **Automated Remediation**: Self-healing systems for common issues
+- [ ] **Compliance Monitoring**: Automated compliance checking and reporting
+- [ ] **Cost Optimization**: Intelligent resource usage optimization
+
+---
+
+## 📊 Success Metrics & KPIs
+
+### User Engagement
+- **Daily Active Users**: Target 10,000+ DAU by v2.0
+- **Session Duration**: Average session length > 30 minutes
+- **Player Retention**: 30-day retention rate > 60%
+- **User Satisfaction**: Player rating > 4.5/5 stars
+- **Community Growth**: 25%+ monthly community growth
+- **Content Creation**: 1000+ user-generated addons and content
+
+### Technical Performance  
+- **System Uptime**: 99.9% availability target
+- **Response Time**: < 100ms average response time
+- **Concurrent Users**: Support 10,000+ simultaneous players
+- **Scalability**: Linear performance scaling with resources
+- **Error Rate**: < 0.1% error rate across all operations
+- **Data Integrity**: 100% data consistency and backup reliability
+
+### Developer Ecosystem
+- **MCP Server Count**: 500+ community-contributed MCP servers
+- **Active Developers**: 1000+ registered developers in ecosystem
+- **API Usage**: 1M+ API calls per month
+- **Documentation Quality**: 95%+ developer satisfaction with docs
+- **Integration Success**: 90%+ successful first-time integrations
+- **Open Source Contributions**: 100+ external contributors
+
+### Business & Community
+- **Revenue Growth**: Self-sustaining through enterprise licensing
+- **Partner Ecosystem**: 50+ technology and content partners
+- **Academic Adoption**: 25+ universities using platform for research
+- **Media Coverage**: Regular coverage in gaming and tech media
+- **Conference Presence**: Speaking opportunities at major conferences
+- **Industry Recognition**: Awards and recognition from industry organizations
+
+---
+
+## 🤝 Community & Contribution Roadmap
+
+### Open Source Strategy
+- [ ] **License Transition**: Gradual open-sourcing of core components
+- [ ] **Contribution Guidelines**: Clear guidelines for community contributions
+- [ ] **Code of Conduct**: Inclusive community standards and enforcement
+- [ ] **Maintainer Program**: Training and support for community maintainers
+- [ ] **Bounty System**: Paid incentives for high-priority contributions
+- [ ] **Hackathons**: Regular community coding events and competitions
+- [ ] **Grant Program**: Funding for significant community projects
+
+### Educational Initiatives  
+- [ ] **Documentation Expansion**: Comprehensive guides and tutorials
+- [ ] **Video Tutorials**: Professional video content for all skill levels
+- [ ] **Certification Program**: Official certification for developers and researchers
+- [ ] **Workshop Series**: Regular online workshops and training sessions
+- [ ] **University Partnerships**: Curriculum development and student programs
+- [ ] **Mentorship Network**: Connect experienced developers with newcomers
+- [ ] **Research Collaboration**: Joint research projects with academic institutions
+
+### Ecosystem Development
+- [ ] **Developer Tools**: IDE plugins and development environment setup
+- [ ] **Template Library**: Starter templates for common use cases
+- [ ] **Component Marketplace**: Reusable components and assets
+- [ ] **Testing Framework**: Automated testing tools for community developers
+- [ ] **Deployment Tools**: One-click deployment for community servers
+- [ ] **Monitoring Integration**: Built-in monitoring for community deployments
+- [ ] **Support Services**: Professional support options for enterprise users
+
+---
+
+## 📅 Timeline & Milestones
+
+### 2025 Q3-Q4 (v1.1)
+- **July**: Quest system and inventory management
+- **August**: Combat system and character progression  
+- **September**: Resource gathering and player trading
+- **October**: Guild system and enhanced social features
+- **November**: Beta testing and community feedback
+- **December**: v1.1 stable release
+
+### 2026 Q1-Q2 (v1.2-1.3)
+- **Q1**: MCP marketplace and advanced server features
+- **Q2**: Social collaboration features and event system
+
+### 2026 Q3-Q4 (v2.0)
+- **Q3**: AI agent ecosystem and multi-agent orchestration
+- **Q4**: Advanced world systems and procedural generation
+
+### 2027 (v2.1-2.5)
+- **H1**: Enterprise platform and mobile applications
+- **H2**: Advanced graphics and AI/ML integration
+
+### 2028+ (v3.0+)
+- **Metaverse integration and VR/AR support**
+- **Research platform and academic partnerships**
+- **Autonomous game evolution systems**
+
+---
+
+## 💰 Funding & Sustainability
+
+### Revenue Streams
+- [ ] **Enterprise Licensing**: B2B platform licensing for corporations
+- [ ] **Premium Features**: Advanced features for individual users
+- [ ] **Marketplace Commission**: Revenue share from addon and content sales
+- [ ] **Consulting Services**: Implementation and customization services
+- [ ] **Training & Certification**: Educational program revenue
+- [ ] **Research Partnerships**: Funded research collaboration projects
+- [ ] **Cloud Hosting**: Managed hosting services for deployments
+
+### Investment Strategy
+- [ ] **Seed Funding**: Initial development and team expansion
+- [ ] **Series A**: Platform scaling and feature development
+- [ ] **Strategic Partnerships**: Technology and distribution partnerships
+- [ ] **Government Grants**: Research and innovation funding
+- [ ] **Crowdfunding**: Community-supported development initiatives
+- [ ] **Revenue Reinvestment**: Sustainable growth through earned revenue
+- [ ] **IPO Consideration**: Long-term public offering evaluation
+
+---
+
+## 🔮 Innovation & Research Focus
+
+### Emerging Technologies
+- [ ] **Quantum Computing Integration**: Quantum-enhanced game simulations
+- [ ] **Brain-Computer Interfaces**: Direct neural control of game characters
+- [ ] **Advanced AI Models**: Integration of next-generation language models
+- [ ] **Edge AI**: On-device AI processing for enhanced privacy
+- [ ] **5G/6G Optimization**: Ultra-low latency gaming experiences
+- [ ] **Holographic Displays**: Next-generation 3D visualization
+- [ ] **Biometric Integration**: Health and wellness monitoring during gameplay
+
+### Research Collaborations
+- [ ] **AI Ethics Research**: Responsible AI development in gaming
+- [ ] **Human-Computer Interaction**: Innovative interface design research
+- [ ] **Social Psychology**: Understanding multiplayer social dynamics
+- [ ] **Game Theory**: Mathematical modeling of player behavior
+- [ ] **Network Science**: Optimization of multiplayer network architectures
+- [ ] **Cognitive Science**: Understanding learning and engagement in games
+- [ ] **Digital Wellness**: Promoting healthy gaming habits and mental well-being
+
+---
+
+## 📞 Roadmap Feedback & Updates
+
+### Community Input
+- **Quarterly Surveys**: Regular community feedback on roadmap priorities
+- **Developer Workshops**: Input sessions with active developers
+- **Player Focus Groups**: Representative player input on new features
+- **Academic Advisory Board**: Research community guidance on platform evolution
+- **Industry Roundtables**: Input from gaming and technology industry leaders
+
+### Roadmap Maintenance
+- **Monthly Reviews**: Regular evaluation of progress and priorities
+- **Quarterly Updates**: Public roadmap updates with progress reports
+- **Annual Planning**: Comprehensive yearly planning and goal setting
+- **Agile Adaptation**: Responsive changes based on technology and market evolution
+- **Community Voting**: Democratic input on feature prioritization
+
+### Communication Channels
+- **Official Blog**: Regular updates and deep-dive articles
+- **Newsletter**: Monthly updates for subscribers
+- **Social Media**: Real-time updates and community engagement
+- **Conference Presentations**: Industry conference roadmap presentations
+- **Documentation Portal**: Living documentation with latest roadmap information
+
+---
+
+*This roadmap is a living document that evolves based on community feedback, technological advances, and changing user needs. Timelines are estimates and may be adjusted based on development priorities and resource availability.*
+
+**Last Updated**: June 6, 2025  
+**Version**: 1.0  
+**Next Review**: July 6, 2025  
+**Community Input**: [feedback@mmop-game.com](mailto:feedback@mmop-game.com)
+
+---
+
+**🚀 Join us in building the future of multiplayer gaming and AI interaction! 🎮**

Documentation/Simple_Game_Client_Guide.md

@@ -0,0 +1,744 @@
+# Simple Game Client Guide
+
+This guide shows you how to create a simple client to connect to the MMORPG game server using the Model Context Protocol (MCP). No LLM integration required - just basic game operations.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Prerequisites](#prerequisites)
+3. [MCP Server Connection](#mcp-server-connection)
+4. [Basic Client Example](#basic-client-example)
+5. [Available Game Operations](#available-game-operations)
+6. [Command Reference](#command-reference)
+7. [Error Handling](#error-handling)
+8. [Advanced Features](#advanced-features)
+
+---
+
+## Overview
+
+The MMORPG game server exposes its functionality through MCP (Model Context Protocol), allowing external clients to:
+
+- 🎮 **Connect** to the game server
+- 👤 **Join/Leave** the game as a player
+- 🗺️ **Move** around the game world
+- 💬 **Send chat** messages to other players
+- 🎯 **Interact** with NPCs and game objects
+- 📊 **Get game state** information
+
+### Game Server Details
+
+- **MCP Endpoint**: `http://localhost:7868/gradio_api/mcp/sse` (when running locally)
+- **Protocol**: Server-Sent Events (SSE) over HTTP
+- **Authentication**: None required for basic operations
+- **Data Format**: JSON messages following MCP specification
+
+---
+
+## Prerequisites
+
+Before building your client, ensure you have:
+
+### Required Dependencies
+
+```bash
+pip install mcp asyncio aiohttp contextlib
+```
+
+### Python Version
+- Python 3.8 or higher
+- Support for async/await syntax
+
+### Game Server Running
+Make sure the MMORPG game server is running:
+
+```bash
+cd c:/Users/Chris4K/Projekte/projecthub/projects/MMOP_second_try
+python app.py
+```
+
+The server should be accessible at `http://localhost:7868` (UI) and the MCP endpoint at `http://localhost:7868/gradio_api/mcp/sse`.
+
+---
+
+## MCP Server Connection
+
+Here's how to establish a connection to the game server:
+
+### Basic Connection Setup
+
+```python
+import asyncio
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from contextlib import AsyncExitStack
+
+class GameClient:
+    def __init__(self, server_url="http://localhost:7868/gradio_api/mcp/sse"):
+        self.server_url = server_url
+        self.session = None
+        self.connected = False
+        self.tools = []
+        self.exit_stack = None
+        self.client_id = None
+    
+    async def connect(self):
+        """Connect to the game server"""
+        try:
+            # Clean up any existing connection
+            if self.exit_stack:
+                await self.exit_stack.aclose()
+            
+            self.exit_stack = AsyncExitStack()
+            
+            # Establish SSE connection
+            transport = await self.exit_stack.enter_async_context(
+                sse_client(self.server_url)
+            )
+            read_stream, write_callable = transport
+            
+            # Create MCP session
+            self.session = await self.exit_stack.enter_async_context(
+                ClientSession(read_stream, write_callable)
+            )
+            
+            # Initialize the session
+            await self.session.initialize()
+            
+            # Get available tools/commands
+            response = await self.session.list_tools()
+            self.tools = response.tools
+            
+            self.connected = True
+            print(f"✅ Connected to game server!")
+            print(f"Available commands: {[tool.name for tool in self.tools]}")
+            
+            return True
+            
+        except Exception as e:
+            print(f"❌ Connection failed: {e}")
+            self.connected = False
+            return False
+    
+    async def disconnect(self):
+        """Disconnect from the game server"""
+        if self.exit_stack:
+            await self.exit_stack.aclose()
+        self.connected = False
+        print("🔌 Disconnected from game server")
+```
+
+### Connection Test
+
+```python
+async def test_connection():
+    client = GameClient()
+    if await client.connect():
+        print("Connection successful!")
+        await client.disconnect()
+    else:
+        print("Connection failed!")
+
+# Run the test
+asyncio.run(test_connection())
+```
+
+---
+
+## Basic Client Example
+
+Here's a complete working client that can perform basic game operations:
+
+```python
+import asyncio
+import json
+import uuid
+from typing import Dict, List, Optional
+
+class SimpleGameClient:
+    def __init__(self, server_url="http://localhost:7868/gradio_api/mcp/sse"):
+        self.server_url = server_url
+        self.session = None
+        self.connected = False
+        self.tools = []
+        self.exit_stack = None
+        self.client_id = str(uuid.uuid4())[:8]
+        self.agent_id = None
+        self.player_name = None
+    
+    async def connect(self):
+        """Connect to the game server"""
+        try:
+            if self.exit_stack:
+                await self.exit_stack.aclose()
+            
+            self.exit_stack = AsyncExitStack()
+            
+            transport = await self.exit_stack.enter_async_context(
+                sse_client(self.server_url)
+            )
+            read_stream, write_callable = transport
+            
+            self.session = await self.exit_stack.enter_async_context(
+                ClientSession(read_stream, write_callable)
+            )
+            
+            await self.session.initialize()
+            response = await self.session.list_tools()
+            self.tools = response.tools
+            
+            self.connected = True
+            return True
+            
+        except Exception as e:
+            print(f"❌ Connection failed: {e}")
+            return False
+    
+    async def register_player(self, player_name: str):
+        """Register as a new player in the game"""
+        if not self.connected:
+            print("❌ Not connected to server")
+            return False
+        
+        try:
+            # Find the register tool
+            register_tool = next((t for t in self.tools if 'register' in t.name), None)
+            if not register_tool:
+                print("❌ Register tool not available")
+                return False
+            
+            # Register the player
+            result = await self.session.call_tool(
+                register_tool.name,
+                {"name": player_name, "client_id": self.client_id}
+            )
+            
+            # Parse the result
+            content = self._extract_content(result)
+            if "registered" in content.lower():
+                self.player_name = player_name
+                # Extract agent_id from response if available
+                if "agent_id" in content or "ID:" in content:
+                    # Parse agent ID from response
+                    lines = content.split('\n')
+                    for line in lines:
+                        if "agent_id" in line.lower() or "id:" in line:
+                            parts = line.split(':')
+                            if len(parts) > 1:
+                                self.agent_id = parts[1].strip()
+                                break
+                
+                print(f"✅ Registered as player: {player_name}")
+                return True
+            else:
+                print(f"❌ Registration failed: {content}")
+                return False
+                
+        except Exception as e:
+            print(f"❌ Registration error: {e}")
+            return False
+    
+    async def move_player(self, direction: str):
+        """Move the player in the specified direction"""
+        if not self.connected or not self.agent_id:
+            print("❌ Not connected or not registered")
+            return False
+        
+        try:
+            # Find the move tool
+            move_tool = next((t for t in self.tools if 'move' in t.name), None)
+            if not move_tool:
+                print("❌ Move tool not available")
+                return False
+            
+            # Move the player
+            result = await self.session.call_tool(
+                move_tool.name,
+                {"client_id": self.client_id, "direction": direction}
+            )
+            
+            content = self._extract_content(result)
+            print(f"🚶 Move result: {content}")
+            return True
+            
+        except Exception as e:
+            print(f"❌ Move error: {e}")
+            return False
+    
+    async def send_chat(self, message: str):
+        """Send a chat message to other players"""
+        if not self.connected or not self.agent_id:
+            print("❌ Not connected or not registered")
+            return False
+        
+        try:
+            # Find the chat tool
+            chat_tool = next((t for t in self.tools if 'chat' in t.name), None)
+            if not chat_tool:
+                print("❌ Chat tool not available")
+                return False
+            
+            # Send the chat message
+            result = await self.session.call_tool(
+                chat_tool.name,
+                {"client_id": self.client_id, "message": message}
+            )
+            
+            content = self._extract_content(result)
+            print(f"💬 Chat sent: {content}")
+            return True
+            
+        except Exception as e:
+            print(f"❌ Chat error: {e}")
+            return False
+    
+    async def get_game_state(self):
+        """Get current game state information"""
+        if not self.connected:
+            print("❌ Not connected to server")
+            return None
+        
+        try:
+            # Find the game state tool
+            state_tool = next((t for t in self.tools if 'state' in t.name or 'game' in t.name), None)
+            if not state_tool:
+                print("❌ Game state tool not available")
+                return None
+            
+            # Get game state
+            result = await self.session.call_tool(state_tool.name, {})
+            content = self._extract_content(result)
+            
+            try:
+                # Try to parse as JSON
+                game_state = json.loads(content)
+                return game_state
+            except json.JSONDecodeError:
+                # Return as text if not JSON
+                return {"info": content}
+                
+        except Exception as e:
+            print(f"❌ Game state error: {e}")
+            return None
+    
+    async def interact_with_npc(self, npc_id: str, message: str):
+        """Interact with an NPC"""
+        if not self.connected or not self.agent_id:
+            print("❌ Not connected or not registered")
+            return False
+        
+        try:
+            # Find the interact tool
+            interact_tool = next((t for t in self.tools if 'interact' in t.name or 'npc' in t.name), None)
+            if not interact_tool:
+                print("❌ Interact tool not available")
+                return False
+            
+            # Interact with NPC
+            result = await self.session.call_tool(
+                interact_tool.name,
+                {"client_id": self.client_id, "npc_id": npc_id, "message": message}
+            )
+            
+            content = self._extract_content(result)
+            print(f"🤖 NPC {npc_id}: {content}")
+            return True
+            
+        except Exception as e:
+            print(f"❌ Interaction error: {e}")
+            return False
+    
+    def _extract_content(self, result):
+        """Extract content from MCP result"""
+        if hasattr(result, 'content') and result.content:
+            if isinstance(result.content, list):
+                return ''.join(str(item) for item in result.content)
+            return str(result.content)
+        return str(result)
+    
+    async def disconnect(self):
+        """Disconnect from the server"""
+        if self.exit_stack:
+            await self.exit_stack.aclose()
+        self.connected = False
+        print("🔌 Disconnected from server")
+
+# Import required modules at the top
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from contextlib import AsyncExitStack
+```
+
+---
+
+## Available Game Operations
+
+The game server exposes these main operations through MCP tools:
+
+### 1. Player Management
+- **`register_ai_agent`** - Register a new player
+- **`move_agent`** - Move player in game world
+- **`get_game_state`** - Get current world state
+
+### 2. Communication
+- **`send_chat`** - Send chat messages
+- **`interact_with_npc`** - Talk to NPCs
+
+### 3. Game Information
+- **`get_game_state`** - World state and player list
+- **Player proximity** - Detect nearby players/NPCs
+
+### Tool Parameters
+
+Each tool expects specific parameters:
+
+```python
+# Register Player
+{
+    "name": "PlayerName",
+    "client_id": "unique_client_id"
+}
+
+# Move Player
+{
+    "client_id": "your_client_id",
+    "direction": "north|south|east|west"
+}
+
+# Send Chat
+{
+    "client_id": "your_client_id", 
+    "message": "Hello world!"
+}
+
+# Interact with NPC
+{
+    "client_id": "your_client_id",
+    "npc_id": "npc_identifier",
+    "message": "Your message to NPC"
+}
+```
+
+---
+
+## Command Reference
+
+### Basic Usage Example
+
+```python
+async def main():
+    # Create and connect client
+    client = SimpleGameClient()
+    
+    if not await client.connect():
+        print("Failed to connect!")
+        return
+    
+    # Register as a player
+    if not await client.register_player("MyPlayer"):
+        print("Failed to register!")
+        return
+    
+    # Get current game state
+    state = await client.get_game_state()
+    print(f"Game state: {state}")
+    
+    # Move around
+    await client.move_player("north")
+    await client.move_player("east")
+    
+    # Send a chat message
+    await client.send_chat("Hello everyone!")
+    
+    # Interact with an NPC
+    await client.interact_with_npc("weather_oracle", "What's the weather in Berlin?")
+    
+    # Disconnect
+    await client.disconnect()
+
+# Run the client
+asyncio.run(main())
+```
+
+### Interactive Console Client
+
+```python
+async def interactive_client():
+    client = SimpleGameClient()
+    
+    print("🎮 MMORPG Simple Client")
+    print("Commands: connect, register <name>, move <direction>, chat <message>, state, quit")
+    
+    while True:
+        command = input("> ").strip().split()
+        
+        if not command:
+            continue
+            
+        cmd = command[0].lower()
+        
+        if cmd == "connect":
+            if await client.connect():
+                print("✅ Connected!")
+            else:
+                print("❌ Connection failed!")
+                
+        elif cmd == "register" and len(command) > 1:
+            name = " ".join(command[1:])
+            if await client.register_player(name):
+                print(f"✅ Registered as {name}")
+            else:
+                print("❌ Registration failed!")
+                
+        elif cmd == "move" and len(command) > 1:
+            direction = command[1]
+            await client.move_player(direction)
+            
+        elif cmd == "chat" and len(command) > 1:
+            message = " ".join(command[1:])
+            await client.send_chat(message)
+            
+        elif cmd == "state":
+            state = await client.get_game_state()
+            print(f"📊 Game State: {json.dumps(state, indent=2)}")
+            
+        elif cmd == "npc" and len(command) > 2:
+            npc_id = command[1]
+            message = " ".join(command[2:])
+            await client.interact_with_npc(npc_id, message)
+            
+        elif cmd == "quit":
+            await client.disconnect()
+            break
+            
+        else:
+            print("❓ Unknown command")
+
+# Run interactive client
+asyncio.run(interactive_client())
+```
+
+---
+
+## Error Handling
+
+### Common Issues and Solutions
+
+#### 1. Connection Errors
+```python
+async def robust_connect(client, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            if await client.connect():
+                return True
+            print(f"Attempt {attempt + 1} failed, retrying...")
+            await asyncio.sleep(2)
+        except Exception as e:
+            print(f"Connection attempt {attempt + 1} error: {e}")
+    
+    print("❌ All connection attempts failed")
+    return False
+```
+
+#### 2. Tool Not Available
+```python
+def find_tool_safe(tools, keywords):
+    """Safely find a tool by keywords"""
+    for keyword in keywords:
+        tool = next((t for t in tools if keyword in t.name.lower()), None)
+        if tool:
+            return tool
+    return None
+
+# Usage
+move_tool = find_tool_safe(client.tools, ['move', 'agent', 'player'])
+if not move_tool:
+    print("❌ No movement tool available")
+```
+
+#### 3. Response Parsing
+```python
+def safe_parse_response(result):
+    """Safely parse MCP response"""
+    try:
+        content = client._extract_content(result)
+        
+        # Try JSON first
+        try:
+            return json.loads(content)
+        except json.JSONDecodeError:
+            # Return as structured text
+            return {"message": content, "type": "text"}
+            
+    except Exception as e:
+        return {"error": str(e), "type": "error"}
+```
+
+---
+
+## Advanced Features
+
+### 1. Automatic Reconnection
+
+```python
+class RobustGameClient(SimpleGameClient):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.auto_reconnect = True
+        self.reconnect_delay = 5
+    
+    async def _ensure_connected(self):
+        """Ensure connection is active, reconnect if needed"""
+        if not self.connected and self.auto_reconnect:
+            print("🔄 Attempting to reconnect...")
+            await self.connect()
+            if self.player_name:
+                await self.register_player(self.player_name)
+    
+    async def move_player(self, direction):
+        await self._ensure_connected()
+        return await super().move_player(direction)
+```
+
+### 2. Event Monitoring
+
+```python
+class EventMonitorClient(SimpleGameClient):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.event_handlers = {}
+    
+    def on_chat_message(self, handler):
+        """Register handler for chat messages"""
+        self.event_handlers['chat'] = handler
+    
+    def on_player_move(self, handler):
+        """Register handler for player movements"""
+        self.event_handlers['move'] = handler
+    
+    async def poll_events(self):
+        """Poll for game events"""
+        while self.connected:
+            try:
+                state = await self.get_game_state()
+                # Process state changes and trigger handlers
+                # Implementation depends on game state format
+                await asyncio.sleep(1)
+            except Exception as e:
+                print(f"Event polling error: {e}")
+                await asyncio.sleep(5)
+```
+
+### 3. Batch Operations
+
+```python
+async def batch_moves(client, moves):
+    """Execute multiple moves in sequence"""
+    for direction in moves:
+        result = await client.move_player(direction)
+        if not result:
+            print(f"❌ Failed to move {direction}")
+            break
+        await asyncio.sleep(0.5)  # Small delay between moves
+
+# Usage
+await batch_moves(client, ["north", "north", "east", "south"])
+```
+
+### 4. Configuration Management
+
+```python
+import json
+
+class ConfigurableClient(SimpleGameClient):
+    def __init__(self, config_file="client_config.json"):
+        # Load configuration
+        try:
+            with open(config_file, 'r') as f:
+                config = json.load(f)
+        except FileNotFoundError:
+            config = self.default_config()
+            
+        super().__init__(config.get('server_url', 'http://localhost:7860/gradio_api/mcp/sse'))
+        self.config = config
+    
+    def default_config(self):
+        return {
+            "server_url": "http://localhost:7860/gradio_api/mcp/sse",
+            "player_name": "DefaultPlayer",
+            "auto_reconnect": True,
+            "move_delay": 0.5
+        }
+```
+
+---
+
+## Quick Start Script
+
+Save this as `quick_client.py` for immediate testing:
+
+```python
+#!/usr/bin/env python3
+"""
+Quick Game Client - Connect and play immediately
+Usage: python quick_client.py [player_name]
+"""
+
+import asyncio
+import sys
+from simple_game_client import SimpleGameClient
+
+async def quick_play(player_name="TestPlayer"):
+    client = SimpleGameClient()
+    
+    print(f"🎮 Connecting as {player_name}...")
+    
+    # Connect and register
+    if not await client.connect():
+        print("❌ Failed to connect!")
+        return
+    
+    if not await client.register_player(player_name):
+        print("❌ Failed to register!")
+        return
+    
+    print("✅ Connected and registered successfully!")
+    
+    # Basic game session
+    await client.send_chat(f"Hello! {player_name} has joined the game!")
+    
+    # Move around a bit
+    moves = ["north", "east", "south", "west"]
+    for move in moves:
+        print(f"🚶 Moving {move}...")
+        await client.move_player(move)
+        await asyncio.sleep(1)
+    
+    # Get final state
+    state = await client.get_game_state()
+    print(f"📊 Final state: {state}")
+    
+    await client.disconnect()
+    print("👋 Session ended!")
+
+if __name__ == "__main__":
+    player_name = sys.argv[1] if len(sys.argv) > 1 else "TestPlayer"
+    asyncio.run(quick_play(player_name))
+```
+
+Run with:
+```bash
+python quick_client.py MyPlayerName
+```
+
+---
+
+## Next Steps
+
+1. **Customize the client** for your specific needs
+2. **Add game-specific features** like inventory management
+3. **Implement advanced AI** for automated gameplay
+4. **Create GUI interfaces** using tkinter, PyQt, or web frameworks
+5. **Build monitoring tools** for game statistics
+
+This guide provides the foundation for any client application that needs to interact with the MMORPG game server!

Documentation/sample_gradio_mcp_server.py

@@ -0,0 +1,475 @@
+#!/usr/bin/env python3
+"""
+Sample Gradio MCP Server
+========================
+
+This is a complete example of how to create a Gradio application that serves as an MCP server.
+This example creates a "Task Manager" service that can be used as an NPC addon in the MMORPG.
+
+Key Features:
+- Full MCP server implementation with Gradio
+- RESTful API endpoints for MCP communication
+- Gradio web interface for direct interaction
+- Error handling and validation
+- Proper MCP protocol responses
+
+Usage:
+1. Run this file: python sample_gradio_mcp_server.py
+2. Access web interface at: http://localhost:7860
+3. Use MCP client to connect to: http://localhost:7860/gradio_api/mcp/sse
+"""
+
+import gradio as gr
+import json
+import time
+import uuid
+from datetime import datetime, timedelta
+from typing import Dict, List, Any, Optional
+from dataclasses import dataclass, asdict
+
+# ============================================================================
+# DATA MODELS
+# ============================================================================
+
+@dataclass
+class Task:
+    id: str
+    title: str
+    description: str
+    status: str  # "pending", "in_progress", "completed"
+    priority: str  # "low", "medium", "high"
+    created_at: float
+    due_date: Optional[float] = None
+    completed_at: Optional[float] = None
+
+class TaskManager:
+    """Core task management logic"""
+    
+    def __init__(self):
+        self.tasks: Dict[str, Task] = {}
+        self.task_counter = 0
+    
+    def create_task(self, title: str, description: str = "", priority: str = "medium", due_date: Optional[str] = None) -> Dict[str, Any]:
+        """Create a new task"""
+        if not title.strip():
+            return {"error": "Task title cannot be empty"}
+        
+        task_id = f"task_{int(time.time())}_{self.task_counter}"
+        self.task_counter += 1
+        
+        due_timestamp = None
+        if due_date:
+            try:
+                # Simple date parsing (format: YYYY-MM-DD)
+                due_timestamp = datetime.strptime(due_date, "%Y-%m-%d").timestamp()
+            except ValueError:
+                return {"error": "Invalid date format. Use YYYY-MM-DD"}
+        
+        task = Task(
+            id=task_id,
+            title=title.strip(),
+            description=description.strip(),
+            status="pending",
+            priority=priority.lower(),
+            created_at=time.time(),
+            due_date=due_timestamp
+        )
+        
+        self.tasks[task_id] = task
+        
+        return {
+            "success": True,
+            "task_id": task_id,
+            "message": f"Task '{title}' created successfully!",
+            "task": asdict(task)
+        }
+    
+    def list_tasks(self, status_filter: Optional[str] = None) -> Dict[str, Any]:
+        """List all tasks or filter by status"""
+        tasks = list(self.tasks.values())
+        
+        if status_filter:
+            tasks = [t for t in tasks if t.status == status_filter.lower()]
+        
+        # Sort by priority and creation date
+        priority_order = {"high": 0, "medium": 1, "low": 2}
+        tasks.sort(key=lambda t: (priority_order.get(t.priority, 2), t.created_at))
+        
+        return {
+            "success": True,
+            "count": len(tasks),
+            "tasks": [asdict(task) for task in tasks]
+        }
+    
+    def update_task_status(self, task_id: str, new_status: str) -> Dict[str, Any]:
+        """Update task status"""
+        if task_id not in self.tasks:
+            return {"error": f"Task {task_id} not found"}
+        
+        valid_statuses = ["pending", "in_progress", "completed"]
+        if new_status.lower() not in valid_statuses:
+            return {"error": f"Invalid status. Must be one of: {', '.join(valid_statuses)}"}
+        
+        task = self.tasks[task_id]
+        old_status = task.status
+        task.status = new_status.lower()
+        
+        if new_status.lower() == "completed":
+            task.completed_at = time.time()
+        
+        return {
+            "success": True,
+            "message": f"Task '{task.title}' status changed from '{old_status}' to '{new_status}'",
+            "task": asdict(task)
+        }
+    
+    def delete_task(self, task_id: str) -> Dict[str, Any]:
+        """Delete a task"""
+        if task_id not in self.tasks:
+            return {"error": f"Task {task_id} not found"}
+        
+        task = self.tasks.pop(task_id)
+        return {
+            "success": True,
+            "message": f"Task '{task.title}' deleted successfully"
+        }
+    
+    def get_task_stats(self) -> Dict[str, Any]:
+        """Get task statistics"""
+        total = len(self.tasks)
+        completed = len([t for t in self.tasks.values() if t.status == "completed"])
+        in_progress = len([t for t in self.tasks.values() if t.status == "in_progress"])
+        pending = len([t for t in self.tasks.values() if t.status == "pending"])
+        
+        # Overdue tasks
+        current_time = time.time()
+        overdue = len([
+            t for t in self.tasks.values() 
+            if t.due_date and t.due_date < current_time and t.status != "completed"
+        ])
+        
+        return {
+            "success": True,
+            "stats": {
+                "total_tasks": total,
+                "completed": completed,
+                "in_progress": in_progress,
+                "pending": pending,
+                "overdue": overdue,
+                "completion_rate": round((completed / total * 100) if total > 0 else 0, 1)
+            }
+        }
+
+# Global task manager instance
+task_manager = TaskManager()
+
+# ============================================================================
+# MCP TOOLS DEFINITION
+# ============================================================================
+
+def mcp_create_task(title: str, description: str = "", priority: str = "medium", due_date: str = "") -> str:
+    """
+    Create a new task in the task manager.
+    
+    Args:
+        title: Task title (required)
+        description: Detailed task description (optional)
+        priority: Task priority - low, medium, or high (default: medium)
+        due_date: Due date in YYYY-MM-DD format (optional)
+    
+    Returns:
+        JSON string with task creation result
+    """
+    result = task_manager.create_task(
+        title=title,
+        description=description,
+        priority=priority,
+        due_date=due_date if due_date else None
+    )
+    return json.dumps(result, indent=2)
+
+def mcp_list_tasks(status_filter: str = "") -> str:
+    """
+    List all tasks or filter by status.
+    
+    Args:
+        status_filter: Filter by status - pending, in_progress, or completed (optional)
+    
+    Returns:
+        JSON string with list of tasks
+    """
+    result = task_manager.list_tasks(status_filter if status_filter else None)
+    return json.dumps(result, indent=2)
+
+def mcp_update_task_status(task_id: str, new_status: str) -> str:
+    """
+    Update the status of an existing task.
+    
+    Args:
+        task_id: ID of the task to update
+        new_status: New status - pending, in_progress, or completed
+    
+    Returns:
+        JSON string with update result
+    """
+    result = task_manager.update_task_status(task_id, new_status)
+    return json.dumps(result, indent=2)
+
+def mcp_delete_task(task_id: str) -> str:
+    """
+    Delete a task from the task manager.
+    
+    Args:
+        task_id: ID of the task to delete
+    
+    Returns:
+        JSON string with deletion result
+    """
+    result = task_manager.delete_task(task_id)
+    return json.dumps(result, indent=2)
+
+def mcp_get_task_stats() -> str:
+    """
+    Get task statistics and completion metrics.
+    
+    Returns:
+        JSON string with task statistics
+    """
+    result = task_manager.get_task_stats()
+    return json.dumps(result, indent=2)
+
+# ============================================================================
+# GRADIO INTERFACE
+# ============================================================================
+
+def create_task_interface():
+    """Create the Gradio interface for the Task Manager MCP Server"""
+    
+    with gr.Blocks(
+        title="Task Manager MCP Server",
+        theme=gr.themes.Soft(),
+        css="""
+        .task-card { 
+            border: 1px solid #ddd; 
+            border-radius: 8px; 
+            padding: 15px; 
+            margin: 10px 0; 
+            background: #f9f9f9; 
+        }
+        .high-priority { border-left: 4px solid #ff4444; }
+        .medium-priority { border-left: 4px solid #ffaa00; }
+        .low-priority { border-left: 4px solid #44aa44; }
+        """
+    ) as demo:
+        
+        gr.Markdown("""
+        # 📋 Task Manager MCP Server
+        
+        **MCP Endpoint:** `http://localhost:7860/gradio_api/mcp/sse`
+        
+        This server provides task management capabilities via MCP protocol.
+        Perfect for integration as an NPC addon in games or other applications!
+        
+        ## Available MCP Tools:
+        - `mcp_create_task` - Create new tasks
+        - `mcp_list_tasks` - List and filter tasks  
+        - `mcp_update_task_status` - Update task progress
+        - `mcp_delete_task` - Remove tasks
+        - `mcp_get_task_stats` - Get statistics
+        """)
+        
+        with gr.Tabs():
+            # Create Task Tab
+            with gr.Tab("➕ Create Task"):
+                with gr.Row():
+                    task_title = gr.Textbox(
+                        label="Task Title",
+                        placeholder="Enter task title...",
+                        scale=2
+                    )
+                    priority = gr.Dropdown(
+                        choices=["low", "medium", "high"],
+                        value="medium",
+                        label="Priority",
+                        scale=1
+                    )
+                
+                task_description = gr.Textbox(
+                    label="Description",
+                    placeholder="Detailed task description...",
+                    lines=3
+                )
+                
+                due_date = gr.Textbox(
+                    label="Due Date (YYYY-MM-DD)",
+                    placeholder="2024-12-31",
+                    value=""
+                )
+                
+                create_btn = gr.Button("Create Task", variant="primary")
+                create_result = gr.JSON(label="Result")
+                
+                def handle_create_task(title, desc, prio, due):
+                    result = task_manager.create_task(title, desc, prio, due if due else None)
+                    return result
+                
+                create_btn.click(
+                    handle_create_task,
+                    inputs=[task_title, task_description, priority, due_date],
+                    outputs=[create_result]
+                )
+            
+            # View Tasks Tab
+            with gr.Tab("📋 View Tasks"):
+                with gr.Row():
+                    status_filter = gr.Dropdown(
+                        choices=["", "pending", "in_progress", "completed"],
+                        value="",
+                        label="Filter by Status",
+                        scale=1
+                    )
+                    refresh_btn = gr.Button("🔄 Refresh", scale=1)
+                
+                tasks_display = gr.JSON(label="Tasks")
+                
+                def handle_list_tasks(status_filter_val):
+                    result = task_manager.list_tasks(status_filter_val if status_filter_val else None)
+                    return result
+                
+                refresh_btn.click(
+                    handle_list_tasks,
+                    inputs=[status_filter],
+                    outputs=[tasks_display]
+                )
+                
+                status_filter.change(
+                    handle_list_tasks,
+                    inputs=[status_filter],
+                    outputs=[tasks_display]
+                )
+            
+            # Update Task Tab
+            with gr.Tab("✏️ Update Task"):
+                update_task_id = gr.Textbox(
+                    label="Task ID",
+                    placeholder="task_1234567890_0"
+                )
+                
+                new_status = gr.Dropdown(
+                    choices=["pending", "in_progress", "completed"],
+                    label="New Status",
+                    value="in_progress"
+                )
+                
+                update_btn = gr.Button("Update Status", variant="primary")
+                update_result = gr.JSON(label="Result")
+                
+                def handle_update_status(task_id, status):
+                    result = task_manager.update_task_status(task_id, status)
+                    return result
+                
+                update_btn.click(
+                    handle_update_status,
+                    inputs=[update_task_id, new_status],
+                    outputs=[update_result]
+                )
+            
+            # Statistics Tab
+            with gr.Tab("📊 Statistics"):
+                stats_btn = gr.Button("📈 Get Current Stats", variant="primary")
+                stats_display = gr.JSON(label="Task Statistics")
+                
+                def handle_get_stats():
+                    result = task_manager.get_task_stats()
+                    return result
+                
+                stats_btn.click(
+                    handle_get_stats,
+                    outputs=[stats_display]
+                )
+            
+            # MCP Testing Tab
+            with gr.Tab("🔌 MCP Testing"):
+                gr.Markdown("""
+                ## Test MCP Functions
+                
+                Use this tab to test the MCP functions that will be available to external clients.
+                """)
+                
+                with gr.Group():
+                    gr.Markdown("### Test mcp_create_task")
+                    with gr.Row():
+                        test_title = gr.Textbox(label="Title", value="Test Task")
+                        test_desc = gr.Textbox(label="Description", value="This is a test task")
+                        test_priority = gr.Dropdown(choices=["low", "medium", "high"], value="medium", label="Priority")
+                    
+                    test_create_btn = gr.Button("Test Create")
+                    test_create_result = gr.Textbox(label="MCP Response", lines=10)
+                    
+                    test_create_btn.click(
+                        lambda t, d, p: mcp_create_task(t, d, p),
+                        inputs=[test_title, test_desc, test_priority],
+                        outputs=[test_create_result]
+                    )
+                
+                with gr.Group():
+                    gr.Markdown("### Test mcp_list_tasks")
+                    test_filter = gr.Dropdown(choices=["", "pending", "in_progress", "completed"], value="", label="Status Filter")
+                    test_list_btn = gr.Button("Test List")
+                    test_list_result = gr.Textbox(label="MCP Response", lines=10)
+                    
+                    test_list_btn.click(
+                        lambda f: mcp_list_tasks(f),
+                        inputs=[test_filter],
+                        outputs=[test_list_result]
+                    )
+                
+                with gr.Group():
+                    gr.Markdown("### Test mcp_get_task_stats")
+                    test_stats_btn = gr.Button("Test Stats")
+                    test_stats_result = gr.Textbox(label="MCP Response", lines=10)
+                    
+                    test_stats_btn.click(
+                        lambda: mcp_get_task_stats(),
+                        outputs=[test_stats_result]
+                    )
+        
+        # Auto-refresh stats on page load
+        demo.load(
+            lambda: task_manager.get_task_stats(),
+            outputs=[stats_display]
+        )
+    
+    return demo
+
+# ============================================================================
+# MAIN APPLICATION
+# ============================================================================
+
+if __name__ == "__main__":
+    print("🚀 Starting Task Manager MCP Server...")
+    print("=" * 60)
+    print("✅ Web Interface: http://localhost:7860")
+    print("🔌 MCP Endpoint: http://localhost:7860/gradio_api/mcp/sse")
+    print("📋 Available MCP Tools:")
+    print("   - mcp_create_task")
+    print("   - mcp_list_tasks") 
+    print("   - mcp_update_task_status")
+    print("   - mcp_delete_task")
+    print("   - mcp_get_task_stats")
+    print("=" * 60)
+    
+    # Create some sample tasks for demonstration
+    task_manager.create_task("Welcome Task", "This is a sample task to get you started!", "high")
+    task_manager.create_task("Learn MCP Protocol", "Study the Model Context Protocol documentation", "medium")
+    task_manager.create_task("Build NPC Addon", "Create a new NPC addon for the MMORPG", "high")
+    
+    # Launch the Gradio app with MCP server enabled
+    interface = create_task_interface()
+    interface.launch(
+        debug=True,
+        share=False,
+        server_port=7860,
+        mcp_server=True,  # This enables MCP protocol support
+        show_error=True
+    )

Documentation/simple_game_client.py

@@ -0,0 +1,485 @@
+#!/usr/bin/env python3
+"""
+Simple MMORPG Game Client
+========================
+
+A basic client implementation for connecting to the MMORPG game server via MCP.
+This client can join the game, move around, chat, and interact with NPCs.
+
+Requirements:
+    pip install mcp aiohttp asyncio
+
+Usage:
+    python simple_game_client.py
+
+Features:
+    - Connect to game server via MCP
+    - Register as a player
+    - Move around the game world  
+    - Send chat messages
+    - Interact with NPCs
+    - Get game state information
+    - Interactive console interface
+"""
+
+import asyncio
+import json
+import uuid
+import sys
+from typing import Dict, List, Optional
+
+try:
+    from mcp import ClientSession
+    from mcp.client.sse import sse_client
+    from contextlib import AsyncExitStack
+except ImportError:
+    print("❌ Missing dependencies. Install with: pip install mcp aiohttp")
+    sys.exit(1)
+
+
+class SimpleGameClient:
+    """Simple client for connecting to the MMORPG game server"""
+    
+    def __init__(self, server_url="http://127.0.0.1:7868/gradio_api/mcp/sse"):
+        self.server_url = server_url
+        self.session = None
+        self.connected = False
+        self.tools = []
+        self.exit_stack = None
+        self.client_id = f"client_{uuid.uuid4().hex[:8]}"
+        self.agent_id = None
+        self.player_name = None
+        
+        print(f"🎮 Game Client initialized with ID: {self.client_id}")
+    
+    async def connect(self):
+        """Connect to the game server"""
+        print(f"🔌 Connecting to {self.server_url}...")
+        
+        try:
+            # Clean up any existing connection
+            if self.exit_stack:
+                await self.exit_stack.aclose()
+            
+            self.exit_stack = AsyncExitStack()
+            
+            # Establish SSE connection to MCP server
+            transport = await self.exit_stack.enter_async_context(
+                sse_client(self.server_url)
+            )
+            read_stream, write_callable = transport
+            
+            # Create MCP client session
+            self.session = await self.exit_stack.enter_async_context(
+                ClientSession(read_stream, write_callable)
+            )
+            
+            # Initialize the session
+            await self.session.initialize()
+            
+            # Get available tools/commands from server
+            response = await self.session.list_tools()
+            self.tools = response.tools
+            
+            self.connected = True
+            tool_names = [tool.name for tool in self.tools]
+            print(f"✅ Connected successfully!")
+            print(f"📋 Available commands: {', '.join(tool_names)}")
+            
+            return True
+            
+        except Exception as e:
+            print(f"❌ Connection failed: {e}")
+            self.connected = False
+            return False
+    
+    async def register_player(self, player_name: str):
+        """Register as a new player in the game"""
+        if not self.connected:
+            print("❌ Not connected to server")
+            return False
+        
+        print(f"👤 Registering player: {player_name}")
+        
+        try:
+            # Find the register tool
+            register_tool = self._find_tool(['register', 'agent'])
+            if not register_tool:
+                print("❌ Register tool not available on server")
+                return False
+            
+            # Register the player
+            result = await self.session.call_tool(
+                register_tool.name,
+                {"name": player_name, "client_id": self.client_id}
+            )
+            
+            # Parse the result
+            content = self._extract_content(result)
+            print(f"📝 Registration response: {content}")
+            
+            if "registered" in content.lower() or "success" in content.lower():
+                self.player_name = player_name
+                # Try to extract agent_id from response
+                self._parse_agent_id(content)
+                print(f"✅ Successfully registered as: {player_name}")
+                return True
+            else:
+                print(f"❌ Registration failed: {content}")
+                return False
+                
+        except Exception as e:
+            print(f"❌ Registration error: {e}")
+            return False
+    
+    async def move_player(self, direction: str):
+        """Move the player in the specified direction"""
+        if not self._check_ready():
+            return False
+        
+        direction = direction.lower()
+        valid_directions = ['north', 'south', 'east', 'west', 'up', 'down']
+        
+        if direction not in valid_directions:
+            print(f"❌ Invalid direction. Use: {', '.join(valid_directions)}")
+            return False
+        
+        try:
+            # Find the move tool
+            move_tool = self._find_tool(['move', 'agent'])
+            if not move_tool:
+                print("❌ Move tool not available")
+                return False
+            
+            # Execute the move
+            result = await self.session.call_tool(
+                move_tool.name,
+                {"client_id": self.client_id, "direction": direction}
+            )
+            
+            content = self._extract_content(result)
+            print(f"🚶 Move {direction}: {content}")
+            return True
+            
+        except Exception as e:
+            print(f"❌ Move error: {e}")
+            return False
+    
+    async def send_chat(self, message: str):
+        """Send a chat message to other players"""
+        if not self._check_ready():
+            return False
+        
+        if not message.strip():
+            print("❌ Cannot send empty message")
+            return False
+        
+        try:
+            # Find the chat tool
+            chat_tool = self._find_tool(['chat', 'send'])
+            if not chat_tool:
+                print("❌ Chat tool not available")
+                return False
+            
+            # Send the chat message
+            result = await self.session.call_tool(
+                chat_tool.name,
+                {"client_id": self.client_id, "message": message}
+            )
+            
+            content = self._extract_content(result)
+            print(f"💬 Chat sent: {content}")
+            return True
+            
+        except Exception as e:
+            print(f"❌ Chat error: {e}")
+            return False
+    
+    async def get_game_state(self):
+        """Get current game state information"""
+        if not self.connected:
+            print("❌ Not connected to server")
+            return None
+        
+        try:
+            # Find the game state tool
+            state_tool = self._find_tool(['state', 'game'])
+            if not state_tool:
+                print("❌ Game state tool not available")
+                return None
+            
+            # Get game state
+            result = await self.session.call_tool(state_tool.name, {})
+            content = self._extract_content(result)
+            
+            try:
+                # Try to parse as JSON
+                game_state = json.loads(content)
+                return game_state
+            except json.JSONDecodeError:
+                # Return as text if not JSON
+                return {"info": content}
+                
+        except Exception as e:
+            print(f"❌ Game state error: {e}")
+            return None
+    
+    async def interact_with_npc(self, npc_id: str, message: str):
+        """Interact with an NPC"""
+        if not self._check_ready():
+            return False
+        
+        if not npc_id.strip() or not message.strip():
+            print("❌ NPC ID and message are required")
+            return False
+        
+        try:
+            # Find the interact tool
+            interact_tool = self._find_tool(['interact', 'npc'])
+            if not interact_tool:
+                print("❌ NPC interaction tool not available")
+                return False
+            
+            # Interact with NPC
+            result = await self.session.call_tool(
+                interact_tool.name,
+                {"client_id": self.client_id, "npc_id": npc_id, "message": message}
+            )
+            
+            content = self._extract_content(result)
+            print(f"🤖 {npc_id}: {content}")
+            return True
+            
+        except Exception as e:
+            print(f"❌ NPC interaction error: {e}")
+            return False
+    
+    async def list_tools(self):
+        """List all available tools on the server"""
+        if not self.connected:
+            print("❌ Not connected to server")
+            return
+        
+        print("🛠️ Available Tools:")
+        for i, tool in enumerate(self.tools, 1):
+            print(f"  {i}. {tool.name}")
+            if hasattr(tool, 'description') and tool.description:
+                print(f"     Description: {tool.description}")
+    
+    def _find_tool(self, keywords: List[str]):
+        """Find a tool by keywords"""
+        for keyword in keywords:
+            tool = next((t for t in self.tools if keyword in t.name.lower()), None)
+            if tool:
+                return tool
+        return None
+    
+    def _extract_content(self, result):
+        """Extract content from MCP result"""
+        try:
+            if hasattr(result, 'content') and result.content:
+                if isinstance(result.content, list):
+                    content_parts = []
+                    for item in result.content:
+                        if hasattr(item, 'text'):
+                            content_parts.append(item.text)
+                        else:
+                            content_parts.append(str(item))
+                    return ''.join(content_parts)
+                elif hasattr(result.content, 'text'):
+                    return result.content.text
+                else:
+                    return str(result.content)
+            return str(result)
+        except Exception as e:
+            return f"Error extracting content: {e}"
+    
+    def _parse_agent_id(self, content: str):
+        """Try to extract agent ID from response"""
+        lines = content.split('\n')
+        for line in lines:
+            if any(keyword in line.lower() for keyword in ['agent_id', 'id:', 'player id']):
+                parts = line.split(':')
+                if len(parts) > 1:
+                    self.agent_id = parts[1].strip()
+                    print(f"🆔 Agent ID: {self.agent_id}")
+                    break
+    
+    def _check_ready(self):
+        """Check if client is ready for game operations"""
+        if not self.connected:
+            print("❌ Not connected to server")
+            return False
+        if not self.player_name:
+            print("❌ Not registered as a player")
+            return False
+        return True
+    
+    async def disconnect(self):
+        """Disconnect from the server"""
+        if self.exit_stack:
+            await self.exit_stack.aclose()
+        self.connected = False
+        self.player_name = None
+        self.agent_id = None
+        print("🔌 Disconnected from server")
+
+
+class InteractiveGameClient:
+    """Interactive console interface for the game client"""
+    
+    def __init__(self):
+        self.client = SimpleGameClient()
+        self.running = True
+    
+    async def start(self):
+        """Start the interactive client"""
+        print("🎮 MMORPG Simple Game Client")
+        print("=" * 40)
+        self.show_help()
+        
+        while self.running:
+            try:
+                command = input("\n> ").strip()
+                if command:
+                    await self.process_command(command)
+            except KeyboardInterrupt:
+                print("\n\n👋 Goodbye!")
+                break
+            except EOFError:
+                break
+        
+        await self.client.disconnect()
+    
+    async def process_command(self, command: str):
+        """Process a user command"""
+        parts = command.split()
+        if not parts:
+            return
+        
+        cmd = parts[0].lower()
+        args = parts[1:]
+        
+        if cmd == "help":
+            self.show_help()
+            
+        elif cmd == "connect":
+            await self.client.connect()
+            
+        elif cmd == "register":
+            if args:
+                name = " ".join(args)
+                await self.client.register_player(name)
+            else:
+                print("❌ Usage: register <player_name>")
+                
+        elif cmd == "move":
+            if args:
+                direction = args[0]
+                await self.client.move_player(direction)
+            else:
+                print("❌ Usage: move <direction>")
+                print("   Directions: north, south, east, west")
+                
+        elif cmd == "chat":
+            if args:
+                message = " ".join(args)
+                await self.client.send_chat(message)
+            else:
+                print("❌ Usage: chat <message>")
+                
+        elif cmd == "state":
+            state = await self.client.get_game_state()
+            if state:
+                print("📊 Game State:")
+                print(json.dumps(state, indent=2))
+            
+        elif cmd == "npc":
+            if len(args) >= 2:
+                npc_id = args[0]
+                message = " ".join(args[1:])
+                await self.client.interact_with_npc(npc_id, message)
+            else:
+                print("❌ Usage: npc <npc_id> <message>")
+                print("   Example: npc weather_oracle What's the weather in Berlin?")
+                
+        elif cmd == "tools":
+            await self.client.list_tools()
+            
+        elif cmd in ["quit", "exit", "q"]:
+            self.running = False
+            
+        else:
+            print(f"❓ Unknown command: {cmd}")
+            print("   Type 'help' for available commands")
+    
+    def show_help(self):
+        """Show available commands"""
+        print("\n📋 Available Commands:")
+        print("  help                    - Show this help")
+        print("  connect                 - Connect to game server")
+        print("  register <name>         - Register as a player")
+        print("  move <direction>        - Move player (north/south/east/west)")
+        print("  chat <message>          - Send chat message")
+        print("  npc <id> <message>      - Talk to an NPC")
+        print("  state                   - Get game state")
+        print("  tools                   - List available server tools")
+        print("  quit                    - Exit the client")
+        print("\n💡 Example session:")
+        print("  > connect")
+        print("  > register MyPlayer")
+        print("  > move north")
+        print("  > chat Hello everyone!")
+        print("  > npc weather_oracle What's the weather?")
+
+
+async def quick_demo():
+    """Quick demo showing basic functionality"""
+    print("🚀 Running Quick Demo...")
+    
+    client = SimpleGameClient()
+    
+    # Connect
+    if not await client.connect():
+        print("❌ Demo failed - could not connect")
+        return
+    
+    # Register
+    if not await client.register_player("DemoPlayer"):
+        print("❌ Demo failed - could not register")
+        return
+    
+    # Send greeting
+    await client.send_chat("Hello! Demo player here!")
+    
+    # Move around
+    moves = ["north", "east", "south", "west"]
+    for direction in moves:
+        await client.move_player(direction)
+        await asyncio.sleep(1)
+    
+    # Get state
+    state = await client.get_game_state()
+    if state:
+        print(f"📊 Current game state: {json.dumps(state, indent=2)}")
+    
+    # Try NPC interaction
+    await client.interact_with_npc("weather_oracle", "Hello there!")
+    
+    await client.disconnect()
+    print("✅ Demo completed!")
+
+
+def main():
+    """Main entry point"""
+    if len(sys.argv) > 1 and sys.argv[1] == "demo":
+        # Run quick demo
+        asyncio.run(quick_demo())
+    else:
+        # Run interactive client
+        client = InteractiveGameClient()
+        asyncio.run(client.start())
+
+
+if __name__ == "__main__":
+    main()

Simple_Game_Client_Guide.md

@@ -0,0 +1,744 @@
+# Simple Game Client Guide
+
+This guide shows you how to create a simple client to connect to the MMORPG game server using the Model Context Protocol (MCP). No LLM integration required - just basic game operations.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Prerequisites](#prerequisites)
+3. [MCP Server Connection](#mcp-server-connection)
+4. [Basic Client Example](#basic-client-example)
+5. [Available Game Operations](#available-game-operations)
+6. [Command Reference](#command-reference)
+7. [Error Handling](#error-handling)
+8. [Advanced Features](#advanced-features)
+
+---
+
+## Overview
+
+The MMORPG game server exposes its functionality through MCP (Model Context Protocol), allowing external clients to:
+
+- 🎮 **Connect** to the game server
+- 👤 **Join/Leave** the game as a player
+- 🗺️ **Move** around the game world
+- 💬 **Send chat** messages to other players
+- 🎯 **Interact** with NPCs and game objects
+- 📊 **Get game state** information
+
+### Game Server Details
+
+- **MCP Endpoint**: `http://localhost:7868/gradio_api/mcp/sse` (when running locally)
+- **Protocol**: Server-Sent Events (SSE) over HTTP
+- **Authentication**: None required for basic operations
+- **Data Format**: JSON messages following MCP specification
+
+---
+
+## Prerequisites
+
+Before building your client, ensure you have:
+
+### Required Dependencies
+
+```bash
+pip install mcp asyncio aiohttp contextlib
+```
+
+### Python Version
+- Python 3.8 or higher
+- Support for async/await syntax
+
+### Game Server Running
+Make sure the MMORPG game server is running:
+
+```bash
+cd c:/Users/Chris4K/Projekte/projecthub/projects/MMOP_second_try
+python app.py
+```
+
+The server should be accessible at `http://localhost:7868` (UI) and the MCP endpoint at `http://localhost:7868/gradio_api/mcp/sse`.
+
+---
+
+## MCP Server Connection
+
+Here's how to establish a connection to the game server:
+
+### Basic Connection Setup
+
+```python
+import asyncio
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from contextlib import AsyncExitStack
+
+class GameClient:
+    def __init__(self, server_url="http://localhost:7868/gradio_api/mcp/sse"):
+        self.server_url = server_url
+        self.session = None
+        self.connected = False
+        self.tools = []
+        self.exit_stack = None
+        self.client_id = None
+    
+    async def connect(self):
+        """Connect to the game server"""
+        try:
+            # Clean up any existing connection
+            if self.exit_stack:
+                await self.exit_stack.aclose()
+            
+            self.exit_stack = AsyncExitStack()
+            
+            # Establish SSE connection
+            transport = await self.exit_stack.enter_async_context(
+                sse_client(self.server_url)
+            )
+            read_stream, write_callable = transport
+            
+            # Create MCP session
+            self.session = await self.exit_stack.enter_async_context(
+                ClientSession(read_stream, write_callable)
+            )
+            
+            # Initialize the session
+            await self.session.initialize()
+            
+            # Get available tools/commands
+            response = await self.session.list_tools()
+            self.tools = response.tools
+            
+            self.connected = True
+            print(f"✅ Connected to game server!")
+            print(f"Available commands: {[tool.name for tool in self.tools]}")
+            
+            return True
+            
+        except Exception as e:
+            print(f"❌ Connection failed: {e}")
+            self.connected = False
+            return False
+    
+    async def disconnect(self):
+        """Disconnect from the game server"""
+        if self.exit_stack:
+            await self.exit_stack.aclose()
+        self.connected = False
+        print("🔌 Disconnected from game server")
+```
+
+### Connection Test
+
+```python
+async def test_connection():
+    client = GameClient()
+    if await client.connect():
+        print("Connection successful!")
+        await client.disconnect()
+    else:
+        print("Connection failed!")
+
+# Run the test
+asyncio.run(test_connection())
+```
+
+---
+
+## Basic Client Example
+
+Here's a complete working client that can perform basic game operations:
+
+```python
+import asyncio
+import json
+import uuid
+from typing import Dict, List, Optional
+
+class SimpleGameClient:
+    def __init__(self, server_url="http://localhost:7868/gradio_api/mcp/sse"):
+        self.server_url = server_url
+        self.session = None
+        self.connected = False
+        self.tools = []
+        self.exit_stack = None
+        self.client_id = str(uuid.uuid4())[:8]
+        self.agent_id = None
+        self.player_name = None
+    
+    async def connect(self):
+        """Connect to the game server"""
+        try:
+            if self.exit_stack:
+                await self.exit_stack.aclose()
+            
+            self.exit_stack = AsyncExitStack()
+            
+            transport = await self.exit_stack.enter_async_context(
+                sse_client(self.server_url)
+            )
+            read_stream, write_callable = transport
+            
+            self.session = await self.exit_stack.enter_async_context(
+                ClientSession(read_stream, write_callable)
+            )
+            
+            await self.session.initialize()
+            response = await self.session.list_tools()
+            self.tools = response.tools
+            
+            self.connected = True
+            return True
+            
+        except Exception as e:
+            print(f"❌ Connection failed: {e}")
+            return False
+    
+    async def register_player(self, player_name: str):
+        """Register as a new player in the game"""
+        if not self.connected:
+            print("❌ Not connected to server")
+            return False
+        
+        try:
+            # Find the register tool
+            register_tool = next((t for t in self.tools if 'register' in t.name), None)
+            if not register_tool:
+                print("❌ Register tool not available")
+                return False
+            
+            # Register the player
+            result = await self.session.call_tool(
+                register_tool.name,
+                {"name": player_name, "client_id": self.client_id}
+            )
+            
+            # Parse the result
+            content = self._extract_content(result)
+            if "registered" in content.lower():
+                self.player_name = player_name
+                # Extract agent_id from response if available
+                if "agent_id" in content or "ID:" in content:
+                    # Parse agent ID from response
+                    lines = content.split('\n')
+                    for line in lines:
+                        if "agent_id" in line.lower() or "id:" in line:
+                            parts = line.split(':')
+                            if len(parts) > 1:
+                                self.agent_id = parts[1].strip()
+                                break
+                
+                print(f"✅ Registered as player: {player_name}")
+                return True
+            else:
+                print(f"❌ Registration failed: {content}")
+                return False
+                
+        except Exception as e:
+            print(f"❌ Registration error: {e}")
+            return False
+    
+    async def move_player(self, direction: str):
+        """Move the player in the specified direction"""
+        if not self.connected or not self.agent_id:
+            print("❌ Not connected or not registered")
+            return False
+        
+        try:
+            # Find the move tool
+            move_tool = next((t for t in self.tools if 'move' in t.name), None)
+            if not move_tool:
+                print("❌ Move tool not available")
+                return False
+            
+            # Move the player
+            result = await self.session.call_tool(
+                move_tool.name,
+                {"client_id": self.client_id, "direction": direction}
+            )
+            
+            content = self._extract_content(result)
+            print(f"🚶 Move result: {content}")
+            return True
+            
+        except Exception as e:
+            print(f"❌ Move error: {e}")
+            return False
+    
+    async def send_chat(self, message: str):
+        """Send a chat message to other players"""
+        if not self.connected or not self.agent_id:
+            print("❌ Not connected or not registered")
+            return False
+        
+        try:
+            # Find the chat tool
+            chat_tool = next((t for t in self.tools if 'chat' in t.name), None)
+            if not chat_tool:
+                print("❌ Chat tool not available")
+                return False
+            
+            # Send the chat message
+            result = await self.session.call_tool(
+                chat_tool.name,
+                {"client_id": self.client_id, "message": message}
+            )
+            
+            content = self._extract_content(result)
+            print(f"💬 Chat sent: {content}")
+            return True
+            
+        except Exception as e:
+            print(f"❌ Chat error: {e}")
+            return False
+    
+    async def get_game_state(self):
+        """Get current game state information"""
+        if not self.connected:
+            print("❌ Not connected to server")
+            return None
+        
+        try:
+            # Find the game state tool
+            state_tool = next((t for t in self.tools if 'state' in t.name or 'game' in t.name), None)
+            if not state_tool:
+                print("❌ Game state tool not available")
+                return None
+            
+            # Get game state
+            result = await self.session.call_tool(state_tool.name, {})
+            content = self._extract_content(result)
+            
+            try:
+                # Try to parse as JSON
+                game_state = json.loads(content)
+                return game_state
+            except json.JSONDecodeError:
+                # Return as text if not JSON
+                return {"info": content}
+                
+        except Exception as e:
+            print(f"❌ Game state error: {e}")
+            return None
+    
+    async def interact_with_npc(self, npc_id: str, message: str):
+        """Interact with an NPC"""
+        if not self.connected or not self.agent_id:
+            print("❌ Not connected or not registered")
+            return False
+        
+        try:
+            # Find the interact tool
+            interact_tool = next((t for t in self.tools if 'interact' in t.name or 'npc' in t.name), None)
+            if not interact_tool:
+                print("❌ Interact tool not available")
+                return False
+            
+            # Interact with NPC
+            result = await self.session.call_tool(
+                interact_tool.name,
+                {"client_id": self.client_id, "npc_id": npc_id, "message": message}
+            )
+            
+            content = self._extract_content(result)
+            print(f"🤖 NPC {npc_id}: {content}")
+            return True
+            
+        except Exception as e:
+            print(f"❌ Interaction error: {e}")
+            return False
+    
+    def _extract_content(self, result):
+        """Extract content from MCP result"""
+        if hasattr(result, 'content') and result.content:
+            if isinstance(result.content, list):
+                return ''.join(str(item) for item in result.content)
+            return str(result.content)
+        return str(result)
+    
+    async def disconnect(self):
+        """Disconnect from the server"""
+        if self.exit_stack:
+            await self.exit_stack.aclose()
+        self.connected = False
+        print("🔌 Disconnected from server")
+
+# Import required modules at the top
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from contextlib import AsyncExitStack
+```
+
+---
+
+## Available Game Operations
+
+The game server exposes these main operations through MCP tools:
+
+### 1. Player Management
+- **`register_ai_agent`** - Register a new player
+- **`move_agent`** - Move player in game world
+- **`get_game_state`** - Get current world state
+
+### 2. Communication
+- **`send_chat`** - Send chat messages
+- **`interact_with_npc`** - Talk to NPCs
+
+### 3. Game Information
+- **`get_game_state`** - World state and player list
+- **Player proximity** - Detect nearby players/NPCs
+
+### Tool Parameters
+
+Each tool expects specific parameters:
+
+```python
+# Register Player
+{
+    "name": "PlayerName",
+    "client_id": "unique_client_id"
+}
+
+# Move Player
+{
+    "client_id": "your_client_id",
+    "direction": "north|south|east|west"
+}
+
+# Send Chat
+{
+    "client_id": "your_client_id", 
+    "message": "Hello world!"
+}
+
+# Interact with NPC
+{
+    "client_id": "your_client_id",
+    "npc_id": "npc_identifier",
+    "message": "Your message to NPC"
+}
+```
+
+---
+
+## Command Reference
+
+### Basic Usage Example
+
+```python
+async def main():
+    # Create and connect client
+    client = SimpleGameClient()
+    
+    if not await client.connect():
+        print("Failed to connect!")
+        return
+    
+    # Register as a player
+    if not await client.register_player("MyPlayer"):
+        print("Failed to register!")
+        return
+    
+    # Get current game state
+    state = await client.get_game_state()
+    print(f"Game state: {state}")
+    
+    # Move around
+    await client.move_player("north")
+    await client.move_player("east")
+    
+    # Send a chat message
+    await client.send_chat("Hello everyone!")
+    
+    # Interact with an NPC
+    await client.interact_with_npc("weather_oracle", "What's the weather in Berlin?")
+    
+    # Disconnect
+    await client.disconnect()
+
+# Run the client
+asyncio.run(main())
+```
+
+### Interactive Console Client
+
+```python
+async def interactive_client():
+    client = SimpleGameClient()
+    
+    print("🎮 MMORPG Simple Client")
+    print("Commands: connect, register <name>, move <direction>, chat <message>, state, quit")
+    
+    while True:
+        command = input("> ").strip().split()
+        
+        if not command:
+            continue
+            
+        cmd = command[0].lower()
+        
+        if cmd == "connect":
+            if await client.connect():
+                print("✅ Connected!")
+            else:
+                print("❌ Connection failed!")
+                
+        elif cmd == "register" and len(command) > 1:
+            name = " ".join(command[1:])
+            if await client.register_player(name):
+                print(f"✅ Registered as {name}")
+            else:
+                print("❌ Registration failed!")
+                
+        elif cmd == "move" and len(command) > 1:
+            direction = command[1]
+            await client.move_player(direction)
+            
+        elif cmd == "chat" and len(command) > 1:
+            message = " ".join(command[1:])
+            await client.send_chat(message)
+            
+        elif cmd == "state":
+            state = await client.get_game_state()
+            print(f"📊 Game State: {json.dumps(state, indent=2)}")
+            
+        elif cmd == "npc" and len(command) > 2:
+            npc_id = command[1]
+            message = " ".join(command[2:])
+            await client.interact_with_npc(npc_id, message)
+            
+        elif cmd == "quit":
+            await client.disconnect()
+            break
+            
+        else:
+            print("❓ Unknown command")
+
+# Run interactive client
+asyncio.run(interactive_client())
+```
+
+---
+
+## Error Handling
+
+### Common Issues and Solutions
+
+#### 1. Connection Errors
+```python
+async def robust_connect(client, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            if await client.connect():
+                return True
+            print(f"Attempt {attempt + 1} failed, retrying...")
+            await asyncio.sleep(2)
+        except Exception as e:
+            print(f"Connection attempt {attempt + 1} error: {e}")
+    
+    print("❌ All connection attempts failed")
+    return False
+```
+
+#### 2. Tool Not Available
+```python
+def find_tool_safe(tools, keywords):
+    """Safely find a tool by keywords"""
+    for keyword in keywords:
+        tool = next((t for t in tools if keyword in t.name.lower()), None)
+        if tool:
+            return tool
+    return None
+
+# Usage
+move_tool = find_tool_safe(client.tools, ['move', 'agent', 'player'])
+if not move_tool:
+    print("❌ No movement tool available")
+```
+
+#### 3. Response Parsing
+```python
+def safe_parse_response(result):
+    """Safely parse MCP response"""
+    try:
+        content = client._extract_content(result)
+        
+        # Try JSON first
+        try:
+            return json.loads(content)
+        except json.JSONDecodeError:
+            # Return as structured text
+            return {"message": content, "type": "text"}
+            
+    except Exception as e:
+        return {"error": str(e), "type": "error"}
+```
+
+---
+
+## Advanced Features
+
+### 1. Automatic Reconnection
+
+```python
+class RobustGameClient(SimpleGameClient):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.auto_reconnect = True
+        self.reconnect_delay = 5
+    
+    async def _ensure_connected(self):
+        """Ensure connection is active, reconnect if needed"""
+        if not self.connected and self.auto_reconnect:
+            print("🔄 Attempting to reconnect...")
+            await self.connect()
+            if self.player_name:
+                await self.register_player(self.player_name)
+    
+    async def move_player(self, direction):
+        await self._ensure_connected()
+        return await super().move_player(direction)
+```
+
+### 2. Event Monitoring
+
+```python
+class EventMonitorClient(SimpleGameClient):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.event_handlers = {}
+    
+    def on_chat_message(self, handler):
+        """Register handler for chat messages"""
+        self.event_handlers['chat'] = handler
+    
+    def on_player_move(self, handler):
+        """Register handler for player movements"""
+        self.event_handlers['move'] = handler
+    
+    async def poll_events(self):
+        """Poll for game events"""
+        while self.connected:
+            try:
+                state = await self.get_game_state()
+                # Process state changes and trigger handlers
+                # Implementation depends on game state format
+                await asyncio.sleep(1)
+            except Exception as e:
+                print(f"Event polling error: {e}")
+                await asyncio.sleep(5)
+```
+
+### 3. Batch Operations
+
+```python
+async def batch_moves(client, moves):
+    """Execute multiple moves in sequence"""
+    for direction in moves:
+        result = await client.move_player(direction)
+        if not result:
+            print(f"❌ Failed to move {direction}")
+            break
+        await asyncio.sleep(0.5)  # Small delay between moves
+
+# Usage
+await batch_moves(client, ["north", "north", "east", "south"])
+```
+
+### 4. Configuration Management
+
+```python
+import json
+
+class ConfigurableClient(SimpleGameClient):
+    def __init__(self, config_file="client_config.json"):
+        # Load configuration
+        try:
+            with open(config_file, 'r') as f:
+                config = json.load(f)
+        except FileNotFoundError:
+            config = self.default_config()
+            
+        super().__init__(config.get('server_url', 'http://localhost:7860/gradio_api/mcp/sse'))
+        self.config = config
+    
+    def default_config(self):
+        return {
+            "server_url": "http://localhost:7860/gradio_api/mcp/sse",
+            "player_name": "DefaultPlayer",
+            "auto_reconnect": True,
+            "move_delay": 0.5
+        }
+```
+
+---
+
+## Quick Start Script
+
+Save this as `quick_client.py` for immediate testing:
+
+```python
+#!/usr/bin/env python3
+"""
+Quick Game Client - Connect and play immediately
+Usage: python quick_client.py [player_name]
+"""
+
+import asyncio
+import sys
+from simple_game_client import SimpleGameClient
+
+async def quick_play(player_name="TestPlayer"):
+    client = SimpleGameClient()
+    
+    print(f"🎮 Connecting as {player_name}...")
+    
+    # Connect and register
+    if not await client.connect():
+        print("❌ Failed to connect!")
+        return
+    
+    if not await client.register_player(player_name):
+        print("❌ Failed to register!")
+        return
+    
+    print("✅ Connected and registered successfully!")
+    
+    # Basic game session
+    await client.send_chat(f"Hello! {player_name} has joined the game!")
+    
+    # Move around a bit
+    moves = ["north", "east", "south", "west"]
+    for move in moves:
+        print(f"🚶 Moving {move}...")
+        await client.move_player(move)
+        await asyncio.sleep(1)
+    
+    # Get final state
+    state = await client.get_game_state()
+    print(f"📊 Final state: {state}")
+    
+    await client.disconnect()
+    print("👋 Session ended!")
+
+if __name__ == "__main__":
+    player_name = sys.argv[1] if len(sys.argv) > 1 else "TestPlayer"
+    asyncio.run(quick_play(player_name))
+```
+
+Run with:
+```bash
+python quick_client.py MyPlayerName
+```
+
+---
+
+## Next Steps
+
+1. **Customize the client** for your specific needs
+2. **Add game-specific features** like inventory management
+3. **Implement advanced AI** for automated gameplay
+4. **Create GUI interfaces** using tkinter, PyQt, or web frameworks
+5. **Build monitoring tools** for game statistics
+
+This guide provides the foundation for any client application that needs to interact with the MMORPG game server!

USER_DOCUMENTATION.md

@@ -0,0 +1,907 @@
+# 🎮 MMORPG with MCP Integration - User Documentation
+
+## 📋 Table of Contents
+
+1. [Overview](#overview)
+2. [Quick Start Guide](#quick-start-guide)
+3. [Core Features](#core-features)
+4. [User Interface Guide](#user-interface-guide)
+5. [Gameplay Mechanics](#gameplay-mechanics)
+6. [MCP Integration](#mcp-integration)
+7. [Developer & AI Agent Usage](#developer--ai-agent-usage)
+8. [NPC Addon System](#npc-addon-system)
+9. [Advanced Features](#advanced-features)
+10. [Troubleshooting](#troubleshooting)
+11. [API Reference](#api-reference)
+
+---
+
+## 📖 Overview
+
+The **MMORPG with MCP Integration** is a real-time multiplayer online role-playing game that serves as both an entertaining game and a powerful platform for testing and developing Model Context Protocol (MCP) integrations. It combines traditional MMORPG elements with cutting-edge AI agent capabilities.
+
+### 🎯 What Makes This Special
+
+- **🌍 Real-time Multiplayer**: Multiple human players can join simultaneously
+- **🤖 AI Agent Support**: AI agents can connect and play alongside humans
+- **🔌 MCP Integration**: Full Model Context Protocol support for extensibility
+- **🧩 Addon System**: Extensible NPC addon architecture
+- **⌨️ Keyboard Controls**: WASD and arrow key support for fluid gameplay
+- **🔥 Secure Messaging**: Read2Burn self-destructing message system
+- **🌤️ Live Services**: Real weather integration via MCP
+- **🔧 Developer Platform**: Complete API for building custom integrations
+
+### 🚀 Use Cases
+
+**For Gamers:**
+- Experience a unique MMORPG with AI-powered NPCs
+- Interact with real-time weather and other live services
+- Send secure self-destructing messages to other players
+
+**For Developers:**
+- Test MCP server integrations in a real-world environment
+- Develop custom NPC addons with rich functionality
+- Build AI agents that can play and interact in the game
+- Prototype multiplayer game mechanics
+
+**For AI Researchers:**
+- Study human-AI interaction in gaming environments
+- Test AI agent behaviors in social multiplayer settings
+- Develop and evaluate conversational AI systems
+
+**For MCP Server Developers:**
+- Test server implementations with real users
+- Demonstrate MCP capabilities in an engaging context
+- Debug and optimize server performance
+
+---
+
+## 🚀 Quick Start Guide
+
+### 1. Starting the Game
+
+```bash
+# Navigate to the project directory
+cd c:\Users\Chris4K\Projekte\projecthub\projects\MMOP_second_try
+
+# Install dependencies (first time only)
+pip install gradio mcp aiohttp asyncio
+
+# Start the game server
+python app.py
+```
+
+The game will start and display:
+```
+🎮 Starting COMPLETE MMORPG with ALL FEATURES...
+🌐 Human players: Access via web interface
+🤖 AI agents: Connect via MCP API endpoints
+⌨️ Keyboard: Use WASD or Arrow Keys for movement
+🔌 MCP Tools available for AI integration
+🔥 Read2Burn mailbox for secure messaging
+🎯 All features working with deadlock fix!
+* Running on local URL: http://127.0.0.1:7868
+🔨 MCP server (using SSE) running at: http://127.0.0.1:7868/gradio_api/mcp/sse
+```
+
+### 2. Joining as a Human Player
+
+1. Open your web browser and go to `http://127.0.0.1:7868`
+2. Navigate to the **🌍 Game World** tab
+3. Enter your desired player name in the "Player Name" field
+4. Click **"🎮 Join Game"**
+5. You'll see your character (🧝‍♂️) appear on the game map
+
+### 3. Basic Movement
+
+**Web Interface:**
+- Use the directional buttons: ↑ ↓ ← →
+
+**Keyboard Controls:**
+- **WASD Keys**: W (up), A (left), S (down), D (right)
+- **Arrow Keys**: ↑ ↓ ← →
+- **Space**: Action key (context-sensitive)
+
+### 4. First Interactions
+
+**Chat with Others:**
+1. Go to the **💬 Chat** tab
+2. Type a message and press Enter
+3. All players will see your message
+
+**Talk to NPCs:**
+1. Move close to an NPC on the map
+2. Go to the **🎯 Private Messages** tab
+3. Select the NPC from the dropdown
+4. Send them a message
+
+---
+
+## 🎮 Core Features
+
+### 🌍 Real-time Game World
+
+**Map System:**
+- **Size**: 500x400 pixel game world
+- **Visual Style**: Fantasy forest theme with grid overlay
+- **Real-time Updates**: All player movements update immediately
+- **Collision Detection**: Prevents players from occupying same space
+
+**Player Characters:**
+- **Humans**: Represented by 🧝‍♂️ (elf character)
+- **AI Agents**: Represented by 🤖 (robot character)
+- **Name Tags**: Player names displayed above characters
+- **Level Display**: Shows current player level
+
+### 👥 Multiplayer System
+
+**Player Management:**
+- **Concurrent Players**: Supports multiple simultaneous players
+- **Unique Sessions**: Each player gets a unique session ID
+- **Real-time Sync**: All actions sync across all connected clients
+- **Player Stats**: Level, HP, gold, experience tracking
+
+**Player Actions:**
+- **Join/Leave**: Seamless game entry/exit
+- **Movement**: 4-directional movement with smooth transitions
+- **Chat**: Public chat visible to all players
+- **Private Messaging**: Direct communication with NPCs
+
+### 🎯 NPC System
+
+**Built-in NPCs:**
+- **🧙‍♂️ Village Elder**: Wise questgiver and general information
+- **⚔️ Warrior Trainer**: Combat training and warrior wisdom
+- **🏪 Merchant**: Trade goods and equipment
+- **🌟 Mystic Oracle**: Magical insights and prophecies
+- **🚶‍♂️ Roaming Rick**: Wandering NPC with location updates
+- **📮 Read2Burn Mailbox**: Secure message handling
+- **🌤️ Weather Oracle**: Real-time weather information
+
+**NPC Features:**
+- **Personality System**: Each NPC has unique response patterns
+- **Proximity Detection**: NPCs respond when players approach
+- **Smart Responses**: Context-aware conversation handling
+- **Addon Support**: Extensible with custom functionality
+
+### 💬 Communication Systems
+
+**Public Chat:**
+- **Real-time Messaging**: Instant message delivery
+- **Player Identification**: Messages show sender name and type
+- **Message History**: Scrollable chat history
+- **Command Support**: Special commands like `/help`
+
+**Private Messaging:**
+- **NPC Communication**: Direct messages to any NPC
+- **Secure Channels**: Private conversation channels
+- **Response Handling**: NPCs can provide detailed responses
+- **Message Logging**: Optional message history tracking
+
+---
+
+## 🖥️ User Interface Guide
+
+### 🌍 Game World Tab
+
+**Main Game View:**
+- **Game Map**: Central 500x400 pixel game world
+- **Player Controls**: Movement buttons (↑ ↓ ← →)
+- **Join/Leave**: Game participation controls
+- **Auto-refresh**: Real-time world updates
+
+**Player Information Panel:**
+```
+🟢 Connected | Player: YourName | Level: 1
+HP: 100/100 | Gold: 50 | XP: 0/100
+Position: (150, 200) | Session: abc12345...
+Last Update: 14:30:15
+```
+
+**Control Layout:**
+```
+Player Name: [_____________]
+[🎮 Join Game] [👋 Leave Game]
+
+        [↑]
+    [←] [⚔️] [→]
+        [↓]
+```
+
+### 💬 Chat Tab
+
+**Interface Elements:**
+- **Message Input**: Text field for typing messages
+- **Send Button**: Submit messages to all players
+- **Chat History**: Scrollable message display
+- **Auto-scroll**: Automatically shows latest messages
+
+**Message Format:**
+```
+[14:30] 👤 PlayerName: Hello everyone!
+[14:31] 🤖 AIAgent: Greetings, fellow adventurers!
+[14:32] 🌍 System: New player joined the world
+```
+
+### 🎯 Private Messages Tab
+
+**NPC Selection:**
+- **Dropdown Menu**: List of all available NPCs
+- **NPC Status**: Shows which NPCs are online/available
+- **Message Input**: Text field for private messages
+- **Response Display**: Shows NPC replies
+
+**Example Interaction:**
+```
+To: 🌤️ Weather Oracle
+Message: What's the weather in Berlin?
+
+🌤️ Weather Oracle: 🌍 The spirits speak of Berlin, Germany:
+☀️ Clear skies with 18°C
+💨 Light winds from the northwest
+🌡️ Feels like 19°C
+Perfect weather for outdoor adventures!
+```
+
+### 📊 Player Stats Tab
+
+**Detailed Statistics:**
+- **Basic Info**: Name, level, type (human/AI)
+- **Combat Stats**: HP, maximum HP, combat level
+- **Resources**: Gold pieces, experience points
+- **Location**: Current X,Y coordinates
+- **Session Info**: Connection time, session ID
+
+### 🔥 Read2Burn Mailbox Tab
+
+**Secure Messaging Interface:**
+- **Create Message**: Compose self-destructing messages
+- **Message Management**: View your active messages
+- **Read Messages**: Access messages sent to you
+- **Security Settings**: Configure burn timers and read limits
+
+**Usage Example:**
+```
+Create Message:
+Content: [Secret meeting at coordinates 200,150]
+[📮 Create Secure Message]
+
+Result:
+✅ Message Created Successfully!
+📝 Message ID: AbC123Xyz789
+🔗 Share this ID with the recipient
+⏰ Expires in 24 hours
+🔥 Burns after 1 read
+```
+
+### 🌤️ Weather Oracle Tab
+
+**Weather Service Interface:**
+- **Location Input**: City, Country format
+- **Get Weather Button**: Fetch current conditions
+- **Weather Display**: Formatted weather information
+- **Examples**: Pre-filled location examples
+
+**Weather Response Format:**
+```
+🌍 Weather for Berlin, Germany:
+🌡️ Temperature: 18°C (feels like 19°C)
+☀️ Conditions: Clear skies
+💨 Wind: 12 km/h northwest
+💧 Humidity: 65%
+👁️ Visibility: 10 km
+```
+
+---
+
+## 🎮 Gameplay Mechanics
+
+### 🚶‍♂️ Movement System
+
+**Movement Controls:**
+- **Web Buttons**: Click directional arrows
+- **Keyboard**: WASD or arrow keys
+- **Movement Speed**: Fixed speed with smooth transitions
+- **Boundary Checking**: Prevents movement outside game world
+
+**Movement Feedback:**
+- **Visual**: Character position updates immediately
+- **Audio**: Optional movement sound effects
+- **Chat**: Movement can trigger proximity events
+- **Stats**: Position coordinates update in real-time
+
+### 📈 Character Progression
+
+**Experience System:**
+- **Starting Level**: All players begin at level 1
+- **Experience Gain**: Earn XP through various activities
+- **Level Up**: Automatic progression when XP threshold reached
+- **Benefits**: Higher levels unlock new features
+
+**Resource Management:**
+- **Health Points (HP)**: Combat and survival metric
+- **Gold**: In-game currency for transactions
+- **Experience (XP)**: Progression tracking
+- **Inventory**: Items and equipment (future feature)
+
+### 🎯 Interaction System
+
+**NPC Interaction:**
+- **Proximity-based**: NPCs respond when players are nearby
+- **Message-based**: Send direct messages to any NPC
+- **Context-aware**: NPCs provide relevant responses
+- **Addon-powered**: Enhanced NPCs with special abilities
+
+**Player Interaction:**
+- **Public Chat**: Communicate with all players
+- **Private Messages**: Future feature for player-to-player
+- **Collaborative**: Work together on quests and challenges
+- **Social**: Build friendships and alliances
+
+### 🌍 World Events
+
+**Dynamic Events:**
+- **Player Join/Leave**: Announced to all players
+- **NPC Activities**: Roaming NPCs change positions
+- **Weather Updates**: Real-time weather changes
+- **System Messages**: Important game announcements
+
+**Event Examples:**
+```
+🌍 PlayerName has joined the adventure!
+🚶‍♂️ Roaming Rick moved to the village square
+🌤️ Weather updated for current location
+⚔️ A new quest has become available
+```
+
+---
+
+## 🔌 MCP Integration
+
+### 🤖 AI Agent Connection
+
+**MCP Endpoint:**
+- **URL**: `http://127.0.0.1:7868/gradio_api/mcp/sse`
+- **Protocol**: Server-Sent Events (SSE)
+- **Format**: JSON messages following MCP specification
+
+**Available MCP Tools:**
+1. **join_game**: Register as a player
+2. **leave_game**: Leave the game world
+3. **move_up_handler/move_down_handler/move_left_handler/move_right_handler**: Movement controls
+4. **handle_chat**: Send public chat messages
+5. **handle_private_message**: Send private messages to NPCs
+6. **register_test_ai_agent**: Register AI agent
+7. **execute_ai_action**: Execute AI agent actions
+8. **handle_mailbox_command**: Interact with Read2Burn system
+9. **handle_weather_request**: Get weather information
+10. **install_addon**: Add new NPC addons
+
+### 📡 MCP Tool Usage Examples
+
+**Joining the Game:**
+```json
+{
+  "tool": "join_game",
+  "parameters": {
+    "name": "MyAIAgent"
+  }
+}
+```
+
+**Moving Around:**
+```json
+{
+  "tool": "move_up_handler",
+  "parameters": {}
+}
+```
+
+**Sending Chat:**
+```json
+{
+  "tool": "handle_chat",
+  "parameters": {
+    "message": "Hello from AI agent!"
+  }
+}
+```
+
+**Talking to NPCs:**
+```json
+{
+  "tool": "handle_private_message",
+  "parameters": {
+    "message": "What quests are available?"
+  }
+}
+```
+
+### 🌐 MCP Server Development
+
+**Creating Custom MCP Servers:**
+1. Implement MCP protocol specification
+2. Expose game-relevant tools
+3. Handle authentication (if required)
+4. Provide tool descriptions and schemas
+5. Test with the game platform
+
+**Integration Process:**
+1. Start your MCP server
+2. Use the **install_addon** tool
+3. Provide server endpoint URL
+4. Configure addon settings
+5. Test functionality in-game
+
+---
+
+## 👨‍💻 Developer & AI Agent Usage
+
+### 🔧 Platform Capabilities
+
+**MCP Testing Platform:**
+- **Real-world Environment**: Test MCP servers with actual users
+- **Interactive Feedback**: See how humans interact with your tools
+- **Performance Monitoring**: Track server response times and errors
+- **Integration Validation**: Verify MCP protocol compliance
+
+**Development Benefits:**
+- **Rapid Prototyping**: Quickly test new MCP server features
+- **User Experience Testing**: Observe how users interact with your tools
+- **Community Feedback**: Get input from real users
+- **Documentation**: Generate examples from actual usage
+
+### 🤖 AI Agent Development
+
+**Agent Capabilities:**
+```python
+# Example AI agent implementation
+class GameAIAgent:
+    def __init__(self, name):
+        self.name = name
+        self.mcp_client = MCPClient("http://127.0.0.1:7868/gradio_api/mcp/sse")
+    
+    async def join_and_explore(self):
+        # Join the game
+        await self.mcp_client.call_tool("join_game", {"name": self.name})
+        
+        # Explore the world
+        directions = ["move_up_handler", "move_right_handler", 
+                     "move_down_handler", "move_left_handler"]
+        
+        for direction in directions:
+            await self.mcp_client.call_tool(direction, {})
+            await asyncio.sleep(1)
+        
+        # Interact with NPCs
+        await self.mcp_client.call_tool("handle_private_message", {
+            "message": "Hello, I'm an AI explorer!"
+        })
+```
+
+**Agent Use Cases:**
+- **Game Testing**: Automated gameplay testing
+- **NPC Interaction**: Test conversational AI systems
+- **Multiplayer Simulation**: Simulate player populations
+- **Data Collection**: Gather interaction data for research
+
+### 🧩 Custom NPC Development
+
+**Addon Architecture:**
+```python
+class CustomNPCAddon(NPCAddon):
+    @property
+    def addon_id(self) -> str:
+        return "my_custom_npc"
+    
+    @property
+    def addon_name(self) -> str:
+        return "My Custom NPC"
+    
+    def get_interface(self) -> gr.Component:
+        # Create Gradio interface
+        pass
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        # Process player commands
+        return "Custom NPC response"
+```
+
+**Development Steps:**
+1. Inherit from `NPCAddon` base class
+2. Implement required methods
+3. Create Gradio interface components
+4. Handle player commands and interactions
+5. Register addon with game world
+
+### 📊 Research Applications
+
+**Human-AI Interaction Studies:**
+- **Mixed Populations**: Study humans and AI agents together
+- **Conversation Analysis**: Analyze chat patterns and interactions
+- **Behavior Modeling**: Model player behavior patterns
+- **Social Dynamics**: Understand multiplayer social structures
+
+**MCP Protocol Research:**
+- **Performance Analysis**: Measure protocol efficiency
+- **Compatibility Testing**: Test different MCP implementations
+- **Feature Evaluation**: Evaluate new MCP features
+- **Integration Patterns**: Develop best practices
+
+---
+
+## 🧩 NPC Addon System
+
+### 📮 Read2Burn Mailbox
+
+**Features:**
+- **Self-destructing Messages**: Messages burn after reading
+- **Expiration Timer**: 24-hour automatic expiration
+- **Read Limits**: Configurable read count before burning
+- **Access Logging**: Track message creation and access
+- **Secure IDs**: Unique, hard-to-guess message identifiers
+
+**Commands:**
+- **create [message]**: Create new secure message
+- **read [message_id]**: Read and burn message
+- **list**: Show your active messages
+
+**Usage Example:**
+```
+Player: create Secret meeting location
+Mailbox: ✅ Message Created! ID: AbC123Xyz789
+
+Player: read AbC123Xyz789
+Mailbox: 📖 Message Content: Secret meeting location
+🔥 This message has been BURNED and deleted forever!
+```
+
+### 🌤️ Weather Oracle
+
+**Features:**
+- **Real-time Weather**: Live weather data via MCP
+- **Global Coverage**: Weather for any city worldwide
+- **Detailed Information**: Temperature, conditions, wind, humidity
+- **Format Flexibility**: Supports "City, Country" format
+- **Error Handling**: Graceful handling of invalid locations
+
+**Usage Examples:**
+```
+Player: Berlin, Germany
+Oracle: 🌍 Weather for Berlin, Germany:
+        🌡️ 18°C, clear skies
+        💨 Light winds, 65% humidity
+
+Player: Tokyo
+Oracle: 🌍 Weather for Tokyo, Japan:
+        🌡️ 22°C, partly cloudy
+        💨 Moderate winds, 70% humidity
+```
+
+### 🏪 Generic NPCs
+
+**Built-in NPCs:**
+- **Village Elder**: Quests and lore
+- **Warrior Trainer**: Combat training
+- **Merchant**: Trading and equipment
+- **Mystic Oracle**: Magical services
+- **Roaming Rick**: Dynamic location updates
+
+**Response System:**
+- **Personality-based**: Each NPC has unique personality
+- **Context-aware**: Responses based on player context
+- **Randomized**: Multiple response options for variety
+- **Extensible**: Easy to add new NPCs and responses
+
+---
+
+## 🔬 Advanced Features
+
+### 🎯 Auto-refresh System
+
+**Real-time Updates:**
+- **World State**: Continuous map updates
+- **Player Positions**: Live position tracking
+- **Chat Messages**: Instant message delivery
+- **NPC Status**: Dynamic NPC state updates
+
+**Performance Optimization:**
+- **Selective Updates**: Only update changed elements
+- **Throttling**: Prevent excessive update frequency
+- **Error Recovery**: Graceful handling of update failures
+- **Resource Management**: Efficient memory usage
+
+### 🔐 Session Management
+
+**Player Sessions:**
+- **Unique IDs**: Each player gets unique session identifier
+- **State Persistence**: Maintain player state across interactions
+- **Cleanup**: Automatic cleanup of disconnected players
+- **Security**: Prevent session hijacking and spoofing
+
+**Multi-client Support:**
+- **Concurrent Players**: Multiple players simultaneously
+- **Session Isolation**: Each player's state remains separate
+- **Resource Sharing**: Efficient sharing of game world state
+- **Conflict Resolution**: Handle simultaneous action conflicts
+
+### 📡 MCP Server Integration
+
+**Server Discovery:**
+- **Endpoint Management**: Track multiple MCP server endpoints
+- **Health Checking**: Monitor server availability
+- **Load Balancing**: Distribute requests across servers
+- **Failover**: Handle server outages gracefully
+
+**Protocol Support:**
+- **SSE Integration**: Server-Sent Events for real-time communication
+- **Tool Discovery**: Automatic detection of available tools
+- **Schema Validation**: Ensure tool parameters match schemas
+- **Error Handling**: Robust error recovery and reporting
+
+### 🎨 UI Customization
+
+**Theme System:**
+- **Color Schemes**: Multiple visual themes
+- **Layout Options**: Customizable interface layouts
+- **Accessibility**: Support for screen readers and keyboard navigation
+- **Responsive Design**: Works on different screen sizes
+
+**Interface Components:**
+- **Gradio Integration**: Rich web interface components
+- **Custom Styling**: CSS customization options
+- **Interactive Elements**: Buttons, inputs, displays
+- **Real-time Updates**: Live data binding and updates
+
+---
+
+## 🔧 Troubleshooting
+
+### 🚨 Common Issues
+
+**Connection Problems:**
+```
+Issue: "Cannot connect to game server"
+Solution: 
+1. Check if server is running (python app.py)
+2. Verify port 7868 is available
+3. Check firewall settings
+4. Try restarting the server
+```
+
+**Keyboard Controls Not Working:**
+```
+Issue: "WASD keys don't move character"
+Solution:
+1. Ensure JavaScript is enabled
+2. Click on the game interface to focus
+3. Check browser console for errors
+4. Try refreshing the page
+```
+
+**NPC Not Responding:**
+```
+Issue: "NPC doesn't reply to messages"
+Solution:
+1. Check NPC addon is loaded
+2. Verify message format
+3. Look for error messages in console
+4. Try different NPC
+```
+
+**MCP Connection Failures:**
+```
+Issue: "AI agent cannot connect via MCP"
+Solution:
+1. Verify MCP endpoint URL
+2. Check MCP server is running
+3. Validate tool parameters
+4. Review MCP protocol compliance
+```
+
+### 🐛 Debug Information
+
+**Enable Debug Mode:**
+```python
+# Add to app.py for detailed logging
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+**Check Logs:**
+- **Console Output**: Server startup and error messages
+- **Browser Console**: JavaScript errors and warnings
+- **MCP Logs**: Tool call results and errors
+- **Game Events**: Player actions and world updates
+
+**Performance Monitoring:**
+- **Player Count**: Monitor concurrent player limits
+- **Memory Usage**: Track RAM consumption
+- **Response Times**: Measure tool execution times
+- **Error Rates**: Monitor failure frequencies
+
+---
+
+## 📚 API Reference
+
+### 🎮 Core Game APIs
+
+**Player Management:**
+```python
+# Join game
+game_world.add_player(player: Player) -> bool
+
+# Leave game  
+game_world.remove_player(player_id: str) -> bool
+
+# Move player
+game_world.move_player(player_id: str, direction: str) -> bool
+```
+
+**Chat System:**
+```python
+# Public chat
+game_world.add_chat_message(sender: str, message: str, 
+                           message_type: str = "public")
+
+# Private message
+game_world.send_private_message(sender_id: str, target_id: str, 
+                               message: str) -> tuple[bool, str]
+```
+
+**World State:**
+```python
+# Get world HTML
+create_game_world_html() -> str
+
+# Player stats
+get_player_stats_display(player_id: str) -> Dict
+
+# Player session
+get_player_id_from_session(session_hash: str) -> Optional[str]
+```
+
+### 🔌 MCP Tool Reference
+
+**Game Control Tools:**
+- `join_game(name: str)`: Join as player
+- `leave_game()`: Leave the game
+- `move_up_handler()`: Move up
+- `move_down_handler()`: Move down  
+- `move_left_handler()`: Move left
+- `move_right_handler()`: Move right
+
+**Communication Tools:**
+- `handle_chat(message: str)`: Send public chat
+- `handle_private_message(message: str)`: Send private message
+
+**AI Agent Tools:**
+- `register_test_ai_agent(ai_name: str)`: Register AI agent
+- `execute_ai_action(action: str, message: str)`: Execute AI action
+
+**Addon Tools:**
+- `handle_mailbox_command(command: str)`: Read2Burn mailbox
+- `handle_weather_request(location: str)`: Weather information
+- `install_addon(addon_type: str, addon_url: str, addon_name: str)`: Install addon
+
+### 🧩 Addon Development APIs
+
+**Base Classes:**
+```python
+class NPCAddon(ABC):
+    @property
+    @abstractmethod
+    def addon_id(self) -> str: ...
+    
+    @property  
+    @abstractmethod
+    def addon_name(self) -> str: ...
+    
+    @abstractmethod
+    def get_interface(self) -> gr.Component: ...
+    
+    @abstractmethod
+    def handle_command(self, player_id: str, command: str) -> str: ...
+```
+
+**Registration:**
+```python
+# Register addon
+game_world.addon_npcs[addon_id] = addon_instance
+
+# Access addon
+addon = game_world.addon_npcs.get(addon_id)
+```
+
+---
+
+## 🎯 Best Practices
+
+### 👥 For Players
+
+**Effective Communication:**
+- Use clear, descriptive messages
+- Be patient with AI agents learning
+- Report bugs and issues promptly
+- Share interesting discoveries with community
+
+**Game Etiquette:**
+- Respect other players
+- Don't spam chat or commands
+- Help new players learn the game
+- Provide feedback to developers
+
+### 🤖 For AI Agents
+
+**Efficient Integration:**
+- Cache frequently used data
+- Handle errors gracefully
+- Respect rate limits
+- Log interactions for debugging
+
+**Social Behavior:**
+- Introduce yourself when joining
+- Respond appropriately to other players
+- Follow game rules and conventions
+- Contribute positively to the community
+
+### 👨‍💻 For Developers
+
+**MCP Server Development:**
+- Follow MCP protocol specifications exactly
+- Provide detailed tool descriptions
+- Handle edge cases and errors
+- Test thoroughly before deployment
+
+**Addon Development:**
+- Keep interfaces simple and intuitive
+- Provide helpful error messages
+- Document your addon's capabilities
+- Share code examples with community
+
+---
+
+## 📞 Support & Community
+
+### 🆘 Getting Help
+
+**Documentation:**
+- This user guide for comprehensive information
+- NPC Addon Development Guide for addon creation
+- Simple Game Client Guide for client development
+- Sample MCP Server for server examples
+
+**Community Resources:**
+- GitHub Issues for bug reports and feature requests
+- Discussion forums for general questions
+- Developer Discord for real-time chat
+- Wiki for community-contributed content
+
+**Contact Information:**
+- **Technical Issues**: Create GitHub issue with detailed description
+- **Feature Requests**: Use GitHub discussions
+- **Security Issues**: Contact maintainers directly
+- **General Questions**: Use community forums
+
+### 🤝 Contributing
+
+**Ways to Contribute:**
+- **Bug Reports**: Help identify and fix issues
+- **Feature Development**: Implement new capabilities
+- **Documentation**: Improve guides and tutorials
+- **Testing**: Quality assurance and validation
+- **Community Support**: Help other users and developers
+
+**Development Process:**
+1. Fork the repository
+2. Create feature branch
+3. Implement changes with tests
+4. Submit pull request
+5. Participate in code review
+
+---
+
+*This documentation is continuously updated. Last updated: June 6, 2025*
+*For the latest version, visit: https://github.com/your-repo/MMOP*
+
+**🎮 Happy Gaming and Developing! 🚀**

plugins/enhanced_chat_plugin.py

@@ -0,0 +1,449 @@
+# Enhanced Chat Plugin
+import asyncio
+from src.interfaces.plugin_interfaces import IChatPlugin, PluginMetadata, PluginType
+from typing import Dict, List, Any
+
+class EnhancedChatPlugin(IChatPlugin):
+    def __init__(self):
+        self._metadata = PluginMetadata(
+            id="enhanced_chat",
+            name="Enhanced Chat System",
+            version="1.2.0",
+            author="MMORPG Dev Team",
+            description="Adds emotes, chat channels, and advanced chat commands",
+            plugin_type=PluginType.SERVICE,
+            dependencies=[],
+            config={
+                "enable_emotes": True,
+                "enable_channels": True,
+                "max_message_length": 500,
+                "chat_cooldown": 1
+            }
+        )
+        self._enabled = False
+        self._context = None
+        
+        # Chat history storage
+        self.chat_history = []
+        self.max_history = 100
+        
+        # Player ignore lists
+        self.ignore_lists = {}
+        
+        # Custom channels
+        self.channels = {
+            'global': {'description': 'Global chat channel', 'members': set()},
+            'trade': {'description': 'Trading channel', 'members': set()},
+            'help': {'description': 'Help and questions channel', 'members': set()}
+        }
+        
+        # Player channel memberships
+        self.player_channels = {}
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        return self._metadata
+
+    def initialize(self, context: Dict[str, Any]) -> bool:
+        """Initialize the enhanced chat plugin."""
+        try:
+            self._context = context
+            self._config = self._metadata.config
+            self._enabled = True
+            print(f"💬 Enhanced Chat Plugin initialized")
+            return True
+        except Exception as e:
+            print(f"💬 Failed to initialize Enhanced Chat Plugin: {e}")
+            return False
+
+    def shutdown(self) -> bool:
+        """Shutdown the plugin and cleanup resources."""
+        self._enabled = False
+        print("💬 Enhanced Chat Plugin shut down")
+        return True
+
+    def get_status(self) -> Dict[str, Any]:
+        """Get current plugin status."""
+        return {
+            "status": "active" if self._enabled else "inactive",
+            "message": "Enhanced chat system with marketplace commands"
+        }
+
+    def process_message(self, player_id: str, message: str, channel: str = "global") -> Dict[str, Any]:
+        """Process and enhance chat messages."""
+        if message.startswith('/'):
+            return self._process_command(player_id, message)
+        else:
+            return self._broadcast_message(player_id, message)
+
+    def get_available_commands(self) -> List[Dict[str, str]]:
+        """Get list of available chat commands."""
+        return [
+            {"command": "/marketplace", "description": "View marketplace listings"},
+            {"command": "/trade create <item> <price>", "description": "Create trade listing"},
+            {"command": "/trade accept <id>", "description": "Accept trade offer"},
+            {"command": "/auction create <item> <start_price>", "description": "Create auction"},
+            {"command": "/tell <player> <message>", "description": "Send private message"},
+            {"command": "/who", "description": "List online players"},
+            {"command": "/help", "description": "Show available commands"},
+            {"command": "/shout <message>", "description": "Shout to all players"},
+            {"command": "/emote <action>", "description": "Perform an emote"},
+            {"command": "/me <action>", "description": "Perform an emote (alias)"},
+            {"command": "/time", "description": "Show current time"},
+            {"command": "/channels", "description": "List available channels"}
+        ]
+
+    def get_chat_channels(self) -> Dict[str, Dict[str, str]]:
+        """Get available chat channels."""
+        return {
+            "global": {"name": "Global", "description": "Main chat channel"},
+            "trade": {"name": "Trade", "description": "Trading discussions"}, 
+            "help": {"name": "Help", "description": "Help and questions"}
+        }
+
+    def _process_command(self, player_id: str, message: str) -> Dict[str, Any]:
+        """Process chat commands"""
+        parts = message.split(' ', 1)
+        command = parts[0].lower()
+        args = parts[1] if len(parts) > 1 else ""
+        
+        # Command handlers
+        command_handlers = {
+            '/marketplace': self._marketplace_command,
+            '/trade': self._trade_command,
+            '/auction': self._auction_command,
+            '/tell': self._tell_command,
+            '/whisper': self._tell_command,  # Alias
+            '/who': self._who_command,
+            '/help': self._help_command,
+            '/commands': self._help_command,  # Alias
+            '/shout': self._shout_command,
+            '/emote': self._emote_command,
+            '/me': self._emote_command,  # Alias
+            '/time': self._time_command,
+            '/channels': self._channels_command
+        }
+        
+        if command in command_handlers:
+            try:
+                return command_handlers[command](player_id, args)
+            except Exception as e:
+                return {
+                    "success": False,
+                    "message": f"Error executing command: {str(e)}",
+                    "target": player_id
+                }
+        else:
+            return {
+                "success": False,
+                "message": f"Unknown command: {command}. Type /help for available commands.",
+                "target": player_id
+            }
+
+    def _broadcast_message(self, player_id: str, message: str) -> Dict[str, Any]:
+        """Broadcast a message to all players"""
+        player_name = self._get_player_name(player_id)
+        formatted_message = f"{player_name}: {message}"
+        
+        # Add to history
+        self._add_to_history(formatted_message)
+        
+        return {
+            "success": True,
+            "message": formatted_message,
+            "type": "broadcast",
+            "sender": player_id
+        }
+
+    def _add_to_history(self, message: str):
+        """Add message to chat history"""
+        import time
+        self.chat_history.append({
+            'timestamp': time.time(),
+            'message': message
+        })
+        
+        # Keep only the last max_history messages
+        if len(self.chat_history) > self.max_history:
+            self.chat_history.pop(0)
+
+    def _marketplace_command(self, player_id: str, args: str) -> Dict[str, Any]:
+        """Handle marketplace command"""
+        marketplace_text = """
+🏪 **MARKETPLACE** 🏪
+═══════════════════════
+
+📦 **AVAILABLE ITEMS:**
+• Iron Sword - 150 gold (Seller: Trader_Bob)
+• Health Potion - 25 gold (Seller: Alchemist_Ann)
+• Magic Ring - 300 gold (Seller: Wizard_Will)
+• Steel Shield - 200 gold (Seller: Smith_Sam)
+
+💰 **RECENT TRADES:**
+• Leather Boots sold for 75 gold
+• Fire Staff sold for 450 gold
+• Healing Herbs sold for 15 gold
+
+📝 Use `/trade create <item> <price>` to list an item
+🤝 Use `/trade accept <seller>` to buy an item
+🔨 Use `/auction create <item> <starting_price>` for auctions
+
+Type `/help` for more trading commands!
+        """
+        
+        return {
+            "success": True,
+            "message": marketplace_text.strip(),
+            "target": player_id,
+            "type": "info"
+        }
+
+    def _trade_command(self, player_id: str, args: str) -> Dict[str, Any]:
+        """Handle trade command"""
+        if not args:
+            return {
+                "success": False,
+                "message": "Usage: /trade <action> [parameters]\nActions: create, accept, list, cancel",
+                "target": player_id
+            }
+        
+        parts = args.split(' ', 1)
+        action = parts[0].lower()
+        
+        if action == 'create':
+            if len(parts) < 2:
+                return {
+                    "success": False,
+                    "message": "Usage: /trade create <item> <price>",
+                    "target": player_id
+                }
+            
+            # Parse item and price
+            create_args = parts[1].split(' ')
+            if len(create_args) < 2:
+                return {
+                    "success": False,
+                    "message": "Usage: /trade create <item> <price>",
+                    "target": player_id
+                }
+            
+            price = create_args[-1]
+            item = ' '.join(create_args[:-1])
+            
+            return {
+                "success": True,
+                "message": f"✅ Trade listing created: {item} for {price} gold",
+                "target": player_id,
+                "type": "trade_create",
+                "data": {"item": item, "price": price, "seller": player_id}
+            }
+            
+        elif action == 'accept':
+            if len(parts) < 2:
+                return {
+                    "success": False,
+                    "message": "Usage: /trade accept <seller_name>",
+                    "target": player_id
+                }
+            
+            seller_name = parts[1]
+            return {
+                "success": True,
+                "message": f"🤝 Attempting to trade with {seller_name}...",
+                "target": player_id,
+                "type": "trade_accept"
+            }
+            
+        elif action == 'list':
+            return {
+                "success": True,
+                "message": "📋 Your active trade listings:\n• No active listings",
+                "target": player_id
+            }
+            
+        else:
+            return {
+                "success": False,
+                "message": "Unknown trade action. Use 'create', 'accept', 'list', or 'cancel'.",
+                "target": player_id
+            }
+
+    def _auction_command(self, player_id: str, args: str) -> Dict[str, Any]:
+        """Handle auction command"""
+        if not args:
+            return {
+                "success": False,
+                "message": "Usage: /auction <action> [parameters]\nActions: create, bid, list",
+                "target": player_id
+            }
+        
+        parts = args.split(' ', 1)
+        action = parts[0].lower()
+        
+        if action == 'create':
+            if len(parts) < 2:
+                return {
+                    "success": False,
+                    "message": "Usage: /auction create <item> <starting_price>",
+                    "target": player_id
+                }
+            
+            # Parse item and starting price
+            create_args = parts[1].split(' ')
+            if len(create_args) < 2:
+                return {
+                    "success": False,
+                    "message": "Usage: /auction create <item> <starting_price>",
+                    "target": player_id
+                }
+            
+            starting_price = create_args[-1]
+            item = ' '.join(create_args[:-1])
+            
+            return {
+                "success": True,
+                "message": f"🔨 Auction created: {item} starting at {starting_price} gold",
+                "target": player_id,
+                "type": "auction_create"
+            }
+            
+        else:
+            return {
+                "success": False,
+                "message": "Unknown auction action. Use 'create' to start an auction.",
+                "target": player_id
+            }
+
+    def _tell_command(self, player_id: str, args: str) -> Dict[str, Any]:
+        """Send a private message to another player"""
+        if not args:
+            return {
+                "success": False,
+                "message": "Usage: /tell <player> <message>",
+                "target": player_id
+            }
+        
+        parts = args.split(' ', 1)
+        if len(parts) < 2:
+            return {
+                "success": False,
+                "message": "Usage: /tell <player> <message>",
+                "target": player_id
+            }
+        
+        target_name, message = parts
+        sender_name = self._get_player_name(player_id)
+        
+        return {
+            "success": True,
+            "message": f"[TELL to {target_name}]: {message}",
+            "target": player_id,
+            "type": "tell",
+            "data": {
+                "target_name": target_name,
+                "sender_name": sender_name,
+                "message": message
+            }
+        }
+
+    def _who_command(self, player_id: str, args: str) -> Dict[str, Any]:
+        """Show list of online players"""
+        # In a real implementation, this would get the actual list of connected players
+        return {
+            "success": True,
+            "message": "👥 Online players (3): Player1, Player2, Player3",
+            "target": player_id,
+            "type": "info"
+        }
+
+    def _help_command(self, player_id: str, args: str) -> Dict[str, Any]:
+        """Show available commands"""
+        commands = self.get_available_commands()
+        help_text = "📋 **AVAILABLE COMMANDS:**\n"
+        help_text += "═══════════════════════\n\n"
+        
+        for cmd in commands:
+            help_text += f"• {cmd['command']} - {cmd['description']}\n"
+        
+        return {
+            "success": True,
+            "message": help_text,
+            "target": player_id,
+            "type": "info"
+        }
+
+    def _shout_command(self, player_id: str, args: str) -> Dict[str, Any]:
+        """Send a message to all players with emphasis"""
+        if not args:
+            return {
+                "success": False,
+                "message": "Usage: /shout <message>",
+                "target": player_id
+            }
+        
+        player_name = self._get_player_name(player_id)
+        formatted_message = f"📢 {player_name} shouts: {args}"
+        
+        self._add_to_history(formatted_message)
+        
+        return {
+            "success": True,
+            "message": formatted_message,
+            "type": "shout",
+            "sender": player_id
+        }
+
+    def _emote_command(self, player_id: str, args: str) -> Dict[str, Any]:
+        """Send an emote message"""
+        if not args:
+            return {
+                "success": False,
+                "message": "Usage: /emote <action> or /me <action>",
+                "target": player_id
+            }
+        
+        player_name = self._get_player_name(player_id)
+        formatted_message = f"✨ {player_name} {args}"
+        
+        self._add_to_history(formatted_message)
+        
+        return {
+            "success": True,
+            "message": formatted_message,
+            "type": "emote",
+            "sender": player_id
+        }
+
+    def _time_command(self, player_id: str, args: str) -> Dict[str, Any]:
+        """Show current game time"""
+        import datetime
+        current_time = datetime.datetime.now().strftime("%H:%M:%S")
+        
+        return {
+            "success": True,
+            "message": f"🕐 Current time: {current_time}",
+            "target": player_id,
+            "type": "info"
+        }
+
+    def _channels_command(self, player_id: str, args: str) -> Dict[str, Any]:
+        """Show available chat channels"""
+        channels = self.get_chat_channels()
+        channels_text = "📺 **CHAT CHANNELS:**\n"
+        channels_text += "═══════════════════\n\n"
+        
+        for channel_id, channel_info in channels.items():
+            channels_text += f"• #{channel_id} - {channel_info['description']}\n"
+        
+        return {
+            "success": True,
+            "message": channels_text,
+            "target": player_id,
+            "type": "info"
+        }
+
+    # Helper methods
+    def _get_player_name(self, player_id: str) -> str:
+        """Get player name from player ID"""
+        # In a real implementation, this would look up the actual player name
+        return f"Player{player_id[-3:]}" if len(player_id) > 3 else f"Player{player_id}"

plugins/enhanced_chat_plugin.py.backup

@@ -0,0 +1,586 @@
+import asyncio
+from src.interfaces.plugin_interfaces import IChatPlugin, PluginMetadata, PluginType
+from typing import Dict, List, Any
+
+class EnhancedChatPlugin(IChatPlugin):
+    def __init__(self):        self._metadata = PluginMetadata(
+            id="enhanced_chat",
+            name="Enhanced Chat System",
+            version="1.2.0",
+            author="MMORPG Dev Team",
+            description="Adds emotes, chat channels, and advanced chat commands",
+            plugin_type=PluginType.SERVICE,
+            dependencies=[],
+            config={
+                "enable_emotes": True,
+                "enable_channels": True,
+                "max_message_length": 500,
+                "chat_cooldown": 1
+            }
+        )
+        self._enabled = False
+        self.commands = {
+            '/tell': self.tell_command,
+            '/whisper': self.whisper_command,
+            '/shout': self.shout_command,
+            '/emote': self.emote_command,
+            '/me': self.emote_command,  # Alias for /emote
+            '/who': self.who_command,
+            '/time': self.time_command,
+            '/help': self.help_command,
+            '/commands': self.help_command,  # Alias for /help
+            '/clear': self.clear_command,
+            '/ignore': self.ignore_command,
+            '/unignore': self.unignore_command,
+            '/history': self.history_command,
+            '/channels': self.channels_command,
+            '/join': self.join_channel_command,
+            '/leave': self.leave_channel_command,
+            '/channel': self.channel_command,
+            '/c': self.channel_command,  # Alias for /channel
+            '/mail': self.mail_command,
+            '/read': self.read_mail_command,
+            '/mailbox': self.mailbox_command,
+            '/marketplace': self.marketplace_command,
+            '/trade': self.trade_command,
+            '/auction': self.auction_command,
+        }
+        
+        # Chat history storage
+        self.chat_history = []
+        self.max_history = 100
+        
+        # Player ignore lists
+        self.ignore_lists = {}
+        
+        # Custom channels
+        self.channels = {
+            'global': {'description': 'Global chat channel', 'members': set()},
+            'trade': {'description': 'Trading channel', 'members': set()},
+            'help': {'description': 'Help and questions channel', 'members': set()}
+        }
+        
+        # Player channel memberships
+        self.player_channels = {}
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        return self._metadata
+
+    def initialize(self, context: Dict[str, Any]) -> bool:
+        """Initialize the enhanced chat plugin."""
+        try:
+            self._config = self._metadata.config
+            self._enabled = True
+            print(f"💬 Enhanced Chat Plugin initialized")
+            return True
+        except Exception as e:
+            print(f"💬 Failed to initialize Enhanced Chat Plugin: {e}")
+            return False
+
+    def shutdown(self) -> bool:
+        """Shutdown the plugin and cleanup resources."""
+        self._enabled = False
+        print("💬 Enhanced Chat Plugin shut down")
+        return True
+
+    def get_status(self) -> Dict[str, Any]:
+        """Get current plugin status."""
+        return {
+            "status": "active" if self._enabled else "inactive",
+            "message": "Enhanced chat system with marketplace commands"
+        }
+
+    def process_message(self, player_id: str, message: str, channel: str = "global") -> Dict[str, Any]:
+        """Process and enhance chat messages."""
+        if message.startswith('/'):
+            return self.process_command(player_id, message)
+        else:
+            return self.broadcast_message(player_id, message)
+
+    def get_available_commands(self) -> List[Dict[str, str]]:
+        """Get list of available chat commands."""
+        return [
+            {"command": "/marketplace", "description": "View marketplace listings"},
+            {"command": "/trade create <item> <price>", "description": "Create trade listing"},
+            {"command": "/trade accept <id>", "description": "Accept trade offer"},
+            {"command": "/auction create <item> <start_price>", "description": "Create auction"},
+            {"command": "/tell <player> <message>", "description": "Send private message"},
+            {"command": "/who", "description": "List online players"},
+            {"command": "/help", "description": "Show available commands"}
+        ]
+
+    def get_chat_channels(self) -> Dict[str, Dict[str, str]]:
+        """Get available chat channels."""
+        return {
+            "global": {"name": "Global", "description": "Main chat channel"},
+            "trade": {"name": "Trade", "description": "Trading discussions"},
+            "help": {"name": "Help", "description": "Help and questions"}
+        }
+
+    async def on_player_message(self, player_id, message):
+        """Handle player chat messages"""
+        if message.startswith('/'):
+            await self.process_command(player_id, message)
+        else:
+            await self.broadcast_message(player_id, message)
+
+    async def process_command(self, player_id, message):
+        """Process chat commands"""
+        parts = message.split(' ', 1)
+        command = parts[0].lower()
+        args = parts[1] if len(parts) > 1 else ""
+        
+        if command in self.commands:
+            try:
+                await self.commands[command](player_id, args)
+            except Exception as e:
+                await self.send_to_player(player_id, f"Error executing command: {str(e)}")
+        else:
+            await self.send_to_player(player_id, f"Unknown command: {command}. Type /help for available commands.")
+
+    async def broadcast_message(self, player_id, message):
+        """Broadcast a message to all players"""
+        player_name = await self.get_player_name(player_id)
+        formatted_message = f"{player_name}: {message}"
+        
+        # Add to history
+        self.add_to_history(formatted_message)
+        
+        # Send to all connected players
+        for pid in self.game_manager.get_connected_players():
+            if pid not in self.ignore_lists.get(player_id, set()):
+                await self.send_to_player(pid, formatted_message)
+
+    def add_to_history(self, message):
+        """Add message to chat history"""
+        self.chat_history.append({
+            'timestamp': asyncio.get_event_loop().time(),
+            'message': message
+        })
+        
+        # Keep only the last max_history messages
+        if len(self.chat_history) > self.max_history:
+            self.chat_history.pop(0)
+
+    async def tell_command(self, player_id, args):
+        """Send a private message to another player"""
+        if not args:
+            await self.send_to_player(player_id, "Usage: /tell <player> <message>")
+            return
+        
+        parts = args.split(' ', 1)
+        if len(parts) < 2:
+            await self.send_to_player(player_id, "Usage: /tell <player> <message>")
+            return
+        
+        target_name, message = parts
+        target_id = await self.find_player_by_name(target_name)
+        
+        if not target_id:
+            await self.send_to_player(player_id, f"Player '{target_name}' not found.")
+            return
+        
+        if target_id in self.ignore_lists.get(player_id, set()):
+            await self.send_to_player(player_id, f"You are ignoring {target_name}.")
+            return
+        
+        sender_name = await self.get_player_name(player_id)
+        await self.send_to_player(target_id, f"[TELL from {sender_name}]: {message}")
+        await self.send_to_player(player_id, f"[TELL to {target_name}]: {message}")
+
+    async def whisper_command(self, player_id, args):
+        """Alias for tell command"""
+        await self.tell_command(player_id, args)
+
+    async def shout_command(self, player_id, args):
+        """Send a message to all players in a wider area"""
+        if not args:
+            await self.send_to_player(player_id, "Usage: /shout <message>")
+            return
+        
+        player_name = await self.get_player_name(player_id)
+        formatted_message = f"{player_name} shouts: {args}"
+        
+        # Add to history
+        self.add_to_history(formatted_message)
+        
+        # Send to all players (could be modified to only nearby players)
+        for pid in self.game_manager.get_connected_players():
+            if pid not in self.ignore_lists.get(player_id, set()):
+                await self.send_to_player(pid, formatted_message)
+
+    async def emote_command(self, player_id, args):
+        """Send an emote message"""
+        if not args:
+            await self.send_to_player(player_id, "Usage: /emote <action> or /me <action>")
+            return
+        
+        player_name = await self.get_player_name(player_id)
+        formatted_message = f"* {player_name} {args}"
+        
+        # Add to history
+        self.add_to_history(formatted_message)
+        
+        # Send to all players
+        for pid in self.game_manager.get_connected_players():
+            if pid not in self.ignore_lists.get(player_id, set()):
+                await self.send_to_player(pid, formatted_message)
+
+    async def who_command(self, player_id, args):
+        """Show list of online players"""
+        connected_players = self.game_manager.get_connected_players()
+        player_names = []
+        
+        for pid in connected_players:
+            name = await self.get_player_name(pid)
+            player_names.append(name)
+        
+        if player_names:
+            message = f"Online players ({len(player_names)}): {', '.join(player_names)}"
+        else:
+            message = "No players currently online."
+        
+        await self.send_to_player(player_id, message)
+
+    async def time_command(self, player_id, args):
+        """Show current game time"""
+        import datetime
+        current_time = datetime.datetime.now().strftime("%H:%M:%S")
+        await self.send_to_player(player_id, f"Current time: {current_time}")
+
+    async def help_command(self, player_id, args):
+        """Show available commands"""
+        commands = [
+            "/tell <player> <msg> - Send private message",
+            "/whisper <player> <msg> - Same as /tell",
+            "/shout <message> - Shout to all players",
+            "/emote <action> - Perform an action",
+            "/me <action> - Same as /emote",
+            "/who - Show online players",
+            "/time - Show current time",
+            "/help - Show this help",
+            "/clear - Clear your chat",
+            "/ignore <player> - Ignore a player",
+            "/unignore <player> - Stop ignoring a player",
+            "/history - Show recent chat history",
+            "/channels - Show available channels",
+            "/join <channel> - Join a channel",
+            "/leave <channel> - Leave a channel",
+            "/channel <channel> <msg> - Send message to channel",
+            "/c <channel> <msg> - Same as /channel",
+            "/mail <player> <msg> - Send mail to player",
+            "/read - Read your mail",
+            "/mailbox - Check mailbox status",
+            "/marketplace - View marketplace listings",
+            "/trade create <item> <price> - Create trade offer",
+            "/trade accept <id> - Accept trade offer",
+            "/auction create <item> <start_price> - Create auction"
+        ]
+        
+        await self.send_to_player(player_id, "Available commands:")
+        for cmd in commands:
+            await self.send_to_player(player_id, f"  {cmd}")
+
+    async def clear_command(self, player_id, args):
+        """Clear player's chat"""
+        # This would typically clear the client-side chat
+        await self.send_to_player(player_id, "\n" * 20)
+        await self.send_to_player(player_id, "Chat cleared.")
+
+    async def ignore_command(self, player_id, args):
+        """Add a player to ignore list"""
+        if not args:
+            await self.send_to_player(player_id, "Usage: /ignore <player>")
+            return
+        
+        target_id = await self.find_player_by_name(args.strip())
+        if not target_id:
+            await self.send_to_player(player_id, f"Player '{args}' not found.")
+            return
+        
+        if target_id == player_id:
+            await self.send_to_player(player_id, "You cannot ignore yourself.")
+            return
+        
+        if player_id not in self.ignore_lists:
+            self.ignore_lists[player_id] = set()
+        
+        self.ignore_lists[player_id].add(target_id)
+        await self.send_to_player(player_id, f"You are now ignoring {args}.")
+
+    async def unignore_command(self, player_id, args):
+        """Remove a player from ignore list"""
+        if not args:
+            await self.send_to_player(player_id, "Usage: /unignore <player>")
+            return
+        
+        target_id = await self.find_player_by_name(args.strip())
+        if not target_id:
+            await self.send_to_player(player_id, f"Player '{args}' not found.")
+            return
+        
+        if player_id in self.ignore_lists and target_id in self.ignore_lists[player_id]:
+            self.ignore_lists[player_id].remove(target_id)
+            await self.send_to_player(player_id, f"You are no longer ignoring {args}.")
+        else:
+            await self.send_to_player(player_id, f"You are not ignoring {args}.")
+
+    async def history_command(self, player_id, args):
+        """Show recent chat history"""
+        if not self.chat_history:
+            await self.send_to_player(player_id, "No chat history available.")
+            return
+        
+        await self.send_to_player(player_id, "Recent chat history:")
+        for entry in self.chat_history[-10:]:  # Show last 10 messages
+            await self.send_to_player(player_id, entry['message'])
+
+    async def channels_command(self, player_id, args):
+        """Show available channels"""
+        await self.send_to_player(player_id, "Available channels:")
+        for channel_name, channel_info in self.channels.items():
+            member_count = len(channel_info['members'])
+            await self.send_to_player(player_id, f"  {channel_name}: {channel_info['description']} ({member_count} members)")
+
+    async def join_channel_command(self, player_id, args):
+        """Join a chat channel"""
+        if not args:
+            await self.send_to_player(player_id, "Usage: /join <channel>")
+            return
+        
+        channel_name = args.strip().lower()
+        if channel_name not in self.channels:
+            await self.send_to_player(player_id, f"Channel '{channel_name}' does not exist.")
+            return
+        
+        if player_id not in self.player_channels:
+            self.player_channels[player_id] = set()
+        
+        self.player_channels[player_id].add(channel_name)
+        self.channels[channel_name]['members'].add(player_id)
+        
+        player_name = await self.get_player_name(player_id)
+        await self.send_to_player(player_id, f"You have joined the '{channel_name}' channel.")
+        
+        # Notify other channel members
+        for member_id in self.channels[channel_name]['members']:
+            if member_id != player_id:
+                await self.send_to_player(member_id, f"{player_name} has joined the '{channel_name}' channel.")
+
+    async def leave_channel_command(self, player_id, args):
+        """Leave a chat channel"""
+        if not args:
+            await self.send_to_player(player_id, "Usage: /leave <channel>")
+            return
+        
+        channel_name = args.strip().lower()
+        if channel_name not in self.channels:
+            await self.send_to_player(player_id, f"Channel '{channel_name}' does not exist.")
+            return
+        
+        if player_id not in self.player_channels or channel_name not in self.player_channels[player_id]:
+            await self.send_to_player(player_id, f"You are not in the '{channel_name}' channel.")
+            return
+        
+        self.player_channels[player_id].remove(channel_name)
+        self.channels[channel_name]['members'].discard(player_id)
+        
+        player_name = await self.get_player_name(player_id)
+        await self.send_to_player(player_id, f"You have left the '{channel_name}' channel.")
+        
+        # Notify other channel members
+        for member_id in self.channels[channel_name]['members']:
+            await self.send_to_player(member_id, f"{player_name} has left the '{channel_name}' channel.")
+
+    async def channel_command(self, player_id, args):
+        """Send a message to a specific channel"""
+        if not args:
+            await self.send_to_player(player_id, "Usage: /channel <channel> <message>")
+            return
+        
+        parts = args.split(' ', 1)
+        if len(parts) < 2:
+            await self.send_to_player(player_id, "Usage: /channel <channel> <message>")
+            return
+        
+        channel_name, message = parts
+        channel_name = channel_name.lower()
+        
+        if channel_name not in self.channels:
+            await self.send_to_player(player_id, f"Channel '{channel_name}' does not exist.")
+            return
+        
+        if player_id not in self.player_channels or channel_name not in self.player_channels[player_id]:
+            await self.send_to_player(player_id, f"You are not in the '{channel_name}' channel. Use /join {channel_name} first.")
+            return
+        
+        player_name = await self.get_player_name(player_id)
+        formatted_message = f"[{channel_name.upper()}] {player_name}: {message}"
+        
+        # Send to all channel members
+        for member_id in self.channels[channel_name]['members']:
+            if member_id not in self.ignore_lists.get(player_id, set()):
+                await self.send_to_player(member_id, formatted_message)
+
+    async def mail_command(self, player_id, args):
+        """Send mail to a player using the read2burn system"""
+        if not args:
+            await self.send_to_player(player_id, "Usage: /mail <player> <message>")
+            return
+        
+        parts = args.split(' ', 1)
+        if len(parts) < 2:
+            await self.send_to_player(player_id, "Usage: /mail <player> <message>")
+            return
+        
+        target_name, message = parts
+        target_id = await self.find_player_by_name(target_name)
+        
+        if not target_id:
+            await self.send_to_player(player_id, f"Player '{target_name}' not found.")
+            return
+        
+        # Use the read2burn addon to send mail
+        try:
+            read2burn_addon = self.game_manager.get_addon('read2burn')
+            if read2burn_addon:
+                sender_name = await self.get_player_name(player_id)
+                await read2burn_addon.send_message(target_id, f"Mail from {sender_name}: {message}")
+                await self.send_to_player(player_id, f"Mail sent to {target_name}.")
+            else:
+                await self.send_to_player(player_id, "Mail system is not available.")
+        except Exception as e:
+            await self.send_to_player(player_id, f"Failed to send mail: {str(e)}")
+
+    async def read_mail_command(self, player_id, args):
+        """Read mail using the read2burn system"""
+        try:
+            read2burn_addon = self.game_manager.get_addon('read2burn')
+            if read2burn_addon:
+                messages = await read2burn_addon.get_messages(player_id)
+                if messages:
+                    await self.send_to_player(player_id, f"You have {len(messages)} unread message(s):")
+                    for i, msg in enumerate(messages):
+                        await self.send_to_player(player_id, f"{i+1}. {msg}")
+                    # Messages are automatically deleted after reading (read2burn)
+                    await read2burn_addon.clear_messages(player_id)
+                else:
+                    await self.send_to_player(player_id, "You have no unread mail.")
+            else:
+                await self.send_to_player(player_id, "Mail system is not available.")
+        except Exception as e:
+            await self.send_to_player(player_id, f"Failed to read mail: {str(e)}")
+
+    async def mailbox_command(self, player_id, args):
+        """Check mailbox status"""
+        try:
+            read2burn_addon = self.game_manager.get_addon('read2burn')
+            if read2burn_addon:
+                message_count = await read2burn_addon.get_message_count(player_id)
+                await self.send_to_player(player_id, f"You have {message_count} unread message(s) in your mailbox.")
+            else:
+                await self.send_to_player(player_id, "Mail system is not available.")
+        except Exception as e:
+            await self.send_to_player(player_id, f"Failed to check mailbox: {str(e)}")
+
+    async def marketplace_command(self, player_id, args):
+        """Show marketplace listings"""
+        # Demo marketplace listings - in a real implementation, this would query the trading system
+        demo_listings = [
+            "1. Iron Sword - 100 gold (seller: Alice)",
+            "2. Magic Potion - 50 gold (seller: Bob)",
+            "3. Dragon Scale - 500 gold (seller: Charlie)",
+            "4. Enchanted Ring - 250 gold (seller: Diana)"
+        ]
+        
+        await self.send_to_player(player_id, "=== MARKETPLACE ===")
+        await self.send_to_player(player_id, "Current listings:")
+        for listing in demo_listings:
+            await self.send_to_player(player_id, f"  {listing}")
+        await self.send_to_player(player_id, "Use '/trade create <item> <price>' to list an item")
+        await self.send_to_player(player_id, "Use '/trade accept <id>' to purchase an item")
+
+    async def trade_command(self, player_id, args):
+        """Handle trading commands"""
+        if not args:
+            await self.send_to_player(player_id, "Usage: /trade <create|accept> [arguments]")
+            return
+        
+        parts = args.split(' ', 1)
+        action = parts[0].lower()
+        
+        if action == 'create':
+            if len(parts) < 2:
+                await self.send_to_player(player_id, "Usage: /trade create <item> <price>")
+                return
+            
+            # Parse item and price
+            create_args = parts[1].split(' ')
+            if len(create_args) < 2:
+                await self.send_to_player(player_id, "Usage: /trade create <item> <price>")
+                return
+            
+            price = create_args[-1]
+            item = ' '.join(create_args[:-1])
+            
+            await self.send_to_player(player_id, f"Created trade listing: {item} for {price} gold")
+            # In a real implementation, this would interact with the trading system plugin
+            
+        elif action == 'accept':
+            if len(parts) < 2:
+                await self.send_to_player(player_id, "Usage: /trade accept <listing_id>")
+                return
+            
+            listing_id = parts[1].strip()
+            await self.send_to_player(player_id, f"Attempting to purchase listing {listing_id}...")
+            # In a real implementation, this would process the trade
+            
+        else:
+            await self.send_to_player(player_id, "Unknown trade action. Use 'create' or 'accept'.")
+
+    async def auction_command(self, player_id, args):
+        """Handle auction commands"""
+        if not args:
+            await self.send_to_player(player_id, "Usage: /auction create <item> <starting_price>")
+            return
+        
+        parts = args.split(' ', 1)
+        action = parts[0].lower()
+        
+        if action == 'create':
+            if len(parts) < 2:
+                await self.send_to_player(player_id, "Usage: /auction create <item> <starting_price>")
+                return
+            
+            # Parse item and starting price
+            create_args = parts[1].split(' ')
+            if len(create_args) < 2:
+                await self.send_to_player(player_id, "Usage: /auction create <item> <starting_price>")
+                return
+            
+            starting_price = create_args[-1]
+            item = ' '.join(create_args[:-1])
+            
+            await self.send_to_player(player_id, f"Created auction: {item} starting at {starting_price} gold")
+            # In a real implementation, this would interact with the auction system
+            
+        else:
+            await self.send_to_player(player_id, "Unknown auction action. Use 'create' to start an auction.")
+
+    # Helper methods
+    async def get_player_name(self, player_id):
+        """Get player name from player ID"""
+        # This should be implemented to get the actual player name
+        return f"Player{player_id}"
+
+    async def find_player_by_name(self, name):
+        """Find player ID by name"""
+        # This should be implemented to find players by name
+        # For now, return None if not found
+        return None
+
+    async def send_to_player(self, player_id, message):
+        """Send a message to a specific player"""
+        # This should be implemented to send messages to players
+        pass

plugins/enhanced_chat_plugin_fixed.py

@@ -0,0 +1,264 @@
+"""
+Enhanced Chat Plugin for MMORPG
+Adds advanced chat features like emotes, channels, and chat commands
+"""
+
+from src.interfaces.plugin_interfaces import IChatPlugin, PluginMetadata, PluginType
+from typing import Dict, List, Any, Optional
+import re
+import time
+
+class EnhancedChatPlugin(IChatPlugin):
+    """Plugin that enhances the chat system with emotes, channels, and commands."""
+    
+    def __init__(self):
+        self._metadata = PluginMetadata(
+            id="enhanced_chat",
+            name="Enhanced Chat System",
+            version="1.2.0",
+            author="MMORPG Dev Team",
+            description="Adds emotes, chat channels, and advanced chat commands",
+            plugin_type=PluginType.SERVICE,
+            dependencies=[],
+            config={
+                "enable_emotes": True,
+                "enable_channels": True,
+                "max_message_length": 500,
+                "chat_cooldown": 1
+            }
+        )
+        self._enabled = False
+        self._chat_channels = {
+            "global": {"name": "Global", "color": "#ffffff"},
+            "trade": {"name": "Trade", "color": "#ffff00"},
+            "help": {"name": "Help", "color": "#00ff00"},
+            "guild": {"name": "Guild", "color": "#ff00ff"}
+        }
+        self._emotes = {
+            ":smile:": "😊", ":laugh:": "😂", ":wink:": "😉", ":heart:": "❤️",
+            ":thumbsup:": "👍", ":thumbsdown:": "👎", ":fire:": "🔥", ":star:": "⭐",
+            ":wave:": "👋", ":clap:": "👏", ":cry:": "😢", ":angry:": "😠",
+            ":surprised:": "😲", ":cool:": "😎", ":thinking:": "🤔", ":sleeping:": "😴"
+        }
+        self._player_cooldowns = {}
+        
+    @property
+    def metadata(self) -> PluginMetadata:
+        return self._metadata
+    
+    def initialize(self, context: Dict[str, Any]) -> bool:
+        """Initialize the enhanced chat plugin."""
+        try:
+            self._config = self._metadata.config
+            self._enabled = True
+            print(f"💬 Enhanced Chat Plugin initialized with {len(self._emotes)} emotes and {len(self._chat_channels)} channels")
+            return True
+        except Exception as e:
+            print(f"💬 Failed to initialize Enhanced Chat Plugin: {e}")
+            return False
+        
+    def cleanup(self) -> None:
+        """Clean up chat plugin resources."""
+        self._enabled = False
+        self._player_cooldowns.clear()
+        print("💬 Enhanced Chat Plugin cleaned up")
+    
+    def is_enabled(self) -> bool:
+        return self._enabled
+    
+    def process_message(self, player_id: str, message: str, channel: str = "global") -> Dict[str, Any]:
+        """Process and enhance chat messages."""
+        if not self._enabled:
+            return {"original": message, "processed": message, "valid": True}
+            
+        result = {
+            "original": message,
+            "processed": message,
+            "valid": True,
+            "channel": channel,
+            "error": None
+        }
+        
+        # Check cooldown
+        if not self._check_cooldown(player_id):
+            result["valid"] = False
+            result["error"] = "Please wait before sending another message"
+            return result
+        
+        # Check message length
+        max_length = self._config.get("max_message_length", 500)
+        if len(message) > max_length:
+            result["valid"] = False
+            result["error"] = f"Message too long (max {max_length} characters)"
+            return result
+        
+        # Process chat commands
+        if message.startswith("/"):
+            return self._process_chat_command(player_id, message, channel)
+        
+        # Process emotes
+        if self._config.get("enable_emotes", True):
+            result["processed"] = self._process_emotes(message)
+        
+        # Validate and set channel
+        if self._config.get("enable_channels", True):
+            if channel not in self._chat_channels:
+                channel = "global"
+            result["channel"] = channel
+            result["channel_info"] = self._chat_channels[channel]
+        
+        # Update cooldown
+        self._player_cooldowns[player_id] = time.time()
+        
+        return result
+    
+    def get_available_commands(self) -> List[Dict[str, str]]:
+        """Get list of available chat commands."""
+        if not self._enabled:
+            return []
+            
+        commands = [
+            {"command": "/emotes", "description": "Show available emotes"},
+            {"command": "/channels", "description": "List available chat channels"},
+            {"command": "/join <channel>", "description": "Join a chat channel"},
+            {"command": "/who", "description": "List players in current channel"},
+            {"command": "/time", "description": "Show current server time"},
+            {"command": "/marketplace", "description": "View marketplace listings"},
+            {"command": "/trade create <player> <items>", "description": "Create a trade offer"},
+            {"command": "/trade accept <trade_id>", "description": "Accept a trade"},
+            {"command": "/auction create <item> <price>", "description": "Create an auction"},
+            {"command": "/help", "description": "Show this help message"}
+        ]
+        
+        return commands
+    
+    def get_chat_channels(self) -> Dict[str, Dict[str, str]]:
+        """Get available chat channels."""
+        if not self._enabled or not self._config.get("enable_channels", True):
+            return {"global": {"name": "Global", "color": "#ffffff"}}
+            
+        return self._chat_channels.copy()
+    
+    def get_emotes_list(self) -> Dict[str, str]:
+        """Get available emotes."""
+        if not self._enabled or not self._config.get("enable_emotes", True):
+            return {}
+            
+        return self._emotes.copy()
+    
+    def _check_cooldown(self, player_id: str) -> bool:
+        """Check if player is within chat cooldown."""
+        cooldown = self._config.get("chat_cooldown", 1)
+        if cooldown <= 0:
+            return True
+            
+        last_message = self._player_cooldowns.get(player_id, 0)
+        return time.time() - last_message >= cooldown
+    
+    def _process_emotes(self, message: str) -> str:
+        """Replace emote codes with emojis."""
+        processed = message
+        for emote_code, emoji in self._emotes.items():
+            processed = processed.replace(emote_code, emoji)
+        return processed
+    
+    def _process_chat_command(self, player_id: str, message: str, channel: str) -> Dict[str, Any]:
+        """Process chat commands."""
+        parts = message.split()
+        command = parts[0].lower()
+        
+        result = {
+            "original": message,
+            "processed": "",
+            "valid": True,
+            "channel": channel,
+            "is_command": True,
+            "command_response": ""
+        }
+        
+        if command == "/emotes":
+            emote_list = ", ".join(self._emotes.keys())
+            result["command_response"] = f"Available emotes: {emote_list}"
+            
+        elif command == "/channels":
+            channel_list = ", ".join([f"{k} ({v['name']})" for k, v in self._chat_channels.items()])
+            result["command_response"] = f"Available channels: {channel_list}"
+            
+        elif command == "/join":
+            if len(parts) > 1:
+                target_channel = parts[1].lower()
+                if target_channel in self._chat_channels:
+                    result["channel"] = target_channel
+                    result["command_response"] = f"Joined channel: {self._chat_channels[target_channel]['name']}"
+                else:
+                    result["command_response"] = f"Channel '{target_channel}' not found"
+            else:
+                result["command_response"] = "Usage: /join <channel>"
+                
+        elif command == "/who":
+            result["command_response"] = "Player list functionality requires game integration"
+            
+        elif command == "/time":
+            current_time = time.strftime("%H:%M:%S", time.localtime())
+            result["command_response"] = f"Server time: {current_time}"
+            
+        elif command == "/marketplace":
+            result["command_response"] = "🏪 **Marketplace**\n\nDemo listings:\n• Iron Sword - 100 gold (Seller: PlayerX)\n• Health Potion - 25 gold (Seller: PlayerY)\n• Magic Staff - 350 gold (Seller: PlayerZ)\n\nUse `/trade create <player> <items>` to start trading!"
+            
+        elif command == "/trade":
+            if len(parts) > 1:
+                action = parts[1].lower()
+                if action == "create":
+                    result["command_response"] = "🤝 Trade creation system coming soon! For now, use direct player interaction."
+                elif action == "accept":
+                    result["command_response"] = "✅ Trade acceptance system coming soon!"
+                else:
+                    result["command_response"] = "Usage: /trade create <player> <items> or /trade accept <trade_id>"
+            else:
+                result["command_response"] = "Usage: /trade <create|accept> [parameters]"
+                
+        elif command == "/auction":
+            if len(parts) > 1:
+                action = parts[1].lower()
+                if action == "create":
+                    result["command_response"] = "🔨 Auction creation system coming soon!"
+                else:
+                    result["command_response"] = "Usage: /auction create <item> <starting_price> <duration>"
+            else:
+                result["command_response"] = "Usage: /auction create <item> <starting_price> <duration>"
+            
+        elif command == "/help":
+            commands = self.get_available_commands()
+            help_text = "Available commands:\n" + "\n".join([f"{cmd['command']} - {cmd['description']}" for cmd in commands])
+            result["command_response"] = help_text
+            
+        else:
+            result["valid"] = False
+            result["command_response"] = f"Unknown command: {command}. Type /help for available commands."
+        
+        return result
+    
+    def get_status(self) -> Dict[str, Any]:
+        """Get the current status of the enhanced chat plugin."""
+        return {
+            "enabled": self._enabled,
+            "total_emotes": len(self._emotes),
+            "total_channels": len(self._chat_channels),
+            "active_cooldowns": len(self._player_cooldowns)
+        }
+    
+    def shutdown(self) -> bool:
+        """Shutdown the enhanced chat plugin."""
+        try:
+            self._enabled = False
+            self._player_cooldowns.clear()
+            print("💬 Enhanced Chat Plugin shutdown")
+            return True
+        except Exception as e:
+            print(f"💬 Error shutting down Enhanced Chat Plugin: {e}")
+            return False
+
+# Plugin entry point
+def create_plugin():
+    """Factory function to create the plugin instance."""
+    return EnhancedChatPlugin()

plugins/plugin_registry.conf

@@ -0,0 +1,62 @@
+"""
+Plugin Registry - Sample Configuration
+This file demonstrates how plugins can be configured and loaded
+"""
+
+# Plugin configuration registry
+PLUGIN_REGISTRY = {
+    "weather_plugin": {
+        "enabled": True,
+        "file": "weather_plugin.py",
+        "config": {
+            "weather_change_interval": 180,  # Change weather every 3 minutes
+            "enable_seasons": True,
+            "weather_effects_enabled": True
+        },
+        "auto_load": True,
+        "priority": 1
+    },
+    
+    "enhanced_chat_plugin": {
+        "enabled": True,
+        "file": "enhanced_chat_plugin.py", 
+        "config": {
+            "enable_emotes": True,
+            "enable_channels": True,
+            "max_message_length": 300,
+            "chat_cooldown": 2  # 2 second cooldown between messages
+        },
+        "auto_load": True,
+        "priority": 2
+    },
+    
+    "trading_system_plugin": {
+        "enabled": True,
+        "file": "trading_system_plugin.py",
+        "config": {
+            "enable_direct_trading": True,
+            "enable_marketplace": True,
+            "trade_tax_rate": 0.03,  # 3% tax on marketplace trades
+            "max_trade_distance": 150
+        },
+        "auto_load": True,
+        "priority": 3,
+        "dependencies": ["enhanced_chat_plugin"]
+    }
+}
+
+# Plugin load order (based on dependencies and priority)
+LOAD_ORDER = [
+    "enhanced_chat_plugin",  # No dependencies
+    "weather_plugin",        # No dependencies
+    "trading_system_plugin"  # Depends on enhanced_chat
+]
+
+# Default plugin directory
+PLUGIN_DIRECTORY = "plugins"
+
+# Plugin file extension
+PLUGIN_EXTENSION = ".py"
+
+# Plugin factory function name
+PLUGIN_FACTORY_FUNCTION = "create_plugin"

plugins/sample_plugin.py

@@ -0,0 +1,54 @@
+"""
+Sample plugin demonstrating the plugin system.
+"""
+
+from src.interfaces.plugin_interfaces import IPlugin, PluginMetadata, PluginType
+from typing import Dict, Any
+
+
+class SamplePlugin(IPlugin):
+    """Sample plugin implementation."""
+    
+    @property
+    def metadata(self) -> PluginMetadata:
+        return PluginMetadata(
+            id="sample_plugin",
+            name="Sample Plugin",
+            version="1.0.0",
+            description="A sample plugin demonstrating the plugin system",
+            author="MMORPG System",
+            plugin_type=PluginType.EVENT,
+            dependencies=[],
+            config={}
+        )
+    
+    def initialize(self, context: Dict[str, Any]) -> bool:
+        """Initialize the plugin."""
+        self.context = context
+        print("[SamplePlugin] Plugin initialized!")
+        return True
+    
+    def shutdown(self) -> bool:
+        """Shutdown the plugin."""
+        print("[SamplePlugin] Plugin shutdown!")
+        return True
+    
+    def get_status(self) -> Dict[str, Any]:
+        """Get plugin status."""
+        return {
+            "status": "active",
+            "message": "Sample plugin is running normally"
+        }
+    
+    def on_player_join(self, player_id: str) -> None:
+        """Called when a player joins."""
+        print(f"[SamplePlugin] Player {player_id} joined!")
+    
+    def on_player_leave(self, player_id: str) -> None:
+        """Called when a player leaves."""
+        print(f"[SamplePlugin] Player {player_id} left!")
+    
+    def on_chat_message(self, sender_id: str, message: str, message_type: str) -> None:
+        """Called when a chat message is sent."""
+        if "hello plugin" in message.lower():
+            print(f"[SamplePlugin] Detected greeting from {sender_id}")

plugins/trading_system_plugin.py

@@ -0,0 +1,378 @@
+"""
+Trading System Plugin for MMORPG
+Adds player-to-player trading and marketplace functionality
+"""
+
+from src.interfaces.plugin_interfaces import IEconomyPlugin, PluginMetadata, PluginType
+from typing import Dict, List, Any, Optional
+import time
+import uuid
+
+class TradingSystemPlugin(IEconomyPlugin):
+    """Plugin that adds comprehensive trading and marketplace features."""
+    
+    def __init__(self):
+        self._metadata = PluginMetadata(
+            id="trading_system",
+            name="Trading System",
+            version="1.1.0",
+            author="MMORPG Dev Team",
+            description="Adds player trading, marketplace, and auction features",
+            plugin_type=PluginType.SERVICE,
+            dependencies=["enhanced_chat"],  # Depends on chat for trade messages
+            config={
+                "enable_direct_trading": True,
+                "enable_marketplace": True,
+                "trade_tax_rate": 0.05,
+                "max_trade_distance": 100
+            }
+        )
+        self._enabled = False
+        self._active_trades = {}  # Trade sessions
+        self._marketplace_listings = {}  # Marketplace items
+        self._trade_history = []
+          # Sample items for trading
+        self._tradeable_items = {
+            "health_potion": {"name": "Health Potion", "base_value": 10, "stackable": True},
+            "mana_potion": {"name": "Mana Potion", "base_value": 15, "stackable": True},
+            "iron_sword": {"name": "Iron Sword", "base_value": 50, "stackable": False},
+            "wooden_shield": {"name": "Wooden Shield", "base_value": 30, "stackable": False},
+            "magic_scroll": {"name": "Magic Scroll", "base_value": 25, "stackable": True},
+            "gold_coin": {"name": "Gold Coin", "base_value": 1, "stackable": True}        }
+    
+    @property
+    def metadata(self) -> PluginMetadata:
+        return self._metadata
+    
+    def initialize(self, context: Dict[str, Any]) -> bool:
+        """Initialize the trading system plugin."""
+        try:
+            self._config = self._metadata.config
+            self._enabled = True
+            print(f"🏪 Trading System Plugin initialized with {len(self._tradeable_items)} tradeable items")
+            return True
+        except Exception as e:
+            print(f"🏪 Failed to initialize Trading System Plugin: {e}")
+            return False
+        
+    def cleanup(self) -> None:
+        """Clean up trading system resources."""
+        # Cancel all active trades
+        for trade_id in list(self._active_trades.keys()):
+            self.cancel_trade(trade_id)
+        
+        self._enabled = False
+        print("💰 Trading System Plugin cleaned up")
+    
+    def is_enabled(self) -> bool:
+        return self._enabled
+    
+    def initiate_trade(self, player1_id: str, player2_id: str, player1_pos: tuple, player2_pos: tuple) -> Dict[str, Any]:
+        """Initiate a trade between two players."""
+        if not self._enabled or not self._config.get("enable_direct_trading", True):
+            return {"success": False, "error": "Trading is disabled"}
+        
+        # Check distance
+        max_distance = self._config.get("max_trade_distance", 100)
+        distance = ((player1_pos[0] - player2_pos[0]) ** 2 + (player1_pos[1] - player2_pos[1]) ** 2) ** 0.5
+        
+        if distance > max_distance:
+            return {"success": False, "error": "Players are too far apart to trade"}
+        
+        # Create trade session
+        trade_id = str(uuid.uuid4())
+        trade_session = {
+            "id": trade_id,
+            "player1": player1_id,
+            "player2": player2_id,
+            "player1_items": {},
+            "player2_items": {},
+            "player1_gold": 0,
+            "player2_gold": 0,
+            "player1_accepted": False,
+            "player2_accepted": False,
+            "status": "active",
+            "created_at": time.time()
+        }
+        
+        self._active_trades[trade_id] = trade_session
+        
+        return {
+            "success": True,
+            "trade_id": trade_id,
+            "message": f"Trade initiated between players {player1_id} and {player2_id}"
+        }
+    
+    def add_item_to_trade(self, trade_id: str, player_id: str, item_id: str, quantity: int = 1) -> Dict[str, Any]:
+        """Add an item to a trade."""
+        if trade_id not in self._active_trades:
+            return {"success": False, "error": "Trade not found"}
+        
+        trade = self._active_trades[trade_id]
+        
+        if trade["status"] != "active":
+            return {"success": False, "error": "Trade is not active"}
+        
+        # Determine which player
+        if player_id == trade["player1"]:
+            items_dict = trade["player1_items"]
+        elif player_id == trade["player2"]:
+            items_dict = trade["player2_items"]
+        else:
+            return {"success": False, "error": "Player not part of this trade"}
+        
+        # Add item
+        if item_id not in items_dict:
+            items_dict[item_id] = 0
+        items_dict[item_id] += quantity
+        
+        # Reset acceptance status
+        trade["player1_accepted"] = False
+        trade["player2_accepted"] = False
+        
+        return {
+            "success": True,
+            "message": f"Added {quantity}x {self._tradeable_items.get(item_id, {}).get('name', item_id)} to trade"
+        }
+    
+    def add_gold_to_trade(self, trade_id: str, player_id: str, amount: int) -> Dict[str, Any]:
+        """Add gold to a trade."""
+        if trade_id not in self._active_trades:
+            return {"success": False, "error": "Trade not found"}
+        
+        trade = self._active_trades[trade_id]
+        
+        if trade["status"] != "active":
+            return {"success": False, "error": "Trade is not active"}
+        
+        # Determine which player and update gold
+        if player_id == trade["player1"]:
+            trade["player1_gold"] += amount
+        elif player_id == trade["player2"]:
+            trade["player2_gold"] += amount
+        else:
+            return {"success": False, "error": "Player not part of this trade"}
+        
+        # Reset acceptance status
+        trade["player1_accepted"] = False
+        trade["player2_accepted"] = False
+        
+        return {"success": True, "message": f"Added {amount} gold to trade"}
+    
+    def accept_trade(self, trade_id: str, player_id: str) -> Dict[str, Any]:
+        """Accept a trade."""
+        if trade_id not in self._active_trades:
+            return {"success": False, "error": "Trade not found"}
+        
+        trade = self._active_trades[trade_id]
+        
+        if trade["status"] != "active":
+            return {"success": False, "error": "Trade is not active"}
+        
+        # Mark player as accepted
+        if player_id == trade["player1"]:
+            trade["player1_accepted"] = True
+        elif player_id == trade["player2"]:
+            trade["player2_accepted"] = True
+        else:
+            return {"success": False, "error": "Player not part of this trade"}
+        
+        # Check if both players accepted
+        if trade["player1_accepted"] and trade["player2_accepted"]:
+            return self._complete_trade(trade_id)
+        
+        return {"success": True, "message": "Trade accepted, waiting for other player"}
+    
+    def cancel_trade(self, trade_id: str) -> Dict[str, Any]:
+        """Cancel a trade."""
+        if trade_id not in self._active_trades:
+            return {"success": False, "error": "Trade not found"}
+        
+        trade = self._active_trades[trade_id]
+        trade["status"] = "cancelled"
+        
+        del self._active_trades[trade_id]
+        
+        return {"success": True, "message": "Trade cancelled"}
+    
+    def get_trade_status(self, trade_id: str) -> Dict[str, Any]:
+        """Get the status of a trade."""
+        if trade_id not in self._active_trades:
+            return {"success": False, "error": "Trade not found"}
+        
+        trade = self._active_trades[trade_id]
+        
+        return {
+            "success": True,
+            "trade": {
+                "id": trade["id"],
+                "status": trade["status"],
+                "player1": trade["player1"],
+                "player2": trade["player2"],
+                "player1_items": trade["player1_items"],
+                "player2_items": trade["player2_items"],
+                "player1_gold": trade["player1_gold"],
+                "player2_gold": trade["player2_gold"],
+                "player1_accepted": trade["player1_accepted"],
+                "player2_accepted": trade["player2_accepted"]
+            }
+        }
+    
+    def create_marketplace_listing(self, player_id: str, item_id: str, quantity: int, price: int) -> Dict[str, Any]:
+        """Create a marketplace listing."""
+        if not self._enabled or not self._config.get("enable_marketplace", True):
+            return {"success": False, "error": "Marketplace is disabled"}
+        
+        listing_id = str(uuid.uuid4())
+        listing = {
+            "id": listing_id,
+            "seller_id": player_id,
+            "item_id": item_id,
+            "quantity": quantity,
+            "price": price,
+            "created_at": time.time(),
+            "status": "active"
+        }
+        
+        self._marketplace_listings[listing_id] = listing
+        
+        item_name = self._tradeable_items.get(item_id, {}).get("name", item_id)
+        
+        return {
+            "success": True,
+            "listing_id": listing_id,
+            "message": f"Listed {quantity}x {item_name} for {price} gold"
+        }
+    
+    def get_marketplace_listings(self, item_filter: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Get marketplace listings."""
+        if not self._enabled or not self._config.get("enable_marketplace", True):
+            return []
+        
+        listings = []
+        for listing in self._marketplace_listings.values():
+            if listing["status"] != "active":
+                continue
+                
+            if item_filter and listing["item_id"] != item_filter:
+                continue
+            
+            item_info = self._tradeable_items.get(listing["item_id"], {})
+            listing_info = {
+                "id": listing["id"],
+                "seller_id": listing["seller_id"],
+                "item_id": listing["item_id"],
+                "item_name": item_info.get("name", listing["item_id"]),
+                "quantity": listing["quantity"],
+                "price": listing["price"],
+                "price_per_unit": listing["price"] / listing["quantity"],
+                "created_at": listing["created_at"]
+            }
+            listings.append(listing_info)
+        
+        # Sort by price per unit
+        listings.sort(key=lambda x: x["price_per_unit"])
+        
+        return listings
+    
+    def purchase_from_marketplace(self, buyer_id: str, listing_id: str) -> Dict[str, Any]:
+        """Purchase an item from the marketplace."""
+        if listing_id not in self._marketplace_listings:
+            return {"success": False, "error": "Listing not found"}
+        
+        listing = self._marketplace_listings[listing_id]
+        
+        if listing["status"] != "active":
+            return {"success": False, "error": "Listing is no longer active"}
+        
+        if listing["seller_id"] == buyer_id:
+            return {"success": False, "error": "Cannot buy your own listing"}
+        
+        # Calculate tax
+        tax_rate = self._config.get("trade_tax_rate", 0.05)
+        tax_amount = int(listing["price"] * tax_rate)
+        seller_receives = listing["price"] - tax_amount
+        
+        # Mark listing as sold
+        listing["status"] = "sold"
+        listing["buyer_id"] = buyer_id
+        listing["sold_at"] = time.time()
+        
+        # Add to trade history
+        trade_record = {
+            "type": "marketplace",
+            "seller_id": listing["seller_id"],
+            "buyer_id": buyer_id,
+            "item_id": listing["item_id"],
+            "quantity": listing["quantity"],
+            "price": listing["price"],
+            "tax_amount": tax_amount,
+            "timestamp": time.time()
+        }
+        self._trade_history.append(trade_record)
+        
+        item_name = self._tradeable_items.get(listing["item_id"], {}).get("name", listing["item_id"])
+        
+        return {
+            "success": True,
+            "message": f"Purchased {listing['quantity']}x {item_name} for {listing['price']} gold",
+            "seller_receives": seller_receives,
+            "tax_paid": tax_amount
+        }
+    
+    def get_tradeable_items(self) -> Dict[str, Dict[str, Any]]:
+        """Get list of tradeable items."""
+        return self._tradeable_items.copy()
+    
+    def _complete_trade(self, trade_id: str) -> Dict[str, Any]:
+        """Complete a trade between two players."""
+        trade = self._active_trades[trade_id]
+        
+        # Mark trade as completed
+        trade["status"] = "completed"
+        trade["completed_at"] = time.time()
+          # Add to trade history
+        trade_record = {
+            "type": "direct_trade",
+            "player1": trade["player1"],
+            "player2": trade["player2"],
+            "player1_items": trade["player1_items"],
+            "player2_items": trade["player2_items"],
+            "player1_gold": trade["player1_gold"],
+            "player2_gold": trade["player2_gold"],
+            "timestamp": time.time()
+        }
+        self._trade_history.append(trade_record)
+        
+        # Remove from active trades
+        del self._active_trades[trade_id]
+        
+        return {
+            "success": True,
+            "message": "Trade completed successfully!",
+            "trade_summary": trade_record
+        }
+    
+    def get_status(self) -> Dict[str, Any]:
+        """Get trading system status."""
+        return {
+            "enabled": self._enabled,
+            "active_trades": len(self._active_trades),
+            "marketplace_listings": len(self._marketplace_listings),
+            "total_items": len(self._tradeable_items),
+            "trade_history_count": len(self._trade_history)
+        }
+    
+    def shutdown(self) -> bool:
+        """Shutdown the trading system."""
+        try:
+            self.cleanup()
+            return True
+        except Exception as e:
+            print(f"🏪 Error shutting down Trading System Plugin: {e}")
+            return False
+
+# Plugin entry point  
+def create_plugin():
+    """Factory function to create the plugin instance."""
+    return TradingSystemPlugin()

plugins/weather_plugin.py

@@ -0,0 +1,187 @@
+"""
+Sample Weather Plugin for MMORPG
+Adds weather effects and seasonal changes to the game world
+"""
+
+from src.interfaces.plugin_interfaces import IWeatherPlugin, PluginMetadata, PluginType
+from typing import Dict, List, Any
+import random
+import time
+
+class WeatherPlugin(IWeatherPlugin):
+    """Plugin that adds dynamic weather system to the game."""
+    
+    def __init__(self):
+        self._metadata = PluginMetadata(
+            id="weather_system",
+            name="Weather System",
+            version="1.0.0",
+            author="MMORPG Dev Team",
+            description="Adds dynamic weather effects and seasonal changes",
+            plugin_type=PluginType.SERVICE,
+            dependencies=[],
+            config={
+                "weather_change_interval": 300,
+                "enable_seasons": True,
+                "weather_effects_enabled": True
+            }
+        )
+        self._enabled = False
+        self._weather_state = {
+            "current_weather": "sunny",
+            "temperature": 20,
+            "season": "spring",
+            "last_change": time.time()
+        }
+        self._weather_types = [
+            "sunny", "cloudy", "rainy", "stormy", "foggy", "snowy"
+        ]
+        
+    @property
+    def metadata(self) -> PluginMetadata:
+        return self._metadata
+    
+    def initialize(self, context: Dict[str, Any]) -> bool:
+        """Initialize the weather plugin."""
+        try:
+            self._config = self._metadata.config
+            self._enabled = True
+            print("Weather Plugin initialized successfully")
+            self._update_weather()
+            return True
+        except Exception as e:
+            print(f"Failed to initialize Weather Plugin: {e}")
+            return False
+    
+    def shutdown(self) -> bool:
+        """Shutdown the weather plugin."""
+        try:
+            self._enabled = False
+            print("Weather Plugin shut down")
+            return True
+        except Exception as e:
+            print(f"Error shutting down Weather Plugin: {e}")
+            return False
+    
+    def get_status(self) -> Dict[str, Any]:
+        """Get weather plugin status."""
+        return {
+            "enabled": self._enabled,
+            "current_weather": self._weather_state["current_weather"],
+            "temperature": self._weather_state["temperature"],
+            "season": self._weather_state["season"],
+            "effects_enabled": self._config.get("weather_effects_enabled", True) if hasattr(self, '_config') else True
+        }
+    
+    def get_weather_info(self) -> Dict[str, Any]:
+        """Get current weather information."""
+        if not self._enabled:
+            return {}
+            
+        return {
+            "weather": self._weather_state["current_weather"],
+            "temperature": self._weather_state["temperature"],
+            "season": self._weather_state["season"],
+            "description": self._get_weather_description()
+        }
+    
+    def update_weather(self) -> Dict[str, Any]:
+        """Update weather conditions."""
+        if not self._enabled:
+            return {}
+            
+        current_time = time.time()
+        interval = self._config.get("weather_change_interval", 300)
+        
+        if current_time - self._weather_state["last_change"] > interval:
+            self._update_weather()
+            self._weather_state["last_change"] = current_time
+            
+        return self.get_weather_info()
+    
+    def apply_weather_effects(self, player_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Apply weather effects to player."""
+        if not self._enabled or not self._config.get("weather_effects_enabled", True):
+            return player_data
+            
+        effects = player_data.copy()
+        weather_modifier = self._get_weather_modifier()
+        
+        if "stats" not in effects:
+            effects["stats"] = {}
+        
+        effects["stats"]["weather_modifier"] = weather_modifier
+        effects["weather_description"] = self._get_weather_description()
+        
+        return effects
+    
+    def _update_weather(self):
+        """Internal method to update weather conditions."""
+        self._weather_state["current_weather"] = random.choice(self._weather_types)
+        
+        base_temp = self._get_seasonal_base_temperature()
+        weather_modifier = self._get_weather_temperature_modifier()
+        self._weather_state["temperature"] = base_temp + weather_modifier + random.randint(-5, 5)
+        
+        if self._config.get("enable_seasons", True):
+            seasons = ["spring", "summer", "autumn", "winter"]
+            if random.random() < 0.01:
+                current_season_idx = seasons.index(self._weather_state["season"])
+                self._weather_state["season"] = seasons[(current_season_idx + 1) % len(seasons)]
+    
+    def _get_seasonal_base_temperature(self) -> int:
+        """Get base temperature for current season."""
+        season_temps = {
+            "spring": 15,
+            "summer": 25,
+            "autumn": 10,
+            "winter": 0
+        }
+        return season_temps.get(self._weather_state["season"], 15)
+    
+    def _get_weather_temperature_modifier(self) -> int:
+        """Get temperature modifier based on weather."""
+        weather_mods = {
+            "sunny": 5,
+            "cloudy": 0,
+            "rainy": -3,
+            "stormy": -5,
+            "foggy": -2,
+            "snowy": -10
+        }
+        return weather_mods.get(self._weather_state["current_weather"], 0)
+    
+    def _get_weather_description(self) -> str:
+        """Get descriptive text for current weather."""
+        weather = self._weather_state["current_weather"]
+        temp = self._weather_state["temperature"]
+        season = self._weather_state["season"]
+        
+        descriptions = {
+            "sunny": f"Bright and sunny {season} day ({temp} degrees C)",
+            "cloudy": f"Overcast {season} sky ({temp} degrees C)",
+            "rainy": f"Light rain falling in {season} ({temp} degrees C)",
+            "stormy": f"Thunderstorm brewing this {season} ({temp} degrees C)",
+            "foggy": f"Thick fog blankets the {season} landscape ({temp} degrees C)",
+            "snowy": f"Snow falling gently in {season} ({temp} degrees C)"
+        }
+        return descriptions.get(weather, f"Unknown weather in {season} ({temp} degrees C)")
+    
+    def _get_weather_modifier(self) -> Dict[str, float]:
+        """Get weather-based stat modifiers."""
+        weather = self._weather_state["current_weather"]
+        
+        modifiers = {
+            "sunny": {"movement_speed": 1.1, "visibility": 1.0, "morale": 1.1},
+            "cloudy": {"movement_speed": 1.0, "visibility": 0.95, "morale": 0.95},
+            "rainy": {"movement_speed": 0.8, "visibility": 0.9, "morale": 0.9},
+            "stormy": {"movement_speed": 0.6, "visibility": 0.7, "morale": 0.8},
+            "foggy": {"movement_speed": 0.9, "visibility": 0.5, "morale": 0.85},
+            "snowy": {"movement_speed": 0.7, "visibility": 0.8, "morale": 0.9}
+        }
+        
+        return modifiers.get(weather, {"movement_speed": 1.0, "visibility": 1.0, "morale": 1.0})
+
+def create_plugin():
+    """Factory function to create the plugin instance."""
+    return WeatherPlugin()

pytest.ini

@@ -0,0 +1,30 @@
+[tool:pytest]
+markers =
+    stress: marks tests as stress tests (deselect with '-m "not stress"')
+    error_handling: marks tests as error handling tests
+    integration: marks tests as integration tests
+    browser: marks tests as browser tests (may require selenium)
+    slow: marks tests as slow running
+    e2e: marks tests as end-to-end tests
+    timeout: marks tests that need timeout protection
+
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+
+# Default timeout for tests
+timeout = 60
+
+# Ignore deprecation warnings from external libraries
+filterwarnings =
+    ignore::DeprecationWarning:websockets.*
+    ignore::pytest.PytestCollectionWarning
+    ignore::pytest.PytestUnknownMarkWarning
+
+# Set asyncio default loop scope
+addopts = 
+    --timeout=60
+    --timeout-method=thread
+    -v
+    --tb=short

quick_test.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""
+Quick verification that the world events auto-refresh fix is working
+"""
+
+import sys
+import os
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+
+def test_world_events_fix():
+    """Quick test of the world events fix"""
+    try:
+        from src.facades.game_facade import GameFacade
+        from src.ui.interface_manager import InterfaceManager
+        
+        print("✅ Import successful")
+        
+        # Test GameFacade has get_world_events method
+        facade = GameFacade()
+        if hasattr(facade, 'get_world_events'):
+            print("✅ GameFacade.get_world_events() method exists")
+            
+            events = facade.get_world_events()
+            print(f"✅ Method returns {len(events)} events")
+        else:
+            print("❌ GameFacade.get_world_events() method missing")
+            return False
+            
+        return True
+        
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        return False
+
+if __name__ == "__main__":
+    print("🔧 QUICK WORLD EVENTS FIX VERIFICATION")
+    print("=" * 50)
+    
+    if test_world_events_fix():
+        print("\n🎉 World events auto-refresh fix is working!")
+        print("📋 Summary of what was fixed:")
+        print("✅ Added 'world_events' as 8th output in timer configuration")
+        print("✅ Fixed mismatch between timer outputs (7) and method returns (8)")
+        print("✅ World events panel will now update automatically")
+        print("\n🌐 Server should be running at: http://localhost:7866")
+    else:
+        print("\n❌ There are still issues with the fix")

requirements.txt

@@ -0,0 +1,53 @@
+# MMOP Second Try - Requirements File
+# MMORPG with Gradio UI, MCP Integration, and Plugin System
+
+# Core Web Framework & UI
+gradio>=4.0.0
+gradio[mcp]
+
+# Data Processing & Math
+numpy>=1.20.0
+pandas>=1.3.0
+
+# Development & Testing
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+
+# Optional Dependencies (uncomment as needed)
+
+# For enhanced logging and debugging
+# colorlog>=6.0.0
+
+# For configuration management
+# pyyaml>=6.0
+# python-dotenv>=0.19.0
+
+# For HTTP/API support (if implementing REST APIs)
+# fastapi>=0.68.0
+# uvicorn>=0.15.0
+
+# For advanced text processing
+# regex>=2021.8.3
+
+# Development Tools (for code quality)
+# black>=22.0.0
+# isort>=5.10.0
+# flake8>=4.0.0
+# mypy>=0.910
+
+# Note: The following are included in Python 3.13 standard library:
+# - dataclasses (built-in since Python 3.7)
+# - typing (built-in)
+# - asyncio (built-in)
+# - threading (built-in)
+# - uuid (built-in)
+# - json (built-in)
+# - pathlib (built-in)
+# - os (built-in)
+# - time (built-in)
+# - random (built-in)
+# - math (built-in)
+# - hashlib (built-in)
+# - importlib (built-in)
+# - inspect (built-in)
+# - sqlite3 (built-in)

setup.bat

@@ -0,0 +1,36 @@
+@echo off
+REM MMOP Second Try - Windows Setup Script
+REM This script sets up the MMORPG environment on Windows
+
+echo.
+echo ========================================
+echo   MMOP Second Try - Setup Script
+echo ========================================
+echo.
+
+REM Check if Python is available
+python --version >nul 2>&1
+if errorlevel 1 (
+    echo ERROR: Python is not installed or not in PATH
+    echo Please install Python 3.8 or higher from python.org
+    pause
+    exit /b 1
+)
+
+echo Python found. Starting setup...
+echo.
+
+REM Run the Python setup script
+python setup.py
+
+echo.
+echo ========================================
+echo Setup completed!
+echo.
+echo To run the MMORPG:
+echo   python app.py
+echo.
+echo Then open your browser to the displayed URL
+echo ========================================
+echo.
+pause

setup.ps1

@@ -0,0 +1,41 @@
+# MMOP Second Try - PowerShell Setup Script
+# This script sets up the MMORPG environment using PowerShell
+
+Write-Host ""
+Write-Host "========================================" -ForegroundColor Cyan
+Write-Host "   MMOP Second Try - Setup Script" -ForegroundColor Cyan
+Write-Host "========================================" -ForegroundColor Cyan
+Write-Host ""
+
+# Check if Python is available
+try {
+    $pythonVersion = python --version 2>&1
+    Write-Host "✅ $pythonVersion found" -ForegroundColor Green
+} catch {
+    Write-Host "❌ ERROR: Python is not installed or not in PATH" -ForegroundColor Red
+    Write-Host "Please install Python 3.8 or higher from python.org" -ForegroundColor Yellow
+    Read-Host "Press Enter to exit"
+    exit 1
+}
+
+Write-Host "🔧 Starting setup..." -ForegroundColor Yellow
+Write-Host ""
+
+# Run the Python setup script
+try {
+    python setup.py
+    Write-Host ""
+    Write-Host "========================================" -ForegroundColor Green
+    Write-Host "🎉 Setup completed successfully!" -ForegroundColor Green
+    Write-Host ""
+    Write-Host "To run the MMORPG:" -ForegroundColor Cyan
+    Write-Host "   python app.py" -ForegroundColor White
+    Write-Host ""
+    Write-Host "Then open your browser to the displayed URL" -ForegroundColor Cyan
+    Write-Host "========================================" -ForegroundColor Green
+} catch {
+    Write-Host "❌ Setup failed. Please check the error messages above." -ForegroundColor Red
+}
+
+Write-Host ""
+Read-Host "Press Enter to continue"

setup.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""
+Setup script for MMOP Second Try
+Installs dependencies and verifies the installation
+"""
+
+import subprocess
+import sys
+import os
+from pathlib import Path
+
+def run_command(command, description):
+    """Run a command and handle errors"""
+    print(f"\n{'='*50}")
+    print(f"🔧 {description}")
+    print(f"{'='*50}")
+    
+    try:
+        result = subprocess.run(command, shell=True, check=True, capture_output=True, text=True)
+        print(f"✅ {description} completed successfully")
+        if result.stdout:
+            print(f"Output: {result.stdout}")
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"❌ {description} failed")
+        print(f"Error: {e.stderr}")
+        return False
+
+def check_python_version():
+    """Check if Python version is suitable"""
+    print(f"🐍 Python version: {sys.version}")
+    if sys.version_info < (3, 8):
+        print("❌ Python 3.8 or higher is required")
+        return False
+    print("✅ Python version is compatible")
+    return True
+
+def install_dependencies():
+    """Install dependencies from requirements.txt"""
+    requirements_file = Path("requirements.txt")
+    if not requirements_file.exists():
+        print("❌ requirements.txt not found")
+        return False
+    
+    return run_command(
+        f"{sys.executable} -m pip install -r requirements.txt",
+        "Installing dependencies"
+    )
+
+def verify_installation():
+    """Verify that key components can be imported"""
+    print(f"\n{'='*50}")
+    print("🔍 Verifying installation")
+    print(f"{'='*50}")
+    
+    tests = [
+        ("import gradio", "Gradio UI framework"),
+        ("import numpy", "NumPy"),
+        ("import pandas", "Pandas"),
+        ("from src.facades.game_facade import GameFacade", "Game Facade"),
+        ("from src.mcp.mcp_tools import GradioMCPTools", "MCP Tools"),
+        ("from app import MMORPGApplication", "Main Application"),
+    ]
+    
+    all_passed = True
+    for test_import, description in tests:
+        try:
+            exec(test_import)
+            print(f"✅ {description}")
+        except ImportError as e:
+            print(f"❌ {description}: {e}")
+            all_passed = False
+        except Exception as e:
+            print(f"⚠️  {description}: {e}")
+    
+    return all_passed
+
+def main():
+    """Main setup function"""
+    print("🎮 MMOP Second Try - Setup Script")
+    print("=" * 50)
+    
+    # Check Python version
+    if not check_python_version():
+        sys.exit(1)
+    
+    # Install dependencies
+    if not install_dependencies():
+        print("\n❌ Dependency installation failed")
+        sys.exit(1)
+    
+    # Verify installation
+    if not verify_installation():
+        print("\n⚠️  Some components failed verification, but you can still try running the application")
+    else:
+        print("\n🎉 Setup completed successfully!")
+    
+    print(f"\n{'='*50}")
+    print("🚀 Next steps:")
+    print("1. Run the application: python app.py")
+    print("2. Open your browser to the displayed URL")
+    print("3. Start playing your MMORPG!")
+    print(f"{'='*50}")
+
+if __name__ == "__main__":
+    main()

src/__init__.py

@@ -0,0 +1,11 @@
+"""
+MMORPG Application - Clean Architecture Implementation
+Main package initialization
+"""
+
+# Package version
+__version__ = "2.0.0"
+
+# Import main components for easy access
+from .core.game_engine import GameEngine
+from .facades.game_facade import GameFacade

src/addons/__init__.py

@@ -0,0 +1,5 @@
+"""
+Add-on system package for MMOP game.
+"""
+
+__version__ = "1.0.0"

src/addons/example_npc_addon.py

@@ -0,0 +1,230 @@
+"""
+Example NPC Addon - Template for creating new NPCs with custom functionality
+"""
+
+import gradio as gr
+from typing import Dict, Any
+from src.interfaces.npc_addon import NPCAddon
+
+
+class ExampleNPCAddon(NPCAddon):
+    """Example NPC addon demonstrating the complete NPC creation process."""
+    
+    def __init__(self):
+        super().__init__()
+        # Initialize any state or data your NPC needs
+        self.npc_inventory = {
+            "health_potion": {"name": "Health Potion", "price": 25, "stock": 10},
+            "magic_scroll": {"name": "Magic Scroll", "price": 50, "stock": 5},
+            "steel_sword": {"name": "Steel Sword", "price": 100, "stock": 3}
+        }
+        self.greeting_messages = [
+            "Welcome to my shop, adventurer!",
+            "Looking for some fine wares?",
+            "I have the best deals in town!",
+            "What can I help you with today?"
+        ]
+    
+    @property
+    def addon_id(self) -> str:
+        """Unique identifier for this addon - must match NPC ID in world."""
+        return "example_merchant"
+    
+    @property
+    def addon_name(self) -> str:
+        """Display name shown in the interface."""
+        return "Example Merchant"
+    
+    def get_interface(self) -> gr.Component:
+        """Create the Gradio interface for this NPC."""
+        with gr.Column() as interface:
+            gr.Markdown("""
+            ## 🏪 Example Merchant
+            
+            *Welcome to my humble shop! I offer fine wares for brave adventurers.*
+            
+            ### Available Services:
+            - **Shop**: Browse and purchase items
+            - **Appraisal**: Get item value estimates  
+            - **Information**: Learn about the local area
+            
+            *Walk near me in the game world to unlock full functionality!*
+            """)
+            
+            with gr.Tabs():
+                # Shop Tab
+                with gr.Tab("🛒 Shop"):
+                    gr.Markdown("### Available Items")
+                    
+                    with gr.Row():
+                        item_select = gr.Dropdown(
+                            label="Select Item",
+                            choices=list(self.npc_inventory.keys()),
+                            value=None
+                        )
+                        quantity = gr.Number(
+                            label="Quantity",
+                            value=1,
+                            minimum=1,
+                            maximum=10
+                        )
+                    
+                    with gr.Row():
+                        buy_btn = gr.Button("💰 Purchase", variant="primary")
+                        refresh_btn = gr.Button("🔄 Refresh Stock", variant="secondary")
+                    
+                    purchase_result = gr.Textbox(
+                        label="Transaction Result",
+                        lines=3,
+                        interactive=False
+                    )
+                      # Shop display
+                    shop_display = gr.JSON(
+                        label="Current Inventory",
+                        value=self.npc_inventory
+                    )
+                    
+                    def handle_purchase(item_key, qty):
+                        if not item_key:
+                            return "❌ Please select an item first!"
+                        
+                        # Get current player (simplified for example)
+                        from ..core.game_engine import GameEngine
+                        game_engine = GameEngine()
+                        game_world = game_engine.get_world()
+                        current_players = list(game_world.players.keys())
+                        if not current_players:
+                            return "❌ You must be in the game to make purchases!"
+                        
+                        player_id = max(current_players, key=lambda pid: game_world.players[pid].last_active)
+                        return self.purchase_item(player_id, item_key, int(qty))
+                    
+                    def refresh_shop():
+                        return self.npc_inventory
+                    
+                    # Wire up the interface
+                    buy_btn.click(handle_purchase, [item_select, quantity], purchase_result)
+                    refresh_btn.click(refresh_shop, outputs=shop_display)
+                
+                # Information Tab
+                with gr.Tab("ℹ️ Information"):
+                    gr.Markdown("""
+                    ### 📍 Local Area Information
+                    
+                    - **Location**: Village Market Square
+                    - **Trading Hours**: Always open for brave adventurers
+                    - **Specialties**: Weapons, potions, and magical items
+                    - **Payment**: Gold coins accepted
+                    
+                    ### 🗺️ Nearby Locations
+                    - **Village Elder**: North of here, near the fountain
+                    - **Training Grounds**: East side of village
+                    - **Mystic Oracle**: In the tower to the south
+                    """)
+                    
+                    info_btn = gr.Button("📋 Get Quest Information")
+                    quest_info = gr.Textbox(
+                        label="Available Quests",
+                        lines=5,
+                        interactive=False
+                    )
+                    
+                    def get_quest_info():
+                        return """
+🗡️ **Available Quests:**
+
+1. **Goblin Problem** (Level 1-3)
+   - Clear goblins from the eastern caves
+   - Reward: 100 gold + basic equipment
+
+2. **Herb Collection** (Level 1-2)  
+   - Gather 10 healing herbs from the forest
+   - Reward: 50 gold + health potion
+
+3. **Lost Merchant** (Level 3-5)
+   - Find the missing merchant on the trade route
+   - Reward: 200 gold + rare item
+                        """
+                    
+                    info_btn.click(get_quest_info, outputs=quest_info)
+        
+        return interface
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle commands sent via private messages to this NPC."""
+        command_lower = command.lower().strip()
+          # Get player info safely
+        from ..core.game_engine import GameEngine
+        game_engine = GameEngine()
+        game_world = game_engine.get_world()
+        player = game_world.players.get(player_id)
+        if not player:
+            return "❌ Player not found!"
+        
+        player_name = player.name
+        
+        # Command parsing
+        if any(word in command_lower for word in ['hello', 'hi', 'greeting', 'hey']):
+            import random
+            return f"🏪 {random.choice(self.greeting_messages)} {player_name}!"
+        
+        elif any(word in command_lower for word in ['shop', 'buy', 'purchase', 'item']):
+            return self._get_shop_summary()
+        
+        elif any(word in command_lower for word in ['quest', 'mission', 'task']):
+            return "📜 I have information about local quests! Visit my Information tab for details."
+        
+        elif any(word in command_lower for word in ['help', 'commands']):
+            return """
+🏪 **Available Commands:**
+- **hello/hi**: Friendly greeting
+- **shop/buy**: View available items
+- **quest**: Learn about available quests  
+- **help**: Show this help message
+
+*Visit the NPC Add-ons tab for my full interface!*
+            """
+        
+        else:
+            return f"🤔 Interesting words, {player_name}! Try 'help' to see what I can do, or visit my shop interface in the NPC Add-ons tab!"
+    
+    def purchase_item(self, player_id: str, item_key: str, quantity: int) -> str:
+        """Handle item purchase logic."""
+        if item_key not in self.npc_inventory:
+            return "❌ Item not found in inventory!"
+        
+        item = self.npc_inventory[item_key]
+        total_cost = item["price"] * quantity
+        
+        if item["stock"] < quantity:
+            return f"❌ Not enough stock! Only {item['stock']} available."
+        
+        # Here you would check player's gold and deduct it
+        # For this example, we'll simulate the transaction
+        
+        # Update inventory
+        self.npc_inventory[item_key]["stock"] -= quantity
+        
+        return f"""
+✅ **Purchase Successful!**
+
+**Item**: {item['name']} x{quantity}
+**Cost**: {total_cost} gold
+**Remaining Stock**: {self.npc_inventory[item_key]['stock']}
+
+*Thank you for your business, adventurer!*
+        """
+    
+    def _get_shop_summary(self) -> str:
+        """Get a summary of available shop items."""
+        summary = "🏪 **Shop Inventory:**\n\n"
+        for key, item in self.npc_inventory.items():
+            if item["stock"] > 0:
+                summary += f"• **{item['name']}** - {item['price']} gold (Stock: {item['stock']})\n"
+        
+        summary += "\n*Visit my shop interface in the NPC Add-ons tab to purchase items!*"
+        return summary
+
+
+# Global instance for auto-registration
+example_merchant_addon = ExampleNPCAddon()

src/addons/fortune_teller_addon.py

@@ -0,0 +1,240 @@
+"""
+Fortune Teller Add-on - Self-contained addon demonstrating the new auto-registration system.
+"""
+
+import random
+import time
+from typing import Dict, Any, Optional
+import gradio as gr
+from ..interfaces.npc_addon import NPCAddon
+
+
+class FortuneTellerAddon(NPCAddon):
+    """Self-contained Fortune Teller NPC that auto-registers and positions itself."""
+    
+    def __init__(self):
+        super().__init__()  # This triggers auto-registration
+        self.fortunes = [
+            "A great adventure awaits you beyond the eastern mountains!",
+            "Beware of strangers bearing gifts in the next full moon.",
+            "Your courage will be tested, but victory will be yours.",
+            "Gold will come to you through an unexpected friendship.",
+            "The stars suggest a powerful ally will join your quest.",
+            "A hidden treasure lies where the old oak meets the stream.",
+            "Your wisdom will grow through helping others in need.",
+            "Trust your instincts - they will guide you true.",
+            "A challenge approaches, but it will make you stronger.",
+            "The path you seek becomes clear under starlight."
+        ]
+        self.player_fortunes: Dict[str, Dict] = {}  # Track player fortune history
+    
+    @property
+    def addon_id(self) -> str:
+        """Unique identifier for this add-on"""
+        return "fortune_teller"
+    
+    @property
+    def addon_name(self) -> str:
+        """Display name for this add-on"""
+        return "🔮 Mystic Fortune Teller"
+    
+    @property
+    def npc_config(self) -> Dict[str, Any]:
+        """NPC configuration for auto-placement in world"""
+        return {
+            'id': 'fortune_teller',
+            'name': 'Mystic Zelda',
+            'x': 125, 'y': 75,
+            'char': '🔮',
+            'type': 'addon',
+            'description': 'Wise fortune teller who can glimpse into your future'
+        }
+    
+    @property
+    def ui_tab_name(self) -> str:
+        """UI tab name for this addon"""
+        return "🔮 Fortune Teller"
+    
+    def get_interface(self) -> gr.Component:
+        """Create the Gradio interface for fortune telling"""
+        with gr.Column() as interface:
+            gr.Markdown("""
+            ## 🔮 Mystic Fortune Teller
+            
+            *Peer into the mists of time and discover your destiny...*
+            
+            **Services Available:**
+            - 🌟 **Daily Fortune** - Receive guidance for your journey
+            - 📜 **Fortune History** - View your past predictions
+            - 🎲 **Lucky Numbers** - Get your lucky numbers for today
+            
+            *Walk near me in the game world for personalized readings!*
+            """)
+            
+            with gr.Row():
+                fortune_btn = gr.Button("🔮 Get My Fortune", variant="primary", scale=2)
+                history_btn = gr.Button("📜 View History", variant="secondary", scale=1)
+                lucky_btn = gr.Button("🎲 Lucky Numbers", variant="secondary", scale=1)
+            
+            fortune_output = gr.Textbox(
+                label="🌟 Your Fortune",
+                lines=6,
+                interactive=False,
+                placeholder="Click 'Get My Fortune' to reveal your destiny..."
+            )
+            
+            def get_player_fortune():
+                """Get fortune for the active player"""
+                # In a real implementation, you'd get the actual player ID
+                # For demo purposes, we'll use a mock player
+                mock_player_id = "demo_player"
+                mock_player_name = "Brave Adventurer"
+                return self.get_daily_fortune(mock_player_id, mock_player_name)
+            
+            def get_player_history():
+                """Get fortune history for the active player"""
+                mock_player_id = "demo_player"
+                return self.get_fortune_history(mock_player_id)
+            
+            def get_lucky_numbers():
+                """Generate lucky numbers for the active player"""
+                mock_player_id = "demo_player"
+                return self.generate_lucky_numbers(mock_player_id)
+            
+            # Wire up the interface
+            fortune_btn.click(get_player_fortune, outputs=[fortune_output])
+            history_btn.click(get_player_history, outputs=[fortune_output])
+            lucky_btn.click(get_lucky_numbers, outputs=[fortune_output])
+            
+        return interface
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle Fortune Teller commands via private messages"""
+        parts = command.strip().split(' ', 1)
+        cmd = parts[0].lower()
+        
+        if cmd == "fortune":
+            # Get player name from game world
+            try:
+                from ..core.world import game_world
+                player_name = game_world.players.get(player_id, {}).get('name', 'Unknown Traveler')
+            except:
+                player_name = "Unknown Traveler"
+            
+            return self.get_daily_fortune(player_id, player_name)
+        
+        elif cmd == "history":
+            return self.get_fortune_history(player_id)
+        
+        elif cmd == "lucky":
+            return self.generate_lucky_numbers(player_id)
+        
+        elif cmd == "help":
+            return """🔮 **Fortune Teller Commands:**
+
+**fortune** - Get your daily fortune reading
+**history** - View your fortune history
+**lucky** - Generate lucky numbers for today
+**help** - Show this help
+
+🌟 **Example:** Send me "fortune" to receive mystical guidance!"""
+        
+        else:
+            # If no specific command, treat as fortune request
+            try:
+                from ..core.world import game_world
+                player_name = game_world.players.get(player_id, {}).get('name', 'Unknown Traveler')
+            except:
+                player_name = "Unknown Traveler"
+            
+            return self.get_daily_fortune(player_id, player_name)
+    
+    def get_daily_fortune(self, player_id: str, player_name: str) -> str:
+        """Get or generate daily fortune for a player"""
+        today = time.strftime("%Y-%m-%d")
+        
+        # Check if player already has a fortune for today
+        if player_id in self.player_fortunes:
+            player_data = self.player_fortunes[player_id]
+            if player_data.get('last_fortune_date') == today:
+                return (f"**{player_name}**, I have already revealed your destiny for today:\n\n"
+                       f"✨ *{player_data['last_fortune']}*\n\n"
+                       f"Return tomorrow for new guidance...")
+        
+        # Generate new fortune
+        fortune = random.choice(self.fortunes)
+        
+        # Store fortune
+        if player_id not in self.player_fortunes:
+            self.player_fortunes[player_id] = {'history': []}
+        
+        self.player_fortunes[player_id].update({
+            'last_fortune': fortune,
+            'last_fortune_date': today
+        })
+        
+        self.player_fortunes[player_id]['history'].append({
+            'date': today,
+            'fortune': fortune,
+            'timestamp': time.time()
+        })
+        
+        # Keep only last 10 fortunes
+        if len(self.player_fortunes[player_id]['history']) > 10:
+            self.player_fortunes[player_id]['history'] = self.player_fortunes[player_id]['history'][-10:]
+        
+        return (f"🔮 **Greetings, {player_name}!**\n\n"
+               f"The crystal ball swirls with mystical energy...\n\n"
+               f"✨ *{fortune}*\n\n"
+               f"💫 This fortune is yours until the dawn of a new day.")
+    
+    def get_fortune_history(self, player_id: str) -> str:
+        """Get fortune history for a player"""
+        if player_id not in self.player_fortunes or not self.player_fortunes[player_id].get('history'):
+            return "📜 **Fortune History**\n\nYou have no fortune history yet. Request your first fortune to begin building your mystical record!"
+        
+        history = self.player_fortunes[player_id]['history']
+        result = "📜 **Your Fortune History**\n\n"
+        
+        for entry in reversed(history[-5:]):  # Show last 5 fortunes
+            result += f"**{entry['date']}:** {entry['fortune']}\n\n"
+        
+        if len(history) > 5:
+            result += f"*...and {len(history) - 5} more in your mystical archives*"
+        
+        return result
+    
+    def generate_lucky_numbers(self, player_id: str) -> str:
+        """Generate lucky numbers for a player"""
+        # Use player ID as seed for consistent daily numbers
+        today = time.strftime("%Y-%m-%d")
+        seed = hash(f"{player_id}-{today}") % 2**31
+        random.seed(seed)
+        
+        # Generate different types of lucky numbers
+        lottery_numbers = sorted([random.randint(1, 49) for _ in range(6)])
+        magic_number = random.randint(1, 100)
+        lucky_color_index = random.randint(0, 6)
+        lucky_colors = ["Red", "Blue", "Green", "Gold", "Silver", "Purple", "Orange"]
+        lucky_color = lucky_colors[lucky_color_index]
+        
+        # Reset random seed
+        random.seed()
+        
+        return (f"🎲 **Lucky Numbers for Today**\n\n"
+               f"🎰 **Lottery Numbers:** {', '.join(map(str, lottery_numbers))}\n"
+               f"✨ **Magic Number:** {magic_number}\n"
+               f"🌈 **Lucky Color:** {lucky_color}\n\n"
+               f"💫 *May fortune smile upon you this day!*")
+    
+    def on_startup(self):
+        """Called when the addon is loaded during game startup"""
+        print(f"[{self.addon_id}] Fortune Teller Mystic Zelda has awakened and is ready to divine your future!")
+    
+    def on_shutdown(self):
+        """Called when the addon is unloaded during game shutdown"""
+        print(f"[{self.addon_id}] The crystal ball dims as Mystic Zelda rests...")
+
+
+# Auto-instantiate the addon for registration
+fortune_teller_addon = FortuneTellerAddon()

src/addons/magic_shop_addon.py

@@ -0,0 +1,509 @@
+"""
+Magic Shop Add-on - Self-contained NPC with position, registration, and UI.
+
+This demonstrates the weather addon pattern where everything is contained in one file:
+- NPC configuration with position
+- Command handling 
+- UI interface
+- Auto-registration through global instance
+
+No manual edits to other files required!
+"""
+
+import time
+import gradio as gr
+from typing import Dict, Any, List, Optional
+from ..interfaces.npc_addon import NPCAddon
+
+
+class MagicShopAddon(NPCAddon):
+    """Self-contained magic shop NPC that handles all aspects in one file."""
+    
+    def __init__(self):
+        super().__init__()  # This auto-registers the addon!
+        
+        # Shop inventory
+        self.spell_inventory = {
+            "healing_spell": {
+                "name": "🌟 Basic Healing Spell",
+                "price": 100,
+                "stock": 8,
+                "description": "Restores 50 health points",
+                "level_required": 1
+            },
+            "fireball_spell": {
+                "name": "🔥 Fireball Spell", 
+                "price": 250,
+                "stock": 5,
+                "description": "Deals fire damage to enemies",
+                "level_required": 3
+            },
+            "teleport_scroll": {
+                "name": "✨ Teleportation Scroll",
+                "price": 500,
+                "stock": 3,
+                "description": "Instantly travel to marked locations",
+                "level_required": 5
+            },
+            "mana_potion": {
+                "name": "🧪 Greater Mana Potion",
+                "price": 75,
+                "stock": 12,
+                "description": "Restores 100 mana points",
+                "level_required": 1
+            }
+        }
+        
+        # Shop stats
+        self.total_sales = 0
+        self.customers_served = []
+        self.last_restock = time.strftime("%Y-%m-%d %H:%M:%S")
+    
+    @property
+    def addon_id(self) -> str:
+        """Unique identifier for this add-on"""
+        return "magic_shop"
+    
+    @property
+    def addon_name(self) -> str:
+        """Display name for this add-on"""
+        return "🪄 Enchanted Magic Shop"
+    
+    @property
+    def npc_config(self) -> Dict[str, Any]:
+        """NPC configuration for auto-placement in world"""
+        return {
+            'id': 'magic_shop_keeper',
+            'name': '🧙‍♀️ Mystical Mage Elara',
+            'x': 300, 'y': 150,  # Position in the game world
+            'char': '🧙‍♀️',
+            'type': 'magic_shop',
+            'description': 'Wise mage selling powerful spells and magical items'
+        }
+    
+    @property
+    def ui_tab_name(self) -> str:
+        """UI tab name for this addon"""
+        return "🪄 Magic Shop"
+    
+    def get_interface(self) -> gr.Component:
+        """Create the Gradio interface for the magic shop"""
+        with gr.Column() as interface:
+            # Header with shop info
+            gr.Markdown(f"""
+            ## 🪄 {self.addon_name}
+            
+            *Greetings, brave adventurer! I am Elara, keeper of ancient magics.*
+            
+            **📍 Shop Location:** ({self.npc_config['x']}, {self.npc_config['y']})
+            **👥 Customers Served:** {len(self.customers_served)}
+            **💰 Total Sales:** {self.total_sales} gold
+            **📦 Last Restock:** {self.last_restock}
+            
+            ---
+            """)
+            
+            with gr.Tabs():
+                # Shop inventory tab
+                with gr.Tab("🛒 Spell Catalog"):
+                    gr.Markdown("### ✨ Available Magical Items")
+                    
+                    # Create inventory display
+                    inventory_data = []
+                    for item_id, item in self.spell_inventory.items():
+                        inventory_data.append({
+                            "Item": item["name"],
+                            "Price": f"{item['price']} gold",
+                            "Stock": item["stock"],
+                            "Level Req.": item["level_required"],
+                            "Description": item["description"]
+                        })
+                    
+                    inventory_display = gr.DataFrame(
+                        value=inventory_data,
+                        label="📜 Spell Inventory",
+                        interactive=False
+                    )
+                    
+                    # Purchase interface
+                    with gr.Row():
+                        item_dropdown = gr.Dropdown(
+                            label="🎯 Select Spell/Item",
+                            choices=[(item["name"], key) for key, item in self.spell_inventory.items()],
+                            value=None
+                        )
+                        quantity_input = gr.Number(
+                            label="📊 Quantity",
+                            value=1,
+                            minimum=1,
+                            maximum=10
+                        )
+                    
+                    purchase_btn = gr.Button("💰 Purchase", variant="primary", size="lg")
+                    
+                    purchase_result = gr.Textbox(
+                        label="🧾 Transaction Result",
+                        lines=4,
+                        interactive=False
+                    )
+                    
+                    def handle_purchase(item_key, qty):
+                        if not item_key:
+                            return "❌ Please select an item first!"
+                        
+                        if item_key not in self.spell_inventory:
+                            return "❌ Item not found in inventory!"
+                        
+                        item = self.spell_inventory[item_key]
+                        
+                        if qty > item["stock"]:
+                            return f"❌ Sorry! Only {item['stock']} {item['name']} in stock."
+                        
+                        total_cost = item["price"] * qty
+                        
+                        # Simulate purchase (in real game, check player gold)
+                        self.spell_inventory[item_key]["stock"] -= qty
+                        self.total_sales += total_cost
+                        
+                        return f"""✅ **Purchase Successful!**
+                        
+**Item:** {item['name']}
+**Quantity:** {qty}
+**Unit Price:** {item['price']} gold
+**Total Cost:** {total_cost} gold
+
+**Remaining Stock:** {self.spell_inventory[item_key]['stock']}
+
+*Thank you for your patronage! May these enchantments serve you well!*"""
+                    
+                    purchase_btn.click(
+                        handle_purchase,
+                        inputs=[item_dropdown, quantity_input],
+                        outputs=[purchase_result]
+                    )
+                
+                # Shop information tab
+                with gr.Tab("ℹ️ Shop Info"):
+                    gr.Markdown("""
+                    ### 🏪 About Elara's Magic Shop
+                    
+                    Welcome to the most enchanted emporium in the realm! I've been practicing
+                    the magical arts for over 200 years, and my shop contains only the finest
+                    spells and potions.
+                    
+                    #### 📋 Services Offered:
+                    - 🔮 **Spell Sales** - Powerful magic for every adventurer
+                    - 🧪 **Potion Brewing** - Restore health and mana
+                    - 📜 **Scroll Creation** - Portable magic for travel
+                    - 🎓 **Magic Consultation** - Learn about spell mechanics
+                    
+                    #### 🕐 Shop Hours:
+                    - **Open:** Always available for brave souls
+                    - **Restocking:** Weekly shipments from the Mage Tower
+                    - **Special Orders:** Available for rare enchantments
+                    
+                    #### 💡 Pro Tips:
+                    - Higher level spells require more experience
+                    - Potions stack in your inventory
+                    - Scrolls are one-time use items
+                    - Ask about bulk discounts for guilds!
+                    """)
+                    
+                    # Current shop stats
+                    shop_stats = gr.JSON(
+                        label="📊 Shop Statistics",
+                        value={
+                            "total_items_in_stock": sum(item["stock"] for item in self.spell_inventory.values()),
+                            "most_expensive_item": max(self.spell_inventory.values(), key=lambda x: x["price"])["name"],
+                            "cheapest_item": min(self.spell_inventory.values(), key=lambda x: x["price"])["name"],
+                            "customers_today": len(self.customers_served),
+                            "shop_established": "Year 1247 of the Third Age"
+                        }
+                    )
+                
+                # Commands help tab
+                with gr.Tab("💬 Commands"):
+                    gr.Markdown("""
+                    ### 🎯 Private Message Commands
+                    
+                    Send these commands via private messages to Mystical Mage Elara:
+                    
+                    #### 🛒 Shopping Commands:
+                    - `shop` - View available items and prices
+                    - `buy <item_name> [quantity]` - Purchase magical items
+                    - `stock` - Check current inventory levels
+                    
+                    #### ℹ️ Information Commands:
+                    - `info` - Get shop information and location
+                    - `hours` - Check shop hours and services
+                    - `help` - Show all available commands
+                    
+                    #### 📊 Status Commands:
+                    - `stats` - View shop statistics
+                    - `history` - Check your purchase history
+                    
+                    #### 🎯 Example Usage:
+                    ```
+                    shop                    # See all items
+                    buy healing_spell 2     # Buy 2 healing spells
+                    info                    # Get shop details
+                    stats                   # View shop statistics
+                    ```
+                    
+                    *Walk near my shop in the game world to unlock the full experience!*
+                    """)
+        
+        return interface
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle magic shop commands via private messages"""
+        if player_id not in self.customers_served:
+            self.customers_served.append(player_id)
+        
+        parts = command.strip().split()
+        if not parts:
+            return self._show_help()
+        
+        cmd = parts[0].lower()
+        
+        if cmd == "shop":
+            return self._show_shop_catalog()
+        
+        elif cmd == "buy":
+            if len(parts) < 2:
+                return "❓ Usage: `buy <item_name> [quantity]`\nExample: `buy healing_spell 2`"
+            
+            item_name = parts[1].lower()
+            quantity = 1
+            if len(parts) > 2:
+                try:
+                    quantity = int(parts[2])
+                    if quantity < 1:
+                        return "❌ Quantity must be at least 1!"
+                except ValueError:
+                    return "❌ Invalid quantity! Please use a number."
+            
+            return self._handle_purchase(player_id, item_name, quantity)
+        
+        elif cmd == "stock":
+            return self._show_stock_levels()
+        
+        elif cmd == "info":
+            return self._show_shop_info()
+        
+        elif cmd == "hours":
+            return self._show_shop_hours()
+        
+        elif cmd == "stats":
+            return self._show_shop_stats()
+        
+        elif cmd == "history":
+            return self._show_customer_history(player_id)
+        
+        elif cmd == "help":
+            return self._show_help()
+        
+        else:
+            return f"❓ Unknown command: `{cmd}`\n\nTry `help` to see available commands."
+    
+    def _show_shop_catalog(self) -> str:
+        """Display the complete shop catalog"""
+        catalog = "🪄 **Elara's Magic Shop - Spell Catalog**\n\n"
+        
+        for item_id, item in self.spell_inventory.items():
+            stock_status = "✅ In Stock" if item["stock"] > 0 else "❌ Sold Out"
+            catalog += f"**{item['name']}**\n"
+            catalog += f"• Price: {item['price']} gold\n"
+            catalog += f"• Stock: {item['stock']} ({stock_status})\n"
+            catalog += f"• Level Required: {item['level_required']}\n"
+            catalog += f"• {item['description']}\n\n"
+        
+        catalog += f"💰 Total Sales Today: {self.total_sales} gold\n"
+        catalog += f"👥 Customers Served: {len(self.customers_served)}\n\n"
+        catalog += "*To purchase: `buy <item_name> [quantity]`*"
+        
+        return catalog
+    
+    def _handle_purchase(self, player_id: str, item_name: str, quantity: int) -> str:
+        """Handle item purchase logic"""
+        # Find item by name or ID
+        item_key = None
+        for key, item in self.spell_inventory.items():
+            if key == item_name or item["name"].lower().replace(" ", "_") == item_name:
+                item_key = key
+                break
+        
+        if not item_key:
+            available_items = ", ".join(self.spell_inventory.keys())
+            return f"❌ Item '{item_name}' not found!\n\nAvailable items: {available_items}\n\nTry: `shop` to see the full catalog"
+        
+        item = self.spell_inventory[item_key]
+        
+        if item["stock"] < quantity:
+            return f"❌ Sorry! Only {item['stock']} {item['name']} available.\n\nTry a smaller quantity or check back after restock."
+        
+        total_cost = item["price"] * quantity
+        
+        # Simulate purchase (in real game, check/deduct player gold)
+        self.spell_inventory[item_key]["stock"] -= quantity
+        self.total_sales += total_cost
+        
+        return f"""✅ **Purchase Successful!**
+
+🎯 **Item:** {item['name']}
+📊 **Quantity:** {quantity}
+💰 **Total Cost:** {total_cost} gold
+📦 **Remaining Stock:** {self.spell_inventory[item_key]['stock']}
+
+*Your magical items have been added to your inventory!*
+*May they serve you well on your adventures!*
+
+Use `shop` to browse more items or `stats` to see shop statistics."""
+    
+    def _show_stock_levels(self) -> str:
+        """Show current stock levels"""
+        stock_report = "📦 **Current Stock Levels**\n\n"
+        
+        for item in self.spell_inventory.values():
+            status_emoji = "🟢" if item["stock"] > 5 else "🟡" if item["stock"] > 0 else "🔴"
+            stock_report += f"{status_emoji} **{item['name']}**: {item['stock']} available\n"
+        
+        stock_report += f"\n📅 **Last Restock:** {self.last_restock}"
+        stock_report += "\n💡 *Low stock items will be restocked weekly*"
+        
+        return stock_report
+    
+    def _show_shop_info(self) -> str:
+        """Show detailed shop information"""
+        return f"""🏪 **Elara's Magic Shop Information**
+
+🧙‍♀️ **Shopkeeper:** Mystical Mage Elara
+📍 **Location:** ({self.npc_config['x']}, {self.npc_config['y']})
+🏛️ **Shop Type:** Magical Items & Spell Emporium
+
+**About the Shop:**
+I've been practicing magic for over 200 years and offer only the finest
+enchantments, potions, and scrolls. My shop serves adventurers of all 
+levels, from novice spell-casters to master wizards.
+
+**Specialties:**
+• 🌟 Healing and restoration magic
+• 🔥 Offensive spells and scrolls  
+• 🧪 Mana and health potions
+• ✨ Utility and travel magic
+
+**Shop Guarantee:**
+All items come with Elara's personal enchantment guarantee!
+If a spell fails due to magical defect, return for full refund.
+
+*Walk near my shop to access the full interface and advanced features!*"""
+    
+    def _show_shop_hours(self) -> str:
+        """Show shop hours and services"""
+        return """🕐 **Shop Hours & Services**
+
+⏰ **Operating Hours:**
+• Always open for adventurers in need
+• Emergency magical supplies available 24/7
+• Personal consultations by appointment
+
+📦 **Restocking Schedule:**
+• Weekly shipments from the Mage Tower
+• Special orders processed every 3 days
+• Rare items available on request
+
+🎓 **Additional Services:**
+• Spell identification and appraisal
+• Magic item consultation
+• Bulk orders for guilds (discount rates)
+• Custom enchantment requests
+
+💡 **Current Status:** 🟢 Open and fully stocked!"""
+    
+    def _show_shop_stats(self) -> str:
+        """Show shop statistics"""
+        total_items = sum(item["stock"] for item in self.spell_inventory.values())
+        most_expensive = max(self.spell_inventory.values(), key=lambda x: x["price"])
+        cheapest = min(self.spell_inventory.values(), key=lambda x: x["price"])
+        
+        return f"""📊 **Shop Statistics**
+
+💰 **Sales Data:**
+• Total Sales: {self.total_sales} gold
+• Customers Served: {len(self.customers_served)}
+• Average Sale: {self.total_sales // max(len(self.customers_served), 1)} gold
+
+📦 **Inventory:**
+• Total Items in Stock: {total_items}
+• Most Expensive: {most_expensive['name']} ({most_expensive['price']} gold)
+• Most Affordable: {cheapest['name']} ({cheapest['price']} gold)
+
+🏆 **Shop Achievements:**
+• Established: Year 1247 of the Third Age
+• Reputation: ⭐⭐⭐⭐⭐ (5/5 stars)
+• Mage Guild Certified: ✅ Premium Vendor
+
+*Thank you for supporting local magical businesses!*"""
+    
+    def _show_customer_history(self, player_id: str) -> str:
+        """Show customer interaction history"""
+        return f"""👤 **Customer History for {player_id}**
+
+📋 **Account Status:** Valued Customer
+🎯 **First Visit:** Today (Welcome!)
+💰 **Total Purchases:** Check your inventory for items
+🏅 **Customer Level:** Novice Adventurer
+
+**Recommended Items:**
+• For beginners: Healing Spell + Mana Potion
+• For adventurers: Fireball Spell
+• For experts: Teleportation Scroll
+
+💡 **Next Purchase Suggestion:**
+Based on your level, I recommend starting with healing magic!
+
+*Continue shopping to unlock loyalty rewards and discounts!*"""
+    
+    def _show_help(self) -> str:
+        """Show all available commands"""
+        return """🪄 **Elara's Magic Shop - Command Help**
+
+**🛒 Shopping Commands:**
+• `shop` - Browse the complete spell catalog
+• `buy <item> [qty]` - Purchase magical items
+• `stock` - Check current inventory levels
+
+**ℹ️ Information Commands:**
+• `info` - Shop location and details
+• `hours` - Operating hours and services
+• `stats` - View shop statistics
+• `history` - Your customer history
+
+**💡 Examples:**
+• `shop` - See all available spells
+• `buy healing_spell 2` - Buy 2 healing spells
+• `buy mana_potion` - Buy 1 mana potion
+• `stock` - Check what's available
+
+**🎯 Item Names:**
+• `healing_spell` - Basic healing magic
+• `fireball_spell` - Fire damage spell
+• `teleport_scroll` - Travel magic
+• `mana_potion` - Mana restoration
+
+*Visit my shop interface in the NPC Add-ons tab for the full experience!*
+*Walk near my location at ({self.npc_config['x']}, {self.npc_config['y']}) in the game world!*"""
+    
+    def on_startup(self):
+        """Called when the addon is loaded during game startup"""
+        print(f"[{self.addon_id}] Elara's Magic Shop is now open for business!")
+        print(f"[{self.addon_id}] Located at ({self.npc_config['x']}, {self.npc_config['y']}) with {len(self.spell_inventory)} magical items")
+    
+    def on_shutdown(self):
+        """Called when the addon is unloaded during game shutdown"""
+        print(f"[{self.addon_id}] Elara's Magic Shop is closing... Total sales: {self.total_sales} gold")
+
+
+# Global instance - this triggers auto-registration!
+# Just like weather_oracle_service at the bottom of weather_oracle_addon.py
+magic_shop_addon = MagicShopAddon()

src/addons/read2burn_addon.py

@@ -0,0 +1,213 @@
+"""
+Read2Burn Mailbox Add-on - Self-destructing secure messaging system.
+"""
+
+import time
+import random
+import string
+from typing import Dict, List, Tuple
+from dataclasses import dataclass
+from abc import ABC, abstractmethod
+import gradio as gr
+
+from ..interfaces.npc_addon import NPCAddon
+
+
+@dataclass
+class Read2BurnMessage:
+    """Data class for Read2Burn messages."""
+    id: str
+    creator_id: str
+    content: str
+    created_at: float
+    expires_at: float
+    reads_left: int
+    burned: bool = False
+
+
+class IRead2BurnService(ABC):
+    """Interface for Read2Burn service operations."""
+    
+    @abstractmethod
+    def create_message(self, creator_id: str, content: str) -> str:
+        """Create a new self-destructing message."""
+        pass
+    
+    @abstractmethod
+    def read_message(self, reader_id: str, message_id: str) -> str:
+        """Read and potentially burn a message."""
+        pass
+    
+    @abstractmethod
+    def list_player_messages(self, player_id: str) -> str:
+        """List messages created by a player."""
+        pass
+
+
+class Read2BurnService(IRead2BurnService, NPCAddon):
+    """Service for managing Read2Burn secure messaging."""
+    
+    def __init__(self):
+        super().__init__()
+        self.messages: Dict[str, Read2BurnMessage] = {}
+        self.access_log: List[Dict] = []
+    
+    @property
+    def addon_id(self) -> str:
+        """Unique identifier for this add-on"""
+        return "read2burn_mailbox"
+    
+    @property
+    def addon_name(self) -> str:
+        """Display name for this add-on"""
+        return "Read2Burn Secure Mailbox"
+    
+    def get_interface(self) -> gr.Component:
+        """Return Gradio interface for this add-on"""
+        # This will be implemented later for the UI
+        return gr.Markdown("📧 **Read2Burn Secure Mailbox**\n\nUse private messages to the read2burn NPC to manage secure messages.")
+        
+    def generate_message_id(self) -> str:
+        """Generate a unique message ID."""
+        return ''.join(random.choices(string.ascii_uppercase + string.digits, k=8))
+    
+    def create_message(self, creator_id: str, content: str) -> str:
+        """Create a new self-destructing message."""
+        message_id = self.generate_message_id()
+        
+        message = Read2BurnMessage(
+            id=message_id,
+            creator_id=creator_id,
+            content=content,  # In production, encrypt this
+            created_at=time.time(),
+            expires_at=time.time() + (24 * 3600),  # 24 hours
+            reads_left=1,
+            burned=False
+        )
+        
+        self.messages[message_id] = message
+        
+        self.access_log.append({
+            'action': 'create',
+            'message_id': message_id,
+            'player_id': creator_id,
+            'timestamp': time.time()
+        })
+        
+        return f"✅ **Message Created Successfully!**\n\n📝 **Message ID:** `{message_id}`\n🔗 Share this ID with the recipient\n⏰ Expires in 24 hours\n🔥 Burns after 1 read"
+    
+    def read_message(self, reader_id: str, message_id: str) -> str:
+        """Read and burn a message."""
+        if message_id not in self.messages:
+            return "❌ Message not found or already burned"
+        
+        message = self.messages[message_id]
+        
+        # Check expiry
+        if time.time() > message.expires_at:
+            del self.messages[message_id]
+            return "❌ Message expired and has been burned"
+        
+        # Check if already burned
+        if message.burned or message.reads_left <= 0:
+            del self.messages[message_id]
+            return "❌ Message has already been burned"
+        
+        # Read the message
+        content = message.content
+        message.reads_left -= 1
+        
+        self.access_log.append({
+            'action': 'read',
+            'message_id': message_id,
+            'player_id': reader_id,
+            'timestamp': time.time()
+        })
+        
+        # Burn the message after reading
+        if message.reads_left <= 0:
+            message.burned = True
+            del self.messages[message_id]
+            return f"🔥 **Message Self-Destructed After Reading**\n\n📖 **Content:** {content}\n\n💨 This message has been permanently destroyed."
+        
+        return f"📖 **Message Content:** {content}\n\n⚠️ Reads remaining: {message.reads_left}"
+    
+    def list_player_messages(self, player_id: str) -> str:
+        """List messages created by a player."""
+        player_messages = [msg for msg in self.messages.values() if msg.creator_id == player_id]
+        
+        if not player_messages:
+            return "📪 No messages found. Create one with: `create Your message here`"
+        
+        result = "📋 **Your Created Messages:**\n\n"
+        for msg in player_messages:
+            status = "🔥 Burned" if msg.burned else f"✅ Active ({msg.reads_left} reads left)"
+            created_time = time.strftime("%Y-%m-%d %H:%M", time.localtime(msg.created_at))
+            expires_time = time.strftime("%Y-%m-%d %H:%M", time.localtime(msg.expires_at))
+            
+            result += f"**ID:** `{msg.id}`\n"
+            result += f"**Status:** {status}\n"
+            result += f"**Created:** {created_time}\n"
+            result += f"**Expires:** {expires_time}\n"
+            result += f"**Preview:** {msg.content[:50]}{'...' if len(msg.content) > 50 else ''}\n\n"
+        
+        return result
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle Read2Burn mailbox commands."""
+        parts = command.strip().split(' ', 1)
+        cmd = parts[0].lower()
+        
+        if cmd == "create" and len(parts) > 1:
+            return self.create_message(player_id, parts[1])
+        elif cmd == "read" and len(parts) > 1:
+            return self.read_message(player_id, parts[1])
+        elif cmd == "list":
+            return self.list_player_messages(player_id)
+        elif cmd == "help":
+            return """📚 **Read2Burn Mailbox Commands:**
+
+**create** `Your secret message here` - Create new message
+**read** `MESSAGE_ID` - Read message (destroys it!)
+**list** - Show your created messages
+**help** - Show this help
+
+🔥 **Features:**
+• Messages self-destruct after reading
+• 24-hour automatic expiration
+• Secure delivery system
+• Anonymous messaging support"""
+        else:
+            return "❓ Invalid command. Try: `create <message>`, `read <id>`, `list`, or `help`"
+    
+    def get_player_message_history(self, player_id: str) -> List[List[str]]:
+        """Get message history for display in a dataframe."""
+        player_messages = [msg for msg in self.messages.values() if msg.creator_id == player_id]
+        
+        history = []
+        for msg in player_messages:
+            status = "🔥 Burned" if msg.burned else "✅ Active"
+            created_time = time.strftime("%H:%M", time.localtime(msg.created_at))
+            reads_left = str(msg.reads_left) if not msg.burned else "0"
+            
+            history.append([msg.id, created_time, status, reads_left])
+        
+        return history
+    
+    def cleanup_expired_messages(self):
+        """Clean up expired messages."""
+        current_time = time.time()
+        expired_ids = [
+            msg_id for msg_id, msg in self.messages.items()
+            if current_time > msg.expires_at
+        ]
+        
+        for msg_id in expired_ids:
+            del self.messages[msg_id]
+            
+        if expired_ids:
+            print(f"[Read2Burn] Cleaned up {len(expired_ids)} expired messages")
+
+
+# Global Read2Burn service instance
+read2burn_service = Read2BurnService()

src/addons/self_contained_example_addon.py

@@ -0,0 +1,215 @@
+"""
+Self-Contained Example Addon - Demonstrates the simplified addon system.
+
+This addon automatically registers itself and requires no manual edits to system files.
+"""
+
+import time
+import gradio as gr
+from typing import Dict, Any, Optional
+
+from ..interfaces.npc_addon import NPCAddon
+
+
+class SelfContainedExampleAddon(NPCAddon):
+    """Example self-contained addon that demonstrates auto-registration."""
+    
+    def __init__(self):
+        super().__init__()
+        self.interaction_count = 0
+        self.last_interaction = None
+        
+    @property
+    def addon_id(self) -> str:
+        """Unique identifier for this add-on"""
+        return "self_contained_example"
+    
+    @property
+    def addon_name(self) -> str:
+        """Display name for this add-on"""
+        return "🎯 Self-Contained Example"
+    
+    @property
+    def npc_config(self) -> Dict[str, Any]:
+        """NPC configuration for auto-placement in world"""
+        return {
+            'id': 'self_contained_npc',
+            'name': '🎯 Example Bot',
+            'x': 400, 'y': 350,
+            'char': '🎯',
+            'type': 'example',
+            'description': 'Self-contained addon demonstration NPC'
+        }
+    
+    @property
+    def ui_tab_name(self) -> str:
+        """UI tab name for this addon"""
+        return "🎯 Example Addon"
+    
+    def get_interface(self) -> gr.Component:
+        """Return Gradio interface for this add-on"""
+        with gr.Column():
+            gr.Markdown("""
+            ## 🎯 Self-Contained Example Addon
+            
+            This demonstrates the new simplified addon system where:
+            - ✅ **Auto-Registration**: No manual file edits needed
+            - ✅ **Self-Contained**: All config in one file
+            - ✅ **Auto-Positioning**: NPC placed automatically
+            - ✅ **UI Integration**: Tab created automatically
+            
+            ### Features:
+            - Counter for interactions
+            - Timestamp of last interaction
+            - Example command processing
+            - Automatic UI generation
+            """)
+            
+            # Status display
+            status_display = gr.JSON(
+                label="📊 Addon Status",
+                value={
+                    "addon_id": self.addon_id,
+                    "addon_name": self.addon_name,
+                    "npc_position": f"({self.npc_config['x']}, {self.npc_config['y']})",
+                    "interaction_count": self.interaction_count,
+                    "last_interaction": self.last_interaction or "Never",
+                    "status": "🟢 Active"
+                }
+            )
+            
+            # Test interaction
+            with gr.Row():
+                test_input = gr.Textbox(
+                    label="🧪 Test Command",
+                    placeholder="Type 'status', 'count', 'reset', or 'help'",
+                    scale=3
+                )
+                test_btn = gr.Button("Send Command", variant="primary", scale=1)
+            
+            test_result = gr.Textbox(
+                label="📤 Response",
+                lines=3,
+                interactive=False
+            )
+            
+            def handle_test_command(command: str):
+                """Handle test commands from the UI"""
+                result = self.handle_command("ui_user", command)
+                
+                # Update status display
+                updated_status = {
+                    "addon_id": self.addon_id,
+                    "addon_name": self.addon_name,
+                    "npc_position": f"({self.npc_config['x']}, {self.npc_config['y']})",
+                    "interaction_count": self.interaction_count,
+                    "last_interaction": self.last_interaction or "Never",
+                    "status": "🟢 Active"
+                }
+                
+                return result, updated_status
+            
+            test_btn.click(
+                handle_test_command,
+                inputs=[test_input],
+                outputs=[test_result, status_display]
+            )
+            
+            test_input.submit(
+                handle_test_command,
+                inputs=[test_input],
+                outputs=[test_result, status_display]
+            )
+            
+            gr.Markdown("""
+            ### 🔧 Development Notes:
+            
+            **File Location:** `src/addons/self_contained_example_addon.py`
+            
+            **No Manual Edits Required:**
+            - ❌ No editing `world.py`
+            - ❌ No editing `game_engine.py`
+            - ❌ No editing `huggingface_ui.py`
+            
+            **Auto-Registration:**
+            1. Inherits from `NPCAddon`
+            2. Calls `super().__init__()` to register
+            3. Implements required properties and methods
+            4. Game engine auto-discovers on startup
+            
+            **Result:** Complete addon with NPC, UI, and commands!
+            """)
+            
+        return gr.Column()  # Return a container component
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle player commands via private messages"""
+        self.interaction_count += 1
+        self.last_interaction = time.strftime("%Y-%m-%d %H:%M:%S")
+        
+        cmd = command.strip().lower()
+        
+        if cmd == "help":
+            return """🎯 **Example Addon Commands:**
+
+**status** - Show addon status
+**count** - Show interaction count  
+**reset** - Reset interaction counter
+**info** - Show addon information
+**help** - Show this help message
+
+*This is a demonstration of the self-contained addon system!*"""
+        
+        elif cmd == "status":
+            return f"""🎯 **Example Addon Status:**
+
+📊 **Interaction Count:** {self.interaction_count}
+🕒 **Last Interaction:** {self.last_interaction}
+📍 **NPC Position:** ({self.npc_config['x']}, {self.npc_config['y']})
+🎮 **Player:** {player_id}
+✅ **Status:** Active and responding"""
+        
+        elif cmd == "count":
+            return f"🔢 **Interaction Count:** {self.interaction_count}"
+        
+        elif cmd == "reset":
+            old_count = self.interaction_count
+            self.interaction_count = 1  # Set to 1 because this command counts as an interaction
+            return f"🔄 **Counter Reset!** Previous count: {old_count}, New count: {self.interaction_count}"
+        
+        elif cmd == "info":
+            return f"""🎯 **Self-Contained Example Addon**
+
+**ID:** `{self.addon_id}`
+**Name:** {self.addon_name}
+**Type:** Demonstration addon
+**Features:** Auto-registration, UI integration, command processing
+
+This addon demonstrates the new simplified system where all configuration, 
+registration, and positioning is contained within the addon file itself!"""
+        
+        else:
+            return f"""❓ **Unknown command:** `{command}`
+
+Try one of these commands:
+• `help` - Show available commands
+• `status` - Show current status
+• `count` - Show interaction count
+• `info` - Show addon information
+
+💡 *Tip: This addon auto-registered itself without any manual file edits!*"""
+    
+    def on_startup(self):
+        """Called when the addon is loaded during game startup"""
+        print(f"[{self.addon_id}] Self-contained example addon started successfully!")
+        print(f"[{self.addon_id}] NPC positioned at ({self.npc_config['x']}, {self.npc_config['y']})")
+        print(f"[{self.addon_id}] UI tab '{self.ui_tab_name}' will be created automatically")
+    
+    def on_shutdown(self):
+        """Called when the addon is unloaded during game shutdown"""
+        print(f"[{self.addon_id}] Self-contained example addon shutting down...")
+        print(f"[{self.addon_id}] Total interactions during session: {self.interaction_count}")
+
+
+# Auto-instantiate the addon (this triggers registration)
+self_contained_example = SelfContainedExampleAddon()

src/addons/simple_trader_addon.py

@@ -0,0 +1,186 @@
+"""
+Simple Trader NPC Add-on - Self-contained NPC with automatic registration.
+"""
+
+import gradio as gr
+from typing import Dict, List
+from ..interfaces.npc_addon import NPCAddon
+
+
+class SimpleTraderAddon(NPCAddon):
+    """Self-contained trader NPC that handles its own registration and positioning."""
+    
+    def __init__(self):
+        super().__init__()
+        self.inventory = {
+            "Health Potion": {"price": 50, "stock": 10, "description": "Restores 100 HP"},
+            "Magic Scroll": {"price": 150, "stock": 5, "description": "Cast magic spells"},
+            "Iron Sword": {"price": 300, "stock": 3, "description": "Sharp iron weapon"},
+            "Shield": {"price": 200, "stock": 4, "description": "Protective gear"}
+        }
+        self.sales_history = []
+    
+    # ===== ADDON INTERFACE =====
+    @property
+    def addon_id(self) -> str:
+        return "simple_trader"
+    
+    @property 
+    def addon_name(self) -> str:
+        return "🛒 Simple Trader"
+    
+    def get_interface(self) -> gr.Component:
+        """Create the Gradio interface for this addon."""
+        with gr.Column() as interface:
+            gr.Markdown("### 🛒 Simple Trader Shop")
+            gr.Markdown("Browse items and check prices. Use private messages to trade!")
+            
+            # Display inventory
+            inventory_data = []
+            for item, info in self.inventory.items():
+                inventory_data.append([item, f"{info['price']} gold", info['stock'], info['description']])
+            
+            gr.Dataframe(
+                headers=["Item", "Price", "Stock", "Description"],
+                value=inventory_data,
+                interactive=False
+            )
+            
+            gr.Markdown("**Commands:** Send private message to Simple Trader")
+            gr.Markdown("• `buy <item>` - Purchase an item")
+            gr.Markdown("• `inventory` - See available items")
+            gr.Markdown("• `help` - Show all commands")
+        
+        return interface
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle commands sent to this NPC."""
+        parts = command.strip().split(' ', 1)
+        cmd = parts[0].lower()
+        
+        if cmd == "buy" and len(parts) > 1:
+            return self._handle_buy(player_id, parts[1])
+        elif cmd == "inventory":
+            return self._show_inventory()
+        elif cmd == "help":
+            return self._show_help()
+        else:
+            return "🛒 I don't understand that command. Try 'help' to see what I can do!"
+    
+    # ===== AUTO-REGISTRATION METHODS =====
+    
+    @classmethod
+    def get_npc_config(cls) -> Dict:
+        """Return the NPC configuration for automatic world registration."""
+        return {
+            'id': 'simple_trader',
+            'name': '🛒 Simple Trader',
+            'x': 450,  # Position on map
+            'y': 150,
+            'char': '🛒',  # Character emoji
+            'type': 'addon',
+            'personality': 'trader',
+            'description': 'A friendly trader selling useful items'
+        }
+    
+    @classmethod
+    def auto_register(cls, game_engine):
+        """Automatically register this NPC with the game engine."""
+        try:
+            # Create addon instance
+            addon_instance = cls()
+            
+            # Get NPC config
+            npc_config = cls.get_npc_config()
+            
+            # Register NPC in world
+            npc_service = game_engine.get_npc_service()
+            npc_service.register_npc(npc_config['id'], npc_config)
+            
+            # Register addon for command handling
+            if not hasattr(game_engine.get_world(), 'addon_npcs'):
+                game_engine.get_world().addon_npcs = {}
+            game_engine.get_world().addon_npcs[npc_config['id']] = addon_instance
+            
+            print(f"[SimpleTrader] Auto-registered NPC '{npc_config['name']}' at position ({npc_config['x']}, {npc_config['y']})")
+            return True
+            
+        except Exception as e:
+            print(f"[SimpleTrader] Auto-registration failed: {e}")
+            return False
+    
+    # ===== PRIVATE METHODS =====
+    
+    def _handle_buy(self, player_id: str, item_name: str) -> str:
+        """Handle buy command."""
+        # Find item (case-insensitive)
+        item_key = None
+        for key in self.inventory.keys():
+            if key.lower() == item_name.lower():
+                item_key = key
+                break
+        
+        if not item_key:
+            return f"❌ I don't have '{item_name}' in stock. Try 'inventory' to see what's available."
+        
+        item = self.inventory[item_key]
+        
+        if item['stock'] <= 0:
+            return f"❌ Sorry, {item_key} is out of stock!"
+        
+        # Simulate purchase (in real game, you'd check player's gold, etc.)
+        item['stock'] -= 1
+        self.sales_history.append({
+            'player': player_id,
+            'item': item_key,
+            'price': item['price']
+        })
+        
+        return f"✅ **Purchase Successful!**\n\n🛒 **Item:** {item_key}\n💰 **Price:** {item['price']} gold\n📦 **Stock Remaining:** {item['stock']}\n\nThank you for your business!"
+    
+    def _show_inventory(self) -> str:
+        """Show current inventory."""
+        if not self.inventory:
+            return "📦 My shop is currently empty. Come back later!"
+        
+        result = "🛒 **Simple Trader Shop Inventory:**\n\n"
+        for item, info in self.inventory.items():
+            stock_status = "✅ In Stock" if info['stock'] > 0 else "❌ Out of Stock"
+            result += f"**{item}**\n"
+            result += f"💰 Price: {info['price']} gold\n"
+            result += f"📦 Stock: {info['stock']}\n"
+            result += f"📝 {info['description']}\n"
+            result += f"Status: {stock_status}\n\n"
+        
+        result += "💬 Send me 'buy <item name>' to purchase!"
+        return result
+    
+    def _show_help(self) -> str:
+        """Show help information."""
+        return """🛒 **Simple Trader Commands:**
+
+**buy** `<item name>` - Purchase an item
+**inventory** - See all available items
+**help** - Show this help
+
+📋 **Example Commands:**
+• buy Health Potion
+• buy magic scroll
+• inventory
+
+💰 **How to Trade:**
+1. Check my inventory to see items and prices
+2. Send me a buy command with the item name
+3. Complete your purchase!
+
+🏪 I'm here to help you gear up for your adventures!"""
+
+
+# Global instance for easy access
+simple_trader_addon = SimpleTraderAddon()
+
+
+# Auto-registration function that can be called from game engine
+def register_simple_trader(game_engine):
+    """Convenience function to register this addon."""
+    return SimpleTraderAddon.auto_register(game_engine)

src/addons/weather_oracle_addon.py

@@ -0,0 +1,380 @@
+"""
+Weather Oracle Add-on - MCP-powered weather information system.
+"""
+
+import time
+import json
+import random
+import string
+import asyncio
+from typing import Dict, List, Optional
+import gradio as gr
+from abc import ABC, abstractmethod
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from contextlib import AsyncExitStack
+
+from ..interfaces.npc_addon import NPCAddon
+
+
+class IWeatherService(ABC):
+    """Interface for Weather service operations."""
+    
+    @abstractmethod
+    def get_weather(self, location: str) -> str:
+        """Get weather information for a location."""
+        pass
+    
+    @abstractmethod
+    def connect_to_mcp(self) -> str:
+        """Connect to MCP weather server."""
+        pass
+
+
+class WeatherOracleService(IWeatherService, NPCAddon):
+    """Service for managing Weather Oracle MCP integration."""
+    
+    def __init__(self):
+        super().__init__()
+        self.connected = False
+        self.last_connection_attempt = 0
+        self.connection_cooldown = 30  # 30 seconds between connection attempts
+        self.server_url = "https://chris4k-weather.hf.space/gradio_api/mcp/sse"
+        self.session = None
+        self.tools = []
+        self.exit_stack = None
+          # Set up event loop for async operations
+        try:
+            self.loop = asyncio.get_event_loop()
+        except RuntimeError:
+            self.loop = asyncio.new_event_loop()
+    
+    @property
+    def addon_id(self) -> str:
+        """Unique identifier for this add-on"""
+        return "weather_oracle"
+    
+    @property
+    def addon_name(self) -> str:
+        """Display name for this add-on"""
+        return "Weather Oracle (MCP)"
+    
+    @property
+    def npc_config(self) -> Dict:
+        """NPC configuration for auto-placement in world"""
+        return {
+            'id': 'weather_oracle',
+            'name': 'Weather Oracle (MCP)',
+            'x': 150, 'y': 300,
+            'char': '🌤️',
+            'type': 'mcp',
+            'description': 'MCP-powered weather information service'
+        }
+    
+    @property
+    def ui_tab_name(self) -> str:
+        """UI tab name for this addon"""
+        return "Weather Oracle"
+    
+    def get_interface(self) -> gr.Component:
+        """Return Gradio interface for this add-on"""
+        with gr.Column() as interface:
+            gr.Markdown("""
+            ## 🌤️ Weather Oracle (MCP)
+            
+            *I commune with the weather spirits through the mystical MCP protocol to bring you weather wisdom from across the realms!*
+            
+            **Ask me about weather in any city:**
+            - Current conditions and temperature
+            - Real-time weather data from global sources
+            - Powered by Model Context Protocol (MCP)
+            
+            *Format: "City, Country" (e.g., "Berlin, Germany")*
+            """)
+            
+            # Connection status
+            connection_status = gr.HTML(
+                value=f"<div style='color: {'green' if self.connected else 'red'};'>{'🟢 Connected to weather spirits' if self.connected else '🔴 Disconnected from weather realm'}</div>"
+            )
+            
+            with gr.Row():
+                location_input = gr.Textbox(
+                    label="Location",
+                    placeholder="e.g., Berlin, Germany",
+                    scale=3
+                )
+                get_weather_btn = gr.Button("🌡️ Consult Weather Spirits", variant="primary", scale=1)
+            
+            weather_output = gr.Textbox(
+                label="🌤️ Weather Wisdom",
+                lines=8,
+                interactive=False,
+                placeholder="Enter a location and I will consult the weather spirits..."
+            )
+            
+            # Example locations
+            with gr.Row():
+                gr.Examples(
+                    examples=[
+                        ["Berlin, Germany"],
+                        ["Tokyo, Japan"], 
+                        ["New York, USA"],
+                        ["London, UK"],
+                        ["Sydney, Australia"],
+                        ["Paris, France"],
+                        ["Moscow, Russia"]
+                    ],
+                    inputs=[location_input],
+                    label="🌍 Try These Locations"
+                )
+            
+            # Connection controls
+            with gr.Row():
+                connect_btn = gr.Button("🔗 Connect to MCP", variant="secondary")
+                status_btn = gr.Button("📊 Check Status", variant="secondary")
+            
+            def handle_weather_request(location: str):
+                if not location.strip():
+                    return "❓ Please enter a location to get weather information."
+                return self.get_weather(location)
+            
+            def handle_connect():
+                result = self.connect_to_mcp()
+                # Update connection status
+                new_status = f"<div style='color: {'green' if self.connected else 'red'};'>{'🟢 Connected to weather spirits' if self.connected else '🔴 Disconnected from weather realm'}</div>"
+                return result, new_status
+            
+            def handle_status():
+                status = "🟢 Connected" if self.connected else "🔴 Disconnected"
+                return f"🌤️ **Weather Oracle Status**\n\nConnection: {status}\nLast update: {time.strftime('%H:%M')}"
+            
+            # Wire up events
+            get_weather_btn.click(
+                handle_weather_request,
+                inputs=[location_input],
+                outputs=[weather_output]
+            )
+            
+            location_input.submit(
+                handle_weather_request,
+                inputs=[location_input], 
+                outputs=[weather_output]
+            )
+            
+            connect_btn.click(
+                handle_connect,
+                outputs=[weather_output, connection_status]
+            )
+            
+            status_btn.click(
+                handle_status,
+                outputs=[weather_output]
+            )
+        
+        return interface
+    
+    def connect_to_mcp(self) -> str:
+        """Connect to MCP weather server."""
+        current_time = time.time()
+        if current_time - self.last_connection_attempt < self.connection_cooldown:
+            return "⏳ Please wait before retrying connection..."
+        
+        self.last_connection_attempt = current_time
+        
+        try:
+            return self.loop.run_until_complete(self._connect())
+        except Exception as e:
+            self.connected = False
+            return f"❌ Connection failed: {str(e)}"
+    
+    async def _connect(self) -> str:
+        """Async connect to MCP server using SSE."""
+        try:
+            # Clean up previous connection
+            if self.exit_stack:
+                await self.exit_stack.aclose()
+
+            self.exit_stack = AsyncExitStack()
+
+            # Connect to SSE MCP server
+            sse_transport = await self.exit_stack.enter_async_context(
+                sse_client(self.server_url)
+            )
+            read_stream, write_callable = sse_transport
+
+            self.session = await self.exit_stack.enter_async_context(
+                ClientSession(read_stream, write_callable)
+            )
+            await self.session.initialize()
+
+            # Get available tools
+            response = await self.session.list_tools()
+            self.tools = response.tools
+
+            self.connected = True
+            tool_names = [tool.name for tool in self.tools]
+            return f"✅ Connected to weather MCP server!\nAvailable tools: {', '.join(tool_names)}"
+
+        except Exception as e:
+            self.connected = False
+            return f"❌ Connection failed: {str(e)}"
+    
+    def get_weather(self, location: str) -> str:
+        """Get weather for a location using actual MCP server"""
+        if not self.connected:
+            # Try to auto-connect
+            connect_result = self.connect_to_mcp()
+            if not self.connected:
+                return f"❌ Failed to connect to weather server. {connect_result}"
+        
+        if not location.strip():
+            return "❌ Please enter a location (e.g., 'Berlin, Germany')"
+        
+        try:
+            return self.loop.run_until_complete(self._get_weather(location))
+        except Exception as e:
+            return f"❌ Error getting weather: {str(e)}"
+    
+    async def _get_weather(self, location: str) -> str:
+        """Async get weather using MCP."""
+        try:
+            # Parse location
+            if ',' in location:
+                city, country = [part.strip() for part in location.split(',', 1)]
+            else:
+                city = location.strip()
+                country = ""
+
+            # Find the weather tool
+            weather_tool = next((tool for tool in self.tools if 'weather' in tool.name.lower()), None)
+            if not weather_tool:
+                return "❌ Weather tool not found on server"
+
+            # Call the tool
+            params = {"city": city, "country": country}
+            result = await self.session.call_tool(weather_tool.name, params)
+
+            # Extract content properly
+            content_text = ""
+            if hasattr(result, 'content') and result.content:
+                if isinstance(result.content, list):
+                    for content_item in result.content:
+                        if hasattr(content_item, 'text'):
+                            content_text += content_item.text
+                        elif hasattr(content_item, 'content'):
+                            content_text += str(content_item.content)
+                        else:
+                            content_text += str(content_item)
+                elif hasattr(result.content, 'text'):
+                    content_text = result.content.text
+                else:
+                    content_text = str(result.content)
+
+            if not content_text:
+                return "❌ No content received from server"
+
+            try:
+                # Try to parse as JSON
+                parsed = json.loads(content_text)
+                if isinstance(parsed, dict):
+                    if 'error' in parsed:
+                        return f"❌ Error: {parsed['error']}"
+
+                    # Format weather data nicely
+                    if 'current_weather' in parsed:
+                        weather = parsed['current_weather']
+                        formatted = f"🌍 **{parsed.get('location', location)}**\n\n"
+                        formatted += f"🌡️ Temperature: {weather.get('temperature_celsius', 'N/A')}°C\n"
+                        formatted += f"🌤️ Conditions: {weather.get('weather_description', 'N/A')}\n"
+                        formatted += f"💨 Wind: {weather.get('wind_speed_kmh', 'N/A')} km/h\n"
+                        formatted += f"💧 Humidity: {weather.get('humidity_percent', 'N/A')}%\n"
+                        formatted += f"\n⏰ Last updated: {time.strftime('%H:%M')}\n⚡ **Powered by MCP**"
+                        return formatted
+                    elif 'temperature (°C)' in parsed:
+                        # Handle the original format from your server
+                        formatted = f"🌍 **{parsed.get('location', location)}**\n\n"
+                        formatted += f"🌡️ Temperature: {parsed.get('temperature (°C)', 'N/A')}°C\n"
+                        formatted += f"🌤️ Weather Code: {parsed.get('weather_code', 'N/A')}\n"
+                        formatted += f"🕐 Timezone: {parsed.get('timezone', 'N/A')}\n"
+                        formatted += f"🕒 Local Time: {parsed.get('local_time', 'N/A')}\n"
+                        formatted += f"\n⏰ Last updated: {time.strftime('%H:%M')}\n⚡ **Powered by MCP**"
+                        return formatted
+                    else:
+                        return f"🌍 **Weather for {location}**\n\n✅ Weather data:\n```json\n{json.dumps(parsed, indent=2)}\n```\n\n⚡ **Powered by MCP**"
+
+            except json.JSONDecodeError:
+                # If not JSON, return as text
+                return f"🌍 **Weather for {location}**\n\n✅ Weather data:\n```\n{content_text}\n```\n\n⚡ **Powered by MCP**"
+
+            return f"🌍 **Weather for {location}**\n\n✅ Raw result:\n{content_text}\n\n⚡ **Powered by MCP**"
+
+        except Exception as e:
+            return f"❌ Failed to get weather: {str(e)}"
+    
+    def handle_command(self, player_id: str, command: str) -> str:
+        """Handle Weather Oracle commands."""
+        parts = command.strip().split(' ', 1)
+        cmd = parts[0].lower()
+        
+        if cmd == "weather" and len(parts) > 1:
+            return self.get_weather(parts[1])
+        elif cmd == "connect":
+            return self.connect_to_mcp()
+        elif cmd == "status":
+            status = "🟢 Connected" if self.connected else "🔴 Disconnected"
+            return f"🌤️ **Weather Oracle Status**\n\nConnection: {status}\nLast update: {time.strftime('%H:%M')}"
+        elif cmd == "help":
+            return """🌤️ **Weather Oracle Commands:**
+
+**weather** `location` - Get weather (e.g., 'weather Berlin, Germany')
+**connect** - Connect to MCP weather server
+**status** - Check connection status
+**help** - Show this help
+
+🌍 **Example Commands:**
+• weather London, UK
+• weather Tokyo
+• weather New York, USA
+
+⚡ **Powered by MCP (Model Context Protocol)**"""
+        else:
+            return "❓ Invalid command. Try: `weather <location>`, `connect`, `status`, or `help`"
+
+
+# Global Weather Oracle service instance
+weather_oracle_service = WeatherOracleService()
+
+
+def auto_register(game_engine):
+    """Auto-register the Weather Oracle addon with the game engine.
+    
+    This function makes the addon self-contained by handling its own registration.
+    """
+    try:
+        # Create the weather oracle NPC definition
+        weather_oracle_npc = {
+            'id': 'weather_oracle_auto',
+            'name': '🌤️ Weather Oracle (Auto)',
+            'x': 300, 'y': 150,
+            'char': '🌤️',
+            'type': 'mcp',
+            'personality': 'weather_oracle',
+            'description': 'Self-contained MCP-powered weather information service'
+        }
+        
+        # Register the NPC with the NPC service
+        npc_service = game_engine.get_npc_service()
+        npc_service.register_npc('weather_oracle_auto', weather_oracle_npc)
+        
+        # Register the addon for handling private message commands
+        world = game_engine.get_world()
+        if not hasattr(world, 'addon_npcs'):
+            world.addon_npcs = {}
+        world.addon_npcs['weather_oracle_auto'] = weather_oracle_service
+        
+        print("[WeatherOracleAddon] Auto-registered successfully as self-contained addon")
+        return True
+        
+    except Exception as e:
+        print(f"[WeatherOracleAddon] Error during auto-registration: {e}")
+        return False