FluffOS MCP 服务器

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

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

此工具的功能

AI 助手现在可以：

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

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

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

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

工具

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

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

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

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

何时使用哪个工具

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 工具进行扩展。

鸣谢

• FluffOS 团队 - 提供出色的驱动程序和 CLI 工具

• Model Context Protocol - 使此集成成为可能

许可证

@gesslar/fluffos-mcp 根据 0BSD 发布。

此包包含或依赖于受其自身许可证约束的第三方组件：