AI导哈

数字孪生控制工具集

JCXiaoZhiMcp 是一个面向 Unreal 数字孪生程序的多 MCP 组件集合，提供本地 MCP 工具服务器、WebSocket 控制枢纽与管道脚本，帮助在云端与本地服务之间建立连接并控制数字孪生场景。

  • by Lafinger
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Lafinger/JCXiaoZhiMcp

使用说明

JCXiaoZhiMcp

小智（XiaoZhi）面向 Unreal 数字孪生程序的多 MCP 组件集合。本仓库提供本地 MCP 工具服务器、WebSocket 控制枢纽与管道脚本，帮助通过 Model Context Protocol 在云端与本地服务之间建立连接，并将控制指令广播给 Unreal 场景。

项目结构

文件/目录 作用概述
calculator.py 基于 FastMCP 的示例计算器工具，向 MCP 客户端暴露 calculator 工具以执行任意 Python 数学表达式。
programming_controller.py 提供名为 Tester 的 MCP 服务器，同时常驻 WebSocket 控制枢纽，向数字孪生程序广播聚焦、漫游、视频、声音等指令。
test_client.py 简易的 WebSocket 监听客户端，可验证控制枢纽广播的消息。
mcp_pipe.py STDIO↔WebSocket 转发器，可根据 mcp_config.json 启动多个 MCP 子进程并与远端 Endpoint 互联。
mcp_config.json 统一的 MCP 服务器配置，定义了本地 stdio 服务及可选的远端 sse/http 服务。
requirements.txt / pyproject.toml Python 依赖声明，推荐使用 uv 或 pip 安装。
数字孪生程序功能.txt 目标数字孪生程序当前支持的四类指令关键词。

核心组件详解

1. Calculator MCP 工具

  • 使用 FastMCP("Calculator") 注册服务，并暴露单一工具 calculator(python_expression)。
  • 自动注入 math 与 random 模块，可执行复杂数学表达式。
  • 通过标准输入输出（STDIO）运行，适合作为 MCP 客户端的示例或测试工具。

2. Unreal 控制 MCP 服务器

  • programming_controller.py 创建 FastMCP("Tester") 服务，并在后台启动 WebSocketControlHub：
    • 默认监听 0.0.0.0:8765，可通过环境变量 TESTER_WS_HOST、TESTER_WS_PORT 调整。
    • 维护客户端集合，支持广播 JSON 指令；未连接客户端时返回 0 投递数。
  • 公开四个工具接口，均使用 _broadcast_action 统一封装：
    • camera_focus(lable)：聚焦/跳转到指定场景。
    • enter_roaming(lable)：触发指定场景的漫游。
    • play_video(lable)：播放命名视频资源。
    • play_sound(lable)：播放命名音频资源。
  • 工具调用成功后会记录日志，并反馈当前连接客户端数量与成功投递数，便于监控实时控制效果。

3. MCP WebSocket 管道

  • mcp_pipe.py 提供从标准输入输出到 WebSocket 的双向转发，核心能力包括：
    • 持续重连机制：指数退避（1s 到 600s），确保远端 MCP Endpoint 中断后自动恢复。
    • 子进程托管：根据 mcp_config.json 的 mcpServers 条目选择启动命令或远端代理。
    • 统一代理：对 http/streamablehttp/sse 类型条目自动改为执行 python -m mcp_proxy 并附加自定义 Header。
    • 信号处理：捕获 SIGINT 优雅退出，并清理子进程。
  • 默认通过硬编码的 wss://api.xiaozhi.me/mcp/ Endpoint 连接，正式部署时应改为环境变量 MCP_ENDPOINT 或配置文件。

4. 工具测试客户端

  • test_client.py 是一个只读 WebSocket 客户端，用于验证控制枢纽的广播消息：
    • 支持命令行参数 <host> <port> 或环境变量覆盖默认地址。
    • 自动对 JSON 消息进行美化输出，便于观察。

快速开始

  1. 环境准备

    python -m venv .venv
source .venv/bin/activate  # Windows 使用 .venv\Scripts\activate
pip install -r requirements.txt

    或使用 uv：

    uv sync

  2. 启动 MCP 控制服务器

    uv run python programming_controller.py
    • 首次启动会自动开启 WebSocket 控制枢纽。
    • 可配合 test_client.py 监听广播：
      uv run python test_client.py 127.0.0.1 8765

  3. 启动计算器工具

    uv run python calculator.py

    在支持 MCP 的客户端中调用 calculator 工具进行数学运算。

  4. 通过管道连接云端 Endpoint

    export MCP_ENDPOINT="wss://your-endpoint"
uv run python mcp_pipe.py
    • 无参数时会读取 mcp_config.json 中未禁用的条目并全部启动。
    • 可指定单个脚本：uv run python mcp_pipe.py programming_controller.py。

配置说明

  • mcp_config.json 的 mcpServers 键用于统一管理 MCP 服务：
    • local-stdio-calculator / local-stdio-tester 示例展示如何使用 uv run 启动本地脚本。
    • remote-sse-server / remote-http-server 演示远端服务定义，可通过设置 disabled: false 启用。
  • 若需要额外环境变量，可在相应条目下添加 "env": {"KEY": "VALUE"}。
  • mcp_pipe.py 自动读取 .env 文件，便于保密令牌。

日志与监控

  • 所有组件均使用 Python logging 输出关键事件：
    • 计算器记录表达式与结果。
    • 控制服务器记录 WebSocket 客户端连接、广播统计及异常。
    • 管道脚本记录连接生命周期、子进程状态及错误细节。
  • 建议结合外部监控或将日志重定向到文件，便于调试与溯源。

注意事项

  • mcp_pipe.py 中当前硬编码的 token 仅供演示，部署前务必替换并妥善管理。
  • 广播指令依赖客户端正确解析 action 与 lable 字段，需与 Unreal 端保持一致。
  • 若在 Windows 运行，脚本已处理 UTF-8 控制台编码，可避免中文日志乱码。

相关资料

  • MCP 规范与工具链：https://github.com/modelcontextprotocol
  • FastMCP 快速入门示例：https://github.com/modelcontextprotocol/python-sdk

相关 MCP