@gesslar/fluffos-mcp 0.1.0

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

package/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: Giddyup
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  cowyboysounds:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [20.x, 22.x]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run ESLint
+        run: npm run lint

package/README.md

@@ -0,0 +1,209 @@
+# FluffOS MCP Server
+
+**Real driver validation for LPC development** - An MCP server that wraps FluffOS CLI tools to provide actual driver-level validation and debugging.
+
+This MCP server exposes FluffOS's powerful CLI utilities (`symbol` and `lpcc`) to AI assistants, enabling them to validate LPC code against the actual driver and examine compiled bytecode.
+
+## What This Enables
+
+**AI assistants can now:**
+
+- Validate LPC files using the actual FluffOS driver (not just syntax checking)
+- Catch runtime compilation issues that static analysis misses
+- Examine compiled bytecode to debug performance or behavior issues
+- Understand how LPC code actually compiles
+
+## Tools
+
+- **`fluffos_validate`**: Validate an LPC file using FluffOS's `symbol` tool
+- **`fluffos_disassemble`**: Disassemble LPC to bytecode using `lpcc`
+- **`fluffos_doc_lookup`**: Search FluffOS documentation for efuns, applies, concepts, etc.
+
+## Prerequisites
+
+### 1. FluffOS Installation
+
+You need FluffOS installed with the CLI tools available. The following binaries should exist:
+
+- `symbol` - For validating LPC files
+- `lpcc` - For disassembling to bytecode
+
+### 2. Node.js
+
+Node.js 16+ required:
+
+```bash
+node --version  # Should be v16.0.0 or higher
+```
+
+### 3. Install Dependencies
+
+```bash
+cd /path/to/fluffos-mcp
+npm install
+```
+
+## Configuration
+
+The server requires these environment variables:
+
+- `FLUFFOS_BIN_DIR` - Directory containing FluffOS binaries (`symbol`, `lpcc`)
+- `MUD_RUNTIME_CONFIG_FILE` - Path to your FluffOS config file (e.g., `/mud/lib/etc/config.test`)
+- `FLUFFOS_DOCS_DIR` - (Optional) Directory containing FluffOS documentation for doc lookup
+
+## Setup for Different AI Tools
+
+### Warp (Terminal)
+
+Add to your Warp MCP configuration:
+
+**Location**: Settings → AI → Model Context Protocol
+
+```json
+{
+  "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"
+    }
+  }
+}
+```
+
+**Important**: Use absolute paths!
+
+Restart Warp after adding the configuration.
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or equivalent:
+
+```json
+{
+  "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"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after configuration.
+
+## Usage Examples
+
+Once configured, you can ask your AI assistant:
+
+**"Validate this LPC file with the actual driver"**
+→ AI uses `fluffos_validate` to run `symbol`
+
+**"Show me the bytecode for this function"**
+→ AI uses `fluffos_disassemble` to run `lpcc`
+
+**"Why is this code slow?"**
+→ AI examines the disassembly to identify inefficient patterns
+
+**"What's the syntax for call_out?"**
+→ AI uses `fluffos_doc_lookup` to search documentation
+
+**"How do I use mappings?"**
+→ AI searches docs for mapping-related documentation
+
+## How It Works
+
+```text
+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 assistant sends MCP tool requests
+2. Server spawns appropriate FluffOS CLI tool
+3. CLI tool validates/disassembles using the driver
+4. Server returns results to AI
+5. AI understands your code at the driver level and can reference FluffOS documentation to explain how functions work!
+
+## Implementation Details
+
+### Architecture
+
+The server is built using the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk) and follows a class-based architecture:
+
+- **FluffOSMCPServer class**: Main server implementation
+- **MCP SDK Server**: Handles protocol communication via stdio
+- **Child process spawning**: Executes FluffOS CLI tools
+- **Path normalization**: Converts absolute paths to mudlib-relative paths
+
+### Path Handling
+
+The server intelligently handles file paths:
+
+1. Parses `mudlib directory` from your FluffOS config file
+2. Normalizes absolute paths to mudlib-relative paths
+3. Passes normalized paths to FluffOS tools (which expect relative paths)
+
+Example: `/mud/ox/lib/std/object.c` → `std/object.c`
+
+### Tool Implementation
+
+**`fluffos_validate`**:
+
+- Spawns `symbol <config> <file>` from the config directory
+- Captures stdout/stderr
+- Returns success/failure with compilation errors
+- Exit code 0 = validation passed
+
+**`fluffos_disassemble`**:
+
+- Spawns `lpcc <config> <file>` from the config directory
+- Returns complete bytecode disassembly
+- Includes function tables, strings, and instruction-level detail
+
+**`fluffos_doc_lookup`** (optional):
+
+- Runs `scripts/search_docs.sh` helper script
+- Uses `grep` to search markdown files
+- Only available if `FLUFFOS_DOCS_DIR` is set
+
+### Error Handling
+
+- Validates required environment variables on startup
+- Returns structured error responses via MCP
+- Gracefully handles missing config or tool execution failures
+- Non-zero exit codes are reported but don't crash the server
+
+## Complementary Tools
+
+This server works great alongside:
+
+- **[lpc-mcp](https://github.com/gesslar/lpc-mcp)** - Language server integration for code intelligence
+- **VS Code with jlchmura's LPC extension** - IDE support
+
+Use them together for the complete LPC development experience!
+
+## Contributing
+
+PRs welcome! This is a simple wrapper that can be extended with more FluffOS tools.
+
+## Credits
+
+- **FluffOS Team** - For the amazing driver and CLI tools
+- [Model Context Protocol](https://modelcontextprotocol.io/) - Making this integration possible
+
+## License
+
+Unlicense - Public Domain. Do whatever you want with this code.

package/UNLICENSE.txt

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/eslint.config.js

@@ -0,0 +1,167 @@
+import js from "@eslint/js"
+import jsdoc from "eslint-plugin-jsdoc"
+import stylistic from "@stylistic/eslint-plugin"
+import globals from "globals"
+
+export default [
+  js.configs.recommended,
+  jsdoc.configs['flat/recommended'], {
+    name: "gesslar/uglier/ignores",
+    ignores: [],
+  }, {
+    name: "gesslar/uglier/languageOptions",
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: {
+        ...globals.node,
+        fetch: "readonly",
+        Headers: "readonly",
+      },
+    },
+  },
+  // Add override for webview files to include browser globals
+  {
+    name: "gesslar/uglier/webview-env",
+    files: ["src/webview/**/*.{js,mjs,cjs}"],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        acquireVsCodeApi: "readonly"
+      }
+    }
+  },
+  // Add override for .cjs files to treat as CommonJS
+  {
+    name: "gesslar/uglier/cjs-override",
+    files: ["src/**/*.cjs"],
+    languageOptions: {
+      sourceType: "script",
+      ecmaVersion: 2021
+    },
+  },
+  // Add override for .mjs files to treat as ES modules
+  {
+    name: "gesslar/uglier/mjs-override",
+    files: ["src/**/*.mjs"],
+    languageOptions: {
+      sourceType: "module",
+      ecmaVersion: 2021
+    }
+  },
+  {
+    name: "gesslar/uglier/lints-js",
+    files: ["{work,src}/**/*.{mjs,cjs,js}"],
+    plugins: {
+      "@stylistic": stylistic,
+    },
+    rules: {
+      "@stylistic/arrow-parens": ["error", "as-needed"],
+      "@stylistic/arrow-spacing": ["error", { before: true, after: true }],
+      "@stylistic/brace-style": ["error", "1tbs", {allowSingleLine: false}],
+      "@stylistic/nonblock-statement-body-position": ["error", "below"],
+      "@stylistic/padding-line-between-statements": [
+        "error",
+        {blankLine: "always",   prev: "if", next: "*"},
+        {blankLine: "always",   prev: "*", next: "return"},
+        {blankLine: "always",   prev: "while", next: "*"},
+        {blankLine: "always",   prev: "for", next: "*"},
+        {blankLine: "always",   prev: "switch", next: "*"},
+        {blankLine: "always",   prev: "do", next: "*"},
+        // {blankLine: "always",   prev: ["const", "let", "var"], next: "*"},
+        // {blankLine: "any",      prev: ["const", "let", "var"], next: ["const", "let", "var"]},
+        {blankLine: "always",   prev: "directive", next: "*" },
+        {blankLine: "any",      prev: "directive", next: "directive" },
+      ],
+      "@stylistic/eol-last": ["error", "always"],
+      "@stylistic/indent": ["error", 2, {
+        SwitchCase: 1 // Indents `case` statements one level deeper than `switch`
+      }],
+      "@stylistic/key-spacing": ["error", { beforeColon: false, afterColon: true }],
+      "@stylistic/keyword-spacing": ["error", {
+        before: false,
+        after: true,
+        overrides: {
+          // Control statements
+          return:  { before: true, after: true },
+          if:      { after: false },
+          else:    { before: true, after: true },
+          for:     { after: false },
+          while:   { before: true, after: false },
+          do:      { after: true },
+          switch:  { after: false },
+          case:    { before: true, after: true },
+          throw:   { before: true, after: false } ,
+
+          // Keywords
+          as:      { before: true, after: true },
+          of:      { before: true, after: true },
+          from:    { before: true, after: true },
+          async:   { before: true, after: true },
+          await:   { before: true, after: false },
+          class:   { before: true, after: true },
+          const:   { before: true, after: true },
+          let:     { before: true, after: true },
+          var:     { before: true, after: true },
+
+          // Exception handling
+          catch:   { before: true, after: true },
+          finally: { before: true, after: true },
+        }
+      }],
+      // Blocks
+      "@stylistic/space-before-blocks": ["error", "always"],
+      "@stylistic/max-len": ["warn", {
+        code: 80,
+        ignoreComments: true,
+        ignoreUrls: true,
+        ignoreStrings: true,
+        ignoreTemplateLiterals: true,
+        ignoreRegExpLiterals: true,
+        tabWidth: 2
+      }],
+      "@stylistic/no-tabs": "error",
+      "@stylistic/no-trailing-spaces": ["error"],
+      "@stylistic/object-curly-spacing": ["error", "never", {
+        objectsInObjects: false,
+        arraysInObjects: false
+      }],
+      "@stylistic/quotes": ["error", "double", {
+        avoidEscape: true,
+        allowTemplateLiterals: "always"
+      }],
+      "@stylistic/semi": ["error", "never"],
+      "@stylistic/space-before-function-paren": ["error", "never"],
+      "@stylistic/yield-star-spacing": ["error", { before: true, after: false }],
+      "constructor-super": "error",
+      "no-unexpected-multiline": "error",
+      "no-unused-vars": ["error", {
+        caughtErrors: "all",
+        caughtErrorsIgnorePattern: "^_+",
+        argsIgnorePattern: "^_+",
+        destructuredArrayIgnorePattern: "^_+",
+        varsIgnorePattern: "^_+"
+      }],
+      "no-useless-assignment": "error",
+      "prefer-const": "error",
+      "@stylistic/no-multiple-empty-lines": ["error", { max: 1 }],
+      "@stylistic/array-bracket-spacing": ["error", "never"],
+    }
+  },
+  {
+    name: "gesslar/uglier/lints-jsdoc",
+    files: ["{work,src}/**/*.{mjs,cjs,js}"],
+    plugins: {
+      jsdoc,
+    },
+    rules: {
+      "jsdoc/require-description": "error",
+      "jsdoc/tag-lines": ["error", "any", {"startLines":1}],
+      "jsdoc/require-jsdoc": ["error", { publicOnly: true }],
+      "jsdoc/check-tag-names": "error",
+      "jsdoc/check-types": "error",
+      "jsdoc/require-param-type": "error",
+      "jsdoc/require-returns-type": "error"
+    }
+  }
+]

