---

"La técnica es una actividad compositora o destructora, violenta, y esto es lo que Aristóteles llamaba la poiesis, la poesía, precisamente." — Gustavo Bueno

---

⚡ Heren Godot MCP v4.3

🔥 Heren Godot MCP — Plus Ultra: ir más allá. 🌍

Servidor MCP de alto rendimiento para Godot Engine 4.x que permite a IAs y asistentes controlar el editor real directamente: crear escenas, manipular nodos, gestionar recursos, conectar señales, animar, esqueletos, shaders y validar código. Todo contra el editor vivo, con Undo/Redo real.

📢 v4.3: MCP 100% Rust (7 MB, sin runtime), construido sobre FlojoMCP — el framework MCP en Rust de alto rendimiento. Conexión directa al Editor Godot mediante un plugin (EditorPlugin) con auto-reconexión y auto-lanzamiento del editor. v4.3: setting con op get/set/list/delete/set_multi + restart-aware, input_map con persistencia real a project.godot (multi-bind, joypad motion), session/reopen, instanciación de escenas como nodos hijos, y plugin que se re-sincroniza SIEMPRE al abrir sesión.

---

🚀 Características

Característica	Descripción
⚡ Server en Rust (FlojoMCP)	heren-server.exe de ~7 MB, sin Python ni Node.js. Arranque instantáneo, schemas en compile-time
🎯 Editor real, no daemon	Se conecta al EditorPlugin dentro del Godot abierto — Undo/Redo, viewports 2D/3D reales, EditorFileSystem
🔄 Auto-launch del editor	session/open lanza Godot, instala el plugin, habilita [editor_plugins] y espera la conexión WS. Reutiliza el editor abierto; relanza limpio si hay uno zombie
🛠️ 15 tools centralizadas	Escenas, nodos, recursos, scripts, señales, animaciones, esqueletos, shaders, tilemaps, validación y debug
👀 Sistema de visión	Jerarquía de costo: coordenadas textuales → resumen/ASCII → captura de los viewports 2D/3D reales del editor, con presupuesto de tokens
↩️ Undo/Redo integrado	Cada mutación pasa por EditorUndoRedoManager — Ctrl+Z deshace lo que la IA creó
⚡ orchestrate	Ejecuta múltiples operaciones en una sola llamada, con plan en archivo para planes complejos
🏗️ Crea proyectos desde cero	project/create genera project.godot + escena main sin necesitar editor

---

🆚 Frente a otros MCPs de Godot

Comparamos contra los MCPs de Godot más usados, con datos verificados de sus repos (.competitors/).

Capacidad	Coding-Solo (godot-mcp)	GoPeak	Heren v4
Runtime	Node.js	Node.js	Rust (7 MB, sin runtime)
Modo de operación	Lanza Godot CLI por operación (execFileAsync)	Bridge HTTP/WS + addons	EditorPlugin vivo conectado por WS
Undo/Redo real	❌ (CLI desde cero)	❌	✅ EditorUndoRedoManager
Señales (connect/list)	❌	❌ (GAP documentado)	✅ signal
Animación	❌	❌ (SIGNIFICANT GAP: no AnimationPlayer/Tree)	✅ 30+ actions: playback, tracks, state machine, tween, one_shot, record, IK
Esqueletos 2D/3D	❌	❌ (solo roadmap)	✅ pose, rest, skin, attachment, IK 2D FABRIK, IK 3D
Shaders	❌	❌ (solo roadmap en su análisis)	✅ create/edit/validate real/material/apply one-shot
Tilemap	❌	❌ (SIGNIFICANT GAP)	✅ set_cell/terrain/pattern
Visión	❌	screenshots runtime	✅ jerarquía de costo: coords → ASCII → viewports 2D/3D reales + presupuesto
Batch	❌	❌	✅ orchestrate con plan en archivo
Config proyecto	setting básico	parcial	✅ setting op (get/set/list/delete/set_multi) + input_map persistente real + autoload
Crear proyecto desde 0	❌	❌	✅ project/create sin editor

Por qué Heren gana donde gana:

