Relapse MCP

Relapse MCP exposes the Roblox executor MCP tools through Relapse's local Unix socket. It runs as a stdio MCP server and does not require a separate HTTP core, WebSocket connector, dashboard, or manual in-game script execution.

It works alongside other Relapse UIs and socket clients, so you can keep your UI open while using MCP tools.

Using a release

Requires Node.js 20 or newer with npm, and a running Relapse executor. Restart your MCP client after updating its configuration.

JSON configuration

Add this to your MCP client's configuration:

{
  "mcpServers": {
    "relapse": {
      "command": "npx",
      "args": [
        "-y",
        "--package=https://github.com/vpu00000/relapse-mcp/releases/download/v0.1.0/relapse-mcp-0.1.0.tgz",
        "relapse-mcp"
      ]
    }
  }
}

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.relapse]
command = "npx"
args = [
  "-y",
  "--package=https://github.com/vpu00000/relapse-mcp/releases/download/v0.1.0/relapse-mcp-0.1.0.tgz",
  "relapse-mcp"
]
startup_timeout_sec = 60

The package includes the compiled server and bundled Luau. The first launch downloads its runtime dependencies. Darklua is not required to run it.

You can also use --package=/absolute/path/to/relapse-mcp-0.1.0.tgz for a downloaded package. Release URLs require the repository to be public for unauthenticated downloads.

Related MCP server: dex-mcp

Development setup

Requires Node.js 20 or newer, Darklua on your PATH (tested with 0.19.0), and a running Relapse executor. From this repository:

npm ci
npm run build
npm start

Edit the Luau modules under connector-src/. The build uses Darklua to bundle them into connector.luau and copies the result into dist/. Darklua is only needed to build; running the built MCP requires Node.js and Relapse.

Configure your MCP client to run node /absolute/path/to/relapse-mcp/dist/index.js as a stdio server. RELAPSE_SOCKET_PATH overrides the default /tmp/relapse.sock when needed. The process connects automatically when Relapse becomes available.

The MCP process connects to Relapse's @main channel to watch the current session and inject its bundled Luau handler. It then uses a private RelapseChannel for tool requests, replies, and script-source updates. The handler is re-injected after a session change. Relapse MCP is an independent socket client with no dependency on any UI. Other implementations can use @main and their own channels at the same time.

All 17 Upio MCP tool names and input schemas remain exposed. Script search and semantic search use an in-memory index of sources decompiled by the active Relapse session. Relapse's built-in decompile function is used; scripts that cannot be decompiled are reported as gaps in the index. The two OS window tools retain their Windows-only implementation.

Semantic search can use OpenAI-compatible embeddings or Ollama. Set RELAPSE_MCP_EMBEDDING_PROVIDER to openai or ollama. For OpenAI, set RELAPSE_MCP_OPENAI_API_KEY (or OPENAI_API_KEY); optional overrides are RELAPSE_MCP_OPENAI_BASE_URL and RELAPSE_MCP_OPENAI_MODEL. For Ollama, optional overrides are RELAPSE_MCP_OLLAMA_BASE_URL and RELAPSE_MCP_OLLAMA_MODEL.

Testing

npm test

The integration test uses a mock Relapse Unix socket to exercise MCP tool registration, a second @main client, script indexing, request/reply routing, and session reinjection. With the luau CLI on your PATH, the tests also execute the bundled connector against a mocked Roblox environment. These tests do not replace a live Roblox session test.

Creating a release

Set the version in package.json and package-lock.json, then commit and push the release changes. With the development prerequisites installed:

npm ci
npm pack

npm pack builds the project and runs the tests before writing relapse-mcp-0.1.0.tgz. Upload this file as a GitHub Release asset. The GitHub-generated source archives do not contain the built server.

To test the actual package through npx with a fresh npm cache and mock Relapse socket:

RELAPSE_MCP_TEST_PACKAGE="$PWD/relapse-mcp-0.1.0.tgz" node --test tests/relapse-runtime.test.mjs

For version 0.1.0, using the GitHub CLI:

git tag v0.1.0
git push origin v0.1.0
gh release create v0.1.0 relapse-mcp-0.1.0.tgz --verify-tag --title v0.1.0 --notes "Relapse MCP 0.1.0"

Use the new version in the tag, filename, and MCP config for subsequent releases.

Attribution

This project derives from Upio's Roblox Executor MCP. The original and modified code are distributed under the MIT license; see LICENSE.