[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-tevonsb--homeassistant-mcp":3,"tool-tevonsb--homeassistant-mcp":61},[4,18,26,36,44,52],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",141543,2,"2026-04-06T11:32:54",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107888,"2026-04-06T11:32:50",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":10,"last_commit_at":50,"category_tags":51,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":53,"name":54,"github_repo":55,"description_zh":56,"stars":57,"difficulty_score":10,"last_commit_at":58,"category_tags":59,"status":17},4292,"Deep-Live-Cam","hacksider\u002FDeep-Live-Cam","Deep-Live-Cam 是一款专注于实时换脸与视频生成的开源工具，用户仅需一张静态照片，即可通过“一键操作”实现摄像头画面的即时变脸或制作深度伪造视频。它有效解决了传统换脸技术流程繁琐、对硬件配置要求极高以及难以实时预览的痛点，让高质量的数字内容创作变得触手可及。\n\n这款工具不仅适合开发者和技术研究人员探索算法边界，更因其极简的操作逻辑（仅需三步：选脸、选摄像头、启动），广泛适用于普通用户、内容创作者、设计师及直播主播。无论是为了动画角色定制、服装展示模特替换，还是制作趣味短视频和直播互动，Deep-Live-Cam 都能提供流畅的支持。\n\n其核心技术亮点在于强大的实时处理能力，支持口型遮罩（Mouth Mask）以保留使用者原始的嘴部动作，确保表情自然精准；同时具备“人脸映射”功能，可同时对画面中的多个主体应用不同面孔。此外，项目内置了严格的内容安全过滤机制，自动拦截涉及裸露、暴力等不当素材，并倡导用户在获得授权及明确标注的前提下合规使用，体现了技术发展与伦理责任的平衡。",88924,"2026-04-06T03:28:53",[14,15,13,60],"视频",{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":77,"owner_email":78,"owner_twitter":79,"owner_website":80,"owner_url":81,"languages":82,"stars":99,"forks":100,"last_commit_at":101,"license":102,"difficulty_score":32,"env_os":103,"env_gpu":104,"env_ram":104,"env_deps":105,"category_tags":112,"github_topics":78,"view_count":32,"oss_zip_url":78,"oss_zip_packed_at":78,"status":17,"created_at":114,"updated_at":115,"faqs":116,"releases":127},4538,"tevonsb\u002Fhomeassistant-mcp","homeassistant-mcp","A MCP server for Home Assistant","homeassistant-mcp 是一款基于模型上下文协议（MCP）构建的开源服务器，旨在搭建本地 Home Assistant 智能家居系统与大型语言模型（LLM）之间的桥梁。它解决了传统智能家居控制依赖固定指令或复杂脚本的痛点，让 AI 能够通过自然语言直接理解并操作家中的各类设备，实现真正的智能交互。\n\n该工具非常适合拥有 Home Assistant 环境的开发者、智能家居爱好者以及希望探索 AI 代理在物联网场景应用的研究人员。通过它，用户不仅能用口语控制灯光、温控、窗帘等数十种设备，还能实时查询状态、管理自动化规则，甚至安装和维护系统插件。\n\n其核心技术亮点在于支持服务器发送事件（SSE），可向 AI 推送毫秒级的设备状态变更和自动化触发信息，确保交互的实时性与准确性。此外，它还提供了细粒度的权限控制和完整的 API 接口，覆盖从基础设备操控到 HACS 包管理的系统级功能。无论是构建个人语音助手，还是开发复杂的家庭智能体，homeassistant-mcp 都提供了一个安全、高效且易于集成的底层支持。","# Model Context Protocol Server for Home Assistant\n\nThe server uses the MCP protocol to share access to a local Home Assistant instance with an LLM application.\n\nA powerful bridge between your Home Assistant instance and Language Learning Models (LLMs), enabling natural language control and monitoring of your smart home devices through the Model Context Protocol (MCP). This server provides a comprehensive API for managing your entire Home Assistant ecosystem, from device control to system administration.\n\n![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-blue.svg)\n![Node.js](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fnode-%3E%3D20.10.0-green.svg)\n![Docker Compose](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocker-compose-%3E%3D1.27.0-blue.svg)\n![NPM](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fnpm-%3E%3D7.0.0-orange.svg)\n![TypeScript](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftypescript-%5E5.0.0-blue.svg)\n![Test Coverage](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fcoverage-95%25-brightgreen.svg)\n\n## Features\n\n- 🎮 **Device Control**: Control any Home Assistant device through natural language\n- 🔄 **Real-time Updates**: Get instant updates through Server-Sent Events (SSE)\n- 🤖 **Automation Management**: Create, update, and manage automations\n- 📊 **State Monitoring**: Track and query device states\n- 🔐 **Secure**: Token-based authentication and rate limiting\n- 📱 **Mobile Ready**: Works with any HTTP-capable client\n\n## Real-time Updates with SSE\n\nThe server includes a powerful Server-Sent Events (SSE) system that provides real-time updates from your Home Assistant instance. This allows you to:\n\n- 🔄 Get instant state changes for any device\n- 📡 Monitor automation triggers and executions\n- 🎯 Subscribe to specific domains or entities\n- 📊 Track service calls and script executions\n\n### Quick SSE Example\n\n```javascript\nconst eventSource = new EventSource(\n  'http:\u002F\u002Flocalhost:3000\u002Fsubscribe_events?token=YOUR_TOKEN&domain=light'\n);\n\neventSource.onmessage = (event) => {\n  const data = JSON.parse(event.data);\n  console.log('Update received:', data);\n};\n```\n\nSee [SSE_API.md](docs\u002FSSE_API.md) for complete documentation of the SSE system.\n\n## Table of Contents\n\n- [Key Features](#key-features)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n  - [Basic Setup](#basic-setup)\n  - [Docker Setup (Recommended)](#docker-setup-recommended)\n- [Configuration](#configuration)\n- [Development](#development)\n- [API Reference](#api-reference)\n  - [Device Control](#device-control)\n  - [Add-on Management](#add-on-management)\n  - [Package Management](#package-management)\n  - [Automation Management](#automation-management)\n- [Natural Language Integration](#natural-language-integration)\n- [Troubleshooting](#troubleshooting)\n- [Project Status](#project-status)\n- [Contributing](#contributing)\n- [Resources](#resources)\n- [License](#license)\n\n## Key Features\n\n### Core Functionality 🎮\n- **Smart Device Control**\n  - 💡 **Lights**: Brightness, color temperature, RGB color\n  - 🌡️ **Climate**: Temperature, HVAC modes, fan modes, humidity\n  - 🚪 **Covers**: Position and tilt control\n  - 🔌 **Switches**: On\u002Foff control\n  - 🚨 **Sensors & Contacts**: State monitoring\n  - 🎵 **Media Players**: Playback control, volume, source selection\n  - 🌪️ **Fans**: Speed, oscillation, direction\n  - 🔒 **Locks**: Lock\u002Funlock control\n  - 🧹 **Vacuums**: Start, stop, return to base\n  - 📹 **Cameras**: Motion detection, snapshots\n\n### System Management 🛠️\n- **Add-on Management**\n  - Browse available add-ons\n  - Install\u002Funinstall add-ons\n  - Start\u002Fstop\u002Frestart add-ons\n  - Version management\n  - Configuration access\n\n- **Package Management (HACS)**\n  - Integration with Home Assistant Community Store\n  - Multiple package types support:\n    - Custom integrations\n    - Frontend themes\n    - Python scripts\n    - AppDaemon apps\n    - NetDaemon apps\n  - Version control and updates\n  - Repository management\n\n- **Automation Management**\n  - Create and edit automations\n  - Advanced configuration options:\n    - Multiple trigger types\n    - Complex conditions\n    - Action sequences\n    - Execution modes\n  - Duplicate and modify existing automations\n  - Enable\u002Fdisable automation rules\n  - Trigger automation manually\n\n### Architecture Features 🏗️\n- **Intelligent Organization**\n  - Area and floor-based device grouping\n  - State monitoring and querying\n  - Smart context awareness\n  - Historical data access\n\n- **Robust Architecture**\n  - Comprehensive error handling\n  - State validation\n  - Secure API integration\n  - TypeScript type safety\n  - Extensive test coverage\n\n## Prerequisites\n\n- **Node.js** 20.10.0 or higher\n- **NPM** package manager\n- **Docker Compose** for containerization\n- Running **Home Assistant** instance\n- Home Assistant long-lived access token ([How to get token](https:\u002F\u002Fcommunity.home-assistant.io\u002Ft\u002Fhow-to-get-long-lived-access-token\u002F162159))\n- **HACS** installed for package management features\n- **Supervisor** access for add-on management\n\n## Installation\n\n### Basic Setup\n\n```bash\n# Clone the repository\ngit clone https:\u002F\u002Fgithub.com\u002Ftevonsb\u002Fhomeassistant-mcp.git\ncd homeassistant-mcp\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\n### Docker Setup (Recommended)\n\nThe project includes Docker support for easy deployment and consistent environments across different platforms.\n\n1. **Clone the repository:**\n    ```bash\n    git clone https:\u002F\u002Fgithub.com\u002Ftevonsb\u002Fhomeassistant-mcp.git\n    cd homeassistant-mcp\n    ```\n\n2. **Configure environment:**\n    ```bash\n    cp .env.example .env\n    ```\n    Edit the `.env` file with your Home Assistant configuration:\n    ```env\n    # Home Assistant Configuration\n    HASS_HOST=http:\u002F\u002Fhomeassistant.local:8123\n    HASS_TOKEN=your_home_assistant_token\n    HASS_SOCKET_URL=ws:\u002F\u002Fhomeassistant.local:8123\u002Fapi\u002Fwebsocket\n\n    # Server Configuration\n    PORT=3000\n    NODE_ENV=production\n    DEBUG=false\n    ```\n\n3. **Build and run with Docker Compose:**\n    ```bash\n    # Build and start the containers\n    docker compose up -d\n\n    # View logs\n    docker compose logs -f\n\n    # Stop the service\n    docker compose down\n    ```\n\n4. **Verify the installation:**\n    The server should now be running at `http:\u002F\u002Flocalhost:3000`. You can check the health endpoint at `http:\u002F\u002Flocalhost:3000\u002Fhealth`.\n\n5. **Update the application:**\n    ```bash\n    # Pull the latest changes\n    git pull\n\n    # Rebuild and restart the containers\n    docker compose up -d --build\n    ```\n\n#### Docker Configuration\n\nThe Docker setup includes:\n- Multi-stage build for optimal image size\n- Health checks for container monitoring\n- Volume mounting for environment configuration\n- Automatic container restart on failure\n- Exposed port 3000 for API access\n\n#### Docker Compose Environment Variables\n\nAll environment variables can be configured in the `.env` file. The following variables are supported:\n- `HASS_HOST`: Your Home Assistant instance URL\n- `HASS_TOKEN`: Long-lived access token for Home Assistant\n- `HASS_SOCKET_URL`: WebSocket URL for Home Assistant\n- `PORT`: Server port (default: 3000)\n- `NODE_ENV`: Environment (production\u002Fdevelopment)\n- `DEBUG`: Enable debug mode (true\u002Ffalse)\n\n## Configuration\n\n### Environment Variables\n\n```env\n# Home Assistant Configuration\nHASS_HOST=http:\u002F\u002Fhomeassistant.local:8123  # Your Home Assistant instance URL\nHASS_TOKEN=your_home_assistant_token       # Long-lived access token\nHASS_SOCKET_URL=ws:\u002F\u002Fhomeassistant.local:8123\u002Fapi\u002Fwebsocket  # WebSocket URL\n\n# Server Configuration\nPORT=3000                # Server port (default: 3000)\nNODE_ENV=production     # Environment (production\u002Fdevelopment)\nDEBUG=false            # Enable debug mode\n\n# Test Configuration\nTEST_HASS_HOST=http:\u002F\u002Flocalhost:8123  # Test instance URL\nTEST_HASS_TOKEN=test_token           # Test token\n```\n\n### Configuration Files\n\n1. **Development**: Copy `.env.example` to `.env.development`\n2. **Production**: Copy `.env.example` to `.env.production`\n3. **Testing**: Copy `.env.example` to `.env.test`\n\n### Adding to Claude Desktop (or other clients)\n\nTo use your new Home Assistant MCP server, you can add Claude Desktop as a client. Add the following to the configuration. Note this will run the MCP within claude and does not work with the Docker method.\n\n```\n{\n  \"homeassistant\": {\n    \"command\": \"node\",\n    \"args\": [\u003Cpath\u002Fto\u002Fyour\u002Fdist\u002Ffolder>]\n    \"env\": {\n      NODE_ENV=development\n      HASS_HOST=http:\u002F\u002Fhomeassistant.local:8123\n      HASS_TOKEN=your_home_assistant_token\n      PORT=3000\n      HASS_SOCKET_URL=ws:\u002F\u002Fhomeassistant.local:8123\u002Fapi\u002Fwebsocket\n      LOG_LEVEL=debug\n    }\n  }\n}\n\n```\n\n\n\n## API Reference\n\n### Device Control\n\n#### Common Entity Controls\n```json\n{\n  \"tool\": \"control\",\n  \"command\": \"turn_on\",  \u002F\u002F or \"turn_off\", \"toggle\"\n  \"entity_id\": \"light.living_room\"\n}\n```\n\n#### Light Control\n```json\n{\n  \"tool\": \"control\",\n  \"command\": \"turn_on\",\n  \"entity_id\": \"light.living_room\",\n  \"brightness\": 128,\n  \"color_temp\": 4000,\n  \"rgb_color\": [255, 0, 0]\n}\n```\n\n### Add-on Management\n\n#### List Available Add-ons\n```json\n{\n  \"tool\": \"addon\",\n  \"action\": \"list\"\n}\n```\n\n#### Install Add-on\n```json\n{\n  \"tool\": \"addon\",\n  \"action\": \"install\",\n  \"slug\": \"core_configurator\",\n  \"version\": \"5.6.0\"\n}\n```\n\n#### Manage Add-on State\n```json\n{\n  \"tool\": \"addon\",\n  \"action\": \"start\",  \u002F\u002F or \"stop\", \"restart\"\n  \"slug\": \"core_configurator\"\n}\n```\n\n### Package Management\n\n#### List HACS Packages\n```json\n{\n  \"tool\": \"package\",\n  \"action\": \"list\",\n  \"category\": \"integration\"  \u002F\u002F or \"plugin\", \"theme\", \"python_script\", \"appdaemon\", \"netdaemon\"\n}\n```\n\n#### Install Package\n```json\n{\n  \"tool\": \"package\",\n  \"action\": \"install\",\n  \"category\": \"integration\",\n  \"repository\": \"hacs\u002Fintegration\",\n  \"version\": \"1.32.0\"\n}\n```\n\n### Automation Management\n\n#### Create Automation\n```json\n{\n  \"tool\": \"automation_config\",\n  \"action\": \"create\",\n  \"config\": {\n    \"alias\": \"Motion Light\",\n    \"description\": \"Turn on light when motion detected\",\n    \"mode\": \"single\",\n    \"trigger\": [\n      {\n        \"platform\": \"state\",\n        \"entity_id\": \"binary_sensor.motion\",\n        \"to\": \"on\"\n      }\n    ],\n    \"action\": [\n      {\n        \"service\": \"light.turn_on\",\n        \"target\": {\n          \"entity_id\": \"light.living_room\"\n        }\n      }\n    ]\n  }\n}\n```\n\n#### Duplicate Automation\n```json\n{\n  \"tool\": \"automation_config\",\n  \"action\": \"duplicate\",\n  \"automation_id\": \"automation.motion_light\"\n}\n```\n\n### Core Functions\n\n#### State Management\n```http\nGET \u002Fapi\u002Fstate\nPOST \u002Fapi\u002Fstate\n```\n\nManages the current state of the system.\n\n**Example Request:**\n```json\nPOST \u002Fapi\u002Fstate\n{\n  \"context\": \"living_room\",\n  \"state\": {\n    \"lights\": \"on\",\n    \"temperature\": 22\n  }\n}\n```\n\n#### Context Updates\n```http\nPOST \u002Fapi\u002Fcontext\n```\n\nUpdates the current context with new information.\n\n**Example Request:**\n```json\nPOST \u002Fapi\u002Fcontext\n{\n  \"user\": \"john\",\n  \"location\": \"kitchen\",\n  \"time\": \"morning\",\n  \"activity\": \"cooking\"\n}\n```\n\n### Action Endpoints\n\n#### Execute Action\n```http\nPOST \u002Fapi\u002Faction\n```\n\nExecutes a specified action with given parameters.\n\n**Example Request:**\n```json\nPOST \u002Fapi\u002Faction\n{\n  \"action\": \"turn_on_lights\",\n  \"parameters\": {\n    \"room\": \"living_room\",\n    \"brightness\": 80\n  }\n}\n```\n\n#### Batch Actions\n```http\nPOST \u002Fapi\u002Factions\u002Fbatch\n```\n\nExecutes multiple actions in sequence.\n\n**Example Request:**\n```json\nPOST \u002Fapi\u002Factions\u002Fbatch\n{\n  \"actions\": [\n    {\n      \"action\": \"turn_on_lights\",\n      \"parameters\": {\n        \"room\": \"living_room\"\n      }\n    },\n    {\n      \"action\": \"set_temperature\",\n      \"parameters\": {\n        \"temperature\": 22\n      }\n    }\n  ]\n}\n```\n\n### Query Functions\n\n#### Get Available Actions\n```http\nGET \u002Fapi\u002Factions\n```\n\nReturns a list of all available actions.\n\n**Example Response:**\n```json\n{\n  \"actions\": [\n    {\n      \"name\": \"turn_on_lights\",\n      \"parameters\": [\"room\", \"brightness\"],\n      \"description\": \"Turns on lights in specified room\"\n    },\n    {\n      \"name\": \"set_temperature\",\n      \"parameters\": [\"temperature\"],\n      \"description\": \"Sets temperature in current context\"\n    }\n  ]\n}\n```\n\n#### Context Query\n```http\nGET \u002Fapi\u002Fcontext?type=current\n```\n\nRetrieves context information.\n\n**Example Response:**\n```json\n{\n  \"current_context\": {\n    \"user\": \"john\",\n    \"location\": \"kitchen\",\n    \"time\": \"morning\",\n    \"activity\": \"cooking\"\n  }\n}\n```\n\n### WebSocket Events\n\nThe server supports real-time updates via WebSocket connections.\n\n```javascript\n\u002F\u002F Client-side connection example\nconst ws = new WebSocket('ws:\u002F\u002Flocalhost:3000\u002Fws');\n\nws.onmessage = (event) => {\n  const data = JSON.parse(event.data);\n  console.log('Received update:', data);\n};\n```\n\n#### Supported Events\n\n- `state_change`: Emitted when system state changes\n- `context_update`: Emitted when context is updated\n- `action_executed`: Emitted when an action is completed\n- `error`: Emitted when an error occurs\n\n**Example Event Data:**\n```json\n{\n  \"event\": \"state_change\",\n  \"data\": {\n    \"previous_state\": {\n      \"lights\": \"off\"\n    },\n    \"current_state\": {\n      \"lights\": \"on\"\n    },\n    \"timestamp\": \"2024-03-20T10:30:00Z\"\n  }\n}\n```\n\n### Error Handling\n\nAll endpoints return standard HTTP status codes:\n\n- 200: Success\n- 400: Bad Request\n- 401: Unauthorized\n- 403: Forbidden\n- 404: Not Found\n- 500: Internal Server Error\n\n**Error Response Format:**\n```json\n{\n  \"error\": {\n    \"code\": \"INVALID_PARAMETERS\",\n    \"message\": \"Missing required parameter: room\",\n    \"details\": {\n      \"missing_fields\": [\"room\"]\n    }\n  }\n}\n```\n\n### Rate Limiting\n\nThe API implements rate limiting to prevent abuse:\n\n- 100 requests per minute per IP for regular endpoints\n- 1000 requests per minute per IP for WebSocket connections\n\nWhen rate limit is exceeded, the server returns:\n\n```json\n{\n  \"error\": {\n    \"code\": \"RATE_LIMIT_EXCEEDED\",\n    \"message\": \"Too many requests\",\n    \"reset_time\": \"2024-03-20T10:31:00Z\"\n  }\n}\n```\n\n### Example Usage\n\n#### Using curl\n```bash\n# Get current state\ncurl -X GET \\\n  http:\u002F\u002Flocalhost:3000\u002Fapi\u002Fstate \\\n  -H 'Authorization: ApiKey your_api_key_here'\n\n# Execute action\ncurl -X POST \\\n  http:\u002F\u002Flocalhost:3000\u002Fapi\u002Faction \\\n  -H 'Authorization: ApiKey your_api_key_here' \\\n  -H 'Content-Type: application\u002Fjson' \\\n  -d '{\n    \"action\": \"turn_on_lights\",\n    \"parameters\": {\n      \"room\": \"living_room\",\n      \"brightness\": 80\n    }\n  }'\n```\n\n#### Using JavaScript\n```javascript\n\u002F\u002F Execute action\nasync function executeAction() {\n  const response = await fetch('http:\u002F\u002Flocalhost:3000\u002Fapi\u002Faction', {\n    method: 'POST',\n    headers: {\n      'Authorization': 'ApiKey your_api_key_here',\n      'Content-Type': 'application\u002Fjson'\n    },\n    body: JSON.stringify({\n      action: 'turn_on_lights',\n      parameters: {\n        room: 'living_room',\n        brightness: 80\n      }\n    })\n  });\n  \n  const data = await response.json();\n  console.log('Action result:', data);\n}\n```\n\n## Development\n\n```bash\n# Development mode with hot reload\nnpm run dev\n\n# Build project\nnpm run build\n\n# Production mode\nnpm run start\n\n# Run tests\nnpx jest --config=jest.config.cjs\n\n# Run tests with coverage\nnpx jest --coverage\n\n# Lint code\nnpm run lint\n\n# Format code\nnpm run format\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Node.js Version (`toSorted is not a function`)**\n   - **Solution:** Update to Node.js 20.10.0+\n   ```bash\n   nvm install 20.10.0\n   nvm use 20.10.0\n   ```\n\n2. **Connection Issues**\n   - Verify Home Assistant is running\n   - Check `HASS_HOST` accessibility\n   - Validate token permissions\n   - Ensure WebSocket connection for real-time updates\n\n3. **Add-on Management Issues**\n   - Verify Supervisor access\n   - Check add-on compatibility\n   - Validate system resources\n\n4. **HACS Integration Issues**\n   - Verify HACS installation\n   - Check HACS integration status\n   - Validate repository access\n\n5. **Automation Issues**\n   - Verify entity availability\n   - Check trigger conditions\n   - Validate service calls\n   - Monitor execution logs\n\n## Project Status\n\n✅ **Complete**\n- Entity, Floor, and Area access\n- Device control (Lights, Climate, Covers, Switches, Contacts)\n- Add-on management system\n- Package management through HACS\n- Advanced automation configuration\n- Basic state management\n- Error handling and validation\n- Docker containerization\n- Jest testing setup\n- TypeScript integration\n- Environment variable management\n- Home Assistant API integration\n- Project documentation\n\n🚧 **In Progress**\n- WebSocket implementation for real-time updates\n- Enhanced security features\n- Tool organization optimization\n- Performance optimization\n- Resource context integration\n- API documentation generation\n- Multi-platform desktop integration\n- Advanced error recovery\n- Custom prompt testing\n- Enhanced macOS integration\n- Type safety improvements\n- Testing coverage expansion\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Implement your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\n## Resources\n\n- [MCP Documentation](https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction)\n- [Home Assistant Docs](https:\u002F\u002Fwww.home-assistant.io)\n- [HA REST API](https:\u002F\u002Fdevelopers.home-assistant.io\u002Fdocs\u002Fapi\u002Frest)\n- [HACS Documentation](https:\u002F\u002Fhacs.xyz)\n- [TypeScript Documentation](https:\u002F\u002Fwww.typescriptlang.org\u002Fdocs)\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file\n","# 适用于 Home Assistant 的模型上下文协议服务器\n\n该服务器使用 MCP 协议，将本地 Home Assistant 实例的访问权限共享给 LLM 应用程序。\n\n作为您 Home Assistant 实例与语言学习模型（LLMs）之间的强大桥梁，它通过模型上下文协议（MCP）实现了对智能家居设备的自然语言控制和监控。此服务器提供了一个全面的 API，用于管理您的整个 Home Assistant 生态系统，从设备控制到系统管理。\n\n![许可证](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-blue.svg)\n![Node.js](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fnode-%3E%3D20.10.0-green.svg)\n![Docker Compose](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocker-compose-%3E%3D1.27.0-blue.svg)\n![NPM](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fnpm-%3E%3D7.0.0-orange.svg)\n![TypeScript](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftypescript-%5E5.0.0-blue.svg)\n![测试覆盖率](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fcoverage-95%25-brightgreen.svg)\n\n## 功能特性\n\n- 🎮 **设备控制**：通过自然语言控制任何 Home Assistant 设备\n- 🔄 **实时更新**：通过服务器发送事件（SSE）获取即时更新\n- 🤖 **自动化管理**：创建、更新和管理自动化规则\n- 📊 **状态监控**：跟踪和查询设备状态\n- 🔐 **安全**：基于令牌的身份验证和速率限制\n- 📱 **移动端友好**：可与任何支持 HTTP 的客户端配合使用\n\n## 使用 SSE 的实时更新\n\n服务器内置了强大的服务器发送事件（SSE）系统，可提供来自 Home Assistant 实例的实时更新。这使您可以：\n\n- 🔄 获取任何设备的状态变化\n- 📡 监控自动化触发和执行情况\n- 🎯 订阅特定域或实体\n- 📊 跟踪服务调用和脚本执行\n\n### SSE 快速示例\n\n```javascript\nconst eventSource = new EventSource(\n  'http:\u002F\u002Flocalhost:3000\u002Fsubscribe_events?token=YOUR_TOKEN&domain=light'\n);\n\neventSource.onmessage = (event) => {\n  const data = JSON.parse(event.data);\n  console.log('收到更新:', data);\n};\n```\n\n有关 SSE 系统的完整文档，请参阅 [SSE_API.md](docs\u002FSSE_API.md)。\n\n## 目录\n\n- [核心功能](#key-features)\n- [先决条件](#prerequisites)\n- [安装](#installation)\n  - [基本设置](#basic-setup)\n  - [推荐的 Docker 设置](#docker-setup-recommended)\n- [配置](#configuration)\n- [开发](#development)\n- [API 参考](#api-reference)\n  - [设备控制](#device-control)\n  - [附加组件管理](#add-on-management)\n  - [软件包管理](#package-management)\n  - [自动化管理](#automation-management)\n- [自然语言集成](#natural-language-integration)\n- [故障排除](#troubleshooting)\n- [项目状态](#project-status)\n- [贡献](#contributing)\n- [资源](#resources)\n- [许可证](#license)\n\n## 核心功能\n\n### 核心功能 🎮\n- **智能设备控制**\n  - 💡 **灯光**：亮度、色温、RGB 颜色\n  - 🌡️ **气候**：温度、空调模式、风扇模式、湿度\n  - 🚪 **窗帘\u002F百叶窗**：位置和倾斜角度控制\n  - 🔌 **开关**：开\u002F关控制\n  - 🚨 **传感器与门磁**：状态监测\n  - 🎵 **媒体播放器**：播放控制、音量调节、源选择\n  - 🌪️ **风扇**：风速、摆动、风向控制\n  - 🔒 **门锁**：上锁\u002F解锁控制\n  - 🧹 **扫地机器人**：启动、停止、返回基站\n  - 📹 **摄像头**：移动侦测、截图\n\n### 系统管理 🛠️\n- **附加组件管理**\n  - 浏览可用的附加组件\n  - 安装\u002F卸载附加组件\n  - 启动\u002F停止\u002F重启附加组件\n  - 版本管理\n  - 配置访问\n\n- **软件包管理（HACS）**\n  - 与 Home Assistant 社区商店集成\n  - 支持多种类型的软件包：\n    - 自定义集成\n    - 前端主题\n    - Python 脚本\n    - AppDaemon 应用\n    - NetDaemon 应用\n  - 版本控制和更新\n  - 仓库管理\n\n- **自动化管理**\n  - 创建和编辑自动化规则\n  - 高级配置选项：\n    - 多种触发类型\n    - 复杂条件\n    - 动作序列\n    - 执行模式\n  - 复制和修改现有自动化\n  - 启用\u002F禁用自动化规则\n  - 手动触发自动化\n\n### 架构特点 🏗️\n- **智能组织**\n  - 按区域和楼层对设备分组\n  - 状态监控和查询\n  - 智能上下文感知\n  - 历史数据访问\n\n- **健壮架构**\n  - 全面的错误处理\n  - 状态验证\n  - 安全的 API 集成\n  - TypeScript 类型安全\n  - 广泛的测试覆盖\n\n## 先决条件\n\n- **Node.js** 20.10.0 或更高版本\n- **NPM** 包管理器\n- **Docker Compose** 用于容器化\n- 正在运行的 **Home Assistant** 实例\n- Home Assistant 长效访问令牌（[如何获取令牌](https:\u002F\u002Fcommunity.home-assistant.io\u002Ft\u002Fhow-to-get-long-lived-access-token\u002F162159)）\n- 已安装 **HACS** 以使用软件包管理功能\n- 具有 **Supervisor** 访问权限以便进行附加组件管理\n\n## 安装\n\n### 基本设置\n\n```bash\n# 克隆仓库\ngit clone https:\u002F\u002Fgithub.com\u002Ftevonsb\u002Fhomeassistant-mcp.git\ncd homeassistant-mcp\n\n# 安装依赖\nnpm install\n\n# 构建项目\nnpm run build\n```\n\n### Docker 设置（推荐）\n\n该项目包含 Docker 支持，便于部署并在不同平台上保持一致的环境。\n\n1. **克隆仓库：**\n    ```bash\n    git clone https:\u002F\u002Fgithub.com\u002Ftevonsb\u002Fhomeassistant-mcp.git\n    cd homeassistant-mcp\n    ```\n\n2. **配置环境：**\n    ```bash\n    cp .env.example .env\n    ```\n    编辑 `.env` 文件以填写您的 Home Assistant 配置：\n    ```env\n    # Home Assistant 配置\n    HASS_HOST=http:\u002F\u002Fhomeassistant.local:8123\n    HASS_TOKEN=your_home_assistant_token\n    HASS_SOCKET_URL=ws:\u002F\u002Fhomeassistant.local:8123\u002Fapi\u002Fwebsocket\n\n    # 服务器配置\n    PORT=3000\n    NODE_ENV=production\n    DEBUG=false\n    ```\n\n3. **使用 Docker Compose 构建并运行：**\n    ```bash\n    # 构建并启动容器\n    docker compose up -d\n\n    # 查看日志\n    docker compose logs -f\n\n    # 停止服务\n    docker compose down\n    ```\n\n4. **验证安装：**\n    服务器现在应该在 `http:\u002F\u002Flocalhost:3000` 上运行。您可以通过访问 `http:\u002F\u002Flocalhost:3000\u002Fhealth` 来检查健康端点。\n\n5. **更新应用：**\n    ```bash\n    # 拉取最新更改\n    git pull\n\n    # 重新构建并重启容器\n    docker compose up -d --build\n    ```\n\n#### Docker 配置\n\nDocker 设置包括：\n- 多阶段构建以优化镜像大小\n- 容器监控的健康检查\n- 环境配置的卷挂载\n- 容器失败时自动重启\n- 暴露端口 3000 用于 API 访问\n\n#### Docker Compose 环境变量\n\n所有环境变量都可以在 `.env` 文件中配置。支持以下变量：\n- `HASS_HOST`：您的 Home Assistant 实例 URL\n- `HASS_TOKEN`：Home Assistant 的长期访问令牌\n- `HASS_SOCKET_URL`：Home Assistant 的 WebSocket URL\n- `PORT`：服务器端口（默认：3000）\n- `NODE_ENV`：环境（生产\u002F开发）\n- `DEBUG`：启用调试模式（true\u002Ffalse）\n\n## 配置\n\n### 环境变量\n\n```env\n# Home Assistant 配置\nHASS_HOST=http:\u002F\u002Fhomeassistant.local:8123  # 您的 Home Assistant 实例 URL\nHASS_TOKEN=your_home_assistant_token       # 长期访问令牌\nHASS_SOCKET_URL=ws:\u002F\u002Fhomeassistant.local:8123\u002Fapi\u002Fwebsocket  # WebSocket URL\n\n# 服务器配置\nPORT=3000                # 服务器端口（默认：3000）\nNODE_ENV=production     # 环境（生产\u002F开发）\nDEBUG=false            # 启用调试模式\n\n# 测试配置\nTEST_HASS_HOST=http:\u002F\u002Flocalhost:8123  # 测试实例 URL\nTEST_HASS_TOKEN=test_token           # 测试令牌\n```\n\n### 配置文件\n\n1. **开发环境**：将 `.env.example` 复制到 `.env.development`\n2. **生产环境**：将 `.env.example` 复制到 `.env.production`\n3. **测试环境**：将 `.env.example` 复制到 `.env.test`\n\n### 添加到 Claude Desktop（或其他客户端）\n\n要使用您的新 Home Assistant MCP 服务器，您可以将 Claude Desktop 添加为客户端。将以下内容添加到配置中。请注意，这会在 Claude 内部运行 MCP，且不适用于 Docker 方法。\n\n```\n{\n  \"homeassistant\": {\n    \"command\": \"node\",\n    \"args\": [\u003Cpath\u002Fto\u002Fyour\u002Fdist\u002Ffolder>]\n    \"env\": {\n      NODE_ENV=development\n      HASS_HOST=http:\u002F\u002Fhomeassistant.local:8123\n      HASS_TOKEN=your_home_assistant_token\n      PORT=3000\n      HASS_SOCKET_URL=ws:\u002F\u002Fhomeassistant.local:8123\u002Fapi\u002Fwebsocket\n      LOG_LEVEL=debug\n    }\n  }\n}\n\n```\n\n\n\n## API 参考\n\n### 设备控制\n\n#### 常见实体控制\n```json\n{\n  \"tool\": \"control\",\n  \"command\": \"turn_on\",  \u002F\u002F 或 \"turn_off\"、\"toggle\"\n  \"entity_id\": \"light.living_room\"\n}\n```\n\n#### 照明控制\n```json\n{\n  \"tool\": \"control\",\n  \"command\": \"turn_on\",\n  \"entity_id\": \"light.living_room\",\n  \"brightness\": 128,\n  \"color_temp\": 4000,\n  \"rgb_color\": [255, 0, 0]\n}\n```\n\n### 插件管理\n\n#### 列出可用插件\n```json\n{\n  \"tool\": \"addon\",\n  \"action\": \"list\"\n}\n```\n\n#### 安装插件\n```json\n{\n  \"tool\": \"addon\",\n  \"action\": \"install\",\n  \"slug\": \"core_configurator\",\n  \"version\": \"5.6.0\"\n}\n```\n\n#### 管理插件状态\n```json\n{\n  \"tool\": \"addon\",\n  \"action\": \"start\",  \u002F\u002F 或 \"stop\"、\"restart\"\n  \"slug\": \"core_configurator\"\n}\n```\n\n### 软件包管理\n\n#### 列出 HACS 软件包\n```json\n{\n  \"tool\": \"package\",\n  \"action\": \"list\",\n  \"category\": \"integration\"  \u002F\u002F 或 \"plugin\"、\"theme\"、\"python_script\"、\"appdaemon\"、\"netdaemon\"\n}\n```\n\n#### 安装软件包\n```json\n{\n  \"tool\": \"package\",\n  \"action\": \"install\",\n  \"category\": \"integration\",\n  \"repository\": \"hacs\u002Fintegration\",\n  \"version\": \"1.32.0\"\n}\n```\n\n### 自动化管理\n\n#### 创建自动化\n```json\n{\n  \"tool\": \"automation_config\",\n  \"action\": \"create\",\n  \"config\": {\n    \"alias\": \"Motion Light\",\n    \"description\": \"当检测到移动时打开灯\",\n    \"mode\": \"single\",\n    \"trigger\": [\n      {\n        \"platform\": \"state\",\n        \"entity_id\": \"binary_sensor.motion\",\n        \"to\": \"on\"\n      }\n    ],\n    \"action\": [\n      {\n        \"service\": \"light.turn_on\",\n        \"target\": {\n          \"entity_id\": \"light.living_room\"\n        }\n      }\n    ]\n  }\n}\n```\n\n#### 复制自动化\n```json\n{\n  \"tool\": \"automation_config\",\n  \"action\": \"duplicate\",\n  \"automation_id\": \"automation.motion_light\"\n}\n```\n\n### 核心功能\n\n#### 状态管理\n```http\nGET \u002Fapi\u002Fstate\nPOST \u002Fapi\u002Fstate\n```\n\n管理系统的当前状态。\n\n**示例请求：**\n```json\nPOST \u002Fapi\u002Fstate\n{\n  \"context\": \"living_room\",\n  \"state\": {\n    \"lights\": \"on\",\n    \"temperature\": 22\n  }\n}\n```\n\n#### 上下文更新\n```http\nPOST \u002Fapi\u002Fcontext\n```\n\n用新信息更新当前上下文。\n\n**示例请求：**\n```json\nPOST \u002Fapi\u002Fcontext\n{\n  \"user\": \"john\",\n  \"location\": \"kitchen\",\n  \"time\": \"morning\",\n  \"activity\": \"cooking\"\n}\n```\n\n### 行动端点\n\n#### 执行行动\n```http\nPOST \u002Fapi\u002Faction\n```\n\n根据给定参数执行指定行动。\n\n**示例请求：**\n```json\nPOST \u002Fapi\u002Faction\n{\n  \"action\": \"turn_on_lights\",\n  \"parameters\": {\n    \"room\": \"living_room\",\n    \"brightness\": 80\n  }\n}\n```\n\n#### 批量行动\n```http\nPOST \u002Fapi\u002Factions\u002Fbatch\n```\n\n按顺序执行多个行动。\n\n**示例请求：**\n```json\nPOST \u002Fapi\u002Factions\u002Fbatch\n{\n  \"actions\": [\n    {\n      \"action\": \"turn_on_lights\",\n      \"parameters\": {\n        \"room\": \"living_room\"\n      }\n    },\n    {\n      \"action\": \"set_temperature\",\n      \"parameters\": {\n        \"temperature\": 22\n      }\n    }\n  ]\n}\n```\n\n### 查询功能\n\n#### 获取可用操作\n```http\nGET \u002Fapi\u002Factions\n```\n\n返回所有可用操作的列表。\n\n**示例响应：**\n```json\n{\n  \"actions\": [\n    {\n      \"name\": \"turn_on_lights\",\n      \"parameters\": [\"room\", \"brightness\"],\n      \"description\": \"在指定房间打开灯光\"\n    },\n    {\n      \"name\": \"set_temperature\",\n      \"parameters\": [\"temperature\"],\n      \"description\": \"设置当前环境的温度\"\n    }\n  ]\n}\n```\n\n#### 上下文查询\n```http\nGET \u002Fapi\u002Fcontext?type=current\n```\n\n获取上下文信息。\n\n**示例响应：**\n```json\n{\n  \"current_context\": {\n    \"user\": \"john\",\n    \"location\": \"厨房\",\n    \"time\": \"早晨\",\n    \"activity\": \"做饭\"\n  }\n}\n```\n\n### WebSocket 事件\n\n服务器支持通过 WebSocket 连接进行实时更新。\n\n```javascript\n\u002F\u002F 客户端连接示例\nconst ws = new WebSocket('ws:\u002F\u002Flocalhost:3000\u002Fws');\n\nws.onmessage = (event) => {\n  const data = JSON.parse(event.data);\n  console.log('收到更新:', data);\n};\n```\n\n#### 支持的事件\n\n- `state_change`: 当系统状态发生变化时触发\n- `context_update`: 当上下文更新时触发\n- `action_executed`: 当某个操作完成时触发\n- `error`: 当发生错误时触发\n\n**事件数据示例：**\n```json\n{\n  \"event\": \"state_change\",\n  \"data\": {\n    \"previous_state\": {\n      \"lights\": \"关\"\n    },\n    \"current_state\": {\n      \"lights\": \"开\"\n    },\n    \"timestamp\": \"2024-03-20T10:30:00Z\"\n  }\n}\n```\n\n### 错误处理\n\n所有端点均返回标准 HTTP 状态码：\n\n- 200：成功\n- 400：请求错误\n- 401：未授权\n- 403：禁止访问\n- 404：未找到\n- 500：服务器内部错误\n\n**错误响应格式：**\n```json\n{\n  \"error\": {\n    \"code\": \"INVALID_PARAMETERS\",\n    \"message\": \"缺少必填参数：room\",\n    \"details\": {\n      \"missing_fields\": [\"room\"]\n    }\n  }\n}\n```\n\n### 速率限制\n\nAPI 实施了速率限制以防止滥用：\n\n- 普通端点每 IP 地址每分钟 100 次请求\n- WebSocket 连接每 IP 地址每分钟 1000 次请求\n\n当超过速率限制时，服务器会返回：\n\n```json\n{\n  \"error\": {\n    \"code\": \"RATE_LIMIT_EXCEEDED\",\n    \"message\": \"请求次数过多\",\n    \"reset_time\": \"2024-03-20T10:31:00Z\"\n  }\n}\n```\n\n### 使用示例\n\n#### 使用 curl\n```bash\n# 获取当前状态\ncurl -X GET \\\n  http:\u002F\u002Flocalhost:3000\u002Fapi\u002Fstate \\\n  -H 'Authorization: ApiKey your_api_key_here'\n\n# 执行操作\ncurl -X POST \\\n  http:\u002F\u002Flocalhost:3000\u002Fapi\u002Faction \\\n  -H 'Authorization: ApiKey your_api_key_here' \\\n  -H 'Content-Type: application\u002Fjson' \\\n  -d '{\n    \"action\": \"turn_on_lights\",\n    \"parameters\": {\n      \"room\": \"客厅\",\n      \"brightness\": 80\n    }\n  }'\n```\n\n#### 使用 JavaScript\n```javascript\n\u002F\u002F 执行操作\nasync function executeAction() {\n  const response = await fetch('http:\u002F\u002Flocalhost:3000\u002Fapi\u002Faction', {\n    method: 'POST',\n    headers: {\n      'Authorization': 'ApiKey your_api_key_here',\n      'Content-Type': 'application\u002Fjson'\n    },\n    body: JSON.stringify({\n      action: 'turn_on_lights',\n      parameters: {\n        room: '客厅',\n        brightness: 80\n      }\n    })\n  });\n  \n  const data = await response.json();\n  console.log('操作结果:', data);\n}\n```\n\n## 开发\n\n```bash\n# 开发模式（热重载）\nnpm run dev\n\n# 构建项目\nnpm run build\n\n# 生产模式\nnpm run start\n\n# 运行测试\nnpx jest --config=jest.config.cjs\n\n# 带覆盖率的测试\nnpx jest --coverage\n\n# 代码检查\nnpm run lint\n\n# 代码格式化\nnpm run format\n```\n\n## 故障排除\n\n### 常见问题\n\n1. **Node.js 版本（`toSorted is not a function`）**\n   - **解决方案：** 更新至 Node.js 20.10.0 及以上版本\n   ```bash\n   nvm install 20.10.0\n   nvm use 20.10.0\n   ```\n\n2. **连接问题**\n   - 确认 Home Assistant 是否正在运行\n   - 检查 `HASS_HOST` 是否可访问\n   - 验证 Token 权限\n   - 确保 WebSocket 连接用于实时更新\n\n3. **附加组件管理问题**\n   - 验证 Supervisor 的访问权限\n   - 检查附加组件的兼容性\n   - 确认系统资源是否充足\n\n4. **HACS 集成问题**\n   - 确认 HACS 是否已安装\n   - 检查 HACS 集成状态\n   - 验证仓库访问权限\n\n5. **自动化问题**\n   - 确认实体是否可用\n   - 检查触发条件\n   - 验证服务调用\n   - 监控执行日志\n\n## 项目状态\n\n✅ **已完成**\n- 实体、楼层和区域访问\n- 设备控制（灯光、气候、遮阳帘、开关、门磁等）\n- 附加组件管理系统\n- 通过 HACS 进行软件包管理\n- 高级自动化配置\n- 基本状态管理\n- 错误处理与验证\n- Docker 容器化\n- Jest 测试框架搭建\n- TypeScript 集成\n- 环境变量管理\n- Home Assistant API 集成\n- 项目文档编写\n\n🚧 **进行中**\n- WebSocket 实现，用于实时更新\n- 安全功能增强\n- 工具组织优化\n- 性能优化\n- 资源上下文集成\n- API 文档生成\n- 多平台桌面应用集成\n- 高级错误恢复机制\n- 自定义提示测试\n- macOS 集成优化\n- 类型安全改进\n- 测试覆盖率扩展\n\n## 贡献\n\n1. 克隆仓库并创建分支\n2. 实现所需功能\n3. 为新功能添加测试\n4. 确保所有测试通过\n5. 提交 Pull Request\n\n## 资源\n\n- [MCP 文档](https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction)\n- [Home Assistant 官方文档](https:\u002F\u002Fwww.home-assistant.io)\n- [HA REST API 文档](https:\u002F\u002Fdevelopers.home-assistant.io\u002Fdocs\u002Fapi\u002Frest)\n- [HACS 文档](https:\u002F\u002Fhacs.xyz)\n- [TypeScript 官方文档](https:\u002F\u002Fwww.typescriptlang.org\u002Fdocs)\n\n## 许可证\n\nMIT 许可证 - 详见 [LICENSE](LICENSE) 文件","# Home Assistant MCP 快速上手指南\n\nHome Assistant MCP 是一个基于 Model Context Protocol (MCP) 的服务器，旨在将本地 Home Assistant 实例与大语言模型（LLM）连接。通过它，你可以使用自然语言控制智能家居设备、管理自动化脚本并实时监控设备状态。\n\n## 环境准备\n\n在开始之前，请确保你的系统满足以下要求：\n\n*   **运行环境**:\n    *   Node.js >= 20.10.0\n    *   NPM >= 7.0.0\n    *   Docker Compose >= 1.27.0 (推荐用于部署)\n*   **Home Assistant 实例**:\n    *   正在运行的 Home Assistant 服务。\n    *   **Long-Lived Access Token**: 需要在 HA 用户配置中生成一个长期有效的访问令牌。\n    *   **HACS**: 已安装 Home Assistant Community Store (用于包管理功能)。\n    *   **Supervisor**: 需要 Supervisor 权限以管理 Add-ons。\n\n## 安装步骤\n\n推荐使用 **Docker Compose** 进行部署，以获得一致且易于维护的环境。\n\n### 1. 克隆项目\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Ftevonsb\u002Fhomeassistant-mcp.git\ncd homeassistant-mcp\n```\n\n### 2. 配置环境变量\n复制示例配置文件并根据你的实际情况修改：\n```bash\ncp .env.example .env\n```\n\n编辑 `.env` 文件，填入你的 Home Assistant 信息：\n```env\n# Home Assistant 配置\nHASS_HOST=http:\u002F\u002Fhomeassistant.local:8123\nHASS_TOKEN=your_home_assistant_token\nHASS_SOCKET_URL=ws:\u002F\u002Fhomeassistant.local:8123\u002Fapi\u002Fwebsocket\n\n# 服务器配置\nPORT=3000\nNODE_ENV=production\nDEBUG=false\n```\n\n### 3. 启动服务\n使用 Docker Compose 构建并后台运行容器：\n```bash\ndocker compose up -d\n```\n\n查看日志以确保服务正常启动：\n```bash\ndocker compose logs -f\n```\n\n> **验证安装**: 服务启动后，可通过访问 `http:\u002F\u002Flocalhost:3000\u002Fhealth` 检查健康状态。\n\n*(可选) 源码安装方式*:\n如果不使用 Docker，可执行以下命令：\n```bash\nnpm install\nnpm run build\nnpm start\n```\n\n## 基本使用\n\n安装完成后，该服务器即可作为 MCP Server 被 LLM 客户端（如 Claude Desktop）调用。\n\n### 1. 配置 LLM 客户端\n若要在 **Claude Desktop** 中使用，需在其配置文件中添加以下内容（注意：此方式直接运行 Node，不使用 Docker）：\n\n```json\n{\n  \"homeassistant\": {\n    \"command\": \"node\",\n    \"args\": [\"\u003Cpath\u002Fto\u002Fyour\u002Fdist\u002Ffolder>\"],\n    \"env\": {\n      \"NODE_ENV\": \"development\",\n      \"HASS_HOST\": \"http:\u002F\u002Fhomeassistant.local:8123\",\n      \"HASS_TOKEN\": \"your_home_assistant_token\",\n      \"PORT\": \"3000\",\n      \"HASS_SOCKET_URL\": \"ws:\u002F\u002Fhomeassistant.local:8123\u002Fapi\u002Fwebsocket\",\n      \"LOG_LEVEL\": \"debug\"\n    }\n  }\n}\n```\n\n### 2. 功能示例\n\n配置成功后，你可以在对话中直接使用自然语言指令，MCP 会自动转换为相应的 API 调用：\n\n*   **控制设备**:\n    > \"把客厅的灯打开，亮度调到 50%。\"\n    > (对应工具调用：`control` -> `turn_on`, `entity_id`: `light.living_room`, `brightness`: 128)\n\n*   **查询状态**:\n    > \"现在卧室的温度是多少？\"\n    > (对应工具调用：查询 `sensor` 实体状态)\n\n*   **管理自动化**:\n    > \"创建一个新自动化：当检测到运动时打开走廊灯。\"\n    > (对应工具调用：`automation_config` -> `create`)\n\n*   **实时订阅 (SSE)**:\n    开发者也可通过 HTTP SSE 端点直接订阅事件：\n    ```javascript\n    const eventSource = new EventSource(\n      'http:\u002F\u002Flocalhost:3000\u002Fsubscribe_events?token=YOUR_TOKEN&domain=light'\n    );\n\n    eventSource.onmessage = (event) => {\n      const data = JSON.parse(event.data);\n      console.log('收到更新:', data);\n    };\n    ```\n\n现在，你的 Home Assistant 已经可以通过大模型进行智能交互了。","资深智能家居开发者李明正在为独居老人构建一套能理解复杂自然语言指令的语音交互系统，旨在让老人无需记忆特定命令词即可控制全屋设备。\n\n### 没有 homeassistant-mcp 时\n- **指令僵化**：必须预先编写大量固定的意图识别规则，老人一旦说“把客厅光线调得柔和点”而非标准指令，系统便无法响应。\n- **状态感知滞后**：无法实时获取设备状态变化，若老人手动关闭了空调，语音助手仍会错误地报告“空调正在运行”。\n- **自动化开发繁琐**：创建新的联动逻辑（如“下雨自动关窗”）需要手动编辑复杂的 YAML 配置文件或调用底层 API，调试周期长。\n- **上下文缺失**：大模型无法直接读取家中传感器的实时数据，导致无法回答“现在卧室温度多少”或“大门锁好了吗”等动态问题。\n\n### 使用 homeassistant-mcp 后\n- **自然语言直达**：homeassistant-mcp 作为桥梁，让大模型直接通过 MCP 协议理解并执行“调柔光线”等模糊指令，自动映射到具体的亮度和色温参数。\n- **实时状态同步**：借助 SSE 服务器发送事件机制，大模型能毫秒级感知设备状态变更，确保语音反馈与家中实际情况完全一致。\n- **动态管理自动化**：开发者可直接用自然语言吩咐大模型创建或修改自动化场景，homeassistant-mcp 即时将其转化为系统配置，无需手动编码。\n- **全域数据透视**：大模型通过工具直接查询任意实体状态，不仅能回答实时环境数据，还能主动分析趋势（如“过去一小时能耗过高”）。\n\nhomeassistant-mcp 将原本割裂的智能家居系统与生成式 AI 深度融合，让冷冰冰的设备拥有了真正理解人类意图和实时感知环境的能力。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftevonsb_homeassistant-mcp_9fd4c21b.png","tevonsb","Tevon Strand-Brown","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Ftevonsb_a34d7e36.jpg","SF-based engineer","Vannevar Labs","San Francisco, CA",null,"strandbrown","tevonsb.com","https:\u002F\u002Fgithub.com\u002Ftevonsb",[83,87,91,95],{"name":84,"color":85,"percentage":86},"TypeScript","#3178c6",96.6,{"name":88,"color":89,"percentage":90},"JavaScript","#f1e05a",1.7,{"name":92,"color":93,"percentage":94},"Shell","#89e051",1.6,{"name":96,"color":97,"percentage":98},"Dockerfile","#384d54",0.1,562,56,"2026-03-31T05:13:08","Apache-2.0","Linux, macOS, Windows","未说明",{"notes":106,"python":104,"dependencies":107},"该工具是基于 Node.js 的服务器，用于连接 Home Assistant 和大语言模型（LLM），本身不运行 AI 模型，因此无 GPU 需求。必须拥有正在运行的 Home Assistant 实例、长期访问令牌，若需使用插件管理功能还需安装 HACS 和 Supervisor 权限。支持通过 Docker Compose 或直接使用 Node.js 部署。",[108,109,110,111],"Node.js >= 20.10.0","NPM >= 7.0.0","Docker Compose >= 1.27.0","TypeScript ^5.0.0",[13,113],"插件","2026-03-27T02:49:30.150509","2026-04-07T02:08:45.902260",[117,122],{"id":118,"question_zh":119,"answer_zh":120,"source_url":121},20658,"该项目与 jango-blockchained\u002Fadvanced-homeassistant-mcp 仓库有什么关系？为什么安装说明指向另一个仓库？","这是一个文档错误。维护者承认在合并 PR 时未仔细检查 README，导致安装说明错误地指向了另一个仓库（jango-blockchained\u002Fadvanced-homeassistant-mcp）及其 docker-compose 配置。该问题已被修正，请以当前仓库的最新 README 说明为准。","https:\u002F\u002Fgithub.com\u002Ftevonsb\u002Fhomeassistant-mcp\u002Fissues\u002F22",{"id":123,"question_zh":124,"answer_zh":125,"source_url":126},20659,"在使用 Home Assistant Add-on 部署时遇到 Token 不匹配或 401 认证错误怎么办？","如果您在尝试将其作为 Home Assistant Add-on 部署时遇到 Token 验证失败（返回 401 错误），建议直接使用 Home Assistant 原生的 MCP Server 集成。您可以使用 Anthropic 的 MCP Inspector 连接到 Home Assistant 新的原生 MCP Server（https:\u002F\u002Fwww.home-assistant.io\u002Fintegrations\u002Fmcp_server\u002F）并代理连接，这通常能解决自定义 Add-on 中的 Token 读取和传递问题。","https:\u002F\u002Fgithub.com\u002Ftevonsb\u002Fhomeassistant-mcp\u002Fissues\u002F10",[]]