xeno MCP

xeno-mcp

一个MCP服务器，允许AI代理与Roblox游戏客户端交互——执行Lua脚本、捕获游戏输出、搜索社区脚本和管理客户端连接——所有这些都可以通过您最喜欢的AI工具完成。

支持两种模式：

• 氙气模式 --与直接整合 Xeno 执行者
• 通用模式 --基于文件的适配器，适用于 任何 执行人（Solara、Velocity等）

为什么是基于文件而不是DLL注入？ 每个执行器都使用自己的内部API，具有不同的函数签名、内存布局和调用约定——没有通用的DLL接口。通过DLL支持执行器意味着为每个执行器编写和维护一个单独的代理，任何执行器更新都可能破坏它。基于文件的方法适用于任何开箱即用的执行器，只要它支持基本的UNC功能(readfile, writefile它也是完全非侵入性的——没有挂接到执行器内部，没有二进制兼容性问题，也没有从外部DLL注入触发反作弊的风险。

Xeno是什么？ --一个免费的无密钥Roblox脚本执行器，支持多连接。抓住它 xeno.now.

______________________________________________________________________

目录

• 建筑
• 先决条件
• 构建
• 设置--氙气模式
• 设置--通用模式
• MCP配置
• 工具
• 远程消息监视程序
• 日志和分页
• HTTP API
• 服务器标志
• 环境变量
• 测试

______________________________________________________________________

建筑

两个组件协同工作：

1. HTTP服务器 （Rust/actix-web，端口3111）——管理客户端状态，从注入的Lua脚本接收日志，代理执行器API
2. MCP电桥 （TypeScript、stdio）——将MCP工具调用转换为HTTP请求，并自动启动服务器

氙气模式：

AI Agent ←—stdio—→ MCP Bridge ←—http—→ HTTP Server ←—http—→ Xeno API ←→ Roblox

通用模式：

AI Agent ←—stdio—→ MCP Bridge ←—http—→ HTTP Server ←—file—→ Exchange Dir ←—poll—→ Loader (in executor) ←→ Roblox

网桥会自动生成HTTP服务器，您不需要手动启动它。

______________________________________________________________________

先决条件

• 视窗 --Roblox执行器仅适用于Windows
• 锈 --构建HTTP服务器(cargo)
• 18+--运行MCP桥(npm)
• Git --克隆仓库
• 遗嘱执行人： Xeno 对于Xeno模式，或任何支持UNC的通用模式执行器

______________________________________________________________________

构建

git clone https://github.com/Lypt1x/xeno-mcp.git
cd xeno-mcp

# 1. Build the Rust HTTP server
cargo build --release

# 2. Build the MCP bridge
cd mcp-bridge
npm install
npm run build
cd ..

第一次Rust构建需要几分钟（拉取依赖项）。后续的构建速度很快。

服务器二进制文件位于 target/release/xeno-mcp.exe。电桥输出为 mcp-bridge/dist/.

______________________________________________________________________

设置--氙气模式

这是默认模式。Xeno有一个内置的API，服务器可以直接与之通信。

1. 构建项目（参见 构建)
2. 将MCP配置添加到您的AI代理中（请参阅 MCP配置)
3. 打开Xeno并注入Roblox客户端
4. 启动你的AI代理——网桥会自动启动服务器

就是这样。代理将检测Xeno客户端，并可以立即执行脚本。

______________________________________________________________________

设置--通用模式

通用模式适用于 任何遗嘱执行人 它支持基本的UNC功能。通过文件系统交换脚本，而不是直接的API。

需求

您的遗嘱执行人必须支持：

• readfile(path) --读取文件内容
• listfiles(path) --列出目录中的文件
• isfile(path) --检查路径是否为文件
• delfile(path) --删除文件
• request({...}) --发出HTTP请求
• getgenv() --全球环境表

设置

1. 构建项目（参见 构建)
2. 查找您的遗嘱执行人 工作区文件夹 （目录中 readfile/writefile 操作）
3. 添加带有通用模式环境变量的MCP配置（请参阅 MCP配置)
4. 启动您的AI代理
5. 打开你的executor，注入Roblox，并将其粘贴到executor中：

   loadstring(game:HttpGet("http://localhost:3111/loader-script"))()

1. 您将看到一个游戏内通知： “装载机已连接” --你准备好了

装载机的功能

加载器脚本在执行器内部运行，并且：

• 民意调查 exchange/pending/ 对于新 .lua 每200ms一个脚本文件
• 通过以下方式执行脚本 loadstring() 并删除该文件
• 捕获所有 print/warn/error 输出并将其发送到服务器
• 每5秒发送一次心跳以保持连接畅通
• 自动重新连接 如果服务器重启（每5秒重试一次，在游戏中通知）
• 玩家离开游戏时自动断开连接
• 防止双重注射（多次运行安全）

自动执行（可选）

要跳过每次注入时粘贴loadstring，请将其保存到executor的autoexec文件夹中：

1. 查找您的遗嘱执行人 autoexec 文件夹（通常在工作区/根目录内）
2. 创建一个名为的文件 xeno-mcp-loader.lua 包含以下内容：

   loadstring(game:HttpGet("http://localhost:3111/loader-script"))()

1. 现在，每次注射时，加载器都会自动连接

______________________________________________________________________

MCP配置

将以下内容添加到AI代理的MCP配置中。将路径替换为实际的克隆位置。

氙气模式

Claude Desktop — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "xeno-mcp": {
      "command": "npx",
      "args": ["-y", "C:/path/to/xeno-mcp/mcp-bridge"]
    }
  }
}

VS Code / GitHub Copilot — .vscode/mcp.json

{
  "mcp": {
    "servers": {
      "xeno-mcp": {
        "command": "npx",
        "args": ["-y", "C:/path/to/xeno-mcp/mcp-bridge"]
      }
    }
  }
}

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "xeno-mcp": {
      "command": "npx",
      "args": ["-y", "C:/path/to/xeno-mcp/mcp-bridge"]
    }
  }
}

通用模式

添加 XENO_MCP_MODE 和 GENERIC_EXECUTOR_WORKSPACE 环境变量：

{
  "mcpServers": {
    "xeno-mcp": {
      "command": "npx",
      "args": ["-y", "C:/path/to/xeno-mcp/mcp-bridge"],
      "env": {
        "XENO_MCP_MODE": "generic",
        "GENERIC_EXECUTOR_WORKSPACE": "C:\\path\\to\\executor\\Workspace"
      }
    }
  }
}

桥会自动创建 exchange/pending/ 和 exchange/done/ 工作区内的子目录。

可选：共享密钥

要要求对所有POST/DELETE端点进行身份验证，请执行以下操作：

{
  "env": {
    "XENO_MCP_SECRET": "your-secret-here"
  }
}

______________________________________________________________________

工具

MCP服务器将这些工具暴露给AI代理：

核心工具

ScriptBlox集成

代理执行安全规则：未经验证的脚本需要明确的用户确认，混淆的脚本会触发警告，关键系统会被标记。

远程间谍工具

看 远程消息监视程序 了解详情。

______________________________________________________________________

远程消息监视程序

远程间谍拦截Roblox远程呼叫（传入和传出），并通过现有的日志系统记录它们。它使用双钩重定向模式来避免阻塞游戏流量。

需求

• 仅通用模式 --需要UNC挂钩功能(hookfunction, hookmetamethod, newcclosure等），这些在Xeno模式下不可用
• 在Xeno模式下，间谍工具返回一个错误，解释UNC要求
• 应先连接记录器以获取状态消息

运作原理

1. attach_spy 注入一个挂钩的Lua脚本 FireServer, InvokeServer （通过 hookfunction)以及 __namecall （通过 hookmetamethod)
2. 这 __namecall 钩子将远程调用重定向到 hookfunctiond版本而不是调用 old() 直接——这是避免阻塞游戏流量的关键模式
3. 被动的 OnClientEvent:Connect() 侦听器捕获传入服务器→客户端事件
4. 所有被截获的电话都会发送到 POST /internal 随着 event: "spy" 并存储为日志条目 source: "remote_spy"

去重

默认情况下，间谍 重复数据消除 --仅记录每个唯一远程（按路径+方向+方法）的第一次出现。这可以防止在繁忙的游戏中用60+/帧的调用淹没日志。

得到 所有通话 对于特定的远程（包括args），使用 spy_subscribe:

spy_subscribe("ReplicatedStorage.Remotes.SetAFK")

这使得间谍记录下每次与该路径匹配的远程调用。支持部分匹配——订阅 "Remotes" 匹配该路径下的所有遥控器。

使用 spy_unsubscribe 将遥控器返回到仅去重模式。

查询间谍日志

间谍日志使用 source: "remote_spy" 和标签 ["spy", "in"|"out"]:

get_logs(source="remote_spy")              — all spy logs
get_logs(source="remote_spy", tag="out")   — outgoing calls only
get_logs(source="remote_spy", tag="in")    — incoming calls only
get_logs(source="remote_spy", search="SetAFK") — specific remote

清理

• detach_spy 发送一个断开连接脚本，恢复所有钩子并清除侦听器
• 当玩家离开游戏时，间谍自动清理
• 间谍防范双重注入：重新连接先断开前一个间谍

______________________________________________________________________

日志和分页

每个脚本执行和所有游戏输出(print, warn, error)被捕获为日志条目。

日志级别

分页

日志已返回 每页50 默认情况下（最大1000）。答复包括：

{
  "logs": [...],
  "total": 247,
  "page": 1,
  "per_page": 50,
  "total_pages": 5,
  "has_more": true
}

使用 page （1-索引）导航，或 offset 用于手动控制。

过滤器

所有过滤器都可以组合：

______________________________________________________________________

HTTP API

对于没有MCP的直接集成：

所有POST/DELETE端点都需要 X-Xeno-Secret 标题时 --secret 已设置。

______________________________________________________________________

服务器标志

xeno-mcp [OPTIONS]

Options:
  -p, --port 
                  Port to listen on [default: 3111]
  -b, --bind                   Bind address [default: 127.0.0.1]
      --console                      Print incoming logs to stdout
      --log-file 
              Append logs to a file
      --secret               Require X-Xeno-Secret header on POST/DELETE
      --max-entries               Max log entries in memory [default: 10000]
      --xeno-url                Xeno API URL [default: http://localhost:3110]
      --mode                   Server mode: xeno or generic [default: xeno]
      --exchange-dir            OS path for script exchange files [default: ./exchange]
      --executor-exchange-dir   Exchange path as seen by the executor's filesystem

要手动运行服务器（对调试很有用）：

./target/release/xeno-mcp --mode generic --exchange-dir "C:\Executor\Workspace\exchange" --executor-exchange-dir exchange --console

______________________________________________________________________

环境变量

通过MCP配置中的环境变量配置MCP网桥：

高级覆盖（很少需要）：

______________________________________________________________________

测试

使用MCP检查器交互式测试工具：

npx @modelcontextprotocol/inspector npx -y ./mcp-bridge

这将打开一个web UI，您可以在其中调用每个工具、检查响应和读取资源。