FluffOS MCP Server

Real driver validation for LPC development - An MCP server that wraps FluffOS CLI tools to provide actual driver-level validation and debugging.

This MCP server exposes FluffOS's powerful CLI utilities (symbol and lpcc) to AI assistants, enabling them to validate LPC code against the actual driver and examine compiled bytecode.

What This Enables

AI assistants can now:

• Validate LPC files using the actual FluffOS driver (not just syntax checking)
• Catch runtime compilation issues that static analysis misses
• Examine compiled bytecode to debug performance or behavior issues
• Understand how LPC code actually compiles

Tools

• fluffos_validate: Validate an LPC file using FluffOS's symbol tool
• fluffos_disassemble: Disassemble LPC to bytecode using lpcc
• fluffos_doc_lookup: Search FluffOS documentation for efuns, applies, concepts, etc.
• fluffos_eval: Evaluate LPC statements against the live driver using lpcshell (opt-in)

fluffos_validate, fluffos_disassemble, and fluffos_doc_lookup are read-only and idempotent — they never modify files, drivers, or running MUDs, and are safe for agents to auto-invoke.

fluffos_eval is not read-only: it boots the full runtime and executes the LPC you give it, so it can have side effects (writing files, mutating daemon/database state, firing events). It is registered only when FLUFFOS_ENABLE_EVAL is set, and should not be auto-invoked on untrusted input.

When to use which tool

| I want to… | Use | | --- | --- | | Check whether a file compiles against the driver | fluffos_validate | | See the bytecode a function compiles to | fluffos_disassemble | | Investigate why a pattern is slow | fluffos_disassemble | | Look up an efun signature or apply semantics | fluffos_doc_lookup | | Find out if an efun exists in this driver build | fluffos_validate on a file that calls it | | Pre-commit / pre-deploy sanity check | fluffos_validate | | See the actual runtime value/behaviour of an expression | fluffos_eval | | Reproduce a runtime error interactively | fluffos_eval |

fluffos_doc_lookup is only registered when the server is started with FLUFFOS_DOCS_DIR set. fluffos_eval is only registered when FLUFFOS_ENABLE_EVAL is set.

Prerequisites

1. FluffOS Installation

You need FluffOS installed with the CLI tools available. The following binaries should exist:

• symbol - For validating LPC files
• lpcc - For disassembling to bytecode
• lpcshell - (Optional) For fluffos_eval; required only when FLUFFOS_ENABLE_EVAL is set

2. Node.js

Node.js 16+ required:

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

Installation

You can install the server via npm:

npm install -g @gesslar/fluffos-mcp

Or clone and install locally:

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

Configuration

The server requires these environment variables:

• FLUFFOS_BIN_DIR - Directory containing FluffOS binaries (symbol, lpcc, and optionally lpcshell)
• MUD_RUNTIME_CONFIG_FILE - Path to your FluffOS config file (e.g., /mud/lib/etc/config.test)
• FLUFFOS_DOCS_DIR - (Optional) Directory containing FluffOS documentation for doc lookup
• FLUFFOS_ENABLE_EVAL - (Optional) Set to true (or 1/yes/on, case-insensitive) to register fluffos_eval, which executes live LPC via lpcshell. Off by default — any other value, including false/0 or leaving it unset, keeps the tool disabled because it is not read-only.
• FLUFFOS_EVAL_TIMEOUT_MS - (Optional) Wall-clock cap in milliseconds for a single fluffos_eval run before the lpcshell child is killed. Defaults to 30000 (30s); ignored unless fluffos_eval is enabled.
• FLUFFOS_EVAL_MAX_BYTES - (Optional) Maximum size in bytes of an fluffos_eval code payload; larger requests are rejected before anything is written to disk. Defaults to 10485760 (10 MiB); ignored unless fluffos_eval is enabled.
• FLUFFOS_EVAL_MAX_CONCURRENT - (Optional) Maximum number of fluffos_eval runs allowed in flight at once; further requests are rejected until a slot frees. Each run spawns a full lpcshell driver boot, so this bounds both temp-storage use and driver load. Defaults to 4; ignored unless fluffos_eval is enabled.

Setup for Different AI Tools

Warp (Terminal)

Add to your Warp MCP configuration:

