Gameplay MCP

Unity游戏MCP服务器

   

用于游戏的模型上下文协议（MCP）服务器。提供AI模型通过嵌入运行时（玩家构建）通过MCP玩游戏的工具。

主要特点

• 内置工具 --让AI模型列出可用的UI操作、与UI元素交互、检查GameObjects、捕获屏幕截图和查询加载的场景——所有这些都是开箱即用的。
• 适用于IL2CPP版本 --您可以在您的播放器版本（包括IL2CPP）上运行MCP服务器。

局限性

• 不支持WebGL平台。

必需

• Unity 2023.1或更新版本
• MCP C#SDK NuGet包v1.0.0或更高版本
• UI测试助手 软件包v1.2.2或更高版本
• 测试助手 软件包v1.4.1或更新版本

内置工具

大多数内置工具都是 UI测试助手 API。

\[！注意\]\ 工具名称以命名空间作为前缀。默认命名空间为 mygame，所以它看起来像 mygame.inspect_game_object.

list_available_actions

以JSON数组的形式返回可操作操作的操作列表。每个条目都包含一个目标游戏对象和可以对其进行操作的运算符类名。对于按钮组件，文本标签和纹理名称也包含在目标中。

• 可到达的 --如果 true （默认），只包括可访问的游戏对象。

invoke_action

查找可访问的游戏对象并对其执行指定的运算符。

• 运算符Name --具体运算符类名（例如。， "UguiClickOperator").
• 路径 --层次结构路径由分隔 /.支持全局通配符(?, *, **).
• 名字 --游戏对象名称。
• 文本 --按钮组件子级上的文本标签。如果指定，则使用 ButtonMatcher.
• 质地 --按钮组件上的纹理/角色名称。如果指定，则使用 ButtonMatcher.
• operatorArgs --特定于运算符的参数为JSON字符串。JSON键必须与运算符的参数名称匹配 OperateAsync 方法重载。内置运算符的已知参数：

- IClickAndHoldOperator: {"holdMillis": 1000} - IDragAndDropOperator （由GameObject提供）： {"destination": {"name": "DropTarget"}, "dragSpeed": 50} - IDragAndDropOperator （按屏幕点）： {"destination": [100.0, 200.0], "dragSpeed": 50} - IScrollWheelOperator: {"direction": [0.0, 1.0], "distance": 100, "scrollSpeed": 50} - ISwipeOperator: {"direction": [1.0, 0.0], "swipeSpeed": 100} - ITextInputOperator: {"text": "input text"} - IToggleOperator: {"isOn": true} - 具有默认值的参数（例如。， dragSpeed, scrollSpeed, swipeSpeed)可以省略。 - 当参数类型为 GameObject，将其指定为 {"name": "...", "path": "...", "text": "...", "texture": "..."} --该工具将自动查找并验证可达性。

inspect_game_object

按名称、路径、文本标签或纹理名称检查游戏对象，并以JSON格式返回属性。等待游戏对象出现并在超时时间内可访问。

• 路径 --层次结构路径由分隔 /.支持全局通配符(?, *, **).
• 名字 --游戏对象名称。
• 文本 --按钮组件子级上的文本标签。如果指定，则使用 ButtonMatcher.
• 质地 --按钮组件上的纹理/角色名称。如果指定，则使用 ButtonMatcher.
• 可到达的 --如果 true （默认），只返回可访问的游戏对象。

take_screenshot

捕获当前游戏屏幕并将其作为图像返回。

• 最大像素 --长边的最大长度（像素）。如果图像超过此值，则会按比例缩小。默认为 1568.
• 格式 --图像格式： "jpeg" （默认）或 "png".
• 质量 --JPEG编码质量（1–100）。仅在以下情况下使用 format 是 "jpeg".默认为 75.

list_scenes

以JSON格式返回当前加载的场景。活动场景标记为 active=true.

没有参数。

\[！提示\]\ 这 list_scenes 该工具仅提供简化的游戏状态。 您需要创建一个自定义工具，返回更详细的游戏状态，以便模型可以确定适当的行动方案。

添加自定义工具

任何类型的注释 [McpServerToolType] 在服务器启动时自动发现，并且任何 public static 该类型上的方法注释如下 [McpServerTool] 已注册为工具，无需注册。

// Assets/Scripts/Runtime/MyGameTools.cs (custom tools created by the game title)
// Just add [McpServerToolType] and it's registered automatically!
[McpServerToolType]
public static class MyGameTools
{
    [McpServerTool(Name = "get_player_status", ReadOnly = true, Destructive = false)]
    [Description("Returns the player's current status as JSON.")]
    [Preserve]
    public static async Task GetPlayerStatus(
        McpConfig config = null,    // injected automatically
        CancellationToken ct = default)
    {
        await UniTask.SwitchToMainThread(ct);
        var player = GameObject.FindWithTag("Player");
        return JsonSerializer.Serialize(new { hp = player.GetComponent().Current });
    }
}

