Servidor MCP de FluffOS

Validación real del driver para el desarrollo en LPC - Un servidor MCP que envuelve las herramientas CLI de FluffOS para proporcionar validación y depuración a nivel de driver real.

Este servidor MCP expone las potentes utilidades CLI de FluffOS (symbol y lpcc) a los asistentes de IA, permitiéndoles validar código LPC contra el driver real y examinar el bytecode compilado.

Qué permite esto

Los asistentes de IA ahora pueden:

• Validar archivos LPC utilizando el driver FluffOS real (no solo comprobación de sintaxis)

• Detectar problemas de compilación en tiempo de ejecución que el análisis estático pasa por alto

• Examinar el bytecode compilado para depurar problemas de rendimiento o comportamiento

• Entender cómo se compila realmente el código LPC

Herramientas

• fluffos_validate: Valida un archivo LPC utilizando la herramienta symbol de FluffOS

• fluffos_disassemble: Desensambla LPC a bytecode utilizando lpcc

• fluffos_doc_lookup: Busca en la documentación de FluffOS efuns, applies, conceptos, etc.

Las tres herramientas son de solo lectura e idempotentes: nunca modifican archivos, drivers ni MUDs en ejecución, y son seguras para que los agentes las invoquen automáticamente.

Cuándo usar cada herramienta

fluffos_doc_lookup solo se registra cuando el servidor se inicia con FLUFFOS_DOCS_DIR configurado.

Requisitos previos

1. Instalación de FluffOS

Necesitas tener FluffOS instalado con las herramientas CLI disponibles. Deben existir los siguientes binarios:

• symbol - Para validar archivos LPC

• lpcc - Para desensamblar a bytecode

2. Node.js

Se requiere Node.js 16+:

node --version  # Should be v16.0.0 or higher

Instalación

Puedes instalar el servidor vía npm:

npm install -g @gesslar/fluffos-mcp

O clonar e instalar localmente:

git clone https://github.com/gesslar/fluffos-mcp.git
cd fluffos-mcp
npm install

Configuración

El servidor requiere estas variables de entorno:

• FLUFFOS_BIN_DIR - Directorio que contiene los binarios de FluffOS (symbol, lpcc)

• MUD_RUNTIME_CONFIG_FILE - Ruta a tu archivo de configuración de FluffOS (ej., /mud/lib/etc/config.test)

• FLUFFOS_DOCS_DIR - (Opcional) Directorio que contiene la documentación de FluffOS para la búsqueda de documentos

Configuración para diferentes herramientas de IA

Warp (Terminal)

Añade a tu configuración de MCP de Warp:

Ubicación: Settings → AI → Model Context Protocol

Si se instaló vía npm:

{
  "fluffos": {
    "command": "npx",
    "args": ["@gesslar/fluffos-mcp"],
    "env": {
      "FLUFFOS_BIN_DIR": "/path/to/fluffos/bin",
      "MUD_RUNTIME_CONFIG_FILE": "/mud/lib/etc/config.test",
      "FLUFFOS_DOCS_DIR": "/path/to/fluffos/docs"
    }
  }
}

Si se clonó localmente:

{
  "fluffos": {
    "command": "node",
    "args": ["/absolute/path/to/fluffos-mcp/index.js"],
    "env": {
      "FLUFFOS_BIN_DIR": "/path/to/fluffos/bin",
      "MUD_RUNTIME_CONFIG_FILE": "/mud/lib/etc/config.test",
      "FLUFFOS_DOCS_DIR": "/path/to/fluffos/docs"
    }
  }
}

Importante: ¡Usa rutas absolutas!

Reinicia Warp después de añadir la configuración.

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o equivalente:

Si se instaló vía npm:

{
  "mcpServers": {
    "fluffos": {
      "command": "npx",
      "args": ["@gesslar/fluffos-mcp"],
      "env": {
        "FLUFFOS_BIN_DIR": "/path/to/fluffos/bin",
        "MUD_RUNTIME_CONFIG_FILE": "/mud/lib/etc/config.test",
        "FLUFFOS_DOCS_DIR": "/path/to/fluffos/docs"
      }
    }
  }
}

Si se clonó localmente:

