WebControl4 MCP 服务端实现
使用说明（Markdown 格式）
-
项目简介
- 该仓库实现了一个基于 MCP（Model Context Protocol）的服务器端，核心功能包括注册并暴露若干“工具”（Tools）、管理资源数据、定义和渲染 Prompt 模板，以及通过不同传输协议与 LLM 客户端通信，提供一致的上下文服务入口。
-
主要功能点
- MCP 核心服务：创建 MCP 服务器、注册共计 13 个工具，用于获取设备信息、历史记录、以及执行控制指令等。
- 资源与工具管理：通过与本地控制器（Control4 Director）REST API 的代理，读取灯光、温控等信息并执行命令。
- 支持的传输途径：STDIO（mcp-stdio.js）以及 HTTP/Streamable HTTP（mcp-http.js）两种传输，方便本地桌面端或云端对接。
- 安全与鉴权：集成 OAuth（Google 登录）与 MCP 自有的授权机制，提供会话和 Bearer token 的鉴权能力。
- 虚拟化与演示模式：支持 mock/director 模拟，方便开发和演示。
- 辅助能力：历史数据、 routines、场景、设备状态等信息的查询，及对单个设备的直接操作（如灯光亮度、 HVAC 模式等）。
-
安装步骤
-
- 安装依赖
- 在仓库根目录执行 npm install，安装所需依赖。
-
- 启动依赖服务
- 启动 Control4 相关的后端 UI/Express 服务器（仓库中提供 server.js，提供前端 UI 与 API，按需运行）。
-
- 启动 MCP 服务器
- 根据需要选择 STDIO 传输还是 HTTP 传输：
- STDIO 模式（适用于桌面端 LLM 客户端）：node mcp-stdio.js
- HTTP 模式（适用于远程/云端对接）：node mcp-http.js
-
- 配置与调试
- 如需开启 OAuth，请配置 GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET 等环境变量，并在需要时调整 ALLOWED_EMAILS。
-
- 运行示例
- 启动后，LLM 客户端可通过 MCP 提供的工具接口，进行设备查询、命令执行、历史查询和 Routine/Scene 的触发等操作。
-
-
服务器配置（JSON 配置示例，适用于 MCP 客户端启动参数）
- 配置对象包含 server name、启动命令以及参数等信息，示例如下（请按实际环境替换值）： { "serverName": "WebControl4 MCP Server", "command": "node", "args": ["mcp-stdio.js"], "baseUrl": "http://localhost:3000", "controllerIp": "mock", "directorToken": "mock-director-token", "authHeader": "Cookie: wc4_session=YOUR_SESSION_ID" } 说明：
- serverName：服务器实例名称，便于在客户端界面区分不同的 MCP 服务。
- command：启动 MCP 服务器的命令，此处以 node 为例。
- args：启动命令的参数列表，STDIO 模式使用 mcp-stdio.js。
- baseUrl、controllerIp、directorToken、authHeader：与后端 Express API 的对接参数。若使用 mock 模式，可将 controllerIp 设置为 mock 且 directorToken 与 authHeader 可为空或使用演示用 Token。
- 客户端不需要构建额外的环境，仅需按上述方式启动对应传输并指向正确的后端服务地址。
-
基本使用方法
- 与 MCP 服务交互的基本流程
- 启动对应传输模式的 MCP 服务端（STDIO 或 HTTP）。
- 配置 MCP 客户端以指向服务器的 baseUrl，并提供必要的认证信息（若使用 OAuth，则需要先完成登录并获取访问令牌）。
- 客户端向 MCP 发送请求（如获取灯光列表、读取变量、执行命令等），服务器返回 JSON-RPC 风格的响应。
- 常用操作
- 查询设备信息（灯、温控、场景等）
- 调用工具执行设备控制（如设置灯光等级、HVAC 模式、设置温度等）
- 调用历史/分 floors 的活动数据
- 执行已有的 Routine、创建新的 Routine
- 安全注意
- 如开启 HTTPS/OAuth，请确保正确配置密钥、证书以及客户端的授权凭证。
- 在生产环境中，建议使用正式域名、受信任的证书和严格的访问控制策略。
- 与 MCP 服务交互的基本流程