package/index.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { spawn } from "child_process";
+import path from "path";
+import fs from "fs";
+
+class FluffOSMCPServer {
+  constructor() {
+    this.server = new Server(
+      {
+        name: "fluffos-mcp-server",
+        version: "0.1.0",
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.binDir = process.env.FLUFFOS_BIN_DIR;
+    this.configFile = process.env.MUD_RUNTIME_CONFIG_FILE;
+    this.docsDir = process.env.FLUFFOS_DOCS_DIR;
+
+    if (!this.binDir) {
+      console.error("Error: FLUFFOS_BIN_DIR environment variable not set");
+      process.exit(1);
+    }
+
+    if (!this.configFile) {
+      console.error("Error: MUD_RUNTIME_CONFIG_FILE environment variable not set");
+      process.exit(1);
+    }
+
+    // Parse mudlib directory from config file
+    this.mudlibDir = this.parseMudlibDir();
+
+    console.error(`FluffOS bin directory: ${this.binDir}`);
+    console.error(`FluffOS config file: ${this.configFile}`);
+    console.error(`Mudlib directory: ${this.mudlibDir || "(not found in config)"}`);
+    
+    if (this.docsDir) {
+      console.error(`FluffOS docs directory: ${this.docsDir}`);
+    } else {
+      console.error(`FluffOS docs directory: not set (doc lookup disabled)`);
+    }
+
+    this.setupHandlers();
+  }
+
+  parseMudlibDir() {
+    try {
+      const configContent = fs.readFileSync(this.configFile, "utf8");
+      const match = configContent.match(/^mudlib directory\s*:\s*(.+)$/m);
+      if (match) {
+        return match[1].trim();
+      }
+    } catch (err) {
+      console.error(`Warning: Could not parse mudlib directory from config: ${err.message}`);
+    }
+    return null;
+  }
+
+  normalizePath(lpcFile) {
+    // If we have a mudlib directory and the file path is absolute and starts with mudlib dir,
+    // convert it to a relative path
+    if (this.mudlibDir && path.isAbsolute(lpcFile) && lpcFile.startsWith(this.mudlibDir)) {
+      // Remove mudlib directory prefix and leading slash
+      return lpcFile.substring(this.mudlibDir.length).replace(/^\/+/, "");
+    }
+    // Otherwise return as-is (already relative or not under mudlib)
+    return lpcFile;
+  }
+
+  setupHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: [
+        {
+          name: "fluffos_validate",
+          description:
+            "Validate an LPC file using the FluffOS driver's symbol tool. Compiles the file and reports success or failure with any compilation errors. Fast and lightweight check for code validity.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              file: {
+                type: "string",
+                description: "Absolute path to the LPC file to validate",
+              },
+            },
+            required: ["file"],
+          },
+        },
+        {
+          name: "fluffos_disassemble",
+          description:
+            "Disassemble an LPC file to show compiled bytecode using lpcc. Returns detailed bytecode, function tables, strings, and disassembly. Useful for debugging and understanding how code compiles.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              file: {
+                type: "string",
+                description: "Absolute path to the LPC file to disassemble",
+              },
+            },
+            required: ["file"],
+          },
+        },
+        ...(this.docsDir ? [{
+          name: "fluffos_doc_lookup",
+          description:
+            "Search FluffOS documentation for information about efuns, applies, concepts, etc. Searches markdown documentation files.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description: "Term to search for in documentation (e.g., 'call_out', 'mapping', 'socket')",
+              },
+            },
+            required: ["query"],
+          },
+        }] : []),
+      ],
+    }));
+
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+
+      try {
+        switch (name) {
+          case "fluffos_validate": {
+            const result = await this.runSymbol(args.file);
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: result,
+                },
+              ],
+            };
+          }
+
+          case "fluffos_disassemble": {
+            const result = await this.runLpcc(args.file);
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: result,
+                },
+              ],
+            };
+          }
+
+          case "fluffos_doc_lookup": {
+            if (!this.docsDir) {
+              throw new Error("Documentation lookup is not available (FLUFFOS_DOCS_DIR not set)");
+            }
+            const result = await this.searchDocs(args.query);
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: result,
+                },
+              ],
+            };
+          }
+
+          default:
+            throw new Error(`Unknown tool: ${name}`);
+        }
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  async runSymbol(lpcFile) {
+    return new Promise((resolve, reject) => {
+      const normalizedPath = this.normalizePath(lpcFile);
+      const symbolPath = path.join(this.binDir, "symbol");
+      const proc = spawn(symbolPath, [this.configFile, normalizedPath], {
+        cwd: path.dirname(this.configFile),
+      });
+
+      let stdout = "";
+      let stderr = "";
+
+      proc.stdout.on("data", (data) => {
+        stdout += data.toString();
+      });
+
+      proc.stderr.on("data", (data) => {
+        stderr += data.toString();
+      });
+
+      proc.on("close", (code) => {
+        const output = (stdout + stderr).trim();
+        
+        if (code === 0) {
+          resolve(`✓ File validated successfully\n\n${output}`);
+        } else {
+          resolve(`✗ Validation failed (exit code: ${code})\n\n${output}`);
+        }
+      });
+
+      proc.on("error", (err) => {
+        reject(new Error(`Failed to run symbol: ${err.message}`));
+      });
+    });
+  }
+
+  async runLpcc(lpcFile) {
+    return new Promise((resolve, reject) => {
+      const normalizedPath = this.normalizePath(lpcFile);
+      const lpccPath = path.join(this.binDir, "lpcc");
+      const proc = spawn(lpccPath, [this.configFile, normalizedPath], {
+        cwd: path.dirname(this.configFile),
+      });
+
+      let stdout = "";
+      let stderr = "";
+
+      proc.stdout.on("data", (data) => {
+        stdout += data.toString();
+      });
+
+      proc.stderr.on("data", (data) => {
+        stderr += data.toString();
+      });
+
+      proc.on("close", (code) => {
+        const output = (stdout + stderr).trim();
+        
+        if (code === 0) {
+          resolve(output);
+        } else {
+          resolve(`Error (exit code: ${code}):\n\n${output}`);
+        }
+      });
+
+      proc.on("error", (err) => {
+        reject(new Error(`Failed to run lpcc: ${err.message}`));
+      });
+    });
+  }
+
+  async searchDocs(query) {
+    return new Promise((resolve, reject) => {
+      const scriptPath = path.join(path.dirname(new URL(import.meta.url).pathname), "scripts", "search_docs.sh");
+      const proc = spawn(scriptPath, [this.docsDir, query]);
+
+      let stdout = "";
+      let stderr = "";
+
+      proc.stdout.on("data", (data) => {
+        stdout += data.toString();
+      });
+
+      proc.stderr.on("data", (data) => {
+        stderr += data.toString();
+      });
+
+      proc.on("close", (code) => {
+        if (code === 0) {
+          if (stdout.trim()) {
+            resolve(`Found documentation for "${query}":\n\n${stdout}`);
+          } else {
+            resolve(`No documentation found for "${query}".`);
+          }
+        } else {
+          resolve(`Error searching documentation:\n${stderr || stdout}`);
+        }
+      });
+
+      proc.on("error", (err) => {
+        reject(new Error(`Failed to search docs: ${err.message}`));
+      });
+    });
+  }
+
+  async run() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+
+    console.error("FluffOS MCP Server running on stdio");
+  }
+}
+
+const server = new FluffOSMCPServer();
+server.run().catch(console.error);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@gesslar/fluffos-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for FluffOS driver tools - validate and disassemble LPC code",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "fluffos-mcp": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "submit": "npm publish --access public",
+    "update": "npx npm-check-updates -u && npm install",
+    "pr": "gt submit --publish --restack --ai -m",
+    "patch": "npm version patch",
+    "minor": "npm version minor",
+    "major": "npm version major"
+  },
+  "keywords": [
+    "fluffos",
+    "lpc",
+    "mud",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "author": "gesslar",
+  "license": "Unlicense",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gesslar/fluffos-mcp.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.0",
+    "@stylistic/eslint-plugin": "^5.5.0",
+    "eslint-plugin-jsdoc": "^61.1.11",
+    "globals": "^16.5.0"
+  }
+}