{
  "mcpServers": {
    "fluffos": {
      "command": "node",
      "args": ["/absolute/path/to/fluffos-mcp/index.js"],
      "env": {
        "FLUFFOS_BIN_DIR": "/path/to/fluffos/bin",
        "MUD_RUNTIME_CONFIG_FILE": "/mud/lib/etc/config.test",
        "FLUFFOS_DOCS_DIR": "/path/to/fluffos/docs"
      }
    }
  }
}

Reinicia Claude Desktop después de la configuración.

Ejemplos de uso

Una vez configurado, puedes preguntar a tu asistente de IA:

"Valida este archivo LPC con el driver real" → La IA usa fluffos_validate para ejecutar symbol

"Muéstrame el bytecode para esta función" → La IA usa fluffos_disassemble para ejecutar lpcc

"¿Por qué este código es lento?" → La IA examina el desensamblado para identificar patrones ineficientes

"¿Cuál es la sintaxis para call_out?" → La IA usa fluffos_doc_lookup para buscar en la documentación

"¿Cómo uso los mappings?" → La IA busca en los documentos información relacionada con mappings

Cómo funciona

AI Assistant
    ↓ (natural language)
  MCP Protocol
    ↓ (tool calls: fluffos_validate, fluffos_disassemble)
  This Server
    ↓ (spawns: symbol, lpcc)
  FluffOS CLI Tools
    ↓ (validates/compiles with actual driver)
  Your LPC Code

1. El asistente de IA envía solicitudes de herramientas MCP

2. El servidor lanza la herramienta CLI de FluffOS apropiada

3. La herramienta CLI valida/desensambla usando el driver

4. El servidor devuelve los resultados a la IA

5. ¡La IA entiende tu código a nivel de driver y puede referenciar la documentación de FluffOS para explicar cómo funcionan las funciones!

Detalles de implementación

Arquitectura

El servidor está construido utilizando el Model Context Protocol SDK y sigue una arquitectura basada en clases:

• Clase FluffOSMCPServer: Implementación principal del servidor

• Servidor MCP SDK: Maneja la comunicación del protocolo vía stdio

• Lanzamiento de procesos hijos: Ejecuta las herramientas CLI de FluffOS

• Normalización de rutas: Convierte rutas absolutas a rutas relativas a la mudlib

Manejo de rutas

El servidor maneja las rutas de archivo de forma inteligente:

1. Analiza el directorio de la mudlib desde tu archivo de configuración de FluffOS

2. Normaliza las rutas absolutas a rutas relativas a la mudlib

3. Pasa las rutas normalizadas a las herramientas de FluffOS (que esperan rutas relativas)

Ejemplo: /mud/ox/lib/std/object.c → std/object.c

Implementación de herramientas

fluffos_validate:

• Lanza symbol <config> <file> desde el directorio de configuración

• Captura stdout/stderr

• Devuelve éxito/fallo con errores de compilación

• Código de salida 0 = validación pasada

fluffos_disassemble:

• Lanza lpcc <config> <file> desde el directorio de configuración

• Devuelve el desensamblado completo del bytecode

• Incluye tablas de funciones, cadenas y detalles a nivel de instrucción

fluffos_doc_lookup (opcional):

• Ejecuta el script auxiliar scripts/search_docs.sh

• Usa grep para buscar en archivos markdown

• Solo disponible si FLUFFOS_DOCS_DIR está configurado

Manejo de errores

• Valida las variables de entorno requeridas al inicio

• Devuelve respuestas de error estructuradas vía MCP

• Maneja con elegancia la falta de configuración o fallos en la ejecución de herramientas

• Los códigos de salida distintos de cero se reportan pero no bloquean el servidor

Herramientas complementarias

Este servidor funciona muy bien junto a:

• lpc-mcp - Integración de servidor de lenguaje para inteligencia de código

• VS Code con la extensión LPC de jlchmura - Soporte para IDE

¡Úsalos juntos para la experiencia completa de desarrollo en LPC!

Contribuciones

¡Las PR son bienvenidas! Este es un envoltorio simple que puede extenderse con más herramientas de FluffOS.

Créditos

• Equipo de FluffOS - Por el increíble driver y herramientas CLI

• Model Context Protocol - Haciendo posible esta integración

Licencia

@gesslar/fluffos-mcp se publica bajo la 0BSD.

Este paquete incluye o depende de componentes de terceros bajo sus propias licencias: