New:Microsoft Teams Notifications Are Now Available in Socket.Learn more →

Get Started

ppsspp-dfx-mcp

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

ppsspp-dfx-mcp

PPSSPP debug MCP server — engineering-grade debugging SDK for PSP game localization

PyPI

Version: 0.1.5

Weekly downloads: 413

Maintainers: 1

Weekly downloads

Created: last week

ppsspp-dfx-mcp

English | 中文

一个把 PPSSPP 变成 AI 可调试目标的 MCP（Model Context Protocol）服务器。它把 PSP 模拟器的 WebSocket 调试器封装为面向 LLM agent 的工具面：会话生命周期、内存读写、反汇编、断点、CPU 控制、输入自动化、截图、回放录制与诊断脚本——并内建结构化契约、防御性错误分类法与任务级评估。

文档：docs/SCOPE.md（范围与协议面边界）· CHANGELOG.md（变更记录）

项目状态

项目处于 alpha 阶段并快速迭代，工具面与配置格式可能出现不兼容变更。运行前请阅读 SECURITY.md。

功能特性

41 个静态工具，全部带结构化 inputSchema / outputSchema——没有无约束的返回值，每个参数都有类型和说明。
动态脚本工具：项目专属的诊断脚本通过 scripts.manifest.yaml 暴露为 ppsspp_script_<name> 工具，输入类型由脚本自带的 Pydantic model 决定； ppsspp_run_script 调用未暴露的脚本，ppsspp_list_scripts 查看清单—— 详见配置。
会话模型：支持多个并发 PPSSPP 会话、就绪探测（wait_ready）与楔死自愈（resilient 启动）。
面向 agent 的人体工学：组合工具（ppsspp_frame_snapshot、 ppsspp_trace_memory_access、ppsspp_batch_step）、session_id 自动解析、防御性错误码（[CODE] message 格式、CPU 冻结与连接断开的区分），错误文本内嵌恢复建议。
后台自动化：批量任务跑在独立的服务端任务上，不受 MCP 客户端工具调用超时的影响；支持状态轮询、取消与注册表盘点（ppsspp_batch_list）。
内建评估体系（evals/）：21 张场景卡 + 确定性门禁 + 对录制夹具的盲测 runner + 汇总报告——工具面按 agent 实际使用的方式被测试。
诚实的协议面：能力只在其背后存在可用实现时才声明；刻意置 false 的开关附有设计理由说明。

运行

环境要求：Python 3.13+（配合独立 venv，原因见从源码运行）；带 WebSocket 调试器的 PPSSPP——官方发行版即可，开启方法见 docs/ppsspp-build.md（服务器负责启动它，并连接 ws://<host>:<port>/debugger）；一个 MCP 客户端（ZCode、Claude Desktop、 MCP Inspector 等）。

从 PyPI 安装运行

使用独立 venv——本服务器的 MCP SDK v2 无法与其他 MCP 服务器锁定的 1.x mcp 包共存：

# Windows：
py -3.14 -m venv .venv
# POSIX：
python3.14 -m venv .venv
.venv\Scripts\python -m pip install ppsspp-dfx-mcp     # Windows
.venv/bin/python -m pip install ppsspp-dfx-mcp         # POSIX

把服务器注册到你的 MCP 客户端（入口由安装包提供，无需指向仓库内脚本）：

{
  "mcpServers": {
    "ppsspp-dfx": {
      "command": "C:/absolute/path/to/.venv/Scripts/ppsspp-dfx-mcp.exe",
      "cwd": "C:/absolute/path/to/your-project"
    }
  }
}

command 指向安装 venv 内的入口可执行文件，POSIX 上为 .venv/bin/ppsspp-dfx-mcp；cwd 是服务器发现 .ppsspp-dfx/ 配置的目录（见配置）。手动启动验证：

.venv/Scripts/ppsspp-dfx-mcp.exe   # Windows
.venv/bin/ppsspp-dfx-mcp           # POSIX

然后直接给 agent 派任务："启动模拟器加载这个 ISO，告诉我当前 PC"——服务器负责会话启动、就绪探测与状态读取。工具描述遵循 PURPOSE / USAGE / BEHAVIOR / RETURNS 约定，错误路径内嵌恢复指引，agent 无需示例即可自助。

