Skip to main content
Glama
deenesjakoruzh
gesslar

FluffOS MCP Server

by gesslar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

FluffOS MCPサーバー

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

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

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

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

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

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

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

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

Related MCP server: LPC MCP Server

ツール

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

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

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

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

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

目的

使用するツール

ファイルがドライバーに対してコンパイル可能か確認する

fluffos_validate

関数がどのようなバイトコードにコンパイルされるか確認する

fluffos_disassemble

パターンが遅い理由を調査する

fluffos_disassemble

efunのシグネチャやapplyのセマンティクスを調べる

fluffos_doc_lookup

このドライバービルドにefunが存在するか確認する

そのefunを呼び出すファイルで fluffos_validate

コミット前/デプロイ前の健全性チェック

fluffos_validate

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の他のツールで拡張可能なシンプルなラッパーです。

クレジット

ライセンス

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

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

依存関係

ライセンス

@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