AI导哈

Solar2D MCP服务器

Solar2D MCP服务器是一个用于与Solar2D（Corona SDK）项目交互的服务器，支持AI助手运行、调试和交互Solar2D游戏。

  • by sensiblecoder
  • Python
  • 本地部署
  • 8 星标
  • 更新于
在 GitHub 查看 sensiblecoder/solar2d-mcp

使用说明

Solar2D MCP服务器

A. 模型上下文协议（MCP） 用于处理Solar2D（Corona SDK）项目的服务器。该服务器使AI助手能够运行、调试Solar2D游戏并与之交互。

适用于任何MCP兼容客户端，包括：

  • Claude 代码命令行工具
  • 其他支持MCP的AI助手
  • 自定义集成

设置

  1. 安装依赖项：

    pip install -e .

  2. 测试服务器：

    python server.py

配置

克劳德桌面版

将此配置添加到您的Claude Desktop配置文件中：

MacOS： ~/Library/Application Support/Claude/claude_desktop_config.json

窗户： %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "solar2d": {
      "command": "/path/to/solar2d-mcp/.venv/bin/python",
      "args": [
        "/path/to/solar2d-mcp/server.py"
      ]
    }
  }
}

添加配置后，重新启动Claude Desktop。

Claude 代码命令行工具

使用添加服务器 claude mcp add 命令：

claude mcp add --scope user --transport stdio solar2d \
  /path/to/solar2d-mcp/.venv/bin/python \
  /path/to/solar2d-mcp/server.py

验证服务器是否已连接：

claude mcp list

您还可以使用以下命令将其添加到特定项目中 --scope project 或创建 .mcp.json 项目根目录中的文件。

首次设置

首次使用时，服务器需要知道Solar2D模拟器的安装位置。

  1. 自动检测：服务器自动扫描常见安装路径
  2. 确认：系统将提示您确认或提供模拟器位置
  3. 铭记：您的选择已保存到 ~/.config/solar2d-mcp/config.json

首次运行流程示例：

User: Run my Solar2D project
Assistant: Solar2D simulator needs to be configured. Detected:
  - /Applications/Corona-3726/Corona Simulator.app/Contents/MacOS/Corona Simulator

Use configure_solar2d with confirm=true to use this path.

User: Yes, use that one
Assistant: [calls configure_solar2d(confirm=true)]
✓ Solar2D simulator confirmed and saved!

特性

工具

  • configure_solar2d -配置Solar2D模拟器路径
    • 自动检测已安装的模拟器
    • 跨会话持久化配置
    • 使用 confirm=true 接受检测到的路径
    • 或者提供自定义路径 simulator_path="..."
  • run_solar2d_project -在模拟器中运行Solar2D项目
    • 接受项目目录或main.lua路径
    • 可选的调试和控制台标志
    • 在后台启动模拟器
    • 注入捕获所有print（）输出的记录器
  • read_solar2d_logs -从运行Solar2D模拟器读取控制台日志
    • 查看游戏代码中的所有Lua print（）语句
    • 可配置显示的最近行数
    • 帮助实时调试Lua代码
    • 自动设置：记录器在第一次运行时自动注入main.lua
    • 注意：仅捕获Lua print（）输出，不捕获Solar2D系统消息
  • list_running_projects -列出所有跟踪的Solar2D模拟器实例
    • 显示PID、状态和日志文件位置
    • 可用于管理多个正在运行的项目
  • start_screenshot_recording -开始从模拟器中捕获屏幕截图
    • 以每秒10帧（间隔100毫秒）的速度拍摄
    • 默认录制时长：60秒（最长：300秒/5分钟）
    • 可以在已捕获的同时扩展录制
  • stop_screenshot_recording -提前停止截图录制
  • get_simulator_screenshot -获取屏幕截图以进行可视化分析
    • which="latest" -立即捕获新的屏幕截图（默认）
    • which="last" -从录制会话中获取最新信息
    • which="all" -列出所有录制的屏幕截图
    • which="5" -按编号获取特定录制的屏幕截图
  • list_screenshots -列出所有可用的截图及其文件大小
  • simulate_tap -点击模拟器屏幕
    • 使用基于百分比的边界框（左、右、上、下）
    • 敲击指定区域的中心
    • 示例：按钮水平30-50%，垂直60-70%
  • simulate_drag -在模拟器屏幕上的两点之间拖动/滑动
    • 基于百分比的开始和结束边界框
    • 可配置拖动持续时间
    • 适用于刷卡、打牌和滑卡
  • find_object -在屏幕上找到可触摸的显示对象
    • 报告位置，以便精确定位轻击/拖动
  • get_display_info -获取显示坐标系信息

游戏状态和场景

  • get_game_state -以JSON格式获取结构化游戏状态
    • 返回当前场景、战斗状态、玩家统计数据和UI状态
    • 比解析屏幕截图更快、更可靠
  • run_scenario -配置并启动测试场景，而无需重新启动
    • 从加载已保存的场景 scenarios/ 或通过内联设置
    • 可选种子 math.random 用于确定性回放
    • 支持带有脚本的场景 steps 运行a的数组 通过/失败测试（操作： wait_for, verify, wait, tap, drag, play_card, tap_stat, tap_choice)
  • list_scenarios -列出项目中保存的场景文件 scenarios/ 文件夹

资源

  • solar2d://info -服务器信息

实验/WIP

