🚀 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
# 安装开发依赖项
uv add --dev
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 的协助下开发