不要在客户端与服务器之间插入包装脚本：Windows 上 os.execv 是 CreateProcess + 父进程等待（不是 POSIX 进程替换），多一层会让最内层服务器立即读到 stdin EOF 并静默退出——表面现象只是 -32000: Connection closed。

从源码运行

仓库检出内自带引导脚本与可直接使用的 .mcp.json：

git clone https://github.com/AstralVoidZ/ppsspp-dfx-mcp.git
cd ppsspp-dfx-mcp

# 在本目录执行——创建 .venv/ppsspp-dfx-mcp 并安装（editable，含 dev 依赖）：
python scripts/check_env.py --bootstrap

# 校验解释器 / SDK 版本 / 包导入：
python scripts/check_env.py --check

把服务器注册到你的 MCP 客户端——让客户端读取仓库里的 .mcp.json，或按同样的结构内联：

{
  "mcpServers": {
    "ppsspp-dfx": {
      "command": ".venv/ppsspp-dfx-mcp/Scripts/python.exe",
      "args": ["-m", "ppsspp_dfx_mcp"],
      "cwd": "${CLAUDE_PROJECT_DIR}"
    }
  }
}

cwd 必须是同时存放 .venv/ 与 .ppsspp-dfx/ 配置的目录（独立检出时即仓库根）。 POSIX 上请用 .venv/ppsspp-dfx-mcp/bin/python 代替 Scripts/python.exe。

手动启动验证：

.venv/ppsspp-dfx-mcp/Scripts/python -m ppsspp_dfx_mcp   # Windows
.venv/ppsspp-dfx-mcp/bin/python -m ppsspp_dfx_mcp        # POSIX

配置

环境变量（全部可选）：

变量	默认值	说明
`PPSSPP_DFX_LOG_LEVEL`	`INFO`	日志级别
`PPSSPP_DFX_LOG_FORMAT`	`text`	日志格式（`text` 或 `json`）
`PPSSPP_DFX_RATE_LIMIT`	`60`	单工具限流（次/分钟，0 为关闭）
`PPSSPP_DFX_WS_HOST`	`127.0.0.1`	PPSSPP WebSocket 主机
`PPSSPP_DFX_WS_PORT`	`12345`	PPSSPP WebSocket 端口
`PPSSPP_DFX_EXE_PATH`	（来自 yaml）	PPSSPP 可执行文件路径
`PPSSPP_DFX_SESSIONS_PATH`	`~/.ppsspp-dfx/sessions.json`	会话状态路径

项目级 YAML 配置位于 .ppsspp-dfx/config/（相对工作目录）：

project.yaml — ppsspp_exe 路径与项目元数据
addresses.yaml — 命名地址常量（同时为内存向导的 completions 能力提供候选）
scripts.manifest.yaml — 诊断脚本清单。每个条目带机器可读的 status （migrated = 可运行，skeleton = 方法体返回 not_implemented）。标记 exposed: true 的脚本在启动时注册为 ppsspp_script_<name> 工具——skeleton 除外，preflight 会拒绝它们。ppsspp_reload_scripts 将动态工具注册表与清单重新同步（无需重启），并报告声明与注册的对账结果。

独立部署快速开始

三份配置文件的开箱模板见 examples/——从这里开始，不要从零手写 YAML：

mkdir -p .ppsspp-dfx/config
cp examples/project.yaml examples/addresses.yaml \
   examples/scripts.manifest.yaml .ppsspp-dfx/config/
# 然后编辑 .ppsspp-dfx/config/project.yaml：把 ppsspp_exe 指向你的
# 带 WebSocket 调试器的 PPSSPP 构建；把 addresses.yaml 里的 PLACEHOLDER
# 地址替换为你自己逆向得到的值。

首次会话前需要知道的两件事：

没有 scripts.manifest.yaml 服务器仍能启动，但所有 ppsspp_script_* 工具会静默消失——即使 scripts: 列表为空也请保留模板（check_env.py --check 报的正是这个警告）。
配置为空且无占位值时，服务器侧一切功能可用；只有会话启动需要真实的 ppsspp_exe（或 PPSSPP_DFX_EXE_PATH），地址常量也只有在你提供自己游戏的数值后才有意义。

协议面

在 initialize 握手时声明——且只声明实际注册的能力（SDK 从请求处理器是否存在来推导各项能力，所以这里出现的每一项背后都有可用实现）：

