AGS MCP Server

Manipula archivos de sala compilados (.crm) de Adventure Game Studio (AGS) para habilitar el desarrollo de juegos impulsado por IA.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de AGS

Servidor de Protocolo de Contexto de Modelo (MCP) para la manipulación de archivos de sala compilados (.crm) de Adventure Game Studio (AGS).

Herramienta puente que brinda a la IA acceso a datos binarios de salas de AGS para el desarrollo completo de juegos de aventura impulsado por IA.

🎯 Visión del Proyecto

Las herramientas de IA sobresalen en leer y escribir archivos de script de AGS (texto), pero no pueden acceder directamente a los archivos de sala compilados (.crm). Esto crea una brecha donde los desarrolladores deben conectar manualmente los scripts generados por IA a los elementos de la sala a través del editor de AGS.

El Servidor MCP de AGS cierra esta brecha al proporcionar acceso programático a los datos binarios .crm, lo que permite a la IA:

Conectar funciones de script a zonas interactivas, objetos y elementos interactivos
Leer diseños de salas y áreas interactivas para obtener contexto
Completar el flujo de trabajo de desarrollo completo sin intervención manual del editor de AGS

Flujo de trabajo principal:

La IA analiza los requisitos del juego y el contexto de la sala
La IA escribe funciones de script (archivos de texto)
La IA utiliza el servidor MCP para conectar funciones a elementos de la sala en archivos binarios .crm
Juego completo listo para pruebas: no se requiere conexión manual

🚀 Inicio Rápido

Ejecutar con npx (Recomendado)

# Run directly without installation
npx ags-mcp-server

Configuración de Desarrollo

# Clone the repository
git clone <repository>
cd ags-mcp-server

# Install dependencies
npm install

# Run the demo
npm run demo  # Shows all functionality working

📋 Características

🔍 Lectura de Datos de Sala: Analiza archivos .crm y extrae información estructurada
📦 Gestión de Bloques: Lista, exporta e importa bloques específicos dentro de archivos de sala
🎯 Herramientas de Zonas Interactivas: Lee y modifica interacciones de zonas interactivas programáticamente
🔗 Integración de Scripts: Conecta eventos de zonas interactivas a funciones de script automáticamente
💻 Multiplataforma: Funciona en Windows, macOS y Linux
🤖 Integración con IA: Compatible con Claude Desktop, Cline y otros clientes MCP

🛠️ Instalación y Despliegue

Usando npx (Recomendado)

# Run directly without installation
npx ags-mcp-server

Desarrollo Local

# Clone the repository
git clone <repository>
cd ags-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start  # Starts MCP server on stdio

🪟 Configuración para Windows

Requisitos previos: Node.js 18+ instalado

Ejecutar con npx:

# Run directly without installation
npx ags-mcp-server

Configuración de Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "ags-server": {
      "command": "npx",
      "args": ["ags-mcp-server"]
    }
  }
}

🍎 Configuración para macOS

Requisitos previos: Node.js 18+ instalado

Ejecutar con npx:

# Run directly without installation
npx ags-mcp-server

Configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ags-server": {
      "command": "npx",
      "args": ["ags-mcp-server"]
    }
  }
}

🐧 Configuración para Linux

Requisitos previos: Node.js 18+ instalado

Ejecutar con npx:

# Run directly without installation
npx ags-mcp-server

Configuración de Claude Desktop (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ags-server": {
      "command": "npx",
      "args": ["ags-mcp-server"]
    }
  }
}

🔧 Herramientas MCP

Operaciones Principales de Sala

read_room_data - Analiza el archivo .crm y devuelve datos estructurados de la sala
list_room_blocks - Lista todos los bloques en un archivo .crm con detalles

Manipulación de Bloques

export_room_block - Exporta un bloque específico a un archivo
import_room_block - Importa/reemplaza datos de bloques en el archivo .crm

Gestión de Zonas Interactivas

get_room_hotspots - Extrae información e interacciones de zonas interactivas
add_hotspot_interaction - Agrega un manejador de eventos de interacción a una zona interactiva

Ejemplo de Uso de Herramientas

{
  "tool": "add_hotspot_interaction",
  "arguments": {
    "roomFile": "room001.crm",
    "hotspotId": 1,
    "event": "Look",
    "functionName": "hotspot1_Look"
  }
}

🤖 Integración con IA

Integración con Claude Desktop

Agrega a tu claude_desktop_config.json (la ubicación depende de tu sistema operativo):

{
  "mcpServers": {
    "ags-server": {
      "command": "npx",
      "args": ["ags-mcp-server"]
    }
  }
}

Extensión Cline para VSCode

Configura en la configuración de Cline:

{
  "ags-mcp-server": {
    "command": "npx",
    "args": ["ags-mcp-server"],
    "type": "stdio"
  }
}

🎮 Ejemplos de Automatización con IA

Flujo de Trabajo de Análisis de Sala

AI → read_room_data → analyze layout → get_room_hotspots → identify missing interactions

Creación de Objetos Interactivos

AI: "Make the door interactive"
MCP: add_hotspot_interaction(door, "Look", "door_Look") 
AI: Generated function: door_Look() { player.Say("A sturdy wooden door."); }

Procesamiento de Salas por Lotes

# AI processes multiple rooms for consistency
for room in ["room001.crm", "room002.crm", "room003.crm"]:
    hotspots = mcp_call("get_room_hotspots", {"roomFile": room})
    # Add missing interactions automatically
    for hotspot in hotspots:
        if "Look" not in hotspot["interactions"]:
            mcp_call("add_hotspot_interaction", {...})

🏗️ Formato de Archivo de Sala de AGS

El servidor MCP funciona con el formato binario .crm (sala compilada) de AGS:

Estructura de Bloques

ID de Bloque	Nombre	Descripción
1	Main	Fondos de sala, objetos, máscaras
2	TextScript	Código fuente de script de texto (heredado)
5	ObjNames	Nombres de objetos y zonas interactivas
6	AnimBg	Fondos animados
7	CompScript3	Script compilado actual
8	Properties	Propiedades personalizadas
9	ObjectScNames	Nombres de script para objetos

Sistema de Zonas Interactivas

Detección: Máscara de mapa de bits donde los colores de píxeles = IDs de zonas interactivas
Interacciones: Sistema basado en eventos (Mirar, Interactuar, UsarInv, etc.)
Conexión de Scripts: Funciones nombradas hotspot{id}_{event} (por ejemplo, hotspot1_Look)
Resolución en Tiempo de Ejecución: Resolución dinámica de funciones desde scripts compilados

🗺️ Hoja de Ruta de Desarrollo

🎯 Misión: Puente Completo IA-AGS

Permitir que las herramientas de IA manipulen completamente los archivos de sala de AGS sin intervención manual del editor de AGS.

✅ Fase 1: Fundamentos (COMPLETA)

Compilación de herramientas de AGS (crmpak, crm2ash)
Arquitectura del servidor MCP
Implementación de lectura/análisis de archivos .crm
Herramientas básicas de manipulación de zonas interactivas
Soporte multiplataforma (Windows, macOS, Linux)
Demostración de prueba de concepto y documentación

✅ Fase 2: Operaciones Mejoradas de Zonas Interactivas (COMPLETA - SOLO LECTURA)

Objetivo: Completar las capacidades de conexión de script a binario de zonas interactivas

Modificación avanzada de propiedades de zonas interactivas (marcador/solo lectura)
Gestión de eventos de interacción de zonas interactivas (marcador/solo lectura)
Actualizaciones de coordenadas de caminar hacia (marcador/solo lectura)
Validación de zonas interactivas y manejo de errores
Operaciones de zonas interactivas por lotes (marcador/solo lectura)
Suite de pruebas integral (58 pruebas, 100% de tasa de aprobación)

✅ ACTUALIZACIÓN: Todas las operaciones ahora usan manipulación binaria directa con datos precisos.

✅ Fase 2.5: Eliminación de CRMPAK y Escritura Binaria Directa (COMPLETADA)

Objetivo: Eliminar dependencias binarias e implementar escritura real de archivos

Eliminadas todas las dependencias de CRMPAK de las operaciones de lectura
Implementada escritura binaria directa para modificaciones de zonas interactivas
Reemplazado list_room_blocks con análisis binario directo
Corregida la precisión de datos de zonas interactivas (IDs, nombres de script, interacciones)
Agregada copia de seguridad/versionado para seguridad de archivos
Solución pura en Node.js/TypeScript: cero dependencias externas

📋 Fase 3: Integración de Objetos de Sala (PLANEADA - BINARIO DIRECTO)

Objetivo: Conectar scripts de IA a objetos de sala mediante análisis binario directo

Enumeración y propiedades de objetos de sala (lectura binaria directa)
Conexiones de funciones de script de objetos (escritura binaria directa)
Posicionamiento de objetos y gestión de estado (escritura binaria directa)
Configuración de comportamiento de objetos interactivos
Controles de visibilidad y animación de objetos

🚶 Fase 4: Áreas Caminables y Límites (PLANEADA - BINARIO DIRECTO)

Objetivo: Control de IA sobre el movimiento de personajes mediante manipulación binaria directa

