🛠️ MMORPG with MCP Integration - Developer Documentation

📖 Table of Contents

Introduction
Project Setup
Architecture Overview
MCP API Reference
Extending the Game
- NPC Add-on Development
- Adding New Game Mechanics
AI Agent Integration
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

Navigate to the project directory (e.g., c:\Users\Chris4K\Projekte\projecthub\projects\MMOP_second_try).
```
cd c:\Users\Chris4K\Projekte\projecthub\projects\MMOP_second_try
```
Install the required Python dependencies:
```
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):

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):

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:

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.
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.
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.
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).

Connection: The agent connects to the MCP SSE endpoint.
Registration: The agent registers itself, providing a name.
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).
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.