能力	声明	说明
`tools`	✅	41 个静态工具 + 动态 `ppsspp_script_<name>`
`resources`	✅	`ppsspp://game-state`、`ppsspp://registers`（快照）
`prompts`	✅	`memory-breakpoint-wizard`、`memory-trace-wizard`
`completions`	✅	两个内存向导的 `address` 参数，候选来自 `addresses.yaml`
`logging`	❌	协议修订 2026-07-28 移除了 `logging/setLevel`
`tasks`	❌	仅 SDK 2.2.0 的类型定义，无服务器端实现

tools.list_changed 与 resources.subscribe 刻意置 false。SDK 2.2.0 的 MCPServer 没有暴露握手期设置 notification_options 的入口，声明它们等于承诺一个服务器发不出的通知。现有替代：

ppsspp_reload_scripts 会报告变化内容（exposed_added / exposed_removed），agent 无需通知通道即可响应。
服务器 instructions 字符串告诉新 agent 工具面包含什么。

若未来 SDK 开放了该入口，翻转开关并补上 send_*_list_changed 调用即可——L2 契约测试（tests/unit/l2_mcp_contract/test_capabilities_contract.py）断言当前的 false 状态并会失败，这是设计信号：该决策需要重新审视，而非回归。

返回形态

图像类工具（ppsspp_screenshot、ppsspp_dump_texture、 ppsspp_dump_clut）返回拆成两半的 CallToolResult：

content — 一个携带像素的 ImageContent 块。
structuredContent — 仅元数据（file_path / size_bytes / format，加上 mode、width、height、empty 等各工具自有字段）。图像的 base64 副本不在这个通道里——那会膨胀 schema，且重复 content 已承载的内容。

每个工具都声明结构化 outputSchema——没有工具返回无约束对象或 items 为空的数组。ppsspp_run_script 的 input 参数是唯一注册在案的例外：其形状由被调用的脚本决定，因此只描述而不约束。

错误处理

当被模拟的 CPU 冻结（死循环 / HLE 阻塞 / GPU 管线停滞）时，服务器返回 CPU_FREEZE_SUSPECTED 而不是笼统的 WS_DISCONNECTED——区分"PPSSPP 进程还活着但 CPU 冻结"与"进程已死 / WebSocket 断开"。

对 CPU_FREEZE_SUSPECTED 的建议处理：

不要重启会话——PPSSPP 还在运行。
用 ppsspp_screenshot 截取当前画面辅助诊断。
尝试 step(action='resume')（对真正的死循环可能无效）。
用 hle.thread.list 查看线程状态（可能暴露 HLE 阻塞）。
在当前 PC 处用 ppsspp_disassemble 检查指令流。

相关错误码：WS_DISCONNECTED（PID 已死，真断开）、WS_TIMEOUT（带票据的 RPC 超时，保守默认）、CPU_STATE_ERROR（当前 CPU 状态不适合该操作）。错误文本始终以 [CODE] 开头，agent 可编程分类；存在下一步的地方都内嵌了恢复建议。

故障排查速查表

