C4 MCP应用程序-语音控制智能家居界面
通过Progressive Web App（PWA）+Node.js后端实现Control4自动化的语音控制智能家居界面，通常部署在Synology NAS上并调用 c4-mcp HTTP服务器。
不可协商的规则
c4-mcp必须始终与c4-mcp-app.
- 边界仅为HTTP(
C4_MCP_BASE_URL)，没有共享代码。
- 双子座（人工智能）做出决定；
c4-mcp执行。
- 后端解释用户命令（意图→ 工具选择→ args）使用Gemini。
- 然后后端调用
c4-mcp执行计划的工具。
项目结构
c4-mcp-app/
├── backend/ # Node.js backend service
│ ├── src/
│ │ ├── config/ # Configuration management
│ │ ├── middleware/ # Express middleware
│ │ ├── routes/ # API routes
│ │ ├── services/ # Business logic (STT, LLM, MCP)
│ │ ├── utils/ # Utilities (logger, errors)
│ │ ├── app.js # Express app setup
│ │ ├── server.js # Server entry point
│ │ └── websocket.js # WebSocket server
│ ├── scripts/ # Deployment and utility scripts
│ ├── package.json
│ ├── .env.example
│ └── README.md
│
├── frontend/ # PWA frontend
│ ├── css/ # Stylesheets
│ ├── js/ # JavaScript modules
│ ├── icons/ # PWA icons (generate these)
│ ├── index.html
│ ├── manifest.json # PWA manifest
│ └── service-worker.js # Service worker
│
├── docs/ # Comprehensive documentation
│ ├── architecture.md
│ ├── project_overview.md
│ ├── bootstrap_summary.md
│ ├── conventions_guardrails.md
│ ├── modules/
│ ├── api/
│ ├── data/
│ ├── ops/
│ └── ...
│
└── scripts/ # Deployment scripts
├── deploy-backend.sh
└── deploy-frontend.sh快速开始
先决条件
- Synology DS218+ DSM 7.x
- Node.js v22 （通过Synology软件包中心安装）
- API密钥：
- Google Cloud STT API或Azure语音服务 - OpenAI API（使用 gpt-4o-mini) - 已配置并可访问Control4 MCP（c4 MCP）
后端设置
cd backend
npm install
# First run only (avoid overwriting an existing .env)
test -f .env || cp .env.example .env
# Edit .env with your API keys / endpoints
npm start前端设置
只需将前端文件复制到Synology Web Station目录：
# See scripts/deploy-frontend.sh for detailed instructions发展模式
# Backend (with auto-reload)
cd backend
npm run dev
# Frontend
# Serve frontend/ directory with any static file server
# or open index.html directly in browser测试
cd backend
npm test # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # Coverage report部署到Synology DS218+
请参阅详细的部署说明：
笔记：
- 当前参考部署使用 Synology容器管理器 使用Docker Compose项目（请参见
compose.nas.yaml). - 后端与
c4-mcp作为一个独立的HTTP服务，通过C4_MCP_BASE_URL（无需共享代码）。 - 此设置中的典型LAN端口：
- 后端： http://:3002 - c4 mcp： http://:3334
API文档
- REST API： 看 docs/api/endpoints.md
- Websocket： 实时流式语音命令
/ws?token=... - 身份验证： JWT令牌（集
JWT_EXPIRY=never非到期）
建筑
- 前端： 带MediaRecorder API的PWA，用于语音捕获
- 后端： Node.js Express服务编排：
1. 语音转文本（Google/AAzure） 1. 意图解析（OpenAI；用 gpt-4o-mini) 1. 命令执行（通过控制4 MCP c4-mcp HTTP）
- 消除歧义的用户体验： 当Control4名称解析不明确时（例如，多个“地下室”房间），UI会提示选择并确定性地重试。
- 部署： Synology容器管理器（Docker Compose）是参考设置；本机进程部署也是可能的。
主要特点
✅ 语音控制智能家居命令\ ✅ 实时WebSocket流媒体\ ✅ 首次离线PWA，配备Service Worker\ ✅ JWT身份验证\ ✅ 使用Winston进行结构化日志记录\ ✅ 全面的错误处理\ ✅ 互动消歧（“哪个地下室？”）\ ✅ 速率限制和安全\ ✅ 80%+测试覆盖率
文档
完整的文档可在 /docs 文件夹：
贡献
这是Control4家庭自动化的个人项目。看 文档/约定_护栏.md 用于编码标准。
许可证
麻省理工学院
作者
Randy Britsch
______________________________________________________________________
技术栈： Node.js v22、Express.js、WebSocket、PWA（HTML/CSS/js）、Google/AAzure STT、OpenAI(gpt-4o-mini)，控制4 MCP(c4-mcp)\ 平台： Synology DS218+（2GB内存，双核Realtek RTD1296）\ 部署： Synology容器管理器（Docker Compose）。原生Synology工具（Web Station/任务调度器）是传统的。