内容
# samp-executor-mcp
> 连接 AI 客户端（Claude Code, Cursor, Codex, OpenCode, Antigravity, Kiro, Gemini CLI, Qwen CLI, Factory Droid, Windsurf, Devin）与实时 SAMP 客户端 **SA-MP 0.3.7 R3**，通过 Moonloader。基于 [notpoiu/roblox-executor-mcp](https://github.com/notpoiu/roblox-executor-mcp)，从 Roblox 修改为 SAMP。
---
## 📖 目录
1. [这是什么以及为什么](#-这是什么以及为什么)
2. [架构（如何连接）](#-架构如何连接)
3. [文件结构](#-文件结构)
4. [需求](#-需求)
5. [4 步安装](#-4-步安装)
6. [检查是否正常工作](#-如何检查是否正常工作)
7. [MCP 工具列表（40 个）](#-mcp-工具列表40-个)
8. [使用示例](#-使用示例)
9. [登录网站](#-登录网站)
10. [HTTP API（外部脚本）](#-http-api外部脚本)
11. [问题解决](#-问题解决)
12. [安全与反作弊](#-安全与反作弊)
13. [与原版 roblox-executor-mcp 的区别](#-与原版-roblox-executor-mcp-的区别)
14. [许可证与致谢](#-许可证与致谢)
---
## 🎯 这是什么以及为什么
允许 AI（Claude, GPT, Gemini 等）**看到和控制** 你的 SAMP 客户端，实时：
- 读取位置、HP、护甲、钱、武器、车辆
- 看见最近的玩家和 NPC，及其速度和方向
- 监控 RPC 数据包（进出）- 服务器发送和客户端发送的内容
- 直接读写游戏内存（CPed、CVehicle、CObject 结构体）
- 回应对话、发送聊天消息、按键
- **编写 Lua 脚本并立即注入到 Moonloader** - AI 编写代码、保存、测试、迭代
- 截图游戏窗口
- 跟踪你的 `.lua` 脚本源码
**用途：**
- 🛠 使用 AI 助手开发和调试 Moonloader 脚本
- 🔍 服务器 RPC 协议逆向工程
- 🤖 创建机器人/宏（谨慎使用 - 参见安全部分）
- 📚 研究 SAMP 0.3.7 R3 内存结构
---
## 🏗 架构（如何连接）
```
┌──────────────────────┐ stdio (JSON-RPC) ┌─────────────────────────────┐
│ AI Client │◀──────────────────────▶│ MCP Server (Node.js + TS) │
│ Claude Code / │ │ src/index.ts │
│ Cursor / Codex / │ │ ├ 40 MCP tools │
│ Gemini CLI / etc. │ │ └ HTTP+WS bridge :16385 │
└──────────────────────┘ │ │
│ Also serves: │
│ ├ Landing site (/) │
│ ├ Static assets (/assets/) │
│ └ REST API (/api/*) │
└─────────────┬───────────────┘
│
│ WebSocket
│ ws://127.0.0.1:16385
▼
┌─────────────────────────────────────────┐
│ connector.lua (在 Moonloader 中) │
│ ├ 注册时加载 │
│ ├ 接收命令，执行，回应│
│ ├ sampev hooks — RPC spy + event log │
│ ├ memory.read/write — 直接内存访问 │
│ ├ loadstring() — 自动脚本注入│
│ └ print() capture — 跟踪输出 │
└────────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ GTA SA + SAMP 0.3.7 R3 │
│ (gta_sa.exe — 单个或多个窗口) │
└─────────────────────────────────────────┘
```
**关键点：**
1. MCP 服务器通过 stdio（标准 MCP）与 AI 客户端通信
2. MCP 服务器在 **16385** 端口开启 HTTP+WS 服务器
3. Moonloader 中的 Lua 连接器连接到此端口，使用 WebSocket
4. 每个 MCP 工具调用 → 命令发送到连接器 → 返回响应
5. 登录网站和 REST API 在同一端口 16385 上提供
---
## 📁 文件结构
```
samp-executor-mcp/
│
├── 📦 package.json # npm 依赖和脚本
├── 📦 tsconfig.json # TypeScript 配置
├── 📦 .gitignore # git 忽略（node_modules, dist）
├── 📄 README.md # 本文件
│
├── 📁 src/ # MCP 服务器源码（TypeScript）
│ ├── index.ts # 入口：启动 MCP 服务器 + bridge
│ ├── bridge/ # 桥梁核心
│ │ ├── boot.ts # 启动 HTTP+WS 服务器
│ │ ├── types.ts # 类型（SAMPClient, SAMPResponse, 等）
│ │ └── handlers/
│ │ ├── shared/
│ │ │ ├── registry.ts # 已连接客户端注册表
│ │ │ ├── communication.ts # 命令发送和响应等待
│ │ │ └── script-source-store.ts
│ │ └── server/
│ │ └── primary.ts # http.createServer + WebSocketServer
│ ├── http/
│ │ ├── router.ts # 自动发现文件路由
│ │ └── routes/
│ │ ├── _ws-fallback.ts # WebSocket 升级处理器
│ │ ├── index.ts # GET / — 登录页面
│ │ ├── assets.ts # GET /assets/* — CSS, JS, 字体
│ │ ├── script.lua.ts # GET /script.lua — 连接器源码
│ │ ├── health.ts # GET /health
│ │ ├── register.ts # POST /register (HTTP 模式)
│ │ ├── poll.ts # GET /poll (HTTP 长轮询)
│ │ ├── respond.ts # POST /respond
│ │ └── api/
│ │ ├── clients.ts # GET /api/clients
│ │ ├── install-info.ts # GET /api/install-info
│ │ └── scripts.ts # /api/scripts/* (保存/获取/列出/删除)
│ └── tools/
│ ├── factory.ts # sendAndWait, formatToolText, clientStamp
│ ├── schemas.ts # 通用 Zod 模式
│ ├── index.ts # registerAllTools + AI 说明
│ └── impl/ # 40 个文件 — 每个 MCP 工具一个
│
├── 📁 connector/ # LUA 连接器（用于 Moonloader）
│ ├── connector.lua # 主文件：处理器 + RPC spy + 自动注入
│ └── ws-client.lua # 最简 WebSocket 客户端（RFC 6455）
│ # → 复制到：GTA SA\moonloader\
│
├── 📁 configs/ # 已准备的 AI 客户端配置文件
│ ├── manifest.json # 所有客户端的列表和元数据
│ ├── claude-code.txt # → .mcp.json 在项目根目录
│ ├── cursor.txt # → ~/.cursor/mcp.json
│ ├── codex.txt # → ~/.codex/config.toml
│ ├── opencode.txt # → opencode.json
│ ├── antigravity.txt # → .antigravity/mcp.json
│ ├── kiro.txt # → ~/.kiro/settings/mcp.json
│ ├── gemini-cli.txt # → ~/.gemini/settings.json
│ ├── qwen-cli.txt # → ~/.qwen/settings.json
│ ├── factory-droid.txt # → .factory/mcp.json
│ ├── windsurf.txt # → ~/.codeium/windsurf/mcp_config.json
│ └── devin.txt # → 通过 Web 界面配置
│
├── 📁 resources/ # AI 参考文档（通过 get-resource-doc 读取）
│ ├── samp-functions.json # ~50 个 SAMP/Moonloader 函数签名
│ ├── sampev-events.md # 所有可 hook 的 sampev 事件
│ └── memory-layout.md # 所有 SAMP 0.3.7 R3 偏移（池，结构体，全局变量）
│
├── 📁 templates/ # LUA 脚本模板（6 个）
│ ├── manifest.json # 模板描述和标签
│ ├── hp-monitor.lua # 简单：每秒 HP/armor/money
│ ├── anti-afk.lua # 防止 AFK 踢出
│ ├── dialog-responder.lua # 根据 ID 自动回应对话
│ ├── server-spy.lua # 被动服务器事件日志
│ ├── esp.lua # 输出最近玩家到聊天窗口
│ └── auto-drive.lua # 自动驾驶与 raycast 障碍检测
│
├── 📁 scripts/ # AI 工作空间 — 保存的脚本
│ # （空文件夹，通过 save-lua-script 填充）
│ # 请勿手动操作 — AI 管理
│
└── 📁 web/ # 登录网站
├── index.html # 首页
└── assets/
├── css/styles.css # 样式（Atlantic.vc 设计系统）
└── js/app.js # 粒子 canvas + 实时轮询
```
---
## ✅ 需求
| 组件 | 版本 | 获取方式 |
|-----------|--------|----------|
| **Windows** | 10/11 | — （仅限 Windows，因内存访问和截图） |
| **Node.js** | ≥ 18 | https://nodejs.org/ |
| **GTA San Andreas** | 1.0 US（非 Steam） | 任意干净安装 |
| **SAMP** | 0.3.7 R3 | https://sa-mp.com/ |
| **Moonloader** | ≥ 0.26 | https://gtaforums.com/topic/890552-moonloader/ |
| **SAMP.Lua** | 包含在 Moonloader 中 | 与 Moonloader 一起安装 |
**Lua 库**，连接器需要（包含在标准 Moonloader 中）：
- `bit`、`memory`、`vkeys`、`socket`、`ffi`、`luasocket` — 内置
- `samp.samp`、`samp.raknet`、`lib.samp.events`（sampev）— 来自 SAMP.Lua
---
## 🚀 4 步安装
### 步骤 1. 克隆仓库并构建 MCP 服务器
```bash
git clone https://github.com/UjanJJ/samp-executor-mcp.git
cd samp-executor-mcp
npm install
npm run build
```
此时，在 `dist/` 文件夹中将出现编译后的 `.js` 文件。
> 💡 **检查**: 运行 `node dist/index.js` — 应该输出到 stderr：
> ```
> [samp-mcp] bridge listening on http://127.0.0.1:16385 (ws + http)
> [samp-mcp] MCP server connected on stdio. Bridge on http://127.0.0.1:16385.
> ```
> 按 Ctrl+C 停止。
### 步骤 2. 在 Moonloader 中安装 Lua 连接器
将 **两个文件** 从仓库复制到 Moonloader 文件夹：
```
从： samp-executor-mcp/connector/connector.lua
从： samp-executor-mcp/connector/ws-client.lua
到： <GTA SA 路径>\moonloader\connector.lua
到： <GTA SA 路径>\moonloader\ws-client.lua
```
**示例路径：** `C:\Program Files\GTA San Andreas\moonloader\`
> 💡 **替代方案**：您不必手动复制文件，而是可以通过 Moonloader 控制台（游戏内 `~`）加载它们：
> ```lua
> loadstring(downloadFile("http://127.0.0.1:16385/script.lua"))()
> ```
> 但是，为了在游戏启动时自动加载，建议复制文件。
### 步骤 3. 将 MCP 服务器连接到您的 AI 客户端
选择下面的 AI 客户端并创建配置文件：
#### Claude Code
在项目根目录创建 `.mcp.json`（或全局 `~/.claude.json`）：
```json
{
"mcpServers": {
"samp-mcp": {
"command": "node",
"args": ["C:\\完整\\路径\\到\\samp-executor-mcp\\dist\\index.js"]
}
}
}
```
#### Cursor
创建 `~/.cursor/mcp.json`（或项目中的 `.cursor/mcp.json`）：
```json
{
"mcpServers": {
"samp-mcp": {
"command": "node",
"args": ["C:\\完整\\路径\\到\\samp-executor-mcp\\dist\\index.js"]
}
}
}
```
#### Codex CLI
在 `~/.codex/config.toml` 中创建：
```toml
[mcp_servers.samp-mcp]
command = "node"
args = ["C:\\完整\\路径\\到\\samp-executor-mcp\\dist\\index.js"]
```
#### OpenCode
在项目根目录创建 `opencode.json`：
```json
{
"mcp": {
"samp-mcp": {
"type": "local",
"command": ["node", "C:\\完整\\路径\\到\\samp-executor-mcp\\dist\\index.js"]
}
}
}
```
#### Antigravity / Kiro / Gemini CLI / Qwen CLI / Factory Droid / Windsurf
在 [`configs/`](configs/) 文件夹中的 `.txt` 文件中有现成的片段 — 打开所需的文件，复制内容并粘贴到指定的路径，如 [`configs/manifest.json`](configs/manifest.json)。
#### Devin
在 Devin 的 Web 界面中配置：Settings → Tools → MCP Servers → Add。参数：
- Server name: `samp-mcp`
- Transport: `stdio`
- Command: `node`
- Arguments: `C:\完整\路径\到\samp-executor-mcp\dist\index.js`
> ⚠️ **重要**: 参数中的路径应为 **完整绝对路径** 到 `dist/index.js`。将 `C:\完整\路径\到\samp-executor-mcp\` 替换为您的实际安装路径。
### 步骤 4. 启动并检查
1. **启动 MCP 服务器** （它应该在您使用 AI 客户端时保持运行）：
```bash
cd samp-executor-mcp
node dist/index.js
```
应该输出：
```
[samp-mcp] bridge listening on http://127.0.0.1:16385
[samp-mcp] MCP server connected on stdio.
```
2. **在浏览器中打开登录页面**：http://127.0.0.1:16385/
- 应该显示带有粒子动画的英雄部分
- **安装** 部分应有 4 个卡片
- **工具** 部分显示 40 个工具
- **AI 客户端** 部分显示 11 个卡片和 **复制配置** 按钮
- **实时状态** 部分 — 更新间隔为 3 秒
- **已保存的脚本** 部分 — 更新间隔为 5 秒
3. **启动 GTA SA + SAMP** （您可以不连接到服务器 — 检查足够菜单）
4. **Moonloader 加载器自动加载**。在登录页面 **实时状态** 部分应该出现您的客户端。
5. **打开您的 AI 客户端**（Claude Code 等）并询问：
> "What SAMP version am I running?"
AI 应该调用 `list-clients` → `get-game-info` 并返回版本号。
---
## 🧪 如何检查是否正常工作
### 检查 1. 登录网站
在浏览器中打开：**http://127.0.0.1:16385/**
应该看到：
- 带有粒子动画的英雄部分
- **安装** 部分，包含 4 个卡片
- **工具** 部分，包含 40 个工具
- **AI 客户端** 部分，包含 11 个卡片和 **复制配置** 按钮
- **实时状态** 部分 — 每 3 秒更新
- **已保存的脚本** 部分 — 每 5 秒更新
### 检查 2. 健康检查
```bash
curl http://127.0.0.1:16385/health
# 返回：{"ok":true,"clients":0}
```
### 检查 3. Moonloader 中的连接器
启动 GTA SA + SAMP 后，在登录页面 **实时状态** 部分应该看到：
```
Bridge ● Listening on :16385
Connected Clients 1
Client c-xxxxxxx ● YourNick @ ServerName (1.2.3.4:7777)
```
如果客户端未出现 — 打开 Moonloader 控制台（游戏内 `~`）并检查错误。
### 检查 4. AI 客户端
在您的 AI 客户端中询问：
> "List my connected SAMP clients"
AI 应该调用 `list-clients` 工具并返回您的数据。
### 检查 5. 脚本保存和注入
请 AI：
> "Save a Lua script named 'test.lua' with content `print('hello from samp-mcp')` and inject it"
之后：
- 在登录页面 **已保存的脚本** 部分应该出现 `test.lua`
- 在 Moonloader 控制台（在游戏内打开 `~`）中应该出现字符串 `hello from samp-mcp`
- AI 可以通过 `watch-script-output(basename='test.lua')` 读取输出
---
## 🛠 MCP 工具列表（40 个）
AI 可以调用这些工具。每个工具的完整文档在登录页面 **工具** 部分。
### 👥 客户端（2）
- `list-clients` — 已连接的 SAMP 客户端列表
- `set-active-client` — 选择活动客户端（前缀匹配）
### ⚡ Lua 执行（2）
- `execute-lua` — 执行 Lua 代码，无返回值（fire-and-forget）
- `eval-return` — 执行 Lua 代码并返回值（bounded serialization）
### 🌐 服务器和游戏（4）
- `get-server-info` — 服务器信息：hostname, IP:port, 玩家, 游戏模式, 延迟
- `get-game-info` — SAMP/Moonloader/GTA 版本，池地址
- `get-local-player` — 当地玩家信息：位置，HP，护甲，钱，武器，车辆
- `get-player-list` — 最近的 SAMP 玩家列表，含距离
### 🧠 内存（4）
- `get-pool-summary` — 池计数器（ped, vehicle, object, pickup）
- `search-memory` — 池搜索，筛选（model, HP, 位置, 皮肤）
- `read-struct` — 读取结构体字段（CPed, CVehicle, CObject, ...）
- `write-struct` — 写入结构体字段（可选验证）
### 📡 RPC Spy（3）
- `rpc-spy-control` — 启动/停止/清除/状态
- `get-rpc-spy-logs` — 捕获的 RPC 数据包日志
- `send-rpc` — 发送任意 RPC 数据包（按 ID 或名称）
### 🖱 GUI 和输入（3）
- `send-dialog-response` — 回应打开的对话框
- `send-chat` — 发送聊天消息或 / 命令
- `press-key` — 模拟按键（VK 或 SAMP 控制）
### 📂 Moonloader 脚本（3）
- `list-scripts` — `moonloader/` 目录中的 `.lua` 文件列表
- `get-script` — 特定脚本的源码（分页）
- `script-grep` — 所有 `.lua` 脚本的正则表达式搜索
### 💾 AI 工作空间（5）— 新增
- `save-lua-script` — 将 Lua 保存到 `scripts/`（永久存储）
- `inject-lua-script` — 立即加载脚本到 Moonloader
- `list-saved-scripts` — 已保存脚本列表
- `get-saved-script` — 已保存脚本的源码
- `delete-saved-script` — 删除已保存脚本
### 🌍 世界理解（5）— 新增
- `get-nearby-entities` — 指定半径内的所有实体，含位置/速度/方向
- `raycast` — 视线检查（障碍物检测）
- `get-vehicle-details` — 车辆详细信息：速度，方向，quaternion，乘员
- `get-camera-state` — 摄像头位置和方向
- `get-screen-state` — 当前屏幕状态：对话框，指针，计分板，显示的玩家
### 📡 服务器上下文（2）— 新增
- `get-event-history` — 最近的 500 个事件（聊天，加入，死亡，对话）
- `discover-server` — 自动检查：/cmdlist + /rules + RPC spy 5 秒
---
## 🧪 使用示例
---
## 🛠 登录网站
---
## 💻 HTTP API（外部脚本）
---
## 🧐 问题解决
---
## 👮 安全与反作弊
---
## 🤔 与原版 Roblox Executor MCP 的区别
---
## 📝 许可证与致谢
---
### 🛠 工作流开发 (6) — 新增
- `watch-script-output` — 捕获特定脚本的 print() 输出
- `reload-script` — 脚本重载（通过标志协同）
- `list-templates` — 可用模板列表
- `get-template` — 模板源码
- `get-samp-function-reference` — 搜索约 50 个 SAMP 函数
- `get-resource-doc` — 读取 sampev-events.md / memory-layout.md
### 📸 视觉 (1)
- `screenshot-window` — gta_sa.exe 窗口的 JPEG 截图
---
## 💡 使用示例
### 示例 1：简单的生命值监控
**询问 AI：**
> "保存一个 Lua 脚本，每秒打印我的生命值、护甲和金钱，然后注入它。"
**发生的情况：**
1. AI 调用 `save-lua-script(path="hp_monitor.lua", source="...")`
2. AI 调用 `inject-lua-script(path="hp_monitor.lua")`
3. 连接器将文件保存在 `moonloader/hp_monitor.lua` 并执行
4. AI 调用 `watch-script-output(basename="hp_monitor.lua")` 并显示输出
### 示例 2：自动对话响应
**询问 AI：**
> "监听 SAMP 对话并告诉我有对话框出现。然后自动用按钮 1 响应。"
**发生的情况：**
1. AI 调用 `get-event-history(filter="Dialog")` — 查看对话历史
2. AI 调用 `get-screen-state` — 查看当前对话框（id, 标题, 正文）
3. AI 调用 `send-dialog-response(button=1, listItem=0, inputText="")`
4. 如有必要，AI 通过 `save-lua-script` + `inject-lua-script` 保存脚本驻留
### 示例 3：自动驾驶
**询问 AI：**
> "使用自动驾驶模板使我的汽车向前行驶，在遇到障碍时刹车。"
**发生的情况：**
1. AI 调用 `list-templates` — 查找 `auto-drive`
2. AI 调用 `get-template(file="auto-drive.lua")` — 读取源码
3. AI 调用 `get-samp-function-reference(query="raycast")` — 检查 API
4. AI 调用 `get-resource-doc(doc="memory-layout.md")` — 检查 CVehicle 偏移
5. AI 修改模板，调用 `save-lua-script` + `inject-lua-script`
6. 在游戏中按 **F1** 启用自动驾驶
### 示例 4：探索新服务器
**询问 AI：**
> "我刚连接到一个新服务器。发现它有哪些命令和 RPC 消息。"
**发生的情况：**
1. AI 调用 `get-server-info` — 基本信息
2. AI 调用 `discover-server` — 运行 /cmdlist, /help, /rules 及 RPC 监视
3. AI 调用 `rpc-spy-control(action="start")` 进行持续监控
4. AI 调用 `get-event-history(filter="Chat")` — 查看近期消息
5. AI 总结：服务器有哪些命令，使用哪些 RPC
---
## 🌐 登陆网站
启动 MCP 服务器后，在浏览器中打开 **http://127.0.0.1:16385/**。
**内容：**
- **Hero** — 动画粒子画布（Atlantic.vc 风格）
- **Install** — 4 张带有复制粘贴代码的安装卡片
- **Tools** — 40 种 MCP 工具的网格视图，附带描述
- **AI Clients** — 11 张卡片，每张卡片带有“复制配置”按钮和文档链接
- **Live Status** — 每 3 秒查询 `/api/clients`，显示已连接的客户端
- **Saved Scripts** — 每 5 秒查询 `/api/scripts/list`，带有注入/删除按钮
**设计：** Atlantic.vc 启发的黑暗 charcoal 画布，冰白色线框，电蓝色（#1f58f2）强调，信号橙色（#ff4105）用于 CTA。无阴影，平坦表面，单间距微标签。
---
## 🔌 HTTP API（用于外部脚本）
所有端点均可在 `http://127.0.0.1:16385` 访问。可从任何语言用于自动化。
### 基础
| 方法 | 路径 | 目的 |
|-------|------|-----------|
| GET | `/` | 登陆页面（HTML） |
| GET | `/assets/*` | CSS, JS, 字体 |
| GET | `/script.lua` | 连接器源码（用于 `loadstring(downloadFile(...))()`） |
| GET | `/health` | 存活探测：`{"ok":true,"clients":N}` |
### AI 工作区 API
| 方法 | 路径 | 目的 |
|-------|------|-----------|
| GET | `/api/clients` | 已连接的 SAMP 客户端列表（JSON） |
| GET | `/api/install-info` | 11 个 AI 客户端的配置片段 |
| GET | `/api/scripts/list` | 已保存的脚本列表 |
| GET | `/api/scripts/get?path=foo.lua` | 特定脚本的源码 |
| POST | `/api/scripts/save?action=save` | 保存脚本（请求体：`{path, source, overwrite}`） |
| POST | `/api/scripts/inject?action=inject` | 保存并注入（请求体：`{path?, source?, clientId?}`） |
| DELETE | `/api/scripts/delete?path=foo.lua` | 删除脚本 |
### 示例：使用 curl 保存和注入脚本
```bash
# 保存
curl -X POST "http://127.0.0.1:16385/api/scripts/save?action=save" \
-H "Content-Type: application/json" \
-d '{"path":"hello.lua","source":"print(\"hi from curl\")","overwrite":true}'
# 注入
curl -X POST "http://127.0.0.1:16385/api/scripts/inject?action=inject" \
-H "Content-Type: application/json" \
-d '{"path":"hello.lua"}'
# 检查列表
curl http://127.0.0.1:16385/api/scripts/list
```
---
## 🔧 问题解决
### 问题：MCP 服务器无法启动
**症状：** `node dist/index.js` 报错或崩溃。
**解决方案：**
1. 检查 Node.js 版本：`node --version`（应 ≥ 18）
2. 确保执行了 `npm install` 和 `npm run build`
3. 检查 `dist/` 目录是否存在且包含 `index.js`
4. 查看 stderr 中的完整错误输出
### 问题：连接器无法连接
**症状：** 登陆页面上的 Live Status 显示“None connected”。
**解决方案：**
1. 确保 MCP 服务器已启动（`node dist/index.js`）
2. 确保 `connector.lua` 和 `ws-client.lua` 位于 `moonloader/`
3. 在游戏中打开 Moonloader 控制台（按键 `~`）并检查错误
4. 检查端口 16385 是否被其他应用程序占用：
```bash
netstat -ano | findstr :16385
```
5. 检查 Moonloader 是否加载了脚本 — 应在 `moonloader.log` 中看到 `[samp-mcp] connector starting`
### 问题：AI 客户端看不到 MCP 工具
**症状：** Claude Code / Cursor 中没有 samp-mcp 工具。
**解决方案：**
1. 检查配置文件是否正确（路径到 `dist/index.js` 应为绝对路径）
2. 在 Claude Code 中执行 `/mcp` — 应显示带有绿色勾选的 samp-mcp
3. 配置文件更改后重启 AI 客户端
4. 检查 `args` 中的路径是否使用双反斜杠：`C:\\path\\to\\dist\\index.js`
5. 在 Windows PowerShell 中检查路径是否用引号括起来，如果有空格
### 问题：AI 无法调用工具
**症状：** AI 调用 `list-clients` 返回错误“No active SAMP client”。
**解决方案：**
1. 检查 GTA SA + SAMP 是否已启动
2. 检查连接器是否已加载（登陆页面上的 Live Status 部分）
3. 如果有多个 SAMP 窗口 — 使用 `set-active-client(prefix="...")`
### 问题：内存访问返回 0 或崩溃游戏
**症状：** `read-struct` 返回零，`write-struct` 崩溃 GTA。
**解决方案：**
1. 首先调用 `get-game-info` — 检查 SAMP 版本确实为 0.3.7 R3
2. 首先调用 `get-pool-summary` — 如果所有池均为 0，则表示池尚未初始化（等待生成）
3. **始终** 在 `write-struct` 之前调用 `read-struct` 以检查地址
4. 如果使用非标准 SAMP 版本（Arizona, SRV 等）— 偏移可能不同
### 问题：注入失败
**症状：** `inject-lua-script` 返回错误。
**解决方案：**
1. 确保连接器已连接（Live Status 显示客户端）
2. 检查 Lua 代码中是否有语法错误 — 连接器将返回错误 `loadstring error: ...`
3. 文件名应符合 `^[A-Za-z0-9_-]+\.lua$` — 无路径，无子目录
### 问题：截图无法工作
**症状：** `screenshot-window` 返回错误。
**解决方案：**
1. 截图 **仅在 Windows 上工作** （使用 PowerShell + user32）
2. 确保 GTA SA 已启动且窗口标题为“GTA:SA:MP”或“GTA: San Andreas”
3. 以管理员身份运行 AI 客户端（有时需要 BitBlt）
### 问题：性能
**症状：** 游戏在活动 RPC 监视时卡顿。
**解决方案：**
1. 使用 `rpc-spy-control(action="start", logPayloads=false)` — 不解码 payload
2. 定期调用 `rpc-spy-control(action="clear")` 以清除日志
3. 不要调用 `get-nearby-entities` 且半径 > 200 — 将扫描许多池
4. 在不需要完整数据的情况下使用 `summaryOnly=true`
---
## ⚠️ 安全性和反作弊
此分支支持 **读取和写入内存** 以及 **发送任意 RPC 消息**。在具有反作弊的服务器上，这可能会导致封禁。
### ✅ 推荐场景
- 本地开发自己的 Moonloader 脚本
- 连接到自己的测试服务器
- 在受控环境中逆向工程 RPC
- 研究 SAMP 0.3.7 R3 的内存结构
### ❌ 不推荐场景
- 具有反作弊的公共服务器（Phoenix, Arizona RP, SRV, Arizona 等）
- 服务器明确禁止自动化
- 任何非法活动
### 安全规则
1. **始终** 在 `write-struct` 之前调用 `read-struct` — 检查地址
2. 不发送不了解格式的 RPC 消息（首先使用 `rpc-spy-control`）
3. 不要在具有反作弊 mod 的服务器上修改内存（除了读取）
4. 不要使用 `send-rpc` 伪造同步（诸如 RakNet 之类的服务会检测到此）
---
## 🔄 与原始 roblox-executor-mcp 的区别
| 方面 | 原始（Roblox） | 此分支（SAMP） |
|--------|-------------------|------------------|
| 游戏 | Roblox | GTA:SA + SAMP 0.3.7 R3 |
| 环境 | Roblox 执行器（Luau） | Moonloader（Lua 5.1） |
| 需要反编译器？ | 是（Luau 字节码） | 否 — `.lua` 源代码为纯文本 |
| RPC 监视 | Cobalt 库 | `sampev.onReceiveRpc/onSendRpc`（内置） |
| 实体树 | `search-instances`（CSS 选择器） | `search-memory`（基于池的谓词搜索） |
| **AI 工作区** | — | **新增**：save/inject/list/get/delete-saved-script |
| **自动注入器** | — | **新增**：连接器保存 + loadstring 脚本 |
| **登陆网站** | — | **新增**：http://127.0.0.1:16385/ 带有实时状态 |
| **AI 客户端配置** | — | **新增**：11 个预制代码片段 |
| **模板** | — | **新增**：6 个预制 Lua 模板 |
| **资源文档** | — | **新增**：sampev-events.md, memory-layout.md, samp-functions.json |
| **事件历史** | — | **新增**：自动捕获聊天/对话框/加入/死亡 |
| **脚本输出监视** | — | **新增**：按来源捕获 print() |
| 多客户端 | 是 | 是 |
| 传输 | WS + HTTP 轮询 | 仅 WebSocket |
| 主要/次要 | 是（跨操作系统） | 否（单个主机） |
| 截图 | Roblox 窗口 | `gta_sa.exe`（使用 PowerShell 方法） |
| 端口 | 16384 | **16385**（避免冲突，如果两者都安装） |
---
## 📄 许可证和致谢
**许可证：** MIT — 与原版相同。
**致谢：**
- **原始项目：** [notpoiu/roblox-executor-mcp](https://github.com/notpoiu/roblox-executor-mcp) — 架构，MCP 模式，工厂帮助程序，输出预算
- **SAMP.Lua / Moonloader** — 没有它们，这个分支就不可能实现
- **SAMP 0.3.7 R3 内存布局** — 由 SA-MP modding 社区记录
- **设计系统：** Atlantic.vc — midnight observatory 调色板（charcoal 画布，ice-white 线框，electric cobalt 强调，signal orange CTA）
---
## 🎯 下一步
安装和检查后：
1. **浏览登陆页面** http://127.0.0.1:16385/ — 里面有 40 个工具的描述
2. **尝试一个简单的脚本**：让 AI 保存并注入 `print("hello")`
3. **使用模板**：让 AI 以 `hp-monitor.lua` 为基础创建脚本
4. **研究 RPC**：启动 `rpc-spy-control` 并在游戏中执行操作 — 查看服务器发送的内容
5. **尝试自动驾驶**：加载模板，坐进车里，按 F1
祝你好运！ 🚀
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器