Location: Settings → AI → Model Context Protocol

If installed via 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"
    }
  }
}

If cloned locally:

{
  "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"
    }
  }
}

Important: Use absolute paths!

Restart Warp after adding the configuration.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent:

If installed via 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"
      }
    }
  }
}

If cloned locally:

{
  "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"
      }
    }
  }
}

Restart Claude Desktop after configuration.

Enabling live LPC eval (optional)

The examples above register only the three read-only tools. To also expose fluffos_eval — which boots the driver and executes LPC, so it can have side effects — add FLUFFOS_ENABLE_EVAL to the env block alongside the others:

"env": {
  "FLUFFOS_BIN_DIR": "/path/to/fluffos/bin",
  "MUD_RUNTIME_CONFIG_FILE": "/mud/lib/etc/config.test",
  "FLUFFOS_ENABLE_EVAL": "true"
}

Accepted "on" values are true, 1, yes, or on (case-insensitive). Any other value — or omitting the variable entirely — leaves the tool disabled. The lpcshell binary must exist in FLUFFOS_BIN_DIR for this to work.

Usage Examples

Once configured, you can ask your AI assistant:

"Validate this LPC file with the actual driver" → AI uses fluffos_validate to run symbol

"Show me the bytecode for this function" → AI uses fluffos_disassemble to run lpcc

"Why is this code slow?" → AI examines the disassembly to identify inefficient patterns

"What's the syntax for call_out?" → AI uses fluffos_doc_lookup to search documentation

"How do I use mappings?" → AI searches docs for mapping-related documentation

How It Works

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. AI assistant sends MCP tool requests
2. Server spawns appropriate FluffOS CLI tool
3. CLI tool validates/disassembles using the driver
4. Server returns results to AI
5. AI understands your code at the driver level and can reference FluffOS documentation to explain how functions work!

Implementation Details

Architecture

The server is built using the Model Context Protocol SDK and follows a class-based architecture:

• FluffOSMCPServer class: Main server implementation
• MCP SDK Server: Handles protocol communication via stdio
• Child process spawning: Executes FluffOS CLI tools
• Path normalization: Converts absolute paths to mudlib-relative paths

Path Handling

The server intelligently handles file paths:

1. Parses mudlib directory from your FluffOS config file
2. Normalizes absolute paths to mudlib-relative paths
3. Passes normalized paths to FluffOS tools (which expect relative paths)

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

Tool Implementation

fluffos_validate:

• Spawns symbol <config> <file> from the config directory
• Captures stdout/stderr
• Returns success/failure with compilation errors
• Exit code 0 = validation passed

fluffos_disassemble:

• Spawns lpcc <config> <file> from the config directory
• Returns complete bytecode disassembly
• Includes function tables, strings, and instruction-level detail

fluffos_doc_lookup (optional):

• Runs scripts/search_docs.sh helper script
• Uses grep to search markdown files
• Only available if FLUFFOS_DOCS_DIR is set

fluffos_eval (optional):

• Writes the submitted LPC statements to a temporary script file, then spawns lpcshell <config> <tmpfile>
• The temp file is a plain OS file (read by lpcshell directly, not through the driver's file system) and so does not need to live inside the mudlib jail — only the LPC statements execute in-jail
• Boots the full runtime and executes the code; captures stdout/stderr and exit code, then deletes the temp file
• Only available if FLUFFOS_ENABLE_EVAL is set

Error Handling

• Validates required environment variables on startup
• Returns structured error responses via MCP
• Gracefully handles missing config or tool execution failures
• Non-zero exit codes are reported but don't crash the server

Complementary Tools

This server works great alongside:

• lpc-mcp - Language server integration for code intelligence
• VS Code with jlchmura's LPC extension - IDE support

Use them together for the complete LPC development experience!

Contributing

PRs welcome! This is a simple wrapper that can be extended with more FluffOS tools.

Credits

• FluffOS Team - For the amazing driver and CLI tools
• Model Context Protocol - Making this integration possible

License

@gesslar/fluffos-mcp is released under the 0BSD.

This package includes or depends on third-party components under their own licenses:

| Dependency | License | | --- | --- | | @gesslar/toolkit | 0BSD | | @modelcontextprotocol/sdk | MIT | | zod | MIT |