这些集成正在进行中，其工具表面可能会发生变化：

  • 特雷洛 -从助理那里管理项目板： configure_trello, setup_trello_board, create_trello_card, list_trello_cards, get_trello_card, update_trello_card, comment_trello_card, attach_to_trello_card
  • 社交媒体 -起草并发布帖子： configure_social_media, preview_social_post, publish_social_post

可能的计划

  • 更复杂的“玩”能力，基于“看”
  • 内置技能
    • 惯例和良好做法
    • 常见模式/模板

发展

服务器使用模型上下文协议（MCP）Python SDK。

项目结构

solar2d-mcp/
├── server.py          # MCP server entry point
├── config.py          # Configuration management and auto-detection
├── utils.py           # Shared utilities
├── tools/
│   ├── __init__.py    # Tool dispatcher
│   ├── configure.py   # configure_solar2d tool
│   ├── run_project.py # run_solar2d_project tool
│   ├── read_logs.py   # read_solar2d_logs tool
│   ├── list_projects.py # list_running_projects tool
│   ├── screenshot.py  # Screenshot recording tools
│   ├── touch.py       # Touch/drag simulation tools
│   ├── state.py       # Game state & test scenario tools
│   ├── social/        # Social media tools (experimental)
│   └── trello/        # Trello board tools (experimental)
├── resources/
│   ├── __init__.py    # Resource dispatcher
│   └── info.py        # solar2d://info resource
├── pyproject.toml     # Project dependencies and metadata
└── README.md          # This file

测试

配置后，您可以使用以下提示测试服务器：

  • “配置Solar2D”（首次设置）
  • “在/path/to/my game上运行我的Solar2D项目”
  • “启动Solar2D模拟器，并为我的项目启用调试”
  • “显示我正在运行的Solar2D项目的日志”
  • “阅读Solar2D日志的最后100行”
  • “列出所有正在运行的Solar2D项目”

捕获Lua print（）输出

MCP服务器 自动地 捕获你所有的Lua print() 声明！

设置（一次）

通过MCP运行项目一次：

  1. 服务器创建 _mcp_logger.lua 项目目录中的文件
  2. 自动注射 require("_mcp_logger") 进入你的 main.lua （如果尚未出现）

记录仪智能插入：

  • 之后 mobdebug 如存在
  • 在其他之前 require 如果没有mobdebug语句
  • 在文件开头，否则

适用于手动启动！

一旦记录仪被注入，它就会工作 永远 -即使您从IDE或命令行手动启动Solar2D！

  • 日志文件位置： /tmp/corona_log_<project-name>.txt （可预测，基于项目目录名称）
  • 所有Lua print() 输出由自动捕获 _mcp_logger.lua
  • 您的打印仍然在控制台中正常显示（Solar2D的输出）
  • 每次启动时都会清除日志文件 - _mcp_logger.lua 在Solar2D启动时截断文件
  • 使用 read_solar2d_logs 无论Solar2D是如何启动的，都可以随时查看日志的工具
  • MCP服务器仅读取日志文件- _mcp_logger.lua 负责所有写作

捕获屏幕截图

MCP服务器可以从运行模拟器中捕获屏幕截图以进行可视化分析！

运作原理

  1. 自动注射模块：当你运行一个项目时， _mcp_screenshot.lua 创建并注入 main.lua
  2. 控制文件信号：MCP服务器写入控制文件以开始/停止录制
  3. 定期捕捉：录制时每100毫秒（10 fps）捕获一次屏幕截图
  4. JPEG压缩：对于较小的文件大小，图像以内容分辨率保存为JPEG

屏幕截图位置

屏幕截图保存到： /tmp/solar2d_screenshots_<project-name>/

模拟器启动时，目录会被清除，但屏幕截图会在同一运行中的录制会话中持续存在。

录制工作流程

User: Start recording screenshots for 30 seconds
Assistant: [calls start_screenshot_recording with duration=30]

User: Show me what the game looks like now
Assistant: [calls get_simulator_screenshot with which="latest"]
         [displays the screenshot for visual analysis]

User: Stop recording early
Assistant: [calls stop_screenshot_recording]

扩展录制

你可以打电话 start_screenshot_recording 同时已经记录以延长持续时间。截图从停止的地方继续（不重置）。

触控交互

MCP服务器可以在运行模拟器上模拟点击，让AI与您的游戏互动！

运作原理

  1. 自动注射模块: _mcp_touch.lua 创建并注入 main.lua
  2. 命中测试：该模块在点击位置找到可触摸的物体
  3. 事件分派：合成触摸事件被发送到目标对象

基于百分比的坐标

点击使用具有百分比坐标（0-100）的边界框：

  • left, right：水平边界（0=左边缘，100=右边缘）
  • top, bottom：垂直边界（0=上边缘，100=下边缘）

工具敲击 中心 边界框。这使得AI可以很容易地从屏幕截图中直观地估计位置。

工作流示例

User: Click on the play button
Assistant: [calls get_simulator_screenshot to see current state]
         I can see a play button in the center of the screen.
         [calls simulate_tap with left=40, right=60, top=45, bottom=55]
         Tapped the play button!

User: Click on any popup buttons you see
Assistant: [calls get_simulator_screenshot]
         I see a "Continue" button at the bottom of the screen.
         [calls simulate_tap with left=30, right=70, top=80, bottom=90]
         Tapped the Continue button.

资源

相关 MCP