Skip to main content
Glama
deenesjakoruzh
gesslar

FluffOS MCP Server

by gesslar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

FluffOS MCP 服务器

用于 LPC 开发的真实驱动程序验证 - 一个封装了 FluffOS CLI 工具的 MCP 服务器，提供实际的驱动程序级验证和调试。

此 MCP 服务器向 AI 助手公开了 FluffOS 强大的 CLI 工具（symbol 和 lpcc），使它们能够根据实际驱动程序验证 LPC 代码并检查编译后的字节码。

此工具的功能

AI 助手现在可以：

  • 使用实际的 FluffOS 驱动程序验证 LPC 文件（不仅仅是语法检查）

  • 捕获静态分析无法发现的运行时编译问题

  • 检查编译后的字节码以调试性能或行为问题

  • 理解 LPC 代码是如何实际编译的

Related MCP server: LPC MCP Server

工具

  • fluffos_validate：使用 FluffOS 的 symbol 工具验证 LPC 文件

  • fluffos_disassemble：使用 lpcc 将 LPC 反汇编为字节码

  • fluffos_doc_lookup：搜索 FluffOS 文档以查找 efun、apply、概念等

所有这三个工具都是只读且幂等的——它们从不修改文件、驱动程序或正在运行的 MUD，并且对于代理自动调用是安全的。

何时使用哪个工具

我想……

使用

检查文件是否能通过驱动程序编译

fluffos_validate

查看函数编译后的字节码

fluffos_disassemble

调查为什么某个模式运行缓慢

fluffos_disassemble

查找 efun 签名或 apply 语义

fluffos_doc_lookup

查明此驱动程序构建中是否存在某个 efun

在调用该 efuns 的文件上使用 fluffos_validate

提交前/部署前的完整性检查

fluffos_validate

fluffos_doc_lookup 仅在服务器启动时设置了 FLUFFOS_DOCS_DIR 时才会注册。

先决条件

1. FluffOS 安装

你需要安装 FluffOS 并提供 CLI 工具。应存在以下二进制文件：

  • 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 搜索文档

“我该如何使用映射 (mappings)？” → 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 返回结构化的错误响应

  • 优雅地处理配置缺失或工具执行失败的情况

  • 非零退出代码会被报告，但不会导致服务器崩溃

补充工具

此服务器可以与以下工具完美配合：

  • lpc-mcp - 用于代码智能的语言服务器集成

  • 带有 jlchmura 的 LPC 扩展的 VS Code - IDE 支持

将它们结合使用以获得完整的 LPC 开发体验！

贡献

欢迎提交 PR！这是一个简单的封装，可以通过更多 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