Melon MCP

MelonMCP

概述

MelonMCP通过MCP协议公开了一套全面的操作，弥合了外部工具和运行Unity游戏之间的差距。它允许您：

• 检查 实时游戏对象、组件、材质和场景层次结构
• 执行 直接在游戏运行时环境中编写C#代码
• 操纵 以编程方式转换、属性和行为
• 查询 类型信息、程序集和游戏状态
• 自动化 通过标准化协议进行游戏交互

两者都适用 单声道 和 IL2CPP Unity游戏。

特性

运行时代码执行

• 在游戏上下文中执行任意C#代码
• 评估表达式并访问任何游戏API
• 支持带变量的多语句代码块
• 泛型方法调用(GetComponent(), FindObjectsOfType())

现场检查

• 列出场景层次结构中的所有游戏对象
• 按名称、路径或实例ID查找对象
• 检查连接到任何游戏对象的组件
• 查看详细的组件属性和字段

对象操纵

• 创建基本游戏对象（立方体、球体等）
• 克隆/实例化现有对象
• 修改变换（位置、旋转、缩放）
• 启用/禁用行为
• 设置属性并调用方法
• 销毁对象和组件

材质和渲染

• 检查渲染器上的材质
• 查看着色器属性、纹理和颜色
• 访问渲染队列和着色器关键字

类型系统探索

• 列出所有已加载的程序集
• 浏览程序集中的类型
• 获取详细的类型信息（方法、属性、字段）
• 按命名空间、基类型或类型类型筛选

游戏状态控制

• 通过时间尺度操作暂停/取消暂停
• 光标可见性和锁定状态控制
• 场景加载
• 屏幕截图

记录和诊断

• 捕获游戏日志（消息、警告、错误）
• 实时日志流
• 筛选日志查询

知识持久性

• 存储有关游戏API和命令的发现
• 跨会话查询存储的知识
• 对发现进行分类（控制台命令、静态访问者、作弊等）

源代码集成

• 设置反编译/伪代码源的路径
• 搜索游戏源代码
• 读取特定源文件

安装

先决条件

• Melon加载器 已安装在Unity游戏中
• .NET 6.0运行时
• Python 3.8+（用于MCP桥）

步骤

1. 构建mod （或从发行版下载）：

   cd MelonMCP
   dotnet build -c Release

1. 复制到游戏:

   cp MelonMCP/bin/Release/MelonMCP.dll /Mods/

1. 配置MCP客户端 （见配置部分）

1. 启动游戏 -MelonMCP将在端口27015上自动启动

配置

MCP网桥设置

MelonMCP使用TCP套接字（默认端口27015）。要连接MCP客户端，请使用附带的Python桥：

{
  "mcpServers": {
    "melonmcp": {
      "command": "python",
      "args": ["path/to/mcp-bridge.py", "--host", "localhost", "--port", "27015"]
    }
  }
}

自定义端口

设置 MELONMCP_PORT 环境变量或修改源中的默认值。

可用工具

用法示例

执行C#代码

{
  "tool": "execute_csharp",
  "arguments": {
    "code": "var player = GameObject.Find(\"Player\"); return player.transform.position.ToString();"
  }
}

查找所有摄像头

{
  "tool": "find_objects_of_type",
  "arguments": {
    "typeName": "Camera",
    "limit": 10
  }
}

检查部件

{
  "tool": "inspect_component",
  "arguments": {
    "gameObjectPath": "Player",
    "componentType": "CharacterController"
  }
}

创建调试多维数据集

{
  "tool": "create_primitive",
  "arguments": {
    "type": "Cube",
    "name": "DebugMarker",
    "position": "10, 5, 0",
    "scale": "0.5, 0.5, 0.5"
  }
}

暂停游戏

{
  "tool": "set_time_scale",
  "arguments": {
    "timeScale": 0
  }
}

技术细节

建筑

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   MCP Client    │────▶│   MCP Bridge    │────▶│   MelonMCP      │
│  (Any MCP app)  │ TCP │   (Python)      │ TCP │   (In-Game)     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                                ┌─────────────────┐
                                                │  Unity Runtime  │
                                                │  (Game Process) │
                                                └─────────────────┘

线程模型

MelonMCP小心处理线程：

• MCP服务器在后台线程上运行以提高响应速度
• Unity API调用通过调度器编组到主线程
• 结果安全地返回给调用线程

IL2CPP支持

完全支持IL2CPP游戏，包括：

• 跨IL2CPP程序集的运行时类型解析
• 通过反射调用泛型方法
• 正确处理IL2CPP包装类型
• 组件枚举回退

聚焦/暂停处理

MelonMCP包含Harmony补丁，可在无焦点时保持游戏运行：

• 补丁 Application.runInBackground 保持真实
• 旁路 GameManager.OnApplicationFocus 暂停逻辑（适用于支持的游戏）
• 允许在窗口之间切换时连续操作

从源头构建

# Clone the repository
git clone https://github.com/yourusername/MelonMCP.git
cd MelonMCP

# Restore dependencies (requires MelonLoader libs)
# Place MelonLoader references in a 'libs' folder or update the .csproj

# Build
dotnet build -c Release

依赖项

• 甜瓜加载器0.6.0+
• Newtonsoft。JSON
• HarmonyX（包含在MelonLoader中）

安全考虑

MelonMCP提供了强大的功能，包括任意代码执行。默认情况下，它只监听本地主机。在以下情况下要小心：

• 在多人游戏中使用（反作弊系统可能会对此进行标记）
• 将端口暴露给非本地主机地址
• 通过execute_csharp工具运行不受信任的代码

故障排除

服务器未启动

• 检查MelonLoader控制台是否有错误消息
• 确保端口27015未被其他应用程序使用
• 验证DLL是否在正确的文件夹中

连接被拒绝

• 确保游戏在加载MelonMCP的情况下运行
• 检查防火墙是否阻止了连接
• 验证您是否连接到正确的端口

工具超时

• 游戏窗口可能需要聚焦
• 有些游戏在注意力不集中时会暂停；MelonMCP修补了这个问题，但它可能不适用于所有游戏
• 确保游戏已完全加载（不在加载屏幕中）

找不到Unity对象

• 场景可能尚未完全加载
• 游戏对象路径可能不正确（使用 list_game_objects 第一）
• 对象可能处于非活动状态（使用 activeOnly: false)

贡献

欢迎投稿！请随时提交问题和拉取请求。

许可证

MIT许可证-请参阅 许可证 了解详情。

致谢

• Melon加载器 -使这成为可能的mod加载器
• 模型上下文协议 -协议规范
• HarmonyX -运行时修补库