• Undo/Redo real: toda mutación pasa por EditorUndoRedoManager — el Ctrl+Z del usuario deshace lo que la IA creó. Coding-Solo reescribe archivos desde CLI (sin deshacer); GoPeak no lo expone.
• Editor real, no archivos: el plugin vive dentro del editor que el usuario ve (viewports, EditorFileSystem, play con breakpoints). GoPeak también usa bridge con addons, pero sus GAPS en animación/señales/tilemap son nuestros dominios.
• Profundidad por dominio: 15 tools centralizadas con ~60+ acciones frente a decenas de tools de 1 función. Una llamada animation/one_shot crea animación completa; en GoPeak sería imposible (no hay animación).
• Sistema de visión con costo: no solo capturas — jerarquía de costo (coords textuales ~20 tok → ASCII → imagen) con presupuesto de tokens, para no quemar contexto.
• Sin runtime externo: Rust nativo. Node.js (ambos competidores) exige npm install + versión de Node.

⚠️ La comparativa anterior marcaba ❌/⚡ sin verificar. Esta tabla usa datos reales de los repositorios (.competitors/). GoPeak es un proyecto sólido en debug/run/LSP/DAP; Coding-Solo es sólido en ejecución de proyectos y captura de output. Donde no competimos es donde ellos destacan; donde competimos, aportamos editor real + undo + dominios profundos.

---

📦 Instalación

Requisitos

• 🦀 Rust (para compilar) — o descarga el .exe precompilado
• ⚙️ Godot >= 4.2 (recomendado 4.6+)
• 💻 Windows / Linux / macOS

Desde fuente

git clone https://github.com/CerebroCanibalus/heren-mcp.git
cd heren-mcp

# Opcion A: instalador automatico (compila + registra MCP + verifica)
python install_mcp.py

# Opcion B: manual
cargo build --release
# → target/release/heren-server.exe

install_mcp.py compila el server, registra el MCP heren en tu opencode.jsonc (detecta rutas) y verifica el arranque. Ver docs/INSTALL.md.

Configuración MCP (OpenCode, Claude Desktop, Cursor, etc.)

{
  "mcpServers": {
    "heren": {
      "command": "path/to/heren-server.exe",
      "environment": {
        "GODOT_EXE": "D:/Mis Juegos/Godot/Godot_v4.6.1-stable_win64.exe"
      }
    }
  }
}

El server habla NDJSON por stdio (el framing estándar de MCP). El editor se lanza solo en session/open.

Variables de entorno

Variable	Descripción
GODOT_EXE	Ruta al ejecutable de Godot
GODOT_PATH	Alias de GODOT_EXE
HEREN_PLUGIN_SOURCE	Ruta al plugin fuente (por defecto addons/heren/)
HEREN_LOG_FILE	Archivo de log (opcional; el server jamás inunda stderr)

---

🚀 Uso Rápido

# Abrir sesión: lanza el editor (si no está), instala el plugin y conecta
session(action="open", project_path="D:/MiJuego")
# → {"launched": true, "message": "launched", "ok": true}

# Crear escena
scene(action="create", project_path="D:/MiJuego", scene_path="res://Player.tscn")

# Añadir nodo (con Undo/Redo)
node(
    action="add",
    project_path="D:/MiJuego",
    parent_path=".",
    node_type="CharacterBody2D",
    node_name="Player"
)

# Guardar
scene(action="save", project_path="D:/MiJuego")

⚠️ En OpenCode las tools aparecen con prefijo godot_ (ej. godot_session, godot_node, godot_scene).

🔹 Batch con orchestrate

# Multiples operaciones en una sola llamada
orchestrate(
    project_path="D:/MiJuego",
    plan={"ops": [
        {"tool": "node", "args": {"action": "add", "node_type": "Sprite2D", "node_name": "Body"}},
        {"tool": "node", "args": {"action": "add", "node_type": "CollisionShape2D", "node_name": "Hitbox"}},
        {"tool": "scene", "args": {"action": "save"}}
    ]},
    on_error="stop"
)

---

🛠️ Las 15 Tools (60+ Acciones)

