FluffOS MCP-Server

Echte Treiber-Validierung für die LPC-Entwicklung - Ein MCP-Server, der FluffOS-CLI-Tools kapselt, um eine tatsächliche Validierung und Fehlersuche auf Treiberebene zu ermöglichen.

Dieser MCP-Server stellt die leistungsstarken CLI-Dienstprogramme von FluffOS (symbol und lpcc) für KI-Assistenten bereit, sodass diese LPC-Code anhand des tatsächlichen Treibers validieren und kompilierten Bytecode untersuchen können.

Was dies ermöglicht

KI-Assistenten können jetzt:

• LPC-Dateien mit dem tatsächlichen FluffOS-Treiber validieren (nicht nur Syntaxprüfung)

• Kompilierungsprobleme zur Laufzeit erkennen, die bei der statischen Analyse übersehen werden

• Kompilierten Bytecode untersuchen, um Leistungs- oder Verhaltensprobleme zu beheben

• Verstehen, wie LPC-Code tatsächlich kompiliert wird

Tools

• fluffos_validate: Validiert eine LPC-Datei mit dem symbol-Tool von FluffOS

• fluffos_disassemble: Disassembliert LPC in Bytecode mithilfe von lpcc

• fluffos_doc_lookup: Durchsucht die FluffOS-Dokumentation nach Efuns, Applies, Konzepten usw.

Alle drei Tools sind schreibgeschützt und idempotent – sie verändern niemals Dateien, Treiber oder laufende MUDs und sind sicher für die automatische Ausführung durch Agenten.

Wann welches Tool zu verwenden ist

fluffos_doc_lookup wird nur registriert, wenn der Server mit gesetztem FLUFFOS_DOCS_DIR gestartet wird.

Voraussetzungen

1. FluffOS-Installation

Sie benötigen eine FluffOS-Installation mit verfügbaren CLI-Tools. Die folgenden Binärdateien sollten vorhanden sein:

• symbol - Zur Validierung von LPC-Dateien

• lpcc - Zum Disassemblieren in Bytecode

2. Node.js

Node.js 16+ erforderlich:

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

Installation

Sie können den Server über npm installieren:

npm install -g @gesslar/fluffos-mcp

Oder lokal klonen und installieren:

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

Konfiguration

Der Server benötigt diese Umgebungsvariablen:

• FLUFFOS_BIN_DIR - Verzeichnis, das die FluffOS-Binärdateien enthält (symbol, lpcc)

• MUD_RUNTIME_CONFIG_FILE - Pfad zu Ihrer FluffOS-Konfigurationsdatei (z. B. /mud/lib/etc/config.test)

• FLUFFOS_DOCS_DIR - (Optional) Verzeichnis mit der FluffOS-Dokumentation für die Suche

Einrichtung für verschiedene KI-Tools

Warp (Terminal)

Fügen Sie dies zu Ihrer Warp-MCP-Konfiguration hinzu:

Ort: Settings → AI → Model Context Protocol

Bei Installation 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"
    }
  }
}

Bei lokalem Klonen:

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

Wichtig: Verwenden Sie absolute Pfade!

Starten Sie Warp nach dem Hinzufügen der Konfiguration neu.

Claude Desktop

Fügen Sie dies zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder äquivalent hinzu:

Bei Installation 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"
      }
    }
  }
}

Bei lokalem Klonen:

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

Starten Sie Claude Desktop nach der Konfiguration neu.

Anwendungsbeispiele

Sobald die Konfiguration abgeschlossen ist, können Sie Ihren KI-Assistenten fragen:

"Validieren Sie diese LPC-Datei mit dem tatsächlichen Treiber" → KI verwendet fluffos_validate, um symbol auszuführen

"Zeigen Sie mir den Bytecode für diese Funktion" → KI verwendet fluffos_disassemble, um lpcc auszuführen

"Warum ist dieser Code langsam?" → KI untersucht das Disassembly, um ineffiziente Muster zu identifizieren

"Wie lautet die Syntax für call_out?" → KI verwendet fluffos_doc_lookup, um die Dokumentation zu durchsuchen

"Wie verwende ich Mappings?" → KI durchsucht die Dokumentation nach Mapping-bezogenen Informationen

Funktionsweise

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. KI-Assistent sendet MCP-Tool-Anfragen

2. Server startet das entsprechende FluffOS-CLI-Tool

3. CLI-Tool validiert/disassembliert mithilfe des Treibers

4. Server sendet Ergebnisse an die KI zurück

5. Die KI versteht Ihren Code auf Treiberebene und kann auf die FluffOS-Dokumentation verweisen, um die Funktionsweise zu erklären!

Implementierungsdetails

Architektur

Der Server basiert auf dem Model Context Protocol SDK und folgt einer klassenbasierten Architektur:

• FluffOSMCPServer-Klasse: Haupt-Server-Implementierung

• MCP SDK Server: Handhabt die Protokollkommunikation über stdio

• Child process spawning: Führt FluffOS-CLI-Tools aus

• Pfadnormalisierung: Konvertiert absolute Pfade in mudlib-relative Pfade

Pfadbehandlung

Der Server handhabt Dateipfade intelligent:

1. Analysiert das mudlib directory aus Ihrer FluffOS-Konfigurationsdatei

2. Normalisiert absolute Pfade zu mudlib-relativen Pfaden

3. Übergibt normalisierte Pfade an FluffOS-Tools (die relative Pfade erwarten)

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

Tool-Implementierung

fluffos_validate:

• Startet symbol <config> <file> aus dem Konfigurationsverzeichnis

• Erfasst stdout/stderr

• Gibt Erfolg/Fehler mit Kompilierungsfehlern zurück

• Exit-Code 0 = Validierung erfolgreich

fluffos_disassemble:

• Startet lpcc <config> <file> aus dem Konfigurationsverzeichnis

• Gibt das vollständige Bytecode-Disassembly zurück

• Enthält Funktionstabellen, Strings und Details auf Instruktionsebene

fluffos_doc_lookup (optional):

• Führt das Hilfsskript scripts/search_docs.sh aus

• Verwendet grep, um Markdown-Dateien zu durchsuchen

• Nur verfügbar, wenn FLUFFOS_DOCS_DIR gesetzt ist

Fehlerbehandlung

• Validiert erforderliche Umgebungsvariablen beim Start

• Gibt strukturierte Fehlerantworten über MCP zurück

• Handhabt fehlende Konfigurationen oder Fehler bei der Tool-Ausführung elegant

• Exit-Codes ungleich Null werden gemeldet, führen aber nicht zum Absturz des Servers

Ergänzende Tools

Dieser Server funktioniert hervorragend zusammen mit:

• lpc-mcp - Language-Server-Integration für Code-Intelligenz

• VS Code mit jlchmura's LPC-Erweiterung - IDE-Unterstützung

Verwenden Sie diese zusammen für das komplette LPC-Entwicklungserlebnis!

Mitwirken

Pull Requests sind willkommen! Dies ist ein einfacher Wrapper, der mit weiteren FluffOS-Tools erweitert werden kann.

Credits

• FluffOS Team - Für den fantastischen Treiber und die CLI-Tools

• Model Context Protocol - Die diese Integration möglich macht

Lizenz

@gesslar/fluffos-mcp ist unter der 0BSD veröffentlicht.

Dieses Paket enthält oder hängt von Komponenten Dritter ab, die unter ihren eigenen Lizenzen stehen: