在本地把 Chatbox + MCP 集成进 Unity

环境：Windows 11，Node.js 22，Unity（Editor），Chatbox 本地部署

最终效果是

• 在 Chatbox 里输入指令，让 MCP 调用工具

• 工具经由本地 Node MCP Server 转发到 Unity

• Unity Editor 收到命令，在编辑器里执行静态方法，例如打印日志等等

  

  

---

1. 整体架构

Chatbox (MCP Client)
        │
        │  STDIO (MCP 协议)
        ▼
Node.js MCP Server (unity-local)
        │
        │  HTTP (本地回环)
        ▼
Unity Editor
  ├─ McpUnityBridge (Editor 脚本，启动 HTTP 监听)
  └─ UnityMCPTools (静态类，承载具体功能)

• Chatbox：作为 MCP 客户端，通过 STDIO 启动 MCP 服务器，并调用工具。
• Node MCP Server：本地 server，暴露 MCP 工具 unity_ping、unity_log 等，把调用转成 HTTP 请求发给 Unity。
• Unity Editor：打开项目时自动启动一个本地 HTTP Bridge，接受 MCP Server 的 /command 请求，然后在主线程调用静态类 UnityMCPTools 里的方法。

---

2. 准备 Node 工程：unity-mcp-server

2.1 初始化项目

在本地创建 MCP Server 目录：

mkdir D:\tools\unity-mcp-server
cd D:\tools\unity-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk

然后在 package.json 里加上 ESM 标记和 CLI 声明：

{
  "name": "unity-mcp-server",
  "version": "1.0.0",
  "main": "index.js",
  "type": "module",
  "bin": {
    "unity-mcp-server": "./server.mjs"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "description": "",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.21.0"
  }
}

• type: "module"：使用 ES Module 语法（import）。
• bin.unity-mcp-server：以后可以通过 unity-mcp-server 作为命令行入口。

2.2 server.mjs：Node 侧 MCP Server

在 D:\tools\unity-mcp-server 下创建 server.mjs，内容如下：

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';

const UNITY_BRIDGE_URL = process.env.UNITY_BRIDGE_URL ?? 'http://127.0.0.1:58888';

class UnityMcpServer {
  constructor() {
    console.error('[Unity MCP] Starting server.mjs');
    console.error('[Unity MCP] UNITY_BRIDGE_URL =', UNITY_BRIDGE_URL);

    this.server = new Server(
      { name: 'unity-local', version: '1.0.0' },
      { capabilities: { tools: {} } }
    );
    this.setupHandlers();
  }

  setupHandlers() {
    // 列出可用工具
    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
      tools: [
        {
          name: 'unity_ping',
          description: '调用 UnityMCPTools.Ping()',
          inputSchema: { type: 'object', properties: {}, additionalProperties: false },
        },
        {
          name: 'unity_log',
          description: '调用 UnityMCPTools.Log(message)',
          inputSchema: {
            type: 'object',
            properties: {
              message: { type: 'string' },
            },
            required: ['message'],
            additionalProperties: false,
          },
        },
      ],
    }));

    // 工具调用入口
    this.server.setRequestHandler(CallToolRequestSchema, async (req) => {
      const { name, arguments: args = {} } = req.params;

      console.error('[Unity MCP] CallTool:', name, 'args =', args);

      if (name === 'unity_ping') {
        return await this.callUnityMethod('Ping', {});
      }

      if (name === 'unity_log') {
        return await this.callUnityMethod('Log', { message: args.message });
      }

      return {
        content: [{ type: 'text', text: `Unknown tool: ${name}` }],
      };
    });
  }

  async callUnityMethod(method, payload) {
    try {
      console.error('[Unity MCP] POST -> Unity:', method, payload);
      const res = await fetch(`${UNITY_BRIDGE_URL}/command`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ method, ...payload }),
      });

      const text = await res.text();
      console.error('[Unity MCP] Unity response:', text);
      return {
        content: [{ type: 'text', text }],
      };
    } catch (e) {
      console.error('[Unity MCP] Failed to call Unity:', e);
      return {
        content: [
          {
            type: 'text',
            text: `Failed to call Unity method "${method}": ${e}`,
          },
        ],
      };
    }
  }

  async run() {
    console.error('[Unity MCP] Connecting to MCP client over stdio...');
    const transport = new StdioServerTransport();
    await this.server.connect(transport);
    console.error('[Unity MCP] Connected. Waiting for requests...');
    process.stdin.resume();
  }
}

const server = new UnityMcpServer();
server.run().catch((err) => {
  console.error('[Unity MCP] Fatal error:', err);
  process.exit(1);
});

这里有几个关键点：

• 使用 StdioServerTransport，通过 stdin/stdout 与 Chatbox 通讯。
• 暴露两个工具：unity_ping 和 unity_log。
• 所有调用都会转成 HTTP POST 到 Unity 本地 Bridge 的 /command 接口。

手动测试时，可以直接在目录下执行：

node .\server.mjs

正常情况下会打印几行初始化日志，然后进程“挂住”——这是在等 MCP 客户端发请求，属于正常状态。

---

3. Unity 侧：桥接与静态工具

Unity 这边的目标有两个：

1. 打开项目时自动启动一个本地 HTTP 服务作为 Bridge。
2. 把 HTTP body 里的 JSON 映射成对静态类 UnityMCPTools 的方法调用。

3.1 MCPCommand & UnityMCPTools：静态工具类

先创建一个脚本 Assets/Editor/MCP/UnityMCPTools.cs：

using UnityEngine;

[System.Serializable]
public class MCPCommand
{
    public string method;   // 要调用的方法名，例如 "Ping" / "Log"
    public string message;  // 示例参数，用于 Log
}

public static class UnityMCPTools
{
    // 统一入口：根据 method 路由到具体静态方法
    public static string HandleCommand(MCPCommand cmd)
    {
        switch (cmd.method)
        {
            case "Ping":
                return Ping();

            case "Log":
                return Log(cmd.message);

            default:
                var unknown = "[MCP] Unknown method: " + cmd.method;
                Debug.LogWarning(unknown);
                return unknown;
        }
    }

    // ===== 真正暴露给 MCP 的功能 =====

    public static string Ping()
    {
        var msg = "[MCP] UnityMCPTools.Ping() at " + System.DateTime.Now;
        Debug.Log(msg);
        return msg;
    }

    public static string Log(string message)
    {
        var msg = "[MCP] UnityMCPTools.Log(): " + message;
        Debug.Log(msg);
        return msg;
    }

    // 后续可以继续扩展：
    // public static string CreateScript(string name, string content) { ... }
    // 在 HandleCommand 里加 case "CreateScript": ...
}

这里的设计是：

• MCP 端只需要传一个 JSON：{"method":"Log","message":"hello"}。
• Unity 解析成 MCPCommand，然后由 UnityMCPTools.HandleCommand 路由到具体方法。

3.2 Unity Bridge：Editor 启动时自动监听 HTTP

再创建 Assets/Editor/MCP/UnityMCPBridge.cs：

using UnityEditor;
using UnityEngine;
using System.Net;
using System.Text;
using System.Threading;
using System.Collections.Generic;

[InitializeOnLoad]
public static class UnityMCPBridge
{
    private static HttpListener listener;
    private static Thread listenerThread;
    private const string Url = "http://127.0.0.1:58888/";

    // 用队列把后台线程收到的命令丢到主线程处理
    private static readonly Queue<string> commandQueue = new Queue<string>();

    static UnityMCPBridge()
    {
        StartServer();
        EditorApplication.update += OnEditorUpdate;
        EditorApplication.quitting += OnQuit;
    }

    private static void StartServer()
    {
        if (listener != null) return;

        try
        {
            listener = new HttpListener();
            listener.Prefixes.Add(Url);
            listener.Start();

            listenerThread = new Thread(ListenLoop);
            listenerThread.IsBackground = true;
            listenerThread.Start();

            Debug.Log("[MCP] Unity bridge listening at " + Url);
        }
        catch (System.Exception e)
        {
            Debug.LogError("[MCP] Failed to start HttpListener: " + e);
        }
    }