Tool	Acciones	¿Qué hace?
session	open, reopen, close, list, info, health	Sesiones; abre/relanza limpio (tras settings restart_required)/cierra el editor
scene	get_open_scenes, get_edited_scene_root, open, save, create, unload	Escenas contra el editor real (SceneRegistry evita escenas fantasma)
node	add, instantiate, remove, set_prop, get_prop, get_info, get_children, find, duplicate, rename, move, set_owner, reorder, array_append, array_remove	CRUD de nodos + instanciar .tscn como hijo (ExtResource, no copia)
resource	create, read, update, delete, list, create_script, read_script, edit_script	Recursos .tres y scripts .gd
project	create, setup_plugin, setting (op get/set/list/delete/set_multi + restart-aware), autoload, remove_autoload, input_map (persistente real: add/get/list/add_event/set_events/remove_event/set_deadzone), shader_global	Configuración, input mapping y creación de proyectos
shader	create, edit, get, inspect, validate, material, uniform, apply	Shaders .gdshader, materiales y aplicar shader+material+uniforms en 1 llamada
animation	create_player, create, add_track, add_key, state_machine, play, stop, seek, speed, get_animations, get_tracks, get_keyframes, one_shot, tween, record, from_path, loop_pose, preview, curve, capture_pose, blend_pose, retarget, reverse, duplicate, delete, rename, tree_*	Animaciones completas: playback, edición, procedural, IK, batch one-shot
skeleton	skeleton_create, skeleton_add_bone, skeleton_set_rest, skeleton_skin, skeleton_attachment, skeleton_get_bones, skeleton_get_pose, skeleton_set_pose, skeleton_ik, skeleton_fabrik, capture_pose	Esqueletos 2D/3D + IK 2D FABRIK e IK 3D
tilemap	inspect_set, inspect_map, set_cell, terrain, pattern	TileMaps/TileSets
signal	connect, disconnect, list, set_script	Señales (CONNECT_PERSIST, defensivo)
validate	scene, script, node, resource	Validación contra la escena viva
debug	run_scene, stop_scene, is_playing, get_editor_errors	Depuración con el editor real
orchestrate	(múltiples ops)	Batch operations, plan en archivo, errores por op sin abortar
visual	coords, summary, ascii, capture, node, budget, cache	Sistema de visión (jerarquía de costo)
health	server + editor	Health check con proyectos conectados

---

🧠 Arquitectura

OpenCode / Claude / Cursor (cliente MCP)
        │  stdio · NDJSON
        ▼
HerenServer.exe  (Rust · FlojoMCP · ~7 MB)
        │  WebSocket local (127.0.0.1)
        ▼
HerenEditorPlugin  (EditorPlugin GDScript)
   ├── editor_plugin.gd      # extends EditorPlugin, lifecycle
   ├── ws_client.gd          # cliente WS con auto-reconnect
   ├── dispatcher.gd         # rutea tools/call → handlers
   ├── undo_redo_wrapper.gd  # EditorUndoRedoManager
   └── handlers/             # scene, node, resource, animation+skeleton,
                             # shader, project, signal, validate, debug,
                             # tilemap, visual, coords

El ciclo de vida:

1. session/open → el server encuentra Godot, instala el plugin, lo habilita en project.godot y lanza godot --editor.
2. El plugin conecta al server por WebSocket (HEREN_MCP_PORT) y se registra por proyecto.
3. Las tools se enrutan al handler correcto, operan sobre el editor real (con Undo/Redo) y devuelven coordenadas/resultados.
4. health te dice qué proyectos tienen editor conectado.

Robustez de conexión: si hay un editor del proyecto abierto pero desconectado (plugin obsoleto o editor colgado), session/open lo relanza limpio. El plugin tiene auto-reconnect con backoff.

---

📚 Documentación

• 🤖 AGENTS.md — Guía completa para agentes de IA (incluye bugs/estado)
• 📦 docs/INSTALL.md — Instalación detallada
• 📋 docs/API.md — Referencia de la API
• 🏗️ docs/ARCHITECTURE.md — Arquitectura técnica
• 🤝 CONTRIBUTING.md — Cómo contribuir
• 📝 CHANGELOG.md — Historial de cambios

---

🔬 Hecho con FlojoMCP

Heren v4 está construido sobre FlojoMCP, el framework de servidores MCP en Rust que genera schemas en compile-time (imposible de romper en runtime), expone un server WebSocket local para que se conecten plugins externos (como este EditorPlugin de Godot), y envía imágenes como image_content MCP estándar. Rápido, pequeño y sin runtime.

---

🤝 Contribuir

¡Las contribuciones son bienvenidas! Lee CONTRIBUTING.md para:

• 📥 Cómo clonar e instalar
• 📥 Cómo correr tests
• 📥 Cómo reportar bugs
• 🎨 Estilo de código
• 📥 Cómo proponer features

---

📄 Licencia

MIT © 2026 Heren MCP Contributors

---

---

多謝垂注
⠀⣏⡱ ⣏⡉ ⣏⡱ ⡇ ⣎⣱   ⡷⢾ ⢇⡸
⠀⠧⠜ ⠧⠤ ⠇⠱ ⠇ ⠇⠸   ⠇⠸ ⠇⠸
https://ko-fi.com/general_beria