dbv-mcp-server

# Unreal MCP Web Client > A powerful web-based client for interacting with Unreal Engine 5.8 Model Context Protocol (MCP) servers. ## 📑 Índice / Table of Contents - [Sobre el proyecto / About](#about) - [Requisitos / Requirements](#requirements) - [Instalación / Installation](#installation) - [Cómo ejecutar / How to run](#usage) - [Cómo parar / How to stop](#stop) - [Integración en Unreal / Unreal Integration](#unreal-integration) - [Skill de Python API para Unreal / Unreal Python API Skill](#python-skill) - [Guías Conceptuales de Desarrollo / Conceptual Dev Guides](#dev-guides) - [Estructura del proyecto / Project structure](#structure) - [Changelog](#changelog) - [Licencia / License](#license) --- <a name="about"></a> ## 📌 Sobre el proyecto / About **Unreal MCP Web Client** es un panel de control interactivo de página única (SPA) diseñado para depurar y consumir los servicios del servidor MCP integrado de Unreal Engine 5.8. Permite inspeccionar de forma gráfica los toolsets activos, sus esquemas JSON-RPC de argumentos, realizar llamadas a herramientas en tiempo real y leer las respuestas progresivas a través de Server-Sent Events (SSE). **Tecnologías principales:** - Frontend: HTML5, JavaScript (ES6+ Vanilla), CSS3 (Tema oscuro, Glassmorphism, HSL tokens). - Servidor local de desarrollo: FastAPI, Uvicorn, HTTPX. --- <a name="requirements"></a> ## 🧰 Requisitos / Requirements - **Unreal Engine 5.8** (con el plugin `ModelContextProtocol` activado en el proyecto). - **Python 3.x** (con `fastapi`, `uvicorn` y `httpx` instalados: `pip install fastapi uvicorn httpx`). - **Playwright** (solo necesario para actualizar la base de guías conceptuales — ver [Guías Conceptuales](#dev-guides)): `pip install playwright && playwright install chromium`. - Un navegador web moderno (Chrome, Edge, Firefox, etc.). --- <a name="installation"></a> ## ⚙️ Instalación / Installation El cliente es ligero y se ejecuta en local: 1. Copia los archivos del cliente en un directorio local del equipo. 2. Asegúrate de tener Python instalado y accesible desde la línea de comandos (`python --version`). --- <a name="usage"></a> ## ▶️ Cómo ejecutar / How to run Usa los scripts incluidos en la raíz: **Windows:** ```cmd start.cmd ``` **macOS / Linux:** ```bash chmod +x start.sh ./start.sh ``` El script levantará el servidor HTTP local y abrirá automáticamente tu navegador en: `http://localhost:5000` --- <a name="stop"></a> ## ⏹ Cómo parar / How to stop Para detener el servidor local de desarrollo: **Windows:** ```cmd stop.cmd ``` **macOS / Linux:** ```bash chmod +x stop.sh ./stop.sh ``` --- <a name="unreal-integration"></a> ## 🔧 Integración en otros proyectos Unreal / Unreal Integration Para replicar esta funcionalidad (incluyendo la ejecución ilimitada de scripts Python) en cualquier proyecto de Unreal Engine 5.8, consulta la guía detallada paso a paso: 👉 **[Guía de Integración del Servidor MCP en Unreal Engine 5.8](./docs/UNREAL_MCP_INTEGRATION_GUIDE.md)** Esta guía cubre: 1. Activación de plugins en el `.uproject`. 2. Enlace de dependencias en el `.Build.cs`. 3. Creación de clases customizadas derivadas de `UToolsetDefinition` expuestas con la macro `UFUNCTION(meta = (AICallable))`. 4. Ejecución multi-sentencia de Python usando `EPythonCommandExecutionMode::ExecuteFile`. 5. Configuración y reutilización del puente de entrada/salida estándar (`bridge.py`) para que Claude Desktop descubra y ejecute herramientas personalizadas. --- <a name="python-skill"></a> ## 🐍 Skill de Python API para Unreal / Unreal Python API Skill Este proyecto incluye el skill **`dbv-unreal-python-api`**, que combina **dos herramientas complementarias** para que los agentes de IA (Claude Desktop o Gemini) generen scripts Python correctos para Unreal Engine 5.8 sin alucinaciones: | Herramienta | Propósito | Cuándo se usa | | --- | --- | --- | | `dbv_unreal_dev_guide` | Búsqueda conceptual — guías y recetas de desarrollo en prosa (PCG, Materiales, Blueprints, Gameplay, Animación, UI, Node References...) | **Primero**, para entender el flujo lógico antes de escribir código | | `dbv_python_unreal_api` | Búsqueda sintáctica — firmas exactas de clases, métodos y parámetros de la API Python oficial | **Después**, para verificar la sintaxis exacta antes de llamar a `RunPython` | ### ¿Qué hace y para qué sirve? Sirve para que los agentes de IA consulten y obtengan de forma precisa tanto el **diseño conceptual** (cómo se resuelve un problema en Unreal) como las **clases, métodos y firmas** de la API oficial de Unreal Python 5.8, permitiendo la generación de scripts Python correctos y/o automatizaciones complejas para ejecutarse en Unreal Engine a través del comando `RunPython`. El skill realiza lo siguiente: 1. **Scraping / Crawling Local**: Descarga y limpia la documentación HTML oficial de Unreal Engine 5.8 (más de 11.000 páginas de la Python API, y prácticamente la totalidad de la documentación conceptual — ver [Guías Conceptuales](#dev-guides)) almacenándola de forma local y eliminando elementos redundantes (menús, sidebars, scripts). 2. **Motor de Búsqueda de Dos Capas**: Indexa y divide la información en chunks, exponiendo búsqueda conceptual (`search_guides`) y sintáctica (`search`, con soporte de búsqueda exacta `exact:ClassName`) basadas en texto natural. 3. **Servidor MCP Local**: Expone un endpoint JSON-RPC y una API HTTP para que los agentes inteligentes puedan realizar consultas directas y dinámicas en caliente. ### ¿Cómo utilizarlo? — 2 formas, elige según tu cliente #### 1. Claude Code — Skill de proyecto (recomendado, cero configuración) Ya viene listo en el repo: `.claude/skills/dbv-unreal-python-api/SKILL.md` es lo que Claude Code autodescubre al abrir este proyecto. Al clonar el repo y abrirlo con Claude Code, el skill ya está disponible — no requiere tocar ningún archivo de configuración. Claude ejecuta la CLI de `search_engine.py` bajo demanda vía Bash/code execution (sin servidor ni puerto abierto), leyendo la knowledge base directamente del disco local: ```bash python skills/dbv-unreal-python-api/scripts/search_engine.py search-guides "conectar textura en material instance" python skills/dbv-unreal-python-api/scripts/search_engine.py search "exact:MaterialEditingLibrary" ``` > ⚠️ **La subida manual como Skill a Claude Desktop / claude.ai no es viable aquí.** Esa UI exige > un `.zip` de menos de 30 MB descomprimido, y este bundle (`scripts/` + `knowledge/`) pesa ~118 MB > por sus 17.000 ficheros de referencia. Además, un Skill subido corre en un sandbox sin acceso al > disco local, así que ni siquiera comprimiendo más funcionaría el buscador. Para Desktop/claude.ai, > usa la opción 2. #### 2. Servidor MCP (Claude Desktop, claude.ai, u otros clientes MCP) Necesario para cualquier cliente que no sea Claude Code, ya que lee la knowledge base directamente del disco local sin límite de tamaño de subida. Regístralo en tu `claude_desktop_config.json` ajustando la ruta absoluta a tu clon local. **En Windows**, usa la ruta completa a `python.exe` (Claude Desktop no siempre hereda tu `PATH`) y escapa las barras invertidas **dobladas** (`\\`): ```json { "mcpServers": { "dbv-unreal-python-api": { "command": "C:\\Program Files\\Python312\\python.exe", "args": [ "-u", "C:\\RUTA\\ABSOLUTA\\A\\TU\\CLON\\MCPCLiente\\skills\\dbv-unreal-python-api\\scripts\\mcp_server.py" ] } } } ``` > Ejemplo para macOS/Linux (barras normales, sin escapar) y detalle completo de ambas vías en > [SKILL.md](./skills/dbv-unreal-python-api/SKILL.md). #### 3. Consumo por API HTTP (cliente web propio de este repo) El servidor local FastAPI (`server.py`) expone endpoints de consulta rápida en los puertos habituales: * **Búsqueda de API**: `GET http://localhost:5000/api/docs/search?q=tu_busqueda` * **Estado de la API**: `GET http://localhost:5000/api/docs/status` * **Búsqueda de guías**: `GET http://localhost:5000/api/guides/search?q=tu_busqueda` * **Estado de las guías**: `GET http://localhost:5000/api/guides/status` #### 5. Actualizar o Re-escanear la API de clases Para descargar y actualizar la base de datos local de la API de Unreal (ej. para Unreal 5.8 o nuevas versiones): * **Scrapear la API oficial (5.8)**: ```bash python skills/dbv-unreal-python-api/scripts/scrape_ue_api.py ``` * **Actualizar para una nueva versión (ej: 5.9)**: ```bash python skills/dbv-unreal-python-api/scripts/update_api.py --version 5.9 ``` --- <a name="dev-guides"></a> ## 📚 Guías Conceptuales de Desarrollo / Conceptual Dev Guides Además de la referencia sintáctica de la API, el skill incluye una base de conocimiento conceptual con **prácticamente toda la documentación oficial de Unreal Engine 5.8** (no solo PCG/Materiales/Blueprints): Gameplay Systems, Animación, Audio, UI (UMG/Slate), Niagara, C++, Mobile, y las fichas de referencia de nodos de Blueprint/Control Rig/Dataflow (`node-reference`). ### ¿Cómo se descarga? — Bypass de Cloudflare El portal de documentación de Epic (`dev.epicgames.com`) es una SPA de Angular protegida por Cloudflare Bot Management: las peticiones HTTP tradicionales (`urllib`, `curl`) reciben `403 Forbidden` por carecer de huella TLS/JS de navegador real. El crawler (`scrape_ue_guides.py`) resuelve esto con **Playwright** (Chromium real), abriendo un **contexto de navegador nuevo por cada página** — Cloudflare degrada la confianza de una sesión tras su primera petición, así que reutilizar el contexto entre páginas produce 403 a partir de la segunda. El descubrimiento de páginas usa el endpoint `table_of_content.json`, que expone el árbol completo de la documentación (miles de páginas) en una sola llamada, en vez de listas de URLs fijas. ### Comandos principales ```bash # Descargar/actualizar TODA la documentación conceptual (recomendado) python skills/dbv-unreal-python-api/scripts/scrape_ue_guides.py --category full --resume # Descargar solo una categoría concreta (atajos disponibles: pcg, materials, blueprints, editor) python skills/dbv-unreal-python-api/scripts/scrape_ue_guides.py --category blueprints # Apuntar a un subárbol literal del árbol de documentación (útil para paralelizar) python skills/dbv-unreal-python-api/scripts/scrape_ue_guides.py --category "node-reference/ControlRig" # Ver el estado actual del índice python skills/dbv-unreal-python-api/scripts/scrape_ue_guides.py --status ``` **Paralelización**: cada ejecución de `--category <x>` escribe en shards propios (`index_guides__<x>.json`) para poder lanzar varios procesos a la vez sin condiciones de carrera. Al terminar, combina todos los shards con: ```bash python skills/dbv-unreal-python-api/scripts/scrape_ue_guides.py --merge ``` > ⚠️ No lances más de ~5-6 procesos en paralelo — Cloudflare degrada el rate-limit de forma sostenida con más concurrencia, no solo al arrancar. Las páginas con error quedan registradas en `.errors_guides__<categoria>.json` (no se marcan como completadas), por lo que un `--resume` posterior las reintenta automáticamente. --- <a name="structure"></a> ## 📂 Estructura del proyecto / Project structure ```text / ├── docs/ # Documentación del proyecto │ ├── UNREAL_MCP_INTEGRATION_GUIDE.md # Guía paso a paso para integrar MCP en otros proyectos │ └── templates/ # Ficheros .h/.cpp del toolset de ejemplo, listos para copiar a Source/ ├── skills/ # Habilidades y base de conocimiento local para agentes de IA │ └── dbv-unreal-python-api/ # Motor de búsqueda y referencia de la API + guías conceptuales de Unreal │ ├── knowledge/classes/ # Clases de la API Python (scrape_ue_api.py) │ ├── knowledge/guides/ # Guías conceptuales de toda la documentación de UE 5.8 (scrape_ue_guides.py) │ └── scripts/ # Crawlers, motor de búsqueda y servidor MCP ├── .well-known/ # Tarjetas declarativas para agentes de IA (robots.txt, api-catalog, etc.) ├── src/ │ ├── css/ │ │ └── style.css # Estilos y diseño visual (dark mode neón, Safari filters) │ └── js/ │ └── app.js # Lógica del cliente, conexión, markdown y decodificador de streams ├── index.html # Estructura del cliente web ├── auth.md # Instrucciones de acceso para bots y agentes ├── start.cmd / .sh # Scripts de inicio ├── stop.cmd / .sh # Scripts de parada ├── project.config.md # Configuración del framework ├── CHANGELOG.md # Historial de cambios └── README.md # Esta guía ``` --- <a name="changelog"></a> ## 📋 Changelog Consulta el historial completo de cambios y versiones en el archivo [CHANGELOG.md](./CHANGELOG.md). --- <a name="license"></a> ## 📄 Licencia / License MIT — consulta el archivo [LICENSE](./LICENSE) para ver los detalles. Copyright (c) 2026 David Bueno Vallejo · https://github.com/davidbuenov --- > 🛠️ Generado con **[dbv-specs-ops](https://github.com/davidbuenov/dbv-specs-ops)**.