\[！重要\]\ 在IL2CPP构建中，自定义工具类型是通过反射发现的，并可能被托管代码剥离器删除。添加 [Preserve] 归因于你的工具方法。

\[！提示\]\ 如果您的自定义工具需要访问 McpConfig （例如，使用 GameObjectFinder 或 OperatorPool)，将其声明为默认值为的参数 null --它在运行时自动注入。

如果自定义工具涵盖了与内置工具相同的用例，则可以使用以下命令禁用内置工具 DisabledTools:

var config = new McpConfig();
config.DisabledTools.Add("mygame.list_scenes"); // use the full prefixed name

代理技能

在向AI模型提供指令时，考虑将以下定义为技能：

• 屏幕过渡和导航 --即使指令描述的是高级目标而不是分步程序，人工智能也需要知道屏幕结构以及哪些按钮导航到哪些屏幕。
• 游戏规则和知识 --如果你想让人工智能自主游戏，它需要了解游戏规则、物品和机制。
• 自定义运算符参数 --如果你的游戏标题使用带有不明显参数的自定义运算符，请记录如何将这些参数指定为技能的一部分。
• 故障排除 --将故障排除信息从 UI测试助手 因此，人工智能可以解决诸如无法找到操作目标等问题。
• 屏幕截图格式建议 --默认格式为JPEG，质量为75，适用于大多数情况。考虑在这些情况下进行调整：

- 提高JPEG质量 --如果游戏有质量为75的精细视觉细节丢失。 - 使用PNG --在以下情况下，PNG是首选： - 当AI需要准确读取UI文本时。 - 适用于压缩伪影可见的像素艺术游戏。 - 当调试需要像素级精度时（例如，视觉回归测试）。

入门指南

1.安装依赖的NuGet包

如果通过OpenUPM安装：

1. 打开“项目设置”窗口(编辑>项目设置)并选择 包管理器 标签
2. 点击 + 按钮下方 登记范围 并输入以下设置：

1. 姓名： unitynuget-registry.openupm.com 1. 网址： https://unitynuget-registry.openupm.com 1. 范围： org.nuget

1. 打开“包管理器”窗口(窗口>包管理器)并选择 我的注册表 标签
2. 选择 模型上下文协议（NuGet） 然后单击 安装 按钮

2.通过包管理器窗口安装

1. 打开“项目设置”窗口(编辑>项目设置)并选择 包管理器 选项卡（图1）
2. 点击 + 按钮下方 登记范围 并输入以下设置：

1. 姓名： package.openupm.com 1. 网址： https://package.openupm.com 1. 范围： com.nowsprinting 和 com.cysharp

1. 打开“包管理器”窗口(窗口>包管理器)并选择 我的注册表 选项卡（图2）
2. 选择 游戏MCP 然后单击 安装 按钮

\[！注意\]\ 别忘了添加 com.cysharp 进入范围。这些在这个包中使用。

图1。 在“项目设置”窗口中设置范围注册表

 

图2: 我在包管理器窗口中的注册表

 

3.启动MCP服务器

从游戏名称的代码启动MCP服务器。一种典型的方法是使用 [RuntimeInitializeOnLoadMethod] 自动启动的属性，或从调试菜单中打开/关闭它。

var config = new McpConfig
{
    OperatorPool = new OperatorPool()
        .Register()
        .Register()
        .Register()
};
var server = new McpServer(config);
server.StartAsync().Forget();

McpConfig 显示超出以下范围的其他设置 OperatorPool，包括 GameObjectFinder, IsInteractable, ReachableStrategy，以及 ToolsNamespace。请参阅 UI测试助手 有关UI相关配置选项的详细信息的文档。

\[！提示\]\ 您可以通过以下方式覆盖监听前缀 -gameplayMcpListenPrefix 命令行参数。请注意，如果 ListenPrefix 已设置 McpConfig，它优先于命令行参数。

如果需要，从调试菜单中停止服务器：

server.Dispose();

4.编码代理中的MCP设置

将MCP服务器配置添加到您的编码代理中。 例如。，

{
  "mcpServers": {
    "gameplay": {
      "type": "http",
      "url": "http://localhost:8010/mcp"
    }
  }
}

许可证

MIT许可证

如何贡献

打开问题或创建拉取请求。

请确保每个PR至少有一个适当的标签，例如 enhancement, bug, chore，或 documentation. 看 PR标签设置 用于根据分支名称自动标记。