Skip to main content
Glama
deenesjakoruzh
gesslar

FluffOS MCP Server

by gesslar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

FluffOS MCP 서버

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

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

이 도구로 가능한 작업

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

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

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

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

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

Related MCP server: LPC MCP Server

도구

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

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

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

세 가지 도구 모두 읽기 전용이며 **멱등성(idempotent)**을 가집니다. 즉, 파일, 드라이버 또는 실행 중인 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 설치

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 도구로 확장 가능한 간단한 래퍼입니다.

크레딧

라이선스

@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