mcp-ppsspp 是一个 MCP 服务器，用于将 PPSSPP（PlayStation Portable 模拟器）接入任何兼容 MCP 的客户端（例如 Claude Desktop、Claude Code 等）。它通过 PPSSPP 内置的 WebSocket 调试器接口工作，因此不需要像 mcp-bizhawk / mcp-mgba 那样在模拟器中加载 Lua 桥接插件——PPSSPP 自带调试器 WebSocket 接口，服务器直接与其进行 JSON 通信。
用途
该服务器面向需要通过 MCP 客户端控制或调试 PSP 游戏的场景。它把 PPSSPP 的调试能力封装为干净的工具接口，让 MCP 客户端可以读取和写入 PSP 内存、用按键输入驱动游戏、截取屏幕截图、设置 CPU 断点、检查 MIPS Allegrex 寄存器等。
主要能力
- 读写 PSP 内存
- 用按键输入驱动游戏
- 截取屏幕截图
- 设置 CPU 断点
- 检查 MIPS Allegrex 寄存器
连接方式
连接使用子协议 debugger.ppsspp.org，通过 PPSSPP 的调试端口进行。
使用方式
前置条件：
- PPSSPP（带 WebSocket 调试器的较新版本，1.7+）
- 在 PPSSPP 中启用“Allow remote debugger”
设置 PPSSPP 调试器：
- 启动 PPSSPP，加载任意 PSP ISO/EBOOT
- 进入 Settings → Tools → Developer Tools → Allow remote debugger（勾选该框）
- PPSSPP 会显示活动的 host:port（例如 ws://192.168.1.10:12345/debugger）
- 记下端口号——稍后将其设置为 MCP 服务器的环境变量
注册到 MCP 客户端：
- Claude Code (CLI)：将 12345 替换为实际端口
- Claude Desktop：编辑 claude_desktop_config.json，编辑后重启 Claude Desktop
也可通过 npx -y mcp-ppsspp 运行。
PSP 内存映射（速查表）
PSP 为小端序（MIPS Allegrex）。内核模式镜像 0x88xxxxxx 映射到与 0x08xxxxxx 相同的物理 RAM。
按键名称
cross、circle、triangle、square、up、down、left、right、start、select、ltrigger、rtrigger、home。
适用场景
适用于需要通过 MCP 客户端对 PPSSPP 中的 PSP 游戏进行内存读写、输入控制、截图、断点调试和寄存器检查的开发、调试或自动化场景。
限制与注意事项
- 无 savestate API：PPSSPP 的 WebSocket 调试器不暴露 savestate.save / load。目前可使用 PPSSPP 的键位绑定（F1-F8 对应存档槽）通过 UI 操作。理论上可通过 input.buttons.press 触发键位绑定来变通，但并非原生支持。
- 帧推进仅为指令级（cpu.stepInto）。要推进整帧，可在 vblank 处理程序处设置断点并 resume。
- 模拟摇杆为共享状态：ppsspp_send_analog 更新的是持久化的摇杆位置，不会自动释放。
- mcp-ppsspp 没有默认端口——需从 PPSSPP 的 Developer Tools → Allow remote debugger 对话框中读取活动端口，并作为 PPSSPP_PORT 传入。
- tools/list 即使未连接 PPSSPP 也可工作；但调用工具需要 PPSSPP 正在运行并已启用远程调试器。
使用 MCP Inspector 调试
可通过 MCP Inspector 交互式浏览和调用该服务器的工具。如果自上次 npm install 后编辑过 src/，需先构建（npm run build，或保持 npm run dev 运行）。
