MCP light demo

MCP Light Service

项目概述

mcp_light_service 提供一个简单的 WebSocket MCP（Multi-Channel Processor）示例：ws_gateway.py 充当 MCP 网关，支持工具提供方和编排方之间的注册与转发；mcp_light_tools.py 模拟一个灯控/打招呼工具集，向网关注册后等待调用。

目录亮点

• ws_gateway.py：接收客户端注册、广播工具目录、将 call_tool 定向到工具提供方、并将执行结果回复原始请求者；还会尝试读取 ngrok 隧道来打印域名。
• mcp_light_tools.py：包含 greet_user 和 control_light 两个工具，分别可打招呼或控制虚拟灯状态，并通过固定的重连策略保持与网关连接。
• docker-compose.yml / Dockerfile：构建网关、工具提供方、以及一个 ngrok tunnel 的容器，方便本地启动整个系统。
• requirements.txt：仅依赖 websockets，保持镜像和运行环境轻量。

快速启动

纯 Python 方式（适用于调试）

1. 创建虚拟环境并安装依赖：

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

1. 运行网关（可选设置 WS_HOST/WS_PORT）：

   WS_HOST=0.0.0.0 WS_PORT=8765 python ws_gateway.py

1. 在另一终端启动工具提供方（MCP_ENDPOINT 指向网关）：

   MCP_ENDPOINT=ws://localhost:8765 python mcp_light_tools.py

Docker Compose （推荐用于集成测试）

• 运行前请确保正确配置 NGROK_AUTHTOKEN 环境变量。

NGROK_AUTHTOKEN=xxx docker-compose up -d

该命令会：

• 构建并启动 mcp-ws-hub（网关）与 mcp-tool-provider（工具提供方）；
• 启动 ngrok 容器并公开网关端口；注意：每次重启后 ngrok 域名会变化，可在日志中查看。
• 端口映射：本地 8765 映射到网关，4040 可访问 ngrok 控制面板。

环境变量

• WS_HOST, WS_PORT：网关监听地址（默认 0.0.0.0:8765）。
• MCP_ENDPOINT：工具提供方连接的网关地址（默认 ws://localhost:8765）。
• LOG_NGROK_DOMAIN：若设置为 0/false/no 则跳过输出 ngrok 域名。
• NGROK_API_URL：ngrok 控制 API 地址（默认 http://ngrok:4040/api/tunnels）。
• NGROK_AUTHTOKEN：在 Docker Compose 中让 ngrok 可以公开端口。

工具说明

mcp_light_tools.py 注册两个工具：

1. greet_user：接受可选的 name 参数，返回问候语。
2. control_light：接受 action（on/off/toggle/turn_on/turn_off），在内存中切换灯的状态并记录在 STATE 中。

无论哪个工具，执行后都会通过 WebSocket 向网关返回 tool_response，再由网关转发给原始调用方。

调试与日志

• 所有日志默认输出到 stdout，级别为 INFO。
• 网关在启动时会尝试读取 ngrok 隧道信息并打印（若 LOG_NGROK_DOMAIN 允许）。
• 工具提供方采用指数退避重连机制，网络抖动时会间隔重试。

未来扩展

• 可在 mcp_light_tools.py 中集成更多实际工具，如调用 Home Assistant API 控制真实设备。
• 网关已暴露工具目录广播逻辑，可直接在编排端订阅并显示工具清单。