@biorand/reframework-mcp 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BioRand Team.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @biorand/reframework-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for running Lua inside RE Engine games via
+[REFramework](https://github.com/praydog/REFramework).
+
+## Add to your MCP servers
+
+```json
+{
+  "mcpServers": {
+    "reframework": {
+      "command": "npx",
+      "args": ["-y", "@biorand/reframework-mcp"]
+    }
+  }
+}
+```
+
+Pin a version if you want reproducible setups, e.g. `"@biorand/reframework-mcp@1.1.0"`.
+
+## Setup
+
+`REF_DATA_DIR` is optional. On first use, ask your agent to run the `install_bridge`
+tool with your game install directory (e.g. `C:\Games\RE9`). It installs the Lua
+bridge into `reframework\autorun`, points the server at `reframework\data`, and
+remembers the choice. Reload the Lua scripts in-game (REFramework menu →
+ScriptRunner → Reset Scripts, or restart the game) after the bridge is installed
+or updated.
+
+You can also set the environment variable explicitly when registering the server:
+
+```json
+"env": {
+  "REF_DATA_DIR": "C:\\Games\\RE9\\reframework\\data"
+}
+```
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `execute_code` | Execute Lua inside a running game via REFramework. |
+| `install_bridge` | Install/update the Lua bridge in a game and activate its data directory. |
+| `set_data_dir` | Point the server at an existing `reframework\data` directory. |
+
+## Requirements
+
+- Node.js 18+
+- A supported RE Engine game with REFramework installed
+
+See the [repository README](https://github.com/biorand/reframework-mcp) for the
+full documentation, environment variables and troubleshooting.

package/dist/index.js

@@ -0,0 +1,531 @@
+#!/usr/bin/env node
+/**
+ * REFramework MCP Server
+ *
+ * Tools:
+ *   execute_code   – run Lua inside a running RE Engine game via REFramework
+ *   install_bridge – install the bundled mcp.lua into a game's reframework\autorun
+ *   set_data_dir   – configure (and remember) the reframework\data directory
+ *
+ * Workflow (execute_code):
+ *   1. Write Lua code to <dataDir>/mcp_input.lua
+ *   2. Poll until the file is empty (the in-game bridge blanks it after running)
+ *   3. Read <dataDir>/mcp_output.txt and return its contents
+ *
+ * Configuration (env vars):
+ *   REF_DATA_DIR   – absolute path to the reframework/data folder (optional; if
+ *                    omitted the agent can set it with install_bridge/set_data_dir
+ *                    and the choice is persisted between server starts)
+ *   POLL_INTERVAL  – ms between polls while waiting   (default: 500)
+ *   POLL_TIMEOUT   – ms before giving up              (default: 30000)
+ *   REF_MCP_CONFIG – override the persisted config file location
+ *   REF_MCP_LUA    – override the bundled mcp.lua source path
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import fs from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// ── config ────────────────────────────────────────────────────────────────────
+const POLL_INTERVAL = Number(process.env.POLL_INTERVAL ?? 500);
+const POLL_TIMEOUT = Number(process.env.POLL_TIMEOUT ?? 30_000);
+/**
+ * Marker written into mcp_input.lua and echoed into mcp_output.txt so output
+ * can be matched to the request that produced it.
+ */
+const REQUEST_ID_PATTERN = /refmcp_request_id:\s*([A-Za-z0-9-]+)/;
+/** File where the runtime data-dir choice is persisted between server starts. */
+const CONFIG_PATH = process.env.REF_MCP_CONFIG ??
+    (process.platform === "win32"
+        ? path.join(process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"), "reframework-mcp", "config.json")
+        : path.join(process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config"), "reframework-mcp", "config.json"));
+function loadConfig() {
+    try {
+        const parsed = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+        if (parsed && typeof parsed === "object") {
+            const { dataDir } = parsed;
+            if (typeof dataDir === "string" && dataDir)
+                return { dataDir };
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+const envDataDir = process.env.REF_DATA_DIR ? path.resolve(process.env.REF_DATA_DIR) : null;
+const savedDataDir = loadConfig().dataDir;
+/** Active data directory; null until configured via env, config file or a tool. */
+let dataDir = envDataDir ?? (savedDataDir ? path.resolve(savedDataDir) : null);
+async function persistDataDir(dir) {
+    try {
+        const config = loadConfig();
+        config.dataDir = dir;
+        await fs.mkdir(path.dirname(CONFIG_PATH), { recursive: true });
+        await fs.writeFile(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", "utf8");
+        return true;
+    }
+    catch (err) {
+        process.stderr.write(`[reframework-mcp] warning: could not save config to ${CONFIG_PATH}: ${String(err)}\n`);
+        return false;
+    }
+}
+function requireDataDir() {
+    if (!dataDir) {
+        throw new Error("No reframework data directory is configured.\n" +
+            "  • If REFramework is already installed, call set_data_dir with the game install " +
+            "directory (e.g. C:\\Games\\RE9) or with <game>\\reframework\\data.\n" +
+            "  • Otherwise call install_bridge with the game install directory to install the " +
+            "Lua bridge and configure this automatically.\n" +
+            "Alternatively set REF_DATA_DIR when registering this MCP server.");
+    }
+    return dataDir;
+}
+// ── helpers ───────────────────────────────────────────────────────────────────
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Read a file, returning "" if it doesn't exist yet.
+ */
+async function readSafe(filePath) {
+    try {
+        return await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+async function isFile(filePath) {
+    try {
+        return (await fs.stat(filePath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function isDir(filePath) {
+    try {
+        return (await fs.stat(filePath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True when a directory looks like a reframework folder: named "reframework",
+ * or containing an autorun/plugins folder.
+ */
+async function isReframeworkDir(dir) {
+    if (path.basename(dir).toLowerCase() === "reframework" && (await isDir(dir)))
+        return true;
+    return (await isDir(path.join(dir, "autorun"))) || (await isDir(path.join(dir, "plugins")));
+}
+/**
+ * Turn a user-supplied path (game install dir, reframework dir, data dir or any
+ * path inside the game tree) into the reframework\data directory.
+ * Creates the data folder when REFramework exists but the game hasn't started once.
+ */
+async function resolveDataDir(input) {
+    let base = path.resolve(input);
+    if (await isFile(base))
+        base = path.dirname(base);
+    const baseName = path.basename(base).toLowerCase();
+    // The data directory itself was passed; create it when the parent is a
+    // reframework folder and the game has not created it yet.
+    if (baseName === "data" && (await isReframeworkDir(path.dirname(base)))) {
+        if (!(await isDir(base)))
+            await fs.mkdir(base, { recursive: true });
+        return base;
+    }
+    if (!(await isDir(base))) {
+        throw new Error(`"${base}" does not exist. Pass the game install directory (e.g. C:\\Games\\RE9), ` +
+            `the reframework directory, or the reframework\\data directory.`);
+    }
+    // A data directory with an unusual name (it already holds MCP files).
+    if ((await isFile(path.join(base, "mcp_input.lua"))) ||
+        (await isFile(path.join(base, "mcp_output.txt")))) {
+        return base;
+    }
+    // The game install directory was passed: <base>\reframework\data
+    if (await isDir(path.join(base, "reframework"))) {
+        const dataPath = path.join(base, "reframework", "data");
+        await fs.mkdir(dataPath, { recursive: true });
+        return dataPath;
+    }
+    // Any other path inside the game tree (e.g. the autorun folder): walk up to
+    // the game install directory.
+    const gameRoot = await findGameRoot(base);
+    if (gameRoot) {
+        const dataPath = path.join(gameRoot, "reframework", "data");
+        await fs.mkdir(dataPath, { recursive: true });
+        return dataPath;
+    }
+    throw new Error(`Could not find a reframework\\data directory from "${base}".\n` +
+        `Pass one of:\n` +
+        `  - the game install directory (the folder containing the game .exe)\n` +
+        `  - the reframework directory\n` +
+        `  - the data directory itself\n` +
+        `  - any path inside the game install directory\n` +
+        `If REFramework is not installed yet, call install_bridge instead.`);
+}
+/**
+ * Health check for a resolved data directory. Returns a short human-readable
+ * note (or warning) about what was found around it.
+ */
+async function describeDataDir(dir) {
+    const refDir = path.dirname(dir);
+    const autorunDir = path.join(refDir, "autorun");
+    const hasReframework = (await isDir(autorunDir)) || (await isDir(path.join(refDir, "plugins")));
+    if (!hasReframework) {
+        return (`Warning: this does not look like a reframework\\data directory ` +
+            `(no autorun or plugins folder found in "${refDir}"). ` +
+            `Make sure REFramework is installed and the path is correct.`);
+    }
+    const bridge = path.join(autorunDir, "mcp.lua");
+    return (await isFile(bridge))
+        ? `Lua bridge found at ${bridge}.`
+        : `Lua bridge (mcp.lua) not found in ${autorunDir} - call install_bridge to install it.`;
+}
+/**
+ * Walk up from a path until a directory containing a "reframework" folder is
+ * found (the game install directory). Returns null when there is none.
+ */
+async function findGameRoot(start) {
+    let dir = path.resolve(start);
+    if (await isFile(dir))
+        dir = path.dirname(dir);
+    while (true) {
+        if (await isDir(path.join(dir, "reframework")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+const KNOWN_GAME_EXES = ["re9.exe", "re8.exe", "re7.exe", "re4.exe", "re3.exe", "re2.exe"];
+/** Best-effort detection of the game executable, for friendlier messages. */
+async function findGameExe(gameRoot) {
+    let entries;
+    try {
+        entries = await fs.readdir(gameRoot);
+    }
+    catch {
+        return null;
+    }
+    const byLower = new Map(entries.map((entry) => [entry.toLowerCase(), entry]));
+    for (const known of KNOWN_GAME_EXES) {
+        const found = byLower.get(known);
+        if (found)
+            return found;
+    }
+    for (const [lower, original] of byLower) {
+        if (/^re[0-9].*\.exe$/.test(lower))
+            return original;
+    }
+    return null;
+}
+/** Candidate locations of the bundled Lua bridge source. */
+function luaSourceCandidates() {
+    const candidates = [
+        process.env.REF_MCP_LUA,
+        path.join(__dirname, "..", "..", "lua", "mcp.lua"), // repo layout: ts/dist -> lua/mcp.lua (live edits win)
+        path.join(__dirname, "mcp.lua"), // copied next to dist/index.js by the build (packaged)
+        path.join(__dirname, "..", "lua", "mcp.lua"),
+    ];
+    return candidates.filter((candidate) => Boolean(candidate));
+}
+async function findLuaSource() {
+    for (const candidate of luaSourceCandidates()) {
+        if (await isFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+/** Checklist-style error for a timed-out execute_code call. */
+async function buildTimeoutError(inputPath) {
+    const refDir = path.dirname(path.dirname(inputPath));
+    const bridgePath = path.join(refDir, "autorun", "mcp.lua");
+    const bridgeHint = (await isFile(bridgePath))
+        ? `Lua bridge found at ${bridgePath}.`
+        : `Lua bridge NOT found at ${bridgePath} - call install_bridge to install it.`;
+    return new Error(`Timed out after ${POLL_TIMEOUT} ms waiting for the Lua bridge to consume the input file.\n` +
+        `Checklist:\n` +
+        `  1. The game is running with REFramework loaded.\n` +
+        `  2. ${bridgeHint}\n` +
+        `  3. If the bridge was just installed or updated, reload the Lua scripts in-game ` +
+        `(REFramework menu > ScriptRunner > Reset Scripts) or restart the game.\n` +
+        `  4. Look for "[mcp]" messages in the REFramework log (in the game directory).`);
+}
+// ── tool implementations ──────────────────────────────────────────────────────
+// Tool calls share state (the input/output files, the active data dir and the
+// config file), so run them one at a time.
+let queue = Promise.resolve();
+function enqueue(task) {
+    const result = queue.then(task);
+    queue = result.then(() => undefined, () => undefined);
+    return result;
+}
+async function executeCode(code) {
+    const dir = requireDataDir();
+    const inputPath = path.join(dir, "mcp_input.lua");
+    const outputPath = path.join(dir, "mcp_output.txt");
+    const requestId = randomUUID();
+    const stampedCode = `-- refmcp_request_id: ${requestId}\n${code}`;
+    const deadline = Date.now() + POLL_TIMEOUT;
+    for (;;) {
+        // 1. Write the Lua code to the input file.
+        try {
+            await fs.writeFile(inputPath, stampedCode, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw new Error(`Data directory "${dir}" does not exist. ` +
+                    `Call set_data_dir again with a valid path (or install_bridge).`);
+            }
+            throw err;
+        }
+        // 2. Wait for the bridge to blank the file (signals execution done).
+        let consumed = false;
+        while (Date.now() < deadline) {
+            await sleep(POLL_INTERVAL);
+            const content = await readSafe(inputPath);
+            if (content.trim() === "") {
+                consumed = true;
+                break;
+            }
+        }
+        if (!consumed) {
+            // Clear the stale input so a bridge starting later does not execute it.
+            await fs.writeFile(inputPath, "", "utf8").catch(() => undefined);
+            throw await buildTimeoutError(inputPath);
+        }
+        // 3. Read the output and make sure it belongs to this request. If the
+        // bridge consumed a stale script it wipes our input before it runs, so on
+        // a request-id mismatch write our code again and keep waiting. Output
+        // without a request id comes from an older bridge and is accepted as-is.
+        const output = await readSafe(outputPath);
+        const outputId = output.match(REQUEST_ID_PATTERN)?.[1];
+        if (outputId === undefined || outputId === requestId) {
+            return output.trim() === ""
+                ? "(no output written – check the REFramework logs)"
+                : output;
+        }
+        process.stderr.write(`[reframework-mcp] warning: bridge consumed a stale script (output request ${outputId}); retrying\n`);
+    }
+}
+async function installBridge(input) {
+    let searchedFrom;
+    if (input) {
+        const abs = path.resolve(input);
+        if (!(await isDir(abs)) && !(await isFile(abs))) {
+            throw new Error(`"${abs}" does not exist. Pass the game install directory (the folder containing ` +
+                `the game .exe), the reframework folder, or a path inside them.`);
+        }
+        searchedFrom = abs;
+    }
+    else if (dataDir) {
+        searchedFrom = dataDir;
+    }
+    else {
+        throw new Error("Where is the game installed? Pass the game install directory, e.g. " +
+            `install_bridge with path "C:\\Games\\RE9".`);
+    }
+    const gameRoot = await findGameRoot(searchedFrom);
+    if (!gameRoot) {
+        const startMissing = !(await isDir(searchedFrom)) && !(await isFile(searchedFrom));
+        throw new Error((startMissing
+            ? `"${searchedFrom}" does not exist, and no "reframework" folder was found at or ` +
+                `above it.\n`
+            : `REFramework does not appear to be installed at or above "${searchedFrom}".\n`) +
+            `I looked for a "reframework" folder in the game install directory (next to the ` +
+            `game .exe) and its parents.\n` +
+            `Install REFramework first: download a release, then extract dinput8.dll and the ` +
+            `reframework folder into the game install directory.\n` +
+            `  https://github.com/praydog/REFramework-nightly/releases`);
+    }
+    const refDir = path.join(gameRoot, "reframework");
+    const autorunDir = path.join(refDir, "autorun");
+    const targetPath = path.join(autorunDir, "mcp.lua");
+    const source = await findLuaSource();
+    if (!source) {
+        throw new Error("Could not find the bundled mcp.lua bridge source.\nLooked in:\n" +
+            luaSourceCandidates().map((candidate) => `  ${candidate}`).join("\n") +
+            "\nRebuild the server (npm run build) or set REF_MCP_LUA to its path.");
+    }
+    // Install (or refresh) the bridge script.
+    await fs.mkdir(autorunDir, { recursive: true });
+    const sourceCode = await fs.readFile(source, "utf8");
+    const previous = await readSafe(targetPath);
+    let action;
+    if (previous === sourceCode) {
+        action = "already up to date";
+    }
+    else {
+        await fs.writeFile(targetPath, sourceCode, "utf8");
+        action = previous ? "updated" : "copied";
+    }
+    // Make sure the data directory exists and activate it.
+    const gameDataDir = path.join(refDir, "data");
+    await fs.mkdir(gameDataDir, { recursive: true });
+    dataDir = gameDataDir;
+    const persisted = await persistDataDir(gameDataDir);
+    const exe = await findGameExe(gameRoot);
+    const lines = [
+        `Lua bridge ${action}.`,
+        `  game install : ${gameRoot}`,
+    ];
+    if (exe)
+        lines.push(`  game exe     : ${exe}`);
+    lines.push(`  bridge file  : ${targetPath}`, `  source       : ${source}`, `  data dir     : ${gameDataDir} (active)`);
+    if (envDataDir && !samePath(envDataDir, gameDataDir)) {
+        lines.push(`  note         : REF_DATA_DIR=${envDataDir} takes over again after a restart`);
+    }
+    else if (persisted) {
+        lines.push(`  note         : saved to ${CONFIG_PATH}; future server starts use it automatically`);
+    }
+    else {
+        lines.push(`Warning: could not save the active data dir to ${CONFIG_PATH}; it will not survive a restart.`);
+    }
+    if (!(await isFile(path.join(gameRoot, "dinput8.dll")))) {
+        lines.push(`Warning: no dinput8.dll found next to the game .exe. If REFramework is not set up ` +
+            `correctly the bridge will never load.`);
+    }
+    if (action === "already up to date") {
+        lines.push("The bridge is already current. Use execute_code once the game is running.");
+    }
+    else {
+        lines.push("ACTION REQUIRED: Tell the user the Lua bridge was just installed/updated and they must " +
+            "reload the Lua plugins in-game before execute_code will work (open the REFramework menu " +
+            "and use ScriptRunner -> Reset Scripts, or simply restart the game). " +
+            "The bridge is only loaded on a script reload.");
+    }
+    return lines.join("\n");
+}
+function samePath(a, b) {
+    const na = path.resolve(a);
+    const nb = path.resolve(b);
+    return process.platform === "win32" ? na.toLowerCase() === nb.toLowerCase() : na === nb;
+}
+async function setDataDir(input) {
+    const dir = await resolveDataDir(input);
+    dataDir = dir;
+    const persisted = await persistDataDir(dir);
+    const lines = [`Data directory set to ${dir}.`, await describeDataDir(dir)];
+    if (envDataDir) {
+        lines.push(`Note: REF_DATA_DIR is set to ${envDataDir} and will take over again after a restart ` +
+            `(update the env value to make this permanent).`);
+    }
+    else if (persisted) {
+        lines.push(`Saved to ${CONFIG_PATH} - future server starts use it automatically.`);
+    }
+    else {
+        lines.push(`Warning: could not save the choice to ${CONFIG_PATH}; it will not survive a restart.`);
+    }
+    return lines.join("\n");
+}
+// ── server setup ──────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "reframework",
+    version: "1.1.0",
+});
+server.tool("execute_code", "Execute Lua code inside a running RE Engine game via REFramework. " +
+    "The code runs in the game process and has full access to REFramework APIs " +
+    "(sdk, re, log, fs, json, imgui, draw). " +
+    "Use print() to produce output; the final return value is also captured. " +
+    "Requires mcp.lua installed in the game's reframework/autorun folder and a configured " +
+    "data directory (use install_bridge or set_data_dir if needed).", {
+    code: z
+        .string()
+        .min(1)
+        .describe("Lua source code to execute inside the game"),
+}, async ({ code }) => {
+    try {
+        const output = await enqueue(() => executeCode(code));
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `[MCP error] ${message}` }],
+            isError: true,
+        };
+    }
+});
+server.tool("set_data_dir", "Set the reframework/data directory used by execute_code. Call this when REFramework is " +
+    "already installed but the server was started without REF_DATA_DIR. Accepts the game " +
+    "install directory (e.g. C:\\Games\\RE9), the reframework directory, or the data " +
+    "directory itself. The choice is remembered for future server starts unless REF_DATA_DIR " +
+    "is set.", {
+    path: z
+        .string()
+        .min(1)
+        .describe("Game install directory, reframework directory, or reframework/data directory (absolute path)"),
+}, async ({ path: input }) => {
+    try {
+        const output = await enqueue(() => setDataDir(input));
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `[MCP error] ${message}` }],
+            isError: true,
+        };
+    }
+});
+server.tool("install_bridge", "Install the REFramework Lua bridge (mcp.lua) into a game so execute_code can run. " +
+    "Copies the bundled mcp.lua to <game>\\reframework\\autorun\\mcp.lua, creates the " +
+    "<game>\\reframework\\data directory and makes it the active data directory. " +
+    "Accepts the game install directory (e.g. C:\\Games\\RE9), the reframework directory, " +
+    "or a path inside them; when omitted, the currently configured data directory is used. " +
+    "Fails with instructions if REFramework is not installed at the given location. " +
+    "When the bridge is copied or updated, tell the user to reload the Lua scripts in-game " +
+    "(or restart the game) so the new bridge actually loads.", {
+    path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Game install directory, reframework directory, or a path inside them (absolute path)"),
+}, async ({ path: input }) => {
+    try {
+        const output = await enqueue(() => installBridge(input));
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `[MCP error] ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ── entry point ───────────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // MCP servers communicate over stdio; log to stderr so it doesn't corrupt the stream.
+    process.stderr.write(`[reframework-mcp] ready\n` +
+        `  data dir : ${dataDir ?? "(not set - use the set_data_dir or install_bridge tool)"}\n` +
+        `  config   : ${CONFIG_PATH}\n` +
+        `  poll     : every ${POLL_INTERVAL} ms, timeout ${POLL_TIMEOUT} ms\n`);
+    if (dataDir && !(await isDir(dataDir))) {
+        process.stderr.write(`[reframework-mcp] warning: data dir ${dataDir} does not exist yet\n`);
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`[reframework-mcp] fatal: ${err}\n`);
+    process.exit(1);
+});

package/dist/mcp.lua

@@ -0,0 +1,167 @@
+-- mcp.lua
+-- Place in: reframework/autorun/mcp.lua
+--
+-- Polls for reframework/data/mcp_input.lua every second.
+-- When found, executes its contents in a sandboxed environment,
+-- captures print() output + return values + errors,
+-- writes everything to reframework/data/mcp_output.txt,
+-- then blanks the input file so it doesn't re-run.
+--
+-- The input may carry a "refmcp_request_id" marker (first line, written by the
+-- MCP server). It is echoed into the output header so the server can match the
+-- output to the request that produced it.
+
+local INPUT_FILE     = "mcp_input.lua"
+local OUTPUT_FILE    = "mcp_output.txt"
+local CHECK_INTERVAL = 60 -- frames between polls (~1 s at 60 fps)
+
+local frame_count    = 0
+
+-- ── helpers ──────────────────────────────────────────────────────────────────
+
+-- Serialize any value to a human-readable string (handles tables recursively).
+local function serialize(val, depth)
+    depth = depth or 0
+    local indent = string.rep("  ", depth)
+
+    local t = type(val)
+    if t == "nil" then
+        return "nil"
+    elseif t == "boolean" or t == "number" then
+        return tostring(val)
+    elseif t == "string" then
+        return string.format("%q", val)
+    elseif t == "table" then
+        if depth > 4 then return "{...}" end -- guard against deep nesting
+        local parts = {}
+        for k, v in pairs(val) do
+            local key_str = (type(k) == "string")
+                and k
+                or ("[" .. tostring(k) .. "]")
+            parts[#parts + 1] = indent .. "  " .. key_str .. " = " .. serialize(v, depth + 1)
+        end
+        if #parts == 0 then return "{}" end
+        return "{\n" .. table.concat(parts, ",\n") .. "\n" .. indent .. "}"
+    else
+        -- userdata, function, thread, etc.
+        return "<" .. t .. ": " .. tostring(val) .. ">"
+    end
+end
+
+-- Extract the request id marker written by the MCP server, if present.
+local function get_request_id(source)
+    return source:match("^%-%- refmcp_request_id: ([%w%-]+)") or "none"
+end
+
+-- Run a Lua source string in a restricted env, return {output, error}.
+local function execute_script(source)
+    local captured_lines = {}
+
+    -- Sandboxed environment that shares the REFramework globals but
+    -- redirects print() so we can capture it.
+    local env = setmetatable({
+        print    = function(...)
+            local args = { ... }
+            local parts = {}
+            for i = 1, #args do
+                parts[i] = serialize(args[i])
+            end
+            captured_lines[#captured_lines + 1] = table.concat(parts, "\t")
+        end,
+        tostring = tostring,
+        tonumber = tonumber,
+        type     = type,
+        pairs    = pairs,
+        ipairs   = ipairs,
+        next     = next,
+        select   = select,
+        unpack   = table.unpack or unpack,
+        error    = error,
+        pcall    = pcall,
+        xpcall   = xpcall,
+        assert   = assert,
+        string   = string,
+        table    = table,
+        math     = math,
+        -- Expose REFramework APIs so scripts can actually use them:
+        sdk      = sdk,
+        re       = re,
+        log      = log,
+        fs       = fs,
+        json     = json,
+        imgui    = imgui,
+        draw     = draw,
+        -- Expose full _G for power users (they can break their own sandbox).
+        _G       = _G,
+    }, { __index = _G })
+
+    local chunk, load_err = load(source, "mcp_input", "t", env)
+    if not chunk then
+        return nil, "Syntax/load error: " .. tostring(load_err)
+    end
+
+    local ok, result = pcall(chunk)
+
+    local output_text = ""
+    if #captured_lines > 0 then
+        output_text = table.concat(captured_lines, "\n") .. "\n"
+    end
+
+    if not ok then
+        return output_text, "Runtime error: " .. tostring(result)
+    end
+
+    -- If the chunk returned a value, append it.
+    if result ~= nil then
+        output_text = output_text .. "=> " .. serialize(result) .. "\n"
+    end
+
+    return output_text, nil
+end
+
+-- ── main poll loop ────────────────────────────────────────────────────────────
+
+re.on_frame(function()
+    frame_count = frame_count + 1
+    if frame_count < CHECK_INTERVAL then return end
+    frame_count = 0
+
+    -- Try to read the input file.
+    local source = fs.read(INPUT_FILE)
+    if source == nil or source == "" then return end
+
+    log.debug("[mcp] mcp_input.lua detected - executing...")
+
+    -- Build the output header (echoing the request id back to the server).
+    local req_id      = get_request_id(source)
+    local timestamp   = os.date("%Y-%m-%d %H:%M:%S")
+    local header      = "-- refmcp_request_id: " .. req_id .. "\n"
+        .. "-- mcp_output.txt | executed: " .. timestamp .. "\n"
+        .. string.rep("-", 60) .. "\n"
+
+    local output, err = execute_script(source)
+
+    local body        = ""
+    if output and output ~= "" then
+        body = body .. output
+    end
+    if err then
+        body = body .. "\n[ERROR]\n" .. err .. "\n"
+    end
+    if body == "" then
+        body = "(script produced no output)\n"
+    end
+
+    local full_output = header .. body
+
+    -- Write result.
+    fs.write(OUTPUT_FILE, full_output)
+    log.debug("[mcp] wrote " .. OUTPUT_FILE)
+
+    -- Erase the input file so it won't re-run next poll.
+    fs.write(INPUT_FILE, "")
+
+    log.debug("[mcp] done.")
+end)
+
+log.debug("[mcp] loaded - polling every " .. CHECK_INTERVAL .. " frames for " .. INPUT_FILE)

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@biorand/reframework-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "MCP server for running Lua inside RE Engine games via REFramework",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc && node scripts/copy-lua.mjs",
+    "start": "node dist/index.js",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "reframework",
+    "re-engine",
+    "modding"
+  ],
+  "author": "biorand",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/biorand/reframework-mcp.git"
+  },
+  "homepage": "https://github.com/biorand/reframework-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/biorand/reframework-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  },
+  "type": "module",
+  "bin": {
+    "reframework-mcp": "dist/index.js"
+  }
+}