FluffOS MCP 서버

LPC 개발을 위한 실제 드라이버 검증 - FluffOS CLI 도구를 래핑하여 실제 드라이버 수준의 검증 및 디버깅을 제공하는 MCP 서버입니다.

이 MCP 서버는 FluffOS의 강력한 CLI 유틸리티(symbol 및 lpcc)를 AI 어시스턴트에게 노출하여, AI가 실제 드라이버를 기준으로 LPC 코드를 검증하고 컴파일된 바이트코드를 검사할 수 있도록 합니다.

이 도구로 가능한 작업

AI 어시스턴트가 이제 다음을 수행할 수 있습니다:

• 실제 FluffOS 드라이버를 사용하여 LPC 파일 검증 (단순 구문 검사가 아님)

• 정적 분석으로는 놓칠 수 있는 런타임 컴파일 문제 포착

• 컴파일된 바이트코드를 검사하여 성능 또는 동작 문제 디버깅

• LPC 코드가 실제로 어떻게 컴파일되는지 이해

도구

• fluffos_validate: FluffOS의 symbol 도구를 사용하여 LPC 파일 검증

• fluffos_disassemble: lpcc를 사용하여 LPC를 바이트코드로 역어셈블

• fluffos_doc_lookup: efun, apply, 개념 등에 대한 FluffOS 문서 검색

세 가지 도구 모두 읽기 전용이며 **멱등성(idempotent)**을 가집니다. 즉, 파일, 드라이버 또는 실행 중인 MUD를 수정하지 않으므로 에이전트가 자동으로 호출해도 안전합니다.

도구별 사용 시기

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을 사용하여 문서 검색

"매핑(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을 사용하여 마크다운 파일 검색

• FLUFFOS_DOCS_DIR이 설정된 경우에만 사용 가능

오류 처리

• 시작 시 필수 환경 변수 검증

• MCP를 통해 구조화된 오류 응답 반환

• 설정 누락 또는 도구 실행 실패를 적절히 처리

• 0이 아닌 종료 코드는 보고되지만 서버가 중단되지는 않음

보완 도구

이 서버는 다음 도구와 함께 사용하면 좋습니다:

• lpc-mcp - 코드 인텔리전스를 위한 언어 서버 통합

• VS Code (jlchmura의 LPC 확장) - IDE 지원

함께 사용하여 완벽한 LPC 개발 환경을 경험하세요!

기여

PR을 환영합니다! 이 도구는 더 많은 FluffOS 도구로 확장 가능한 간단한 래퍼입니다.

크레딧

• FluffOS 팀 - 훌륭한 드라이버와 CLI 도구 제공

• Model Context Protocol - 이 통합을 가능하게 함

라이선스

@gesslar/fluffos-mcp는 0BSD 하에 릴리스되었습니다.

이 패키지는 자체 라이선스를 따르는 타사 구성 요소를 포함하거나 이에 의존합니다: