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 客户端，用于验证控制枢纽的广播消息：
- 支持命令行参数 或环境变量覆盖默认地址。 - 自动对 JSON 消息进行美化输出，便于观察。
快速开始
- 环境准备
python -m venv .venv
source .venv/bin/activate # Windows 使用 .venv\Scripts\activate
pip install -r requirements.txt或使用 uv：
uv sync- 启动 MCP 控制服务器
uv run python programming_controller.py- 首次启动会自动开启 WebSocket 控制枢纽。 - 可配合 test_client.py 监听广播：
uv run python test_client.py 127.0.0.1 8765- 启动计算器工具
uv run python calculator.py在支持 MCP 的客户端中调用 calculator 工具进行数学运算。
- 通过管道连接云端 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