package/scripts/search_docs.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# search_docs.sh - Search FluffOS documentation
+# Usage: search_docs.sh <docs_dir> <query>
+
+DOCS_DIR="$1"
+QUERY="$2"
+
+if [ -z "$DOCS_DIR" ] || [ -z "$QUERY" ]; then
+    echo "Usage: $0 <docs_dir> <query>"
+    exit 1
+fi
+
+if [ ! -d "$DOCS_DIR" ]; then
+    echo "Error: Documentation directory does not exist: $DOCS_DIR"
+    exit 1
+fi
+
+# Search for the query in markdown files, showing filename and context
+# Use ripgrep if available, otherwise fall back to grep
+if command -v rg &> /dev/null; then
+    rg --type md -i -C 3 --heading --color never "$QUERY" "$DOCS_DIR"
+else
+    grep -r -i --include="*.md" -H -C 3 "$QUERY" "$DOCS_DIR"
+fi

package/src/index.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+
+import {Server} from "@modelcontextprotocol/sdk/server/index.js"
+import {StdioServerTransport} from "@modelcontextprotocol/sdk/server/stdio.js"
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js"
+import {spawn} from "child_process"
+import path from "path"
+import fs from "fs"
+
+class FluffOSMCPServer {
+  constructor() {
+    this.server = new Server(
+      {
+        name: "fluffos-mcp-server",
+        version: "0.1.0",
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    )
+
+    this.binDir = process.env.FLUFFOS_BIN_DIR
+    this.configFile = process.env.MUD_RUNTIME_CONFIG_FILE
+    this.docsDir = process.env.FLUFFOS_DOCS_DIR
+    this.mudlibDir = null
+
+    if(!this.binDir) {
+      console.error("Error: FLUFFOS_BIN_DIR environment variable not set")
+      process.exit(1)
+    }
+
+    if(!this.configFile) {
+      console.error("Error: MUD_RUNTIME_CONFIG_FILE environment variable not set")
+      process.exit(1)
+    }
+
+    // Parse mudlib directory from config file
+    this.mudlibDir = this.parseMudlibDir()
+
+    console.error(`FluffOS bin directory: ${this.binDir}`)
+    console.error(`FluffOS config file: ${this.configFile}`)
+    console.error(`Mudlib directory: ${this.mudlibDir || "(not found in config)"}`)
+
+    if(this.docsDir) {
+      console.error(`FluffOS docs directory: ${this.docsDir}`)
+    } else {
+      console.error(`FluffOS docs directory: not set (doc lookup disabled)`)
+    }
+
+    this.setupHandlers()
+  }
+
+  parseMudlibDir() {
+    try {
+      const configContent = fs.readFileSync(this.configFile, "utf8")
+      const match = configContent.match(/^mudlib directory\s*:\s*(.+)$/m)
+      if(match) {
+        return match[1].trim()
+      }
+    } catch(err) {
+      console.error(`Warning: Could not parse mudlib directory from config: ${err.message}`)
+    }
+
+    return null
+  }
+
+  normalizePath(lpcFile) {
+    // If we have a mudlib directory and the file path is absolute and starts with mudlib dir,
+    // convert it to a relative path
+    if(this.mudlibDir &&
+      path.isAbsolute(lpcFile) &&
+      lpcFile.startsWith(this.mudlibDir)
+    ) {
+      // Remove mudlib directory prefix and leading slash
+      return lpcFile.substring(this.mudlibDir.length).replace(/^\/+/, "")
+    }
+
+    // Otherwise return as-is (already relative or not under mudlib)
+    return lpcFile
+  }
+
+  setupHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async() => ({
+      tools: [
+        {
+          name: "fluffos_validate",
+          description:
+            "Validate an LPC file using the FluffOS driver's symbol tool. " +
+            "Compiles the file and reports success or failure with any " +
+            "compilation errors. Fast and lightweight check for code validity.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              file: {
+                type: "string",
+                description: "Absolute path to the LPC file to validate",
+              },
+            },
+            required: ["file"],
+          },
+        },
+        {
+          name: "fluffos_disassemble",
+          description:
+            "Disassemble an LPC file to show compiled bytecode using lpcc. Returns detailed bytecode, function tables, strings, and disassembly. Useful for debugging and understanding how code compiles.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              file: {
+                type: "string",
+                description: "Absolute path to the LPC file to disassemble",
+              },
+            },
+            required: ["file"],
+          },
+        },
+        ...(this.docsDir ? [{
+          name: "fluffos_doc_lookup",
+          description:
+            "Search FluffOS documentation for information about efuns, applies, concepts, etc. Searches markdown documentation files.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description: "Term to search for in documentation (e.g., 'call_out', 'mapping', 'socket')",
+              },
+            },
+            required: ["query"],
+          },
+        }] : []),
+      ],
+    }))
+
+    this.server.setRequestHandler(CallToolRequestSchema, async request => {
+      const {name, arguments: args} = request.params
+
+      try {
+        switch(name) {
+          case "fluffos_validate": {
+            const result = await this.runSymbol(args.file)
+
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: result,
+                },
+              ],
+            }
+          }
+
+          case "fluffos_disassemble": {
+            const result = await this.runLpcc(args.file)
+
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: result,
+                },
+              ],
+            }
+          }
+
+          case "fluffos_doc_lookup": {
+            if(!this.docsDir) {
+              throw new Error("Documentation lookup is not available (FLUFFOS_DOCS_DIR not set)")
+            }
+
+            const result = await this.searchDocs(args.query)
+
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: result,
+                },
+              ],
+            }
+          }
+
+          default:
+            throw new Error(`Unknown tool: ${name}`)
+        }
+      } catch(error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${error.message}`,
+            },
+          ],
+          isError: true,
+        }
+      }
+    })
+  }
+
+  async runSymbol(lpcFile) {
+    return new Promise((resolve, reject) => {
+      const normalizedPath = this.normalizePath(lpcFile)
+      const symbolPath = path.join(this.binDir, "symbol")
+      const proc = spawn(symbolPath, [this.configFile, normalizedPath], {
+        cwd: path.dirname(this.configFile),
+      })
+
+      let stdout = ""
+      let stderr = ""
+
+      proc.stdout.on("data", data => {
+        stdout += data.toString()
+      })
+
+      proc.stderr.on("data", data => {
+        stderr += data.toString()
+      })
+
+      proc.on("close", code => {
+        const output = (stdout + stderr).trim()
+
+        if(code === 0) {
+          resolve(`✓ File validated successfully\n\n${output}`)
+        } else {
+          resolve(`✗ Validation failed (exit code: ${code})\n\n${output}`)
+        }
+      })
+
+      proc.on("error", err => {
+        reject(new Error(`Failed to run symbol: ${err.message}`))
+      })
+    })
+  }
+
+  async runLpcc(lpcFile) {
+    return new Promise((resolve, reject) => {
+      const normalizedPath = this.normalizePath(lpcFile)
+      const lpccPath = path.join(this.binDir, "lpcc")
+      const proc = spawn(lpccPath, [this.configFile, normalizedPath], {
+        cwd: path.dirname(this.configFile),
+      })
+
+      let stdout = ""
+      let stderr = ""
+
+      proc.stdout.on("data", data => {
+        stdout += data.toString()
+      })
+
+      proc.stderr.on("data", data => {
+        stderr += data.toString()
+      })
+
+      proc.on("close", code => {
+        const output = (stdout + stderr).trim()
+
+        if(code === 0) {
+          resolve(output)
+        } else {
+          resolve(`Error (exit code: ${code}):\n\n${output}`)
+        }
+      })
+
+      proc.on("error", err => {
+        reject(new Error(`Failed to run lpcc: ${err.message}`))
+      })
+    })
+  }
+
+  async searchDocs(query) {
+    return new Promise((resolve, reject) => {
+      const scriptPath = path.join(path.dirname(new URL(import.meta.url).pathname), "scripts", "search_docs.sh")
+      const proc = spawn(scriptPath, [this.docsDir, query])
+
+      let stdout = ""
+      let stderr = ""
+
+      proc.stdout.on("data", data => {
+        stdout += data.toString()
+      })
+
+      proc.stderr.on("data", data => {
+        stderr += data.toString()
+      })
+
+      proc.on("close", code => {
+        if(code === 0) {
+          if(stdout.trim()) {
+            resolve(`Found documentation for "${query}":\n\n${stdout}`)
+          } else {
+            resolve(`No documentation found for "${query}".`)
+          }
+        } else {
+          resolve(`Error searching documentation:\n${stderr || stdout}`)
+        }
+      })
+
+      proc.on("error", err => {
+        reject(new Error(`Failed to search docs: ${err.message}`))
+      })
+    })
+  }
+
+  async run() {
+    const transport = new StdioServerTransport()
+    await this.server.connect(transport)
+
+    console.error("FluffOS MCP Server running on stdio")
+  }
+}
+
+const server = new FluffOSMCPServer()
+server.run().catch(console.error)