症状	原因 / 修复
`-32000: Connection closed`（无任何信息）	MCP 客户端与服务器之间有包装脚本：Windows 上 `os.execv` 实为 `CreateProcess` + 父进程等待（非 POSIX 替换），内层 server 的 stdin 立即 EOF 静默退出。去掉中间层，直接以 venv 解释器为 `command`（见从源码运行）
`check_env` 报「独立 venv 缺失」	`.venv/` 被 gitignore 排除，新 clone 必然没有。运行 `python scripts/check_env.py --bootstrap`（见从源码运行）
`mcp SDK 版本不满足` / 导入期崩溃	系统 Python 的 `mcp` 包常被其他 MCP server 钉在 1.x，与 SDK v2 不可调和。不要全局安装——用 `check_env.py --bootstrap` 建独立 venv，或按从 PyPI 安装运行安装到独立 venv
`ppsspp_script_*` 工具全部消失（服务器正常启动）	`.ppsspp-dfx/config/scripts.manifest.yaml` 缺失——缺失仅告警不阻断，动态工具静默清空。从 `examples/` 拷贝三份模板修复（`check_env.py --check` 会提示）
`[PPSSPP_NOT_FOUND]`	PPSSPP 可执行文件未配置。设 `PPSSPP_DFX_EXE_PATH`，或 `.ppsspp-dfx/config/project.yaml` 的 `ppsspp_exe`（优先级 env > yaml）
找不到 `.ppsspp-dfx/config`	配置目录按 cwd 发现（无父级上溯）。从含 `.ppsspp-dfx/` 的目录启动，或设 `PPSSPP_DFX_CONFIG_DIR` 指向它
WebSocket 连接失败 / `WS_DISCONNECTED`	PPSSPP 未运行、端口不对，或未启用 WebSocket debugger。`check_env.py --check` 验证环境，`ppsspp_session(action='get')` 验证会话
工具调用挂起 / 超时（`WS_TIMEOUT`）	PPSSPP 主循环负责 dispatch WebSocket 请求：UI 卡死、模态对话框弹出或模拟暂停时请求不会被处理。先截图确认 UI 状态
boot 阶段 `[BOOT_TIMEOUT]`	启动楔死疑似。`start(resilient=true)` 会隔离 GPU 后端黑名单（仅重命名 `FailedGraphicsBackends.txt`，不删除）并自愈重启（≤2 次重试）
`read_u32` 返回 `IR_ENCODING_DETECTED`	读到的是 JIT-IR 代码而非 MIPS 指令。改用 `ppsspp_disassemble`

已知限制

诚实声明协议面的边界——以下各项均已在对应工具的描述中标注，此处汇总：

无存档 API：PPSSPP 的 WebSocket debugger 不暴露 savestate.* 事件，服务器无法提供存档保存/加载。用 PPSSPP 的 UI 快捷键（F1-F8 存档槽）。
帧推进只有指令级：step 走 cpu.stepInto。整帧推进的替代：在 vblank 处理器设断点后 resume。
analog 摇杆是持久共享态：send_analog 写入后保持到下次写入，无自动复位。
VRAM 直读截图不可靠：直读 VRAM 与 GPU 渲染输出不同步，颜色可能失真；默认走 render 通道。source='output' 在部分游戏上有崩溃风险，仅在 render 通道空帧回退时使用。
replay 时钟锚定：replay 时间线使用录制会话 boot 时刻的绝对游戏时钟，只能在全新 boot 后按 boot 对齐序列注入（工具返回体带对齐序列说明）。
保护地址段写入需显式 force=true：内核内存与 top.prx 代码段默认拒绝写入/汇编码——这是防误写设计，不是限制性 bug。
会话状态单写者：~/.ppsspp-dfx/sessions.json 跨进程共享会话登记，并发多个 MCP 服务器实例指向同一路径时后写覆盖。

社区与支持

通过 GitHub Issues 提交缺陷报告与功能建议。
配置与会话问题先查故障排查速查表与已知限制。

贡献

见 CONTRIBUTING.md。

开发

从 docs/SCOPE.md（范围与协议面边界）与 evals/README.md（盲测评估体系：场景卡、确定性门禁、 runner、报告）入手。

# 全量测试套件（单元 + 契约 + 集成；约 1500 个测试）：
.venv/ppsspp-dfx-mcp/Scripts/python -m pytest tests -q

# 工具签名/描述变更后重新生成工具面基线（与变更同笔提交）：
.venv/ppsspp-dfx-mcp/Scripts/python scripts/dump_tool_surface.py

致谢

PPSSPP —— 被调试目标本身。本服务的 WebSocket 调试协议契约（debugger.ppsspp.org 子协议、事件语义与 HLE 内省字段）对照其源码逐项梳理并建档（见 docs/SCOPE.md）。
mcp-ppsspp、mcp-bizhawk、 mcp-mgba —— 同类模拟器-MCP 桥接方案；本服务的覆盖定位以它们为对照（见 docs/SCOPE.md 的「与同类项目的覆盖对比」）。
运行时依赖（MCP Python SDK、 pydantic、PyYAML、websockets）声明于 pyproject.toml。

引用

@misc{ppssppdfxmcp2026,
  title={ppsspp-dfx-mcp: a PPSSPP debug MCP server for PSP game localization},
  author={AstralVoidZ and contributors},
  year={2026},
  publisher={GitHub},
  howpublished={\url{https://github.com/AstralVoidZ/ppsspp-dfx-mcp}},
}