mcp-pyboy

🚀 MCP PyBoy 模拟器服务器

这是一个 MCP（模型上下文协议）服务器，它能让大语言模型（LLMs）通过 PyBoy 模拟器与 Game Boy 游戏进行交互。

🚀 快速开始

运行服务器

# 基本用法
uv run mcp-pyboy

# 带选项（即将推出）
uv run mcp-pyboy --roms-dir ./roms --log-level DEBUG

项目结构

mcp-pyboy/
├── src/mcp_server/          # 主包
│   ├── mcp_server/         # MCP 协议实现
│   ├── game_session/       # PyBoy 模拟器包装器
│   ├── notebook/           # 知识持久化
│   ├── handlers/           # MCP 工具实现
│   └── utils/              # 共享工具
├── tests/                  # 测试套件
├── docs/                   # 架构文档
├── roms/                   # ROM 文件目录
├── saves/                  # 存档目录
├── notebooks/              # 游戏知识存储

✨ 主要特性

本服务器为大语言模型（LLMs）提供了以下能力：

• 🎮 加载并游玩 Game Boy ROM 文件
• 🎯 通过按钮输入和序列控制游戏
• 📸 捕获并分析游戏画面
• 💾 保存和加载游戏状态
• 📝 维护关于游戏的持久知识

📦 安装指南

1. 安装 uv（如果尚未安装）

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或者使用 pip
pip install uv

2. 克隆仓库

git clone https://github.com/yourusername/mcp-pyboy.git
cd mcp-pyboy

3. 设置开发环境

# 安装所有依赖项（自动创建 .venv）
uv sync

# 安装开发依赖项
uv sync --extra dev

4. 验证安装

# 检查 CLI 是否可用
uv run mcp-pyboy

# 运行测试（实现后）
uv run pytest

🔧 技术细节

开发工具

本项目使用了现代 Python 开发工具：

• uv - 快速依赖管理
• Black - 代码格式化（88 字符行长度）
• Ruff - 代码检查和导入排序
• MyPy - 静态类型检查
• pytest - 测试框架

常见开发命令

# 格式化代码
uv run black src/ tests/

# 运行代码检查
uv run ruff check src/ tests/

# 类型检查
uv run mypy src/

# 运行测试
uv run pytest tests/ -v

# 安装新依赖项
uv add <package-name>

# 安装开发依赖项
uv add --dev <package-name>

VS Code 集成

本项目包含了 VS Code 的配置，以实现最佳开发体验：

• .vscode/settings.json - 集成了 Black/Ruff 的工作区设置
• .vscode/extensions.json - 推荐的扩展

该配置确保：

• Black 处理所有格式化
• Ruff 仅处理代码检查（无格式化冲突）
• 从虚拟环境中使用正确的 Python 解释器

💻 使用示例

基础用法

# 基本用法
uv run mcp-pyboy

高级用法

# 带选项（即将推出）
uv run mcp-pyboy --roms-dir ./roms --log-level DEBUG

📚 详细文档

MCP 可用工具

服务器完全实现后，将提供以下工具：

模拟控制

• load_rom - 加载 Game Boy ROM 文件
• reset_game - 重置当前游戏
• set_emulation_speed - 控制游戏速度

输入控制

• press_button - 按下 Game Boy 按钮
• hold_button - 按住按钮
• release_button - 释放按住的按钮
• send_input_sequence - 执行输入序列

屏幕和状态

• capture_screen - 获取当前游戏画面
• save_state - 保存当前游戏状态
• load_state - 加载保存的状态
• list_states - 列出可用的存档状态

知识管理

• create_note - 创建关于游戏的笔记
• update_note - 更新现有笔记
• search_notes - 搜索游戏知识
• list_notes - 列出当前游戏的所有笔记

架构

有关详细的架构文档，请参阅：

• 项目设计
• 技术架构
• MVP 实现路线图

📄 许可证

[待添加许可证信息]

致谢

• 基于 PyBoy - Game Boy 模拟器构建
• 使用 MCP - 模型上下文协议
• 在 Claude Code 的协助下开发