AI导哈

WebSocket MCP网关服务

一个基于WebSocket的多通道处理器（MCP）网关服务，支持工具提供方和编排方之间的注册与转发，适用于轻量级工具集成与远程控制场景。

  • by bestjane
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 bestjane/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
  2. 运行网关（可选设置 WS_HOST/WS_PORT）：
    WS_HOST=0.0.0.0 WS_PORT=8765 python ws_gateway.py
  3. 在另一终端启动工具提供方（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 控制真实设备。
  • 网关已暴露工具目录广播逻辑，可直接在编排端订阅并显示工具清单。

相关 MCP