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.

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

2. Node.js

Node.js 16+ required:

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

3. Install Dependencies

cd /path/to/fluffos-mcp
npm install

Configuration

The server requires these environment variables:

• FLUFFOS_BIN_DIR - Directory containing FluffOS binaries (symbol, lpcc)
• 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

Setup for Different AI Tools

Warp (Terminal)

Add to your Warp MCP configuration:

Location: Settings → AI → Model Context Protocol

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

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

Restart Claude Desktop after configuration.

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!

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

Unlicense - Public Domain. Do whatever you want with this code.