Skip to main content
Glama
deenesjakoruzh
gesslar

FluffOS MCP Server

by gesslar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

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

Related MCP server: LPC MCP Server

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

Quiero…

Usar

Comprobar si un archivo compila contra el driver

fluffos_validate

Ver el bytecode al que se compila una función

fluffos_disassemble

Investigar por qué un patrón es lento

fluffos_disassemble

Buscar la firma de una efun o la semántica de un apply

fluffos_doc_lookup

Averiguar si una efun existe en esta compilación del driver

fluffos_validate en un archivo que la llame

Comprobación de integridad pre-commit / pre-deploy

fluffos_validate

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

Licencia

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

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

Dependencia

Licencia

@gesslar/toolkit

0BSD

@modelcontextprotocol/sdk

MIT

zod

MIT

Available Tools

2 tools
fluffos_disassembleB

Disassemble an LPC file to show compiled bytecode using lpcc. Useful for debugging and understanding how code compiles.

ParametersJSON Schema
NameRequiredDescriptionDefault
fileYesAbsolute path to the LPC file to disassemble

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions the tool is 'useful for debugging and understanding how code compiles,' which gives some behavioral context about its purpose. However, it doesn't disclose important behavioral traits like whether this is a read-only operation, what permissions are needed, whether it modifies the file, error handling, or output format details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded. The first sentence clearly states the core functionality, and the second sentence adds valuable context about when to use it. Both sentences earn their place with zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 1 parameter with 100% schema coverage and no output schema, the description provides adequate but minimal context. It explains what the tool does and its use cases, but for a tool with no annotations and no output schema, it should ideally provide more behavioral details about what the disassembly output looks like or any limitations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, with the single parameter 'file' well-documented in the schema. The description doesn't add any parameter-specific information beyond what the schema provides. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't need to.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Disassemble an LPC file to show compiled bytecode using lpcc.' It specifies the verb (disassemble), resource (LPC file), and method (using lpcc). However, it doesn't explicitly differentiate from the sibling tool 'fluffos_validate', which appears to be a different operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides implied usage context: 'Useful for debugging and understanding how code compiles.' This suggests when to use the tool, but doesn't explicitly state when not to use it or mention alternatives. No comparison to the sibling tool is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fluffos_validateA

Validate an LPC file using the FluffOS driver's symbol tool. Returns success/failure and any compilation errors.

ParametersJSON Schema
NameRequiredDescriptionDefault
fileYesAbsolute path to the LPC file to validate

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the validation outcome ('success/failure and any compilation errors'), which is useful context beyond basic functionality. However, it doesn't address important behavioral aspects like error handling, performance characteristics, or whether this operation has side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly concise with two sentences that each earn their place: the first states the core functionality, and the second describes the return value. There's zero waste or redundancy, and it's appropriately front-loaded with the main purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter validation tool with no annotations and no output schema, the description provides adequate but minimal information. It covers what the tool does and what it returns, but doesn't address potential complexities like what constitutes validation success versus failure, error message formats, or limitations of the validation process.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents the single 'file' parameter. The description doesn't add any additional meaning about the parameter beyond what the schema provides, such as file format requirements or validation scope limitations. The baseline of 3 is appropriate when the schema does all the parameter documentation work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('validate an LPC file') and resource ('using the FluffOS driver's symbol tool'), distinguishing it from the sibling tool 'fluffos_disassemble' which implies a different operation. It provides a complete verb+resource+scope statement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. While the sibling tool name suggests a different function, the description doesn't explicitly state when to choose validation over disassembly or other potential options. There's no mention of prerequisites or context for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.0
    • First observedfluffos_disassemble
    • First observedfluffos_validate
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

B3.4/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: disassemble focuses on showing compiled bytecode for debugging, while validate checks for compilation errors and success/failure. There is no overlap or ambiguity between these functions.

Naming Consistency5/5

Both tools follow a consistent 'fluffos_verb' naming pattern (fluffos_disassemble and fluffos_validate), using the same prefix and verb-based structure. This makes them predictable and easy to identify.

Tool Count2/5

With only 2 tools, the server feels thin for a FluffOS/LPC development environment. While disassembly and validation are useful, typical development workflows would benefit from additional tools like code execution, file management, or debugging support, making this set under-scoped.

Completeness2/5

The server covers only disassembly and validation, leaving significant gaps for a FluffOS development tool. Missing are core operations like running LPC code, editing files, managing projects, or advanced debugging features, which limits agents' ability to handle comprehensive development tasks.

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Almide MCP Server

    almide
    F
    license
    Not graded
    quality
    Not graded
    maintenance
    Enables AI agents to compile, execute, and check Almide code for syntax or compilation errors. It provides tools for generating ASTs and accessing language grammar resources.
    -

  • LPC MCP Server

    gesslar
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI assistants to understand and query LPC codebases through natural language, using a language server for hover info, definitions, references, and diagnostics.
    18 npm
    2
    BSD Zero Clause