Actualizar README.md con secciones de demostración y arquitectura, y mejorar la interfaz de usuario en app.py para manejar bloques HTML. También se corrigen comentarios y traducciones en obr.py y test.py.

README.md

@@ -12,4 +12,184 @@ tags:
   - mcp-server-track
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🧙‍♂️ LLM Game Master MCP Server 🐉
+
+## 🎥 Video Demo
+
+```html
+<iframe width="560" height="315" src="https://www.youtube.com/embed/SlbW-kjekBg?si=r6x8GeVnKLipriZL" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+```
+
+Video Demo: [https://www.youtube.com/watch?v=SlbW-kjekBg&ab_channel=AlejandroGarcíaAmador](https://www.youtube.com/watch?v=SlbW-kjekBg&ab_channel=AlejandroGarcíaAmador)
+
+## 🧩 Complete Architecture Overview
+![Architecture Overview](https://huggingface.co/spaces/Agents-MCP-Hackathon/LLM-GameMaster-Agent/resolve/main/media/architecture.png)
+
+## 🔗 Useful Links:
+- [Owlbear Rodeo Chat Interface](https://github.com/Agamador/OwlBear-llm-chat)
+- [MCP server](https://huggingface.co/spaces/Agents-MCP-Hackathon/LLM-GameMaster-MPC-Server)
+- [Video Demo](https://www.youtube.com/watch?v=SlbW-kjekBg&ab_channel=AlejandroGarcíaAmador)
+
+## 🌟 Introduction
+
+The **OwlBear Rodeo MCP Server** is a revolutionary Model Context Protocol (MCP) server implementation that bridges the gap between AI agents and tabletop gaming experiences. This sophisticated system transforms the popular OwlBear Rodeo virtual tabletop platform into a fully programmable environment, enabling AI Game Masters to create, manipulate, and orchestrate dynamic D&D sessions with unprecedented precision and creativity.
+
+Built using Gradio's cutting-edge MCP server capabilities, this application showcases the power of combining modern AI infrastructure with traditional gaming platforms. The server exposes a comprehensive suite of tools that allow AI agents to interact with virtual tabletops in real-time, creating immersive gaming experiences that adapt dynamically to player actions and narrative requirements.
+
+Unlike static gaming interfaces, this MCP server provides AI agents with the ability to programmatically control every aspect of the virtual tabletop experience, from token placement and movement to map management and atmospheric effects like fog of war and lighting systems.
+
+## 🎯 Core Functionality
+
+### 🗺️ Dynamic Map Management
+The server provides powerful map manipulation capabilities that allow AI agents to create diverse gaming environments on demand. Through the integrated map system, agents can instantly deploy various pre-configured environments including mystical forests with winding paths, quaint villages with detailed buildings, isolated cabin settings, and epic battle arenas designed for climactic encounters.
+
+The map insertion system works seamlessly with OwlBear Rodeo's rendering engine, ensuring that each environment is properly scaled and optimized for tactical gameplay. Maps can be swapped dynamically during sessions, allowing for seamless transitions between different scenes and locations as the narrative unfolds.
+
+### 🎭 Intelligent Token System
+The token creation and management system represents one of the most sophisticated aspects of the MCP server. AI agents can spawn a diverse array of characters and objects, from heroic knights and mystical archers to fearsome dragons and cunning goblins. Each token type corresponds to carefully selected visual assets that enhance the immersive experience.
+
+The system supports dynamic token properties including customizable sizes, precise positioning using grid-based coordinates, and intelligent naming conventions that help track multiple entities throughout complex encounters. Tokens can be moved programmatically, allowing AI Game Masters to orchestrate tactical movements, dramatic reveals, and coordinated battle sequences.
+
+### 🌫️ Advanced Fog of War
+The fog of war implementation provides AI agents with sophisticated tools for controlling information flow and creating suspenseful gaming moments. The system can instantly fill entire maps with fog, creating mysterious environments where only illuminated areas remain visible to players.
+
+The clear fog functionality allows for dramatic reveals, while the selective fog management enables AI Game Masters to control exactly what players can see at any given moment. This creates opportunities for strategic gameplay and narrative tension that rivals traditional tabletop experiences.
+
+### 💡 Dynamic Lighting System
+The lighting system adds another layer of tactical depth and atmospheric immersion to gaming sessions. AI agents can attach light sources to any token, creating realistic illumination effects that interact with the fog of war system. Torches, magical auras, and character-based light sources can be programmatically managed to enhance both gameplay mechanics and visual storytelling.
+
+Light sources move automatically with their attached tokens, ensuring that the lighting environment remains consistent as characters navigate through the virtual space. This feature is particularly powerful for creating tension in dungeon exploration scenarios or highlighting important story elements.
+
+### 🔧 Utility Tools Integration
+Beyond the OwlBear Rodeo specific features, the MCP server includes a comprehensive suite of utility tools that enhance AI agent capabilities. These include mathematical functions for dice rolling simulations, coin flip mechanics for random decision making, prime factorization for complex calculations, and text analysis tools for processing player input.
+
+These utility functions demonstrate the extensibility of the MCP architecture, showing how specialized gaming tools can be combined with general-purpose utilities to create a comprehensive AI assistant platform.
+
+## 🛠️ MCP Tools Reference
+
+This section provides the complete technical reference for all tools available through the Model Context Protocol server. Each tool is documented with its exact function name, required parameters, and expected behavior to facilitate seamless integration with MCP clients.
+
+### 🎲 General Utility Tools
+
+The server includes essential utility tools that provide mathematical and randomization capabilities commonly needed in gaming scenarios. These tools demonstrate the extensibility of the MCP architecture and can be used independently or in conjunction with the OwlBear Rodeo specific functionality.
+
+**letter_counter**
+- Parameters: `word` (string), `letter` (string)
+- Description: Counts occurrences of a specific letter within any text string
+- Use case: Text analysis and word games integration
+
+**prime_factors**
+- Parameters: `n` (integer, must be > 1)
+- Description: Computes the complete prime factorization of any positive integer
+- Use case: Mathematical puzzles and complex calculations
+
+**roll_dice**
+- Parameters: `faces` (integer), `rolls` (integer)
+- Description: Simulates dice rolling with customizable faces and number of rolls
+- Use case: Random number generation for game mechanics
+
+**coin_flip**
+- Parameters: `flips` (integer)
+- Description: Simulates multiple coin flips returning "Heads" or "Tails" results
+- Use case: Binary random decisions and probability demonstrations
+
+### 🗺️ OwlBear Rodeo Map Management
+
+The map management system provides comprehensive control over virtual tabletop environments, enabling dynamic scene transitions and environmental storytelling through programmatic map manipulation.
+
+**insert_map**
+- Parameters: `tab_id` (string), `map_type` (string)
+- Description: Inserts pre-configured map environments into the gaming session
+- Available map types: `FOREST`, `VILLAGE`, `LONELY_CABIN`, `BATTLE_ARENA`, `CABIN`
+- Use case: Setting scenes and creating immersive environments
+
+**clean_map**
+- Parameters: `tab_id` (string)
+- Description: Removes all tokens, shapes, and objects from the current map
+- Use case: Resetting the playing field for new encounters
+
+### 🎭 Token and Character Management
+
+The token system provides sophisticated character and object management capabilities, allowing AI Game Masters to populate virtual spaces with interactive entities that enhance storytelling and tactical gameplay.
+
+**create_token**
+- Parameters: `name` (string), `type` (string), `x` (integer), `y` (integer), `size` (integer), `tab_id` (string)
+- Description: Creates character or item tokens with specified visual assets
+- Available token types: `BOOK`, `CHEST`, `SWORD`, `TORCH`, `ARCHER`, `HUMAN`, `WOMAN`, `CHILD`, `ORC`, `KNIGHT`, `DRAGON`, `GOBLIN`, `GOLEM`
+- Use case: Populating scenes with characters, items, and interactive objects
+
+**move_item**
+- Parameters: `tab_id` (string), `item_id` (string), `x` (integer), `y` (integer)
+- Description: Moves any existing token or shape to new grid coordinates
+- Use case: Orchestrating movement during combat or narrative sequences
+
+**delete_item**
+- Parameters: `tab_id` (string), `item_id` (string)
+- Description: Permanently removes a specific token or shape from the map
+- Use case: Cleaning up defeated enemies or consumed items
+
+### 🎨 Shape and Visual Elements
+
+The shape creation system enables the addition of geometric elements that can serve as terrain features, area markers, or visual indicators to enhance tactical understanding and environmental storytelling.
+
+**create_shape**
+- Parameters: `width` (integer), `height` (integer), `x` (integer), `y` (integer), `shape_type` (string), `fill_color` (hex string), `stroke_color` (hex string), `tab_id` (string)
+- Description: Creates geometric shapes with customizable appearance and positioning
+- Available shape types: `RECTANGLE`, `CIRCLE`, `TRIANGLE`, `HEXAGON`
+- Use case: Creating terrain features, spell areas, or visual markers
+
+### 🌫️ Fog of War and Visibility Control
+
+The fog of war system provides sophisticated visibility management tools that enable AI Game Masters to control information flow and create suspenseful moments through strategic revelation of map areas.
+
+**fill_fog**
+- Parameters: `tab_id` (string)
+- Description: Covers the entire map with fog of war, hiding all areas from player view
+- Use case: Creating mystery and controlling information revelation
+
+**clear_fog**
+- Parameters: `tab_id` (string)
+- Description: Removes all fog of war from the map, revealing the complete environment
+- Use case: Dramatic reveals and full area illumination
+
+### 💡 Lighting and Atmosphere
+
+The lighting system adds tactical depth and atmospheric immersion by providing programmable light sources that interact dynamically with the fog of war system to create realistic illumination effects.
+
+**add_token_light**
+- Parameters: `tab_id` (string), `item_id` (string), `light_radius` (integer)
+- Description: Attaches a light source to any token with specified illumination radius
+- Use case: Creating torch effects, magical auras, or character-based lighting
+
+### 🎥 Camera and Viewport Control
+
+The viewport management system enables cinematic control over player perspective, allowing AI Game Masters to direct attention and create dramatic focus during key narrative moments.
+
+**animate_token_viewport**
+- Parameters: `tab_id` (string), `item_id` (string)
+- Description: Smoothly animates the camera to focus on a specific token
+- Use case: Directing player attention during important events
+
+### 📊 State Management
+
+The state management tool provides essential functionality for monitoring and retrieving the current status of all elements within the virtual tabletop environment.
+
+**game_state**
+- Parameters: `tab_id` (string)
+- Description: Returns complete current state including all tokens, shapes, and map information
+- Use case: Monitoring session status and making informed decisions
+
+### 🔧 Testing and Demonstration
+
+**test_function**
+- Parameters: `tab_id` (string)
+- Description: Executes a comprehensive demonstration of all OwlBear Rodeo functionality
+- Use case: System validation and feature showcase
+
+All tools require a `tab_id` parameter that identifies the specific OwlBear Rodeo session. Coordinates are specified in grid cells, with the origin (0,0) typically located at the top-left corner of the map. Colors must be specified in hexadecimal format (e.g., "#FF0000" for red).
+
+## 🔗 Links & Resources
+- [Model Context Protocol (MCP)](https://github.com/microsoft/model-context-protocol) - The foundational protocol enabling AI agent tool integration
+- [Gradio Documentation](https://www.gradio.app/) - The web framework powering the user interface and MCP server implementation
+- [OwlBear Rodeo](https://www.owlbear.rodeo/) - The virtual tabletop platform integrated through this MCP server
+- [MCP Server Documentation](https://modelcontextprotocol.io/docs/) - Comprehensive guides for MCP server development and deployment

app.py

@@ -21,20 +21,43 @@ from tools.obr import (
 from tools.test import test_function
 from dotenv import load_dotenv
 import os
+import re
 
 load_dotenv()
 
+with open("README.md", "r", encoding="utf-8") as f:
+    readme = f.read()
+    if readme.startswith("---"):
+        parts = readme.split("---", 2)
+        if len(parts) >= 3:
+            readme = parts[2]
+
+html_blocks = re.findall(r'```html\n(.*?)\n```', readme, re.DOTALL)
+for i, html_block in enumerate(html_blocks):
+    readme = readme.replace(f"```html\n{html_block}\n```", f"{{HTML_BLOCK_{i}}}")
+
+with gr.Blocks() as intro_demo:
+    parts = re.split(r'({HTML_BLOCK_\d+})', readme)
+    
+    for part in parts:
+        if part.startswith("{HTML_BLOCK_"):
+            block_idx = int(part.replace("{HTML_BLOCK_", "").replace("}", ""))
+            gr.HTML(html_blocks[block_idx])
+        else:
+            if part.strip():
+                gr.Markdown(part)
+
 # === GRADIO INTERFACE ===
 demo = gr.TabbedInterface(
-    [        # Pestaña de pruebas (sin api_name)
-        gr.Interface(
+    [   
+        intro_demo,        gr.Interface(
             test_function,
             [
                 gr.Textbox(label="Tab ID"),
             ],
-            gr.JSON(label="Resultados de la prueba"),
-            title="Ventana de Pruebas de OBR",
-            description="Esta ventana demuestra todas las funcionalidades de OwlBear Rodeo disponibles.",
+            gr.JSON(label="Test Results"),
+            title="OBR Test Window",
+            description="This window demonstrates all available OwlBear Rodeo functionalities.",
             api_name=False
         ),
         gr.Interface(letter_counter, [gr.Textbox(), gr.Textbox()], gr.Textbox(), api_name="letter_counter"),
@@ -148,9 +171,9 @@ demo = gr.TabbedInterface(
             gr.JSON(),
             api_name="clean_map"
         )
-    ],
-    [
-        "🧪 Pruebas",
+    ],    [
+        "🧙‍♂️ Introduction",
+        "🧪 Tests",
         "Letter Counter",
         "Prime Factors",
         "Roll Dice",

tools/obr.py

@@ -2,7 +2,7 @@ import requests as request
 import os 
 import urllib3
 
-# Suprimir advertencias sobre conexiones SSL inseguras
+# Suppress warnings about insecure SSL connections
 urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
 
 ASSETS_NAMES = {
@@ -227,10 +227,10 @@ def animate_token_viewport(tab_id:str, item_id:str) -> dict:
     
     return execute_action(tab_id=tab_id, action="animateViewport", params=params)
 
-def insert_map(tab_id:str, map_type:str) -> dict:
+def insert_map(tab_id:str, map_type:str) -> dict:    
     """
     Insert a map into the game.
-    The avaulablr maps are:
+    The available maps are:
         - FOREST: A forest with multiple paths and trees.
         - VILLAGE: A small village with 3 houses and a well in the middle.  
         - LONELY_CABIN: A lonely cabin in the middle of a plain.

tools/test.py

@@ -13,25 +13,25 @@ from tools.obr import (
 )
 import time
 
-# === FUNCIÓN DE PRUEBA ===
+# === TEST FUNCTION ===
 def test_function(tab_id):
-    """Función de prueba que demuestra todas las funcionalidades de OBR"""
+    """Test function that demonstrates all OBR functionalities"""
     results = []
     
     try:
-        # 1. Limpiar el mapa
-        results.append({"step": "1. Limpiando mapa", "result": clean_map(tab_id)})
+        # 1. Clean the map
+        results.append({"step": "1. Cleaning map", "result": clean_map(tab_id)})
         time.sleep(1)
         
-        # 2. Limpiar niebla
-        results.append({"step": "2. Limpiando niebla", "result": clear_fog(tab_id)})
+        # 2. Clear fog
+        results.append({"step": "2. Clearing fog", "result": clear_fog(tab_id)})
         time.sleep(1)
 
-        # 3. Insertar mapa
-        results.append({"step": "3. Insertando mapa", "result": insert_map(tab_id, "FOREST")})
+        # 3. Insert map
+        results.append({"step": "3. Inserting map", "result": insert_map(tab_id, "FOREST")})
         time.sleep(1)
 
-        # 4. Crear formas geométricas (círculos rojos en diagonal)
+        # 4. Create geometric shapes (red circles in diagonal)
         for i in range(0, 30, 6):
             shape_result = create_shape(
                 width=2, 
@@ -43,10 +43,10 @@ def test_function(tab_id):
                 stroke_color="#FF0000", 
                 tab_id=tab_id
             )
-            results.append({"step": f"4. Creando círculo en ({i},{i})", "result": shape_result})
+            results.append({"step": f"4. Creating circle at ({i},{i})", "result": shape_result})
             time.sleep(0.5)
 
-        # 5. Crear token principal (Knight)
+        # 5. Create main token (Knight)
         knight_result = create_token(
             name="Knight",
             type="KNIGHT",
@@ -55,21 +55,20 @@ def test_function(tab_id):
             size=1,
             tab_id=tab_id
         )
-        knight_id = [i for i in knight_result['result']["gameState"]['images'] if i["name"] == "Knight"][0]["id"]
-        
-        results.append({"step": "5. Creando Knight", "result": knight_result, "token_id": knight_id})
+        knight_id = [i for i in knight_result['result']["gameState"]['images'] if i["name"] == "Knight"][0]["id"]        
+        results.append({"step": "5. Creating Knight", "result": knight_result, "token_id": knight_id})
         time.sleep(1)
 
-        # 6. Mover el knight a posición intermedia
+        # 6. Move the knight to intermediate position
         if knight_id:
-            results.append({"step": "6. Moviendo Knight a (14,14)", "result": move_item(tab_id, knight_id, 14, 14)})
+            results.append({"step": "6. Moving Knight to (14,14)", "result": move_item(tab_id, knight_id, 14, 14)})
             time.sleep(1)
 
-            # 7. Mover el knight a posición final
-            results.append({"step": "7. Moviendo Knight a (29,29)", "result": move_item(tab_id, knight_id, 29, 29)})
+            # 7. Move the knight to final position
+            results.append({"step": "7. Moving Knight to (29,29)", "result": move_item(tab_id, knight_id, 29, 29)})
             time.sleep(1)
 
-        # 8. Crear token dragón
+        # 8. Create dragon token
         dragon_result = create_token(
             name="Red Dragon",
             type="DRAGON",
@@ -79,43 +78,41 @@ def test_function(tab_id):
             tab_id=tab_id
         )
         dragon_id = [i for i in dragon_result['result']["gameState"]['images'] if i["name"] == "Red Dragon"][0]["id"]   
-        results.append({"step": "8. Creando Red Dragon", "result": dragon_result, "token_id": dragon_id})
+        results.append({"step": "8. Creating Red Dragon", "result": dragon_result, "token_id": dragon_id})
         time.sleep(1)
 
-        # 9. Animar viewport al dragón
+        # 9. Animate viewport to dragon
         if dragon_id:
-            results.append({"step": "9. Animando viewport al dragón", "result": animate_token_viewport(tab_id, dragon_id)})
+            results.append({"step": "9. Animating viewport to dragon", "result": animate_token_viewport(tab_id, dragon_id)})
             time.sleep(1)
 
-        # 10. Llenar con niebla
-        results.append({"step": "10. Llenando con niebla", "result": fill_fog(tab_id)})
-        time.sleep(1)
-
-        # 11. Añadir luz al knight
+        # 10. Fill with fog
+        results.append({"step": "10. Filling with fog", "result": fill_fog(tab_id)})
+        time.sleep(1)        # 11. Add light to knight
         if knight_id:
-            results.append({"step": "11. Añadiendo luz al Knight", "result": add_token_light(tab_id, knight_id, 5)})
+            results.append({"step": "11. Adding light to Knight", "result": add_token_light(tab_id, knight_id, 5)})
             time.sleep(1)
 
-            # 12. Mover knight de vuelta al centro
-            results.append({"step": "12. Moviendo Knight de vuelta a (14,14)", "result": move_item(tab_id, knight_id, 14, 14)})
+            # 12. Move knight back to center
+            results.append({"step": "12. Moving Knight back to (14,14)", "result": move_item(tab_id, knight_id, 14, 14)})
             time.sleep(1)
 
-            # 13. Animar viewport al knight
-            results.append({"step": "13. Animando viewport al Knight", "result": animate_token_viewport(tab_id, knight_id)})
+            # 13. Animate viewport to knight
+            results.append({"step": "13. Animating viewport to Knight", "result": animate_token_viewport(tab_id, knight_id)})
             time.sleep(1)
 
-        # 14. Obtener estado final del juego
+        # 14. Get final game state
         final_state = game_state(tab_id)
-        results.append({"step": "14. Estado final del juego", "result": final_state})
+        results.append({"step": "14. Final game state", "result": final_state})
         time.sleep(5)
 
-        #15. Limpiar mapa al final
-        results.append({"step": "15. Limpiando mapa", "result": clean_map(tab_id)})
+        #15. Clean map at the end
+        results.append({"step": "15. Cleaning map", "result": clean_map(tab_id)})
 
         
         return {
             "success": True,
-            "message": "Prueba completada exitosamente",
+            "message": "Test completed successfully",
             "total_steps": len(results),
             "results": results
         }