FluffOS MCPサーバー

LPC開発のための本格的なドライバー検証 - FluffOS CLIツールをラップし、実際のドライバーレベルの検証とデバッグを提供するMCPサーバーです。

このMCPサーバーは、FluffOSの強力なCLIユーティリティ（symbolおよびlpcc）をAIアシスタントに公開し、実際のドライバーに対してLPCコードを検証したり、コンパイル済みバイトコードを調査したりできるようにします。

これにより可能になること

AIアシスタントは以下のことが可能になります：

• 実際のFluffOSドライバーを使用してLPCファイルを検証する（単なる構文チェックではありません）

• 静的解析では見逃される実行時のコンパイル問題を検出する

• コンパイル済みバイトコードを調査して、パフォーマンスや動作の問題をデバッグする

• LPCコードが実際にどのようにコンパイルされるかを理解する

ツール

• fluffos_validate: FluffOSのsymbolツールを使用してLPCファイルを検証する

• fluffos_disassemble: lpccを使用してLPCをバイトコードに逆アセンブルする

• fluffos_doc_lookup: efuns、applies、概念などのFluffOSドキュメントを検索する

これら3つのツールはすべて読み取り専用かつ**冪等（べきとう）**です。ファイル、ドライバー、実行中のMUDを変更することはなく、エージェントが自動的に呼び出しても安全です。

ツールを使い分けるタイミング

fluffos_doc_lookupは、サーバーがFLUFFOS_DOCS_DIRを設定して起動された場合にのみ登録されます。

前提条件

1. FluffOSのインストール

CLIツールが利用可能な状態でFluffOSがインストールされている必要があります。以下のバイナリが存在している必要があります：

• symbol - LPCファイルの検証用

• lpcc - バイトコードへの逆アセンブル用

2. Node.js

Node.js 16以上が必要です：

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

インストール

npm経由でサーバーをインストールできます：

npm install -g @gesslar/fluffos-mcp

または、クローンしてローカルにインストールします：

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

設定

サーバーには以下の環境変数が必要です：

• FLUFFOS_BIN_DIR - FluffOSバイナリ（symbol, lpcc）を含むディレクトリ

• MUD_RUNTIME_CONFIG_FILE - FluffOS設定ファイルへのパス（例: /mud/lib/etc/config.test）

• FLUFFOS_DOCS_DIR - （オプション）ドキュメント検索用のFluffOSドキュメントを含むディレクトリ

各種AIツール向けの設定

Warp (ターミナル)

WarpのMCP設定に追加します：

場所: Settings → AI → Model Context Protocol

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

ローカルにクローンした場合:

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

重要: 絶対パスを使用してください！

設定を追加した後、Warpを再起動してください。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または同等のファイルに追加します：

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

ローカルにクローンした場合:

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

設定後、Claude Desktopを再起動してください。

使用例

設定が完了すると、AIアシスタントに以下のように尋ねることができます：

「このLPCファイルを実際のドライバーで検証して」 → AIはfluffos_validateを使用してsymbolを実行します

「この関数のバイトコードを見せて」 → AIはfluffos_disassembleを使用してlpccを実行します

「なぜこのコードは遅いのですか？」 → AIは逆アセンブル結果を調べて非効率なパターンを特定します

「call_outの構文は何ですか？」 → AIはfluffos_doc_lookupを使用してドキュメントを検索します

「マッピングの使い方は？」 → AIはドキュメントでマッピング関連の情報を検索します

仕組み

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アシスタントがMCPツールリクエストを送信

2. サーバーが適切なFluffOS CLIツールを起動

3. CLIツールがドライバーを使用して検証/逆アセンブルを実行

4. サーバーが結果をAIに返却

5. AIはドライバーレベルでコードを理解し、FluffOSドキュメントを参照して関数の動作を説明可能になります！

実装の詳細

アーキテクチャ

このサーバーはModel Context Protocol SDKを使用して構築されており、クラスベースのアーキテクチャに従っています：

• FluffOSMCPServerクラス: メインサーバーの実装

• MCP SDK Server: stdio経由のプロトコル通信を処理

• 子プロセスの生成: FluffOS CLIツールを実行

• パスの正規化: 絶対パスをmudlib相対パスに変換

パスの取り扱い

サーバーはファイルパスをインテリジェントに処理します：

1. FluffOS設定ファイルからmudlib directoryを解析

2. 絶対パスをmudlib相対パスに正規化

3. 正規化されたパスをFluffOSツールに渡す（ツールは相対パスを期待するため）

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

ツールの実装

fluffos_validate:

• 設定ディレクトリから symbol <config> <file> を起動

• stdout/stderrをキャプチャ

• コンパイルエラーとともに成功/失敗を返却

• 終了コード0 = 検証成功

fluffos_disassemble:

• 設定ディレクトリから lpcc <config> <file> を起動

• 完全なバイトコードの逆アセンブル結果を返却

• 関数テーブル、文字列、命令レベルの詳細を含む

fluffos_doc_lookup (オプション):

• scripts/search_docs.sh ヘルパースクリプトを実行

• grep を使用してMarkdownファイルを検索

• FLUFFOS_DOCS_DIR が設定されている場合のみ利用可能

エラーハンドリング

• 起動時に必要な環境変数を検証

• MCP経由で構造化されたエラーレスポンスを返却

• 設定の欠落やツール実行の失敗を適切に処理

• 0以外の終了コードは報告されるが、サーバーはクラッシュしない

補完ツール

このサーバーは以下と併用すると非常に便利です：

• lpc-mcp - コードインテリジェンスのための言語サーバー統合

• VS Code (jlchmura氏のLPC拡張機能) - IDEサポート

これらを組み合わせて、完全なLPC開発体験を実現してください！

貢献

プルリクエストを歓迎します！これはFluffOSの他のツールで拡張可能なシンプルなラッパーです。

クレジット

• FluffOS Team - 素晴らしいドライバーとCLIツールに感謝

• Model Context Protocol - この統合を可能にしてくれたことに感謝

ライセンス

@gesslar/fluffos-mcp は 0BSD の下でリリースされています。

このパッケージには、独自のライセンスの下でサードパーティのコンポーネントが含まれているか、依存しています：