内容
# mcp-pine
[](https://www.npmjs.com/package/mcp-pine)
[](https://www.npmjs.com/package/mcp-pine)
[](https://github.com/dmang-dev/mcp-pine/actions/workflows/ci.yml)
[](LICENSE)
[](https://snyk.io/test/npm/mcp-pine)
[](https://socket.dev/npm/package/mcp-pine)
[](https://bundlephobia.com/package/mcp-pine)
[](https://npmgraph.js.org/?q=mcp-pine)
MCP 服务器，适用于支持 PINE（网络模拟器仪表协议） 的模拟器 - 优先支持 **PCSX2**（PS2）和 **RPCS3**（PS3），目标感知工具描述，以便代理看到正确的内存映射。公开内存读写和存档控制。由兼容 MCP 的客户端驱动（Claude Desktop，Claude Code 等）。
## 您可以用它做什么
- **读取和写入模拟内存** - 8/16/32/64 位，模拟器的地址空间中的任何位置（PCSX2 的 PS2 EE，RPCS3 的 PPU 主内存）
- **触发保存/加载状态** 到编号的槽位
- **查询游戏元数据** - 标题，序列号，磁盘 CRC，版本
- **检查模拟器状态** - 运行/暂停/关闭
工具描述，内存映射上下文和设置帮助在启动时 **按目标渲染** - 设置 `PINE_TARGET=rpcs3`，每个内存工具描述显示 PS3 PPU 地址而不是 PS2 EE 地址。
您 **不能** 做的事情（因为 PINE 本身不暴露这些）：
- 发送控制器输入
- 截取屏幕截图
- 单步/暂停/重置模拟器
这使得 mcp-pine 非常适合 **内存检查，作弊/ RAM 猎人，存档自动化和逆向工程**，但不适合“通过 Claude 玩游戏”。对于 Game Boy Advance，请参阅配套项目 [mcp-mgba](https://github.com/dmang-dev/mcp-mgba)。
## 它是如何工作的
```
+----------------+ stdio +----------------+ PINE socket +-----------------+
| MCP 客户端 | JSON-RPC | mcp-pine | (TCP 或 Unix) | 模拟器 |
| (Claude 等) | -----------> | (Node.js) | ---------------> | (PINE 服务器) |
+----------------+ +----------------+ +-----------------+
```
`mcp-pine` 打开到模拟器的 PINE 服务器的环回连接（Windows 上为 TCP，Linux/macOS 上为 Unix 域套接字），并将每个 MCP 工具调用转换为二进制 PINE 消息。
## 兼容的模拟器
| 模拟器 | 平台 | 内置 PINE？ | 默认槽位 | `PINE_TARGET` |
|------------------|---------------|-------------------------------------------|--------------|---------------|
| **PCSX2 ≥ 1.7** ([设置](#pcsx2)) | PlayStation 2 | ✅ 是（在设置中切换） | 28011 | `pcsx2`（默认） |
| **RPCS3** ([设置](#rpcs3)) | PlayStation 3 | ⚠️ 有 IPC 与 PINE 兼容的操作码 — 验证后再依赖它 | 28012 | `rpcs3` |
其他实现 PINE 规范的模拟器应该开箱即用，只要您将 `mcp-pine` 指向正确的槽位 - 如果您已经测试过一个并且它有效，请打开一个问题。
**关于 DuckStation（PS1）的说明**：DuckStation 从 2024 年 5 月到 9 月有 PINE 支持，但 [在提交 19698559 中删除了它](https://github.com/stenzek/duckstation/commit/19698559)。当前版本没有 PINE 服务器。如果上游恢复了它，则保留 `PINE_TARGET=duckstation`。
设置 `PINE_TARGET` 会执行两件事：（1）选择 Linux/macOS 上的正确 Unix 套接字文件名，（2）为该模拟器的地址空间渲染所有工具描述，内存映射和设置帮助。默认值为 `pcsx2` 以保持向后兼容。
## 要求
- 启用 PINE 的模拟器（请参见下面的设置）
- **Node.js 22+**
## 安装
### 选项 A - 从 npm 安装（推荐）
```bash
npm install -g mcp-pine
```
通过 `mcp-pine` 验证（它打印启动行并等待标准输入 - `Ctrl+C` 退出）。
### 选项 B - `npx`（无需安装）
```bash
npx -y mcp-pine
```
### 选项 C - 克隆并开发
```bash
git clone https://github.com/dmang-dev/mcp-pine
cd mcp-pine
npm install # 也通过 `prepare` 钩子运行构建
```
## 模拟器设置
### PCSX2
1. 启动 PCSX2（1.7.x Qt 或更新版本）。
2. **设置 → 高级 → 启用 PINE 服务器** （该选项可能在某些版本中位于不同的子菜单中 - 在设置中搜索“PINE”）。
3. 默认槽位是 **28011**。如果您更改了它，请为 `mcp-pine` 设置 `PINE_SLOT`。
4. 加载任何游戏。
就是这样 - 没有脚本，没有控制台命令。启用后，PINE 始终可用。
### RPCS3
RPCS3 有自己的 IPC 实现，镜像 PINE 的操作码集，但尚未与此客户端彻底测试。要试用：
1. **配置 → 高级 → 启用 IPC 服务器** （或类似 - 检查当前的 RPCS3 文档）。
2. 记下配置的端口。
3. 运行 `PINE_TARGET=rpcs3 PINE_SLOT=<port> mcp-pine`。
如果某些操作不正常，请提交问题并提供详细信息。
## 在您的 MCP 客户端中注册
### Claude Code（CLI）
```bash
claude mcp add pine --scope user mcp-pine
```
验证：
```bash
claude mcp list
# pine: mcp-pine - ✓ 已连接
```
### Claude Desktop
编辑 `claude_desktop_config.json`:
| 平台 | 路径 |
|---|---|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
```json
{
"mcpServers": {
"pine": {
"command": "mcp-pine"
}
}
}
```
重启 Claude Desktop 后生效。
### 其他 MCP 客户端
`mcp-pine` 通过标准 MCP 进行通信。运行它并连接任何兼容的客户端。
## 配置
| 环境变量 | 默认值 | 目的 |
|---------------------|---------------|---------|
| `PINE_TARGET` | `pcsx2` | 模拟器名称。已知值：`pcsx2`，`rpcs3`。选择（1）Linux/macOS 上的 Unix 套接字文件前缀（`<target>.sock.<slot>`），和（2）工具描述中显示的内存映射和设置帮助。未知值传递时会使用通用内存映射。 |
| `PINE_SLOT` | 目标默认值 | PINE 槽位 - 也是 Windows 上的 TCP 端口。默认值：`pcsx2`=28011，`rpcs3`=28012。显式设置以覆盖。 |
| `PINE_HOST` | `127.0.0.1` | 覆盖主机（仅限 TCP） |
| `PINE_SOCKET_PATH` | （自动） | 覆盖 Linux/macOS 上的完整 Unix 套接字路径，绕过自动解析 |
## 工具
| 工具 | 描述 |
|------|-------------|
| `pine_ping` | 通过查询模拟器版本验证连接 |
| `pine_get_info` | 标题，序列号（例如 `SLUS-21274`），磁盘 CRC，游戏版本，状态 |
| `pine_get_status` | 仅运行/暂停/关闭状态 |
| `pine_read8` / `pine_read16` / `pine_read32` / `pine_read64` | 读取内存 |
| `pine_read_range` | 批量读取最多 4096 个字节（客户端管道 PINE 调用） |
| `pine_write8` / `pine_write16` / `pine_write32` / `pine_write64` | 写入内存（仅限 RAM - ROM 写入被静默丢弃） |
| `pine_save_state` | 触发保存状态到编号的槽位（0-255） |
| `pine_load_state` | 触发从编号的槽位加载状态（0-255） |
参阅 [`docs/RECIPES.md`](docs/RECIPES.md) 以获取端到端示例（RAM 猎人，结构解码，快照-实验-恢复）。
### PlayStation 2 地址空间（PCSX2，默认目标）
| 范围 | 区域 |
|-------|--------|
| `0x00100000-0x01FFFFFF` | EE 主 RAM（32 MiB） - **从这里开始查找游戏数据** |
| `0x10000000` | 硬件寄存器（DMA，GIF，VIF） |
| `0x11000000` | VU0 / VU1 内存 |
| `0x12000000` | GS 特权寄存器 |
| `0x1C000000-0x1C1FFFFF` | IOP RAM（2 MiB） |
| `0x1F800000` | IOP 临时存储 |
| `0x70000000` | EE 临时存储（16 KiB） |
## 故障排除
| 症状 | 原因/解决方法 |
|---|---|
| `无法访问 PINE 服务器` | 模拟器未运行，PINE 未在设置中启用，或槽位/端口不匹配。检查 `PINE_SLOT`。 |
| `PINE FAIL 响应` （0xFF） | 模拟器拒绝了请求 - 通常是因为未加载游戏，或地址未映射。 |
| 读取返回零 | 地址位于未分配的区域。尝试 `0x00100000` 首先（几乎总是位于加载的 EE RAM 中）。 |
| 工具调用有效，但值看起来损坏 | 检查字节顺序预期 - PINE 返回小端；如果您正在解释字符串，请使用 `read_range` 样式的字节读取。 |
| `PINE 调用超时（10 秒）` 从 `pine_ping` 在一些重度使用后 | **PCSX2 的 PINE 服务器可能会卡住。** 其请求队列很脆弱 - 如果第三方工具过于激进地进行管道传输（超过 ~6 个正在进行的请求），它会静默丢弃请求，从那时起每个回复都与错误对齐的客户端不符。症状：即使是全新的 `pine_ping` 也超时。 **解决方法：完全重启 PCSX2.** 重新连接 alone 无效 - 损坏在模拟器端。 |
| `pine_read_range` 比 mGBA 的 `read_range` 慢 | 预期。PINE 没有本机批量读取，因此我们 **串行** 发出调用（管道传输可能会使 PCSX2 卡住 - 见上文）。环回 TCP 很快，因此这通常不是问题：测量 PCSX2 v2.6.3 上完整的 4096 字节读取时间 ~52 毫秒。对于需要较低延迟且可以容忍偶尔重启模拟器的工作负载，请设置 `PINE_PIPELINE_BATCH=2`。 |
## 开发
```bash
npm install
npm run dev # tsc --watch
```
针对正在运行的 PCSX2 进行快速烟雾测试：
```bash
node .scratch/smoke.cjs
```
## 使用 MCP 检测器进行调试
使用 [MCP 检测器](https://github.com/modelcontextprotocol/inspector) 浏览和调用此服务器的工具：
```bash
PINE_TARGET=pcsx2 npm run inspector
```
如果您已编辑 `src/`，请先构建（`npm run build`，或保持 `npm run dev` 运行）。设置 `PINE_TARGET` （`pcsx2` 默认，或 `rpcs3`）和 `PINE_SLOT` 以匹配您的模拟器 - 例如 `PINE_TARGET=rpcs3 PINE_SLOT=28012 npm run inspector`。`tools/list` 即使没有连接模拟器也有效；**调用** 工具需要 PCSX2（或 RPCS3）运行并启用 PINE/IPC。
## 许可证
[MIT](LICENSE)
## 相关
- [mcp-mgba](https://github.com/dmang-dev/mcp-mgba) — MCP 服务器，适用于 mGBA Game Boy Advance 模拟器（还包括按钮输入 + 截图，这是 PINE 不提供的）
- [PINE 协议规范](https://github.com/GovanifY/pine) — 底层 IPC 标准
