MCP-сервер FluffOS

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

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

Что это дает

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

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

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

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

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

Инструменты

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

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

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

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

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

Инструмент 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.

Благодарности

• Команда FluffOS — за потрясающий драйвер и инструменты командной строки

• Model Context Protocol — за возможность такой интеграции

Лицензия

@gesslar/fluffos-mcp выпущен под лицензией 0BSD.

Этот пакет включает или зависит от сторонних компонентов, распространяемых под их собственными лицензиями: