shazz/ShirazMCP

# ShirazMCP [](https://github.com/shazz/ShirazMCP/actions/workflows/ci.yml) [](LICENSE)  一个本地的 [MCP](https://modelcontextprotocol.io/) 服务器，用于驱动 [Hatari](https://hatari.tuxfamily.org/) Atari ST/STE 模拟器，以便 AI agent 能够 **运行、调试、冻结、截图、提取和热补丁** Atari ST 程序 — 以非交互方式通过 stdio 进行。 这是一个 2026 年无头 agent 版的经典 ST 冻结/提取 卡带重生物 —— **Ultimate Ripper**（提取图片 + 音乐，保存为数据或可运行的 `.PRG`）和 **Multiface ST**（冻结、内存查看/编辑、反汇编器）。`pause`/`resume` 就是那个冻结按钮；`rip`/`extract` 就是那个提取菜单；`save_prg mode=snapshot` 就是卡带闻名的“保存冻结的机器”功能。 ## 亮点 - **冻结与检查** — `pause` 通过 debugger 中断挂起 CPU；读取寄存器、内存、 视频/声音状态以及截图，全部来自同一冻结瞬间。 - **提取** — 图形（Degas/NeoChrome/MPP），音乐（SNDH/YM，带有播放器指纹数据库）， 打包数据（Pack-Ice/Atomik/PowerPacker/RNC/**ZX0**，递归），引导扇区，以及 **STE DMA-PCM 采样** → WAV。图片识别结果经过**结构评分**（排序并设限 — 不会产生大量误报）。 - **实时逆向工程** — 数值变更**监视点**，静态**交叉引用**，确定性 **帧步进**，以及 Action-Replay **作弊扫描**内存差异搜索。 - **实时热补丁 68k** — `assemble`/`patch`（通过 vasm），然后**持久化**修改：`save_prg` 重新生成打过补丁的 `.PRG`，或者**快照整个机器**到一个自恢复的 `.PRG` 中。 - **查看与聆听**硬件 — 具有STE总线争用模型的周期精确分析， `spectrogram`（“看见音乐”），以及实时的 Ym2149 解码（`ym_state`）。 ## 前置条件 **要*运行* ShirazMCP**（驱动模拟器）： | 需求 | 用途 | 备注 | |---|---|---| | `shiraz-mcp` 二进制文件 | 任何操作 | 自行构建（见下文）— 目前没有预编译版本 | | **hatari** | 模拟器 | 默认为 `/usr/bin/hatari`；使用 `apt install hatari` 或从源码构建 | | **TOS ROM** 镜像 | 启动 ST | 用户提供；路径可配置 | | **X display** (`DISPLAY`) | Hatari 渲染 | 目前不支持无头（`Xvfb`）模式 | | **vasm** (`vasmm68k_mot`) | *可选* — `assemble`/`patch` | 通过 `SHIRAZMCP_VASM` 设置路径；快照 stub 已预编译 | **要从源码*构建*：** **Rust 1.92**（2021 edition）。Rust 仅在构建时需要 — 运行 编译后的二进制文件不需要 Rust 工具链中的任何内容。 ## 构建 ``` cargo build --release # -> target/release/shiraz-mcp ``` ## 添加 MCP 服务器 ShirazMCP 通过 **stdio** 进行 MCP 通信，由 MCP 客户端启动。将其注册到 Claude Code： ``` claude mcp add shirazmcp --env DISPLAY=:0 -- /abs/path/to/target/release/shiraz-mcp ``` 然后输入 `/mcp`（或重启会话）以加载工具 — 它们会显示为 `mcp__shirazmcp__*`。 有关替代的“harness”模式（通过 JSON-RPC 直接驱动二进制文件 — 在服务器本身进行迭代时非常方便），请参阅 **[DEVELOPMENT.md](DEVELOPMENT.md)**。 ## 安装技能 该仓库附带了一个使用技能，用于教导 agent 如何驱动这些工具： - **项目本地：** 它位于 `.claude/skills/shirazmcp/`，当您在此仓库中工作时会被自动识别。 - **全局：** 将该文件夹复制到 `~/.claude/skills/shirazmcp/` 以便在任何项目中使用它。 ## 工具 (35) | 分组 | 工具 | |---|---| | **生命周期** | `start` · `stop` · `pause` · `resume` · `status` | | **调试与内存** | `registers` · `read_memory` · `write_memory` · `search_memory` · `screenshot` · `machine_state` · `debug` | | **分析** | `disasm` · `profile` · `breakpoint` · `state` | | **逆向工程** | `watch` · `xrefs` · `run_frames` · `cheat_scan` | | **提取器** | `rip` · `list_ripper_plugins` · `extract` · `find_picture` · `identify_music` · `rip_sample` · `bootsector` · `view_memory_as_screen` · `depack` | | **汇编 / 补丁 / 持久化** | `assemble` · `patch` · `save_prg` (`mode=repatch\|snapshot`) | | **音频** | `record_audio` · `spectrogram` · `ym_state` | 完整的行为、工作流程和注意事项详见 **[shirazmcp 技能](.claude/skills/shirazmcp/SKILL.md)**。 ## 一个完整的示例 `docs/live-patching.md` 演示了如何热补丁正在运行的 demo — 更改其滚动文本、 渐变颜色，并**在内存中实时**交换其 logo 行，然后通过 MCP 工具调用将结果持久化为一个 独立的 `.PRG`。 ## 平台支持 在 **Linux** 和 **macOS** 上构建和运行。目前**不支持 Windows**：模拟器是通过 Unix FIFO 控制的，而原生的 Hatari 在 Windows 上没有外部命令通道。 跨平台传输适配器（目标是 `tattlemuss/hatari` hrdb 分支的 TCP debug 协议）已经设计并处于跟踪中 — 请参阅 issues。 ## 文档 - **[DEVELOPMENT.md](DEVELOPMENT.md)** — 在开发环境中构建、运行和驱动服务器 - **[docs/live-patching.md](docs/live-patching.md)** — 实时逆向工程/热补丁教程 - **[ARCHITECTURE.md](ARCHITECTURE.md)** — 层次、结构和模式 - **[decisions.md](decisions.md)** — 架构决策记录 - **`docs/plan/*.md`** — 各功能的实现规范 ## 许可证 [MIT](LICENSE) © shazz

标签：Atari ST, MCP服务器, Rust, 云资产清单, 可视化界面, 模拟器工具, 游戏资源提取, 热补丁, 网络流量审计, 逆向工程, 通知系统