Skip to main content
Glama
deenesjakoruzh
gesslar

FluffOS MCP Server

by gesslar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

MCP-сервер FluffOS

Реальная проверка драйвером для разработки на LPC — MCP-сервер, который оборачивает инструменты командной строки FluffOS для обеспечения проверки и отладки на уровне драйвера.

Этот MCP-сервер предоставляет ИИ-ассистентам доступ к мощным утилитам командной строки FluffOS (symbol и lpcc), позволяя им проверять код LPC с помощью реального драйвера и изучать скомпилированный байт-код.

Что это дает

ИИ-ассистенты теперь могут:

  • Проверять файлы LPC с помощью реального драйвера FluffOS (а не просто выполнять проверку синтаксиса)

  • Выявлять проблемы компиляции во время выполнения, которые пропускает статический анализ

  • Изучать скомпилированный байт-код для отладки проблем производительности или поведения

  • Понимать, как именно компилируется код LPC

Related MCP server: LPC MCP Server

Инструменты

  • fluffos_validate: Проверка файла LPC с помощью инструмента symbol из состава FluffOS

  • fluffos_disassemble: Дизассемблирование LPC в байт-код с помощью lpcc

  • fluffos_doc_lookup: Поиск в документации FluffOS по efun, apply, концепциям и т. д.

Все три инструмента работают только на чтение и являются идемпотентными — они никогда не изменяют файлы, драйверы или работающие MUD, поэтому безопасны для автоматического вызова агентами.

Когда какой инструмент использовать

Я хочу…

Используйте

Проверить, компилируется ли файл драйвером

fluffos_validate

Увидеть байт-код, в который компилируется функция

fluffos_disassemble

Исследовать, почему шаблон работает медленно

fluffos_disassemble

Найти сигнатуру efun или семантику apply

fluffos_doc_lookup

Узнать, существует ли efun в этой сборке драйвера

fluffos_validate для файла, который ее вызывает

Выполнить проверку перед коммитом / деплоем

fluffos_validate

Инструмент fluffos_doc_lookup регистрируется только в том случае, если сервер запущен с установленной переменной FLUFFOS_DOCS_DIR.

Предварительные требования

1. Установка FluffOS

Вам необходимо установить 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 для поиска

Настройка для различных ИИ-инструментов

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.

Примеры использования

После настройки вы можете спросить своего ИИ-ассистента:

"Проверь этот файл LPC с помощью реального драйвера" → ИИ использует fluffos_validate для запуска symbol

"Покажи мне байт-код для этой функции" → ИИ использует fluffos_disassemble для запуска lpcc

"Почему этот код работает медленно?" → ИИ изучает дизассемблированный код для выявления неэффективных шаблонов

"Какой синтаксис у call_out?" → ИИ использует fluffos_doc_lookup для поиска в документации

"Как использовать mappings?" → ИИ ищет в документации информацию о mapping

Как это работает

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. ИИ-ассистент отправляет запросы к инструментам MCP

  2. Сервер запускает соответствующий инструмент командной строки FluffOS

  3. Инструмент CLI проверяет/дизассемблирует код с помощью драйвера

  4. Сервер возвращает результаты ИИ

  5. ИИ понимает ваш код на уровне драйвера и может ссылаться на документацию FluffOS, чтобы объяснить, как работают функции!

Детали реализации

Архитектура

Сервер построен с использованием Model Context Protocol SDK и следует классовой архитектуре:

  • Класс FluffOSMCPServer: основная реализация сервера

  • MCP SDK Server: обрабатывает обмен протоколами через stdio

  • Запуск дочерних процессов: выполняет инструменты командной строки FluffOS

  • Нормализация путей: преобразует абсолютные пути в пути относительно mudlib

Обработка путей

Сервер интеллектуально обрабатывает пути к файлам:

  1. Анализирует mudlib directory из вашего файла конфигурации FluffOS

  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 — интеграция языкового сервера для интеллектуальной работы с кодом

  • VS Code с расширением LPC от jlchmura — поддержка 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