这个项目能做什么

ccu-mcp 是一个模型上下文协议（MCP）服务器，旨在将 AI 助手（如 Claude、Cursor 或任何 MCP 客户端）桥接到 HomeMatic 智能家居系统。它直接连接到 CCU 内置的 JSON-RPC API（通过 `/api/homematic.cgi`），无需插件、XML-API 或云服务。它适用于任何 HomeMatic CCU，包括 debmatic、CCU3 和 OpenCCU（前身为 RaspberryMatic）。 该服务器处理设备发现、类型解析、会话管理和值转换，提供工具让用户可以使用自然语言提问，例如“浴室的温度是多少？”、“有窗户开着吗？”、“将客厅供暖设置为 21 度”或“显示所有电池电量低的设备”。它还支持高级操作，如重命名设备以遵循命名规范、查找不匹配的通道名称以及检查设备健康状况。 **主要功能：** - **直接连接 CCU**：无需插件或云服务；使用标准 JSON-RPC 端点。 - **多种传输方式**：作为子进程（stdio）或独立 HTTP 服务器（Docker）运行。 - **Docker 支持**：发布 linux/amd64 和 linux/arm64 镜像，并提供供应链安全的认证。 - **多 CCU 配置文件**：在一个服务器上配置和切换多个 CCU（例如 prod 和 dev）。 - **安全性**：Bearer 令牌认证（自动生成或显式设置）、DNS 重绑定保护、CORS 允许列表、TLS 支持（包括自签名证书固定）以及可选的 fail2ban 集成。 - **设置向导**：交互式 `init` 命令探测 CCU、固定 TLS 证书、测试登录并写入可用的 `.env` 文件。对话式设置模式允许 LLM 通过聊天引导过程。 - **诊断**：`doctor` 命令端到端验证配置。 - **速率限制**：内置突发和持续速率限制以保护 CCU。 - **资源轮询**：可选轮询以获取 MCP 资源变更通知。 **安装与使用：** - **快速启动（stdio）**：设置 `CCU_HOST` 和 `CCU_PASSWORD` 环境变量，然后运行 `npx ccu-mcp --stdio`。使用 `.mcp.json` 文件配置您的 MCP 客户端（例如 Claude Code）。 - **Docker（HTTP）**：拉取镜像，使用环境变量运行，并从容器的数据卷获取认证令牌。使用服务器 URL 和 Bearer 令牌配置客户端。 - **配置**：所有设置均通过环境变量完成（见 README 中的表格）。支持内联环境、`.env` 文件或 shell 导出。 - **CLI 标志**：`init`、`doctor`、`secret`、`--stdio`、`--http`、`--env`、`--version`、`--help`。 **安全注意事项：** - 服务器默认使用明文 HTTP，但在非环回接口上提供令牌时会发出警告；设置 `MCP_ALLOW_PLAINTEXT=true` 以确认。 - 对于远程访问，请使用 TLS（反向代理或原生 HTTPS）并设置 `MCP_ALLOWED_HOSTS` 以避免 403 错误。 - 支持令牌轮换，并设有宽限期以避免客户端中断。 - CORS 默认拒绝；为基于浏览器的客户端允许来源。 **要求：** Node.js 24+（用于源代码/stdio）或 Docker。需要具有管理员凭据的运行中的 HomeMatic CCU。 **示例客户端配置（stdio）：** ```json { "mcpServers": { "ccu-mcp": { "command": "npx", "args": ["ccu-mcp", "--stdio"], "env": { "CCU_HOST": "your-ccu-hostname-or-ip", "CCU_PASSWORD": "your-ccu-admin-password" } } } } ``` **示例客户端配置（HTTP）：** ```json { "mcpServers": { "ccu-mcp": { "url": "http://your-server-ip:3000", "headers": { "Authorization": "Bearer PASTE-YOUR-TOKEN-HERE" } } } } ``` 该项目是开源的，欢迎贡献。它包含 OpenSSF 最佳实践和 Scorecard 徽章，表明其对安全性和质量的关注。