    private static void ListenLoop()
    {
        while (listener != null && listener.IsListening)
        {
            HttpListenerContext ctx = null;
            try
            {
                ctx = listener.GetContext();
                HandleRequest(ctx);
            }
            catch
            {
                try { ctx?.Response.Abort(); } catch { }
            }
        }
    }

    private static void HandleRequest(HttpListenerContext ctx)
    {
        var path = ctx.Request.Url.AbsolutePath;

        // 健康检查
        if (path == "/ping")
        {
            var bytes = Encoding.UTF8.GetBytes("Unity bridge OK");
            ctx.Response.OutputStream.Write(bytes, 0, bytes.Length);
            ctx.Response.Close();
            return;
        }

        // MCP 调用统一走 /command，body 是 JSON：{ "method": "...", ... }
        if (path == "/command" && ctx.Request.HttpMethod == "POST")
        {
            string body;
            using (var reader = new System.IO.StreamReader(ctx.Request.InputStream, ctx.Request.ContentEncoding))
            {
                body = reader.ReadToEnd();
            }

            lock (commandQueue)
            {
                commandQueue.Enqueue(body);
            }

            var bytes = Encoding.UTF8.GetBytes("Unity accepted command.");
            ctx.Response.OutputStream.Write(bytes, 0, bytes.Length);
            ctx.Response.Close();
            return;
        }

        ctx.Response.StatusCode = 404;
        ctx.Response.Close();
    }

    // 主线程中执行 MCPCommand -> UnityMCPTools
    private static void OnEditorUpdate()
    {
        while (true)
        {
            string body = null;
            lock (commandQueue)
            {
                if (commandQueue.Count == 0) break;
                body = commandQueue.Dequeue();
            }

            if (!string.IsNullOrEmpty(body))
            {
                try
                {
                    var cmd = JsonUtility.FromJson<MCPCommand>(body);
                    var result = UnityMCPTools.HandleCommand(cmd);
                }
                catch (System.Exception e)
                {
                    Debug.LogError("[MCP] Failed to handle command: " + e);
                }
            }
        }
    }

    private static void OnQuit()
    {
        try
        {
            if (listener != null)
            {
                listener.Stop();
                listener.Close();
                listener = null;
            }
        }
        catch { }
    }
}

要点：

• 使用 [InitializeOnLoad]，只要打开这个 Unity 工程，编辑器就自动启动 HTTP 监听。
• 使用 commandQueue 把后台线程收到的命令交给主线程处理，避免在非主线程使用 Unity API。
• /ping 用于简单健康检查； /command 用于 MCP 调用。

此时只要打开 Unity 工程，在 Console 里应该能看到：

[MCP] Unity bridge listening at http://127.0.0.1:58888/

可以用 curl 测一下：

curl http://127.0.0.1:58888/ping
# 期待输出：Unity bridge OK

---

4. Chatbox 端：配置 MCP Server

Chatbox 作为 MCP 客户端，需要在配置里加入一个 server，指向刚刚写的 server.mjs。

关键点只有两条：

1. 使用绝对路径，不要用相对路径，否则会出现类似：

   Cannot find module 'D:\tools\Chatbox\toolsunity-mcp-serverserver.mjs'

2. Windows 下在 JSON 里写路径要用 \\ 转义。

MCP 配置：

{
  "mcpServers": {
    "unity-local": {
      "command": "node",
      "args": [
        "D:\\tools\\unity-mcp-server\\server.mjs"
      ],
      "env": {
        "UNITY_BRIDGE_URL": "http://127.0.0.1:58888"
      },
      "description": "Unity local MCP server",
      "capabilities": {
        "tools": {}
      }
    }
  }
}

之后重启 Chatbox，在对应会话中启用 unity-local 这个 MCP server，就可以从 Chatbox 里调用 unity_ping、unity_log 工具。