MCP server for FluffOS driver tools - validate and disassemble LPC code
FluffOS MCP Server demonstrates good definition quality with four well-named, purpose-specific tools. All tools have comprehensive descriptions (200-400+ characters each) that include use-case guidance, preconditions, and relationships to other tools. Input schemas are present with type declarations and detailed parameter descriptions. However, output schemas are incompletely documented in code, descriptions reference 'structuredContent' payloads but the actual Zod/JSON Schema definitions for outputs are not visible in the provided source. Tool annotations (readOnlyHint/destructiveHint) are present for risk classification. Error handling descriptions are good but implementation details are not fully visible. The server follows the single-responsibility principle well: each tool does one thing (validate, disassemble, eval, doc-lookup), and naming is consistently verb-noun (fluffos_*). Parameter descriptions are LLM-optimized with explicit guidance on when to use each tool and how to chain them. Major gap: output schema implementations not visible in source code sample, preventing full validation.
Compile an LPC file with the `lpcc` CLI and return the resulting bytecode disassembly. **Use when:** - Debugging unexpected runtime behaviour by inspecting the instruction stream. - Comparing two implementations for generated-code efficiency. - Understanding how closures, inherited calls, or control flow resolve at the bytecode level. - Investigating why a particular pattern is slow. **Do not use for:** - Quick validity checks — prefer `fluffos_validate`, which is faster and far easier to read. - Anything requiring a running MUD state — this is a static compile/disassemble only. **Returns** the full disassembly as text: program header, function table, string table, and per-function instruction listings. On compile failure the text is an error block containing the driver's output and a non-zero exit code. A matching `structuredContent` payload with `success`, `exitCode`, and `output` fields is also returned. Read-only and idempotent. **Related tools:** `fluffos_validate` to confirm the file compiles before chasing disassembly quirks; `fluffos_doc_lookup` to look up efun semantics referenced in the bytecode.
Search the FluffOS documentation (usually Markdown files in the docs directory) for efun signatures, apply definitions, or conceptual information. Returns matching sections with filename and surrounding context. **Use when:** - Looking up the signature of an efun (e.g., `query_property`, `set_heart_beat`). - Researching how a concept like inheritance, sefuns, or string interpolation works. - Confirming the expected behaviour of a driver feature before calling `fluffos_eval` or `fluffos_validate`. - Clarifying error messages from compilation or runtime that reference unfamiliar functions. **Do not use for:** - LPC language reference — that is typically in the mudlib's own documentation or comments, not the driver docs. - MUD-specific functions — the docs cover only driver-level efuns and applies, not game logic. **Returns** matching documentation excerpts as text, grouped by filename. If no results match, returns an explanatory message. Uses ripgrep (`rg`) if available (faster, better formatting), falling back to `grep`. Case-insensitive and context-aware. Read-only and idempotent. **Related tools:** `fluffos_validate` and `fluffos_disassemble` for testing and inspecting the code after you've read the docs.
Output schemas not fully visible in source code. Descriptions reference 'structuredContent' with 'success', 'exitCode', 'output' fields but actual Zod schema definitions are not shown in the provided code sample. This prevents validation that output is properly typed and documented for LLM consumption.
Input schema definitions use raw Zod API syntax (z.string().describe()) rather than explicit JSON Schema objects. While functionally correct with mcp-sdk, the full schema structure is harder to audit. For example, fluffos_eval accepts 'code' with only a string type, no length constraints visible despite mentioning FLUFFOS_EVAL_MAX_BYTES in constructor.
Error handling is documented in tool descriptions but implementation details are not visible. Code references 'success' and 'stderr' fields but actual error response structure, error codes, recovery guidance, and error categorization (retryable vs user-fixable vs fatal) are not shown in source.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 64 | 2025-06-18+ | v2 |
| 2026-03-09 | F | 0 | - | v1 |
Execute live LPC code against the mudlib via the FluffOS driver's lpcshell tool. The code runs in a fresh driver instance with access to all loaded mudlib objects, sefuns, and efuns, then returns the result. **Use when:** - Rapid iteration on untested code (functions, object properties, edge cases). - Debugging runtime issues in a safe, scripted way (no side effects persist unless the code writes to disk or modifies global state). - Verifying complex logic before rolling it into a production file. **Do not use for:** - Side-effect-free checks that could be done offline (prefer `fluffos_validate` or `fluffos_disassemble`). - Large-scale MUD state mutations (the driver boots fresh, so persistence requires careful code). - Anything time-critical (startup and teardown add overhead). **Returns** the LPC result as a string (or nested structure if the code returns one), alongside `success` and `stderr` fields. If the code times out or crashes, `success` is false and `stderr` contains the driver's diagnostic. This tool must be explicitly enabled via `FLUFFOS_ENABLE_EVAL=1` and respects per-invocation timeout and byte-size limits. **Related tools:** `fluffos_validate` for syntax-only checks; `fluffos_disassemble` for bytecode inspection of the code being tested.
Compile an LPC source file against the live FluffOS driver using the `symbol` CLI, without loading it into a running MUD. **Use when:** - Confirming a file will load cleanly (pre-commit, pre-deploy, or after edits). - Surfacing driver-level errors that static analysis and editor linting miss (inherit resolution, sefun availability, efun signatures, driver-specific semantics). - Verifying a fix before disassembly or runtime testing. **Do not use for:** - Runtime behaviour testing — this only validates compilation. Exercise behaviour in the MUD itself. - Performance analysis — follow up with `fluffos_disassemble` for that. **Returns** a text block: `✓ File validated successfully` plus any driver output on success, or `✗ Validation failed (exit code: N)` plus the compiler errors on failure. A matching `structuredContent` payload with `success`, `exitCode`, and `output` fields is also returned. Read-only and idempotent — never modifies files, drivers, or running MUDs. **Related tools:** `fluffos_disassemble` for bytecode inspection once validation passes; `fluffos_doc_lookup` for reference material on efuns, applies, or concepts cited in error messages.
Parameter naming inconsistency risk: 'file' parameter in fluffos_validate and fluffos_disassemble could be clearer. Consider 'lpc_file' or 'source_file' to distinguish from other file-related tools. Current name is acceptable but less explicit than baseline production patterns.