Lectura y modificación de áreas caminables (binario directo)
Gestión de áreas de caminar detrás (binario directo)
Validación de rutas de personajes
Configuración de colisiones de límites
Scripting de transiciones de áreas

🎯 Fase 5: Regiones y Áreas Especiales (PLANEADA - BINARIO DIRECTO)

Objetivo: Configuración de zonas de activación por IA mediante manipulación binaria directa

Definición y propiedades de regiones (binario directo)
Conexiones de manejadores de eventos de regiones (escritura binaria directa)
Scripting de zonas de activación
Configuración de efectos de áreas especiales
Gestión de interacciones multi-región

👤 Fase 6: Puntos de Aparición de Personajes (PLANEADA - BINARIO DIRECTO)

Objetivo: Colocación de personajes por IA mediante manipulación binaria directa

Definición de puntos de aparición de personajes (binario directo)
Gestión de posición inicial (escritura binaria directa)
Inicialización de estado de personajes
Configuración de salas multi-personaje
Scripting de interacciones de personajes

🔮 Fase 7: Características Avanzadas (FUTURO - CONTROL BINARIO COMPLETO)

Manipulación completa de bloques de script (edición binaria directa de CompScript3)
Soporte de otros formatos de archivo de AGS (.ags, .chr, etc.)
Integración de scripts a nivel de proyecto de AGS
Pruebas y validación automatizadas
LOGRADO: Manipulación de salas de AGS 100% libre de CRMPAK

📊 Estado del Proyecto

🎯 Estado: Manipulación Binaria Completa Terminada

✅ LOGRADO: Manipulación Binaria Pura

✅ Lectura: Análisis binario directo con datos precisos de zonas interactivas (IDs corregidos, nombres de script, interacciones)
✅ Escritura: Modificaciones reales de archivos binarios con funciones de copia de seguridad/seguridad
✅ Dependencias: Cero dependencias externas: solución pura en Node.js/TypeScript
✅ Precisión: Corregidas todas las discrepancias de datos reportadas entre MCP y el Editor de AGS
🔧 Beneficio: Sin dependencias binarias, solución pura en Node.js/TypeScript

🧪 Pruebas y Validación

Ejecutar Demostración

# If you've cloned the repository
npm run demo  # Shows all MCP tools with mock data

# Or using npx
npx ags-mcp-server demo

Validar Protocolo MCP

# Test the JSON-RPC interface
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx ags-mcp-server

Verificar Instalación

# Check if the MCP server is working correctly
npx ags-mcp-server --version

🔧 Desarrollo

Proceso de Compilación

# Install dependencies
npm install

# Build TypeScript code
npm run build

# Run tests
npm test

Requisitos Previos

Node.js 18+
npm 7+

Arquitectura

AI Request → MCP Server → AGS Tools (crmpak) → Binary .crm Files → Structured Data → AI Response

🛡️ Seguridad y Producción

Acceso a Archivos: Lectura/escritura controlada solo a archivos .crm
Validación de Entrada: Todos los parámetros de herramientas validados
Soporte de Plataformas: Funciona en Windows, macOS y Linux
Manejo de Errores: Manejo y reporte de errores elegante

📈 Rendimiento

Uso de Memoria: ~50MB típico, ~200MB pico durante operaciones
Tiempo de Respuesta: <100ms para la mayoría de las llamadas de herramientas MCP
Soporte Concurrente: Maneja múltiples operaciones de herramientas
Formatos de Archivo: Soporta todas las versiones de salas de AGS (1.14+)

🚨 Solución de Problemas

Problemas Comunes

Comando npx no encontrado:

# Make sure Node.js is installed
node --version

# If needed, install or update npm
npm install -g npm

Problemas de permisos con npx:

# On Linux/macOS, you might need to use sudo
sudo npx ags-mcp-server

# Or fix npm permissions
https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally

Conexión MCP fallida:

# Check stdio configuration and tool responses
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx ags-mcp-server

Errores de acceso a archivos:

# Make sure you're using absolute file paths or paths relative to your current directory
# Not paths relative to the MCP server installation

Modo de Depuración

DEBUG=ags-mcp:* npx ags-mcp-server

🤝 Contribuciones

Haz un fork del repositorio
Crea una rama de características: git checkout -b feature/new-tool
Agrega pruebas: npm test
Actualiza la documentación
Envía una solicitud de extracción

📄 Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.

🔗 Proyectos Relacionados

Adventure Game Studio - El motor principal de AGS
Model Context Protocol - Especificación y ejemplos de MCP

¿Listo para automatizar tu desarrollo de juegos de AGS con IA? ¡Comienza con npm run demo para verlo en acción! 🎮✨