Gameplay MCP Server for Unity

关键词

Model Context ProtocolUnity AI toolingJSON-RPC streamingUI automationGame testing

使用说明（以便开发者快速上手为目标，包含核心要点、安装与运行步骤、以及配置要点）

  • 项目简介

    • 这是一个基于 MCP（Model Context Protocol）搭建的后端服务器实现，专注于在 Unity 环境中提供“资源读取/数据访问”、“工具注册与执行”、“Prompt/模板渲染”等能力，供大模型/LLM 客户端调用。
    • 服务器通过 HTTP Transport（Streamable HTTP）实现请求/响应的通信，通过 /mcp 路径接收 MCP 请求，支持 POST/GET/DELETE 的 JSON-RPC 世代交互和事件流传输。

  • 主要功能点

    • 资源与数据访问：通过工具集与资源管理暴露游戏内上下文信息给 AI 客户端。
    • 工具注册与执行：内置以及自定义工具类（通过特性标记）自动注册，AI 模型可以调用这些工具执行外部功能。
    • 闭环通信与会话管理：基于会话标识符管理 MCP 会话，支持持续的服务器端推送（事件流）。
    • 跨传输模式支持：设计意图包含多种传输协议，当前实现以 Streamable HTTP 为核心，便于在 Unity 运行时嵌入。
    • 安全与扩展性：通过 DI 容器、工具过滤、命名空间前缀等方式提供可控的能力声明和工具列表。

  • 安装步骤

    1. 将源码集成到 Unity 项目中，确保符合 Unity 2023.1 及以上版本的要求（并考虑 IL2CPP/WebGL 的限制）。
    2. 引入 Model Context Protocol 的 C# SDK（NuGet 包）及相关依赖，确保 McpServer、工具和会话机制能够正常编译。
    3. 将 McpServer 启动逻辑嵌入到游戏启动流程中，示例通常通过 RuntimeInitializeOnLoad 启动。
    4. 按需配置工具命名空间、互动对象发现策略、以及需要隐藏的工具（DisabledTools）。
    5. 构建并运行游戏。服务器启动后，客户端可通过配置的服务端地址进行连接。

  • 服务器配置（MCP 客户端需要的最小信息与注释） 注：以下信息描述用于 MCP 客户端在建立连接前所需的配置信息（以 JSON 形式表达，实际客户端无需源码，仅供理解和集成文档使用）。请根据仓库提供的运行环境和默认设置调整相应字段。

    • serverName（服务器标识）
    • command（用于启动服务器的可执行文件路径或启动命令）
    • args（启动参数，通常包含用于绑定监听地址的选项，例如 -gameplayMcpListenPrefix 等）
    • 说明：MCP 客户端需要知道如何启动并与 MCP 服务器建立连接，但实际的连接信息要以客户端配置为准，服务器端的实现与集成在源码中已经涵盖。

  • 基本使用方法

    • 在 Unity 项目中集成后，使用 RuntimeInitializeOnLoadOnStartup 启动 MCP 服务器实例。
    • 通过设置 McpConfig，指定监听前缀（默认为 http://+:8010/）以及工具命名空间等选项，确保默认工具命名空间为 mygame。
    • 客户端通过 http(s) 方式连接到 /mcp 端点，发送 JSON-RPC 请求，接收服务器返回的 JSON-RPC 响应和事件流。
    • 调用内置工具（如 list_scenes、inspect_game_object、take_screenshot、list_available_actions 等）也可通过客户端进行测试与使用。

服务器信息

访问项目