Skip to main content
Glama
deenesjakoruzh
gesslar

FluffOS MCP Server

by gesslar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

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

Related MCP server: LPC MCP Server

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

Ich möchte…

Verwenden Sie

Prüfen, ob eine Datei mit dem Treiber kompiliert

fluffos_validate

Den Bytecode sehen, zu dem eine Funktion kompiliert wird

fluffos_disassemble

Untersuchen, warum ein Muster langsam ist

fluffos_disassemble

Eine Efun-Signatur oder Apply-Semantik nachschlagen

fluffos_doc_lookup

Herausfinden, ob eine Efun in diesem Treiber-Build existiert

fluffos_validate für eine Datei, die sie aufruft

Pre-Commit / Pre-Deploy Plausibilitätsprüfung

fluffos_validate

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

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:

Abhängigkeit

Lizenz

@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