内容
# Matcha MCP
连接 AI 助手到实时 [Matcha LuaVM](https://doc.wabisabi.mom/matcha/) 会话的 MCP 服务器。您的代理可以运行 Luau，探索游戏树，反编译脚本，搜索代码，并使用 Matcha 内存 API — 所有这些都来自 Cursor，Claude Code 或任何 MCP 客户端。
**仓库：** [github.com/wavelyz/roblox-matcha-mcp](https://github.com/wavelyz/roblox-matcha-mcp)
```
AI 客户端 ←stdio→ matcha-mcp (Node, :16385)
↑ HTTP询 / 注册 / 响应
matcha-connector.luau (在 Matcha 内)
↑
Matcha LuaVM ↔ Roblox
```
## 要求
- **Node.js** 18+（运行 MCP 服务器）
- **[Matcha](https://doc.wabisabi.mom/matcha/)** 连接到 Roblox 会话
- 支持 MCP 的编辑器（Cursor，Claude Desktop，Windsurf 等）
## 安装
### 1.并构建服务器
```bash
git clone https://github.com/wavelyz/roblox-matcha-mcp.git
cd roblox-mcp/matcha-mcp
npm install
npm run build
```
### 2. 添加到 MCP 配置
**Cursor** — 项目 `.cursor/mcp.json` 或全局 `~/.cursor/mcp.json````json
{
"mcpServers": {
"matcha-mcp": {
"command": "node",
"args": ["/absolute/path/to/matcha-mcp/dist/index.js"]
}
}
}
```
**Claude Code：**
```bash
claude mcp add --global matcha-mcp -- node /absolute/path/to/matcha-mcp/dist/index.js
```
参见 [docs/setup.md](docs/setup.md) 以获取 Windsurf、Codex 和其他客户端的设置说明。
在更改配置后，请重启编辑器中的 MCP 服务器。
### 3. 连接 Matcha 到桥接器
每个 Roblox 会话运行一次（Matcha 自动运行 / 脚本中心）：
```lua
-- matcha-loader.luau （或粘贴此代码）
_G.MatchaMCP = _G.MatchaMCP or {}
_G.MatcharidgeURL = _G.MatchaMCP.BridgeURL or "localhost:16385"
loadstring(game:HttpGet("http://" .. _G.MatchaMCP.BridgeURL .. "/script.luau"))()
```
连接器从 MCP 服务器的 `http://localhost:16385/script.luau` 提供服务 — 无需单独下载。
**仪表盘：** [http://localhost:16385/](http://localhost:16385/) — 连接状态，脚本索引进度。
### 4. 验证
在您的 AI 客户端中，调用 `list-clients`。您应该看到您的玩家名称和位置 ID。然后尝试 `get-game-info` 或 `get-descendants-tree` 在 `game.Players.LocalPlayer.Backpack` 上。
## 代理可以执行的操作
| 工具 | 功能 |
|------|----------------|
| `list-clients` / `set-active-client` | 查看和选择的 Roblox 会话 |
| `execute` / `execute-file` | 在 Matcha 中运行 Luau（无返回值） |
| `get-data-by-code` | 运行 Luau 并获取返回值（小探针） |
| `get-descendants-tree` | 探索路径下的实例层次结构 |
| `search-instances` | 在根目录下按类别 |
| `get-game-info` | 地点 ID，作业 ID，游戏名称，执行器版本 |
| `get-script-content` | 按路径反编译脚本（行范围） |
| `script-grep` | 在反编译的源代码中搜索文本/正则表达式 |
| `semantic-search-scripts` | 按行为搜索脚本（需要嵌入配置） |
| `get-console-output` | 会话的最近打印输出 |
| `memory-read` / `memory-write` / `get-memory-base` | Matcha 进程内存（不安全的 Luau） |
完整工具指南：[docs/tools.md](docs/tools.md)
**不包含** （仅执行器功能）：远程间谍，GUI 点击/类型，截图，WebSocket 传输。
## 仓库布局
| 路径 | 用途 |
|------|---------|
| `matcha-mcp/` | Node MCP 服务器 + 仪表盘 |
| `matcha-mcp/matcha-connector.luau` | VM 内的桥接器（在 `/script.luau` 处提供服务） |
| `matcha-loader.luau` | 最小加载器代码片段 |
| `matcha-scripts/` | 可选 [SaveInstance](https://github.com/Matt-T-123/SaveInstance) 导出预设 |
| `docs/` | 架构，Matcha LuaVM 注释，设置 |
## 连接器配置
在加载前设置 `_G.MatchaMCP`：
| 键 | 默认值 | 描述 |
|-----|---------|-------------|
| `BridgeURL` | `localhost:16385` | MCP HTTP 主机 |
| `MaxScriptMapping` | `700` | 连接时 `script-grep` 的最大脚本反编译数量 |
| `DisableInitialScriptDecompMapping` | — | 设置 `true` 以跳过脚本索引 |
索引顺序：Backpack → PlayerScripts → PlayerGui → Character → Workspace.Entities → ReplicatedStorage → `getscripts()` 直到上限。
## 安全
- **16385** 端口 **无身份验证**。仅在 **localhost** 上使用。切勿暴露给互联网。
- `memory-read` / `memory-write` 可能损坏 Roblox 进程。仅在您了解风险时启用。
## 文档
- [Matcha LuaVM 入门](docs/matcha-luavm.md) — 什么是 Matcha，API，限制与执行器
- [架构](docs/architecture.md) — 桥接器工作原理
- [工具](docs/tools.md) — 何时使用每个 MCP 工具
- [设置（所有客户端）](docs/setup.md)
- [官方 Matcha 文档](https://doc.wabisabi.mom/matcha/)
## 致谢
灵感来自 [roblox-executor-mcp](https://github.com/notpoiu/roblox-executor-mcp)。为 Matcha 的仅 HTTP、无钩子 LuaVM 重建。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
