Woow ha MCP chatbot

HA MCP客户端——家庭助理AI聊天机器人

英语 | 繁体中文

______________________________________________________________________

英语

概述

HA MCP客户端是一个定制的家庭助理集成，它添加了一个功能齐全的人工智能聊天机器人，具有深度的智能家居控制功能。它连接到大型语言模型（Anthropic Claude、OpenAI GPT、Ollama或任何与OpenAI兼容的API），并公开 62工具 让AI通过自然对话查询、控制和管理您的家庭助理安装的几乎所有方面。

主要特点

• AI聊天面板 --专用侧边栏面板（“AI聊天“）具有对话历史记录、搜索和多对话管理功能
• 62智能家居工具 --全面覆盖家庭助理服务领域，包括灯光、盖子、气候、锁、风扇、开关、媒体播放器、摄像头、阀门、计时器、计数器等
• CRUD操作 --通过对话创建、读取、更新和删除区域、标签、自动化、脚本、场景、日历事件和待办事项
• 4 AI提供商 --Anthropic Claude、OpenAI、Ollama（本地）和OpenAI兼容API（LM Studio、vLLM等）
• HA辅助集成 --在Home Assistant的内置辅助管道中充当对话代理
• MCP服务器 --通过模型上下文协议（SSE）为外部MCP客户端公开工具
• 持久历史 --对话历史记录存储在本地数据库中，具有可配置的保留期
• 双语用户界面 --英文和繁体中文界面

建筑

┌─────────────────────────────────────────────────┐
│                  Home Assistant                  │
│                                                  │
│  ┌──────────┐  ┌────────────┐  ┌─────────────┐  │
│  │ Chat     │  │ HA Assist  │  │ MCP SSE     │  │
│  │ Panel    │  │ Pipeline   │  │ Server      │  │
│  │ (iframe) │  │            │  │ (external)  │  │
│  └────┬─────┘  └─────┬──────┘  └──────┬──────┘  │
│       │              │                │          │
│       └──────────────┼────────────────┘          │
│                      ▼                           │
│           ┌──────────────────┐                   │
│           │ Conversation     │                   │
│           │ Entity           │                   │
│           └────────┬─────────┘                   │
│                    ▼                             │
│  ┌─────────────────────────────────────────┐     │
│  │ AI Service (Anthropic/OpenAI/Ollama)    │     │
│  │ + Tool Calling Loop (max N iterations)  │     │
│  └─────────────────┬───────────────────────┘     │
│                    ▼                             │
│  ┌─────────────────────────────────────────┐     │
│  │ Tool Registry — 62 Tools                │     │
│  │ helpers.py (implementations)            │     │
│  │ registry.py (schemas + handlers)        │     │
│  └─────────────────────────────────────────┘     │
└─────────────────────────────────────────────────┘

安装

HACS（推荐）

1. 将此存储库添加为HACS中的自定义存储库
2. 搜索“HA MCP客户端”并安装
3. 重新启动家庭助理
4. 首选 设置>设备和服务>添加集成>HA MCP客户端

手册

1. 复制 custom_components/ha_mcp_client 文件夹到您的家庭助理 config/custom_components/ 目录
2. 重新启动家庭助理
3. 首选 设置>设备和服务>添加集成>HA MCP客户端

配置

安装向导将指导您完成4个步骤：

支持的AI模型：

工具（共62个）

Entity & Service (4)

Area & Label Management (8)

Entity Assignment (3)

Automation (6)

Script (5)

Scene (5)

Calendar (4)

Todo (5)

Device Controls (14)

Utilities (8)

用法示例

通过聊天面板：

打开“AI聊天“侧边栏项目并开始用自然语言聊天：

• “把客厅里的灯都关掉”
• “卧室里的温度是多少？”
• “创建一个在日落时打开门廊灯的自动化系统”
• “将牛奶添加到购物清单中”
• “在过去的一个小时里，车库门怎么了？”
• “将卧室窗帘打开50%”

通过HA协助：

在辅助设置中选择“HA MCP客户端”作为对话代理，然后使用辅助对话框或语音命令。

通过MCP协议：

将任何兼容MCP的客户端连接到 http://your-ha:8087/sse 以编程方式使用所有62个工具。

服务

项目结构

custom_components/ha_mcp_client/
├── __init__.py              # Integration setup, services, panel registration
├── config_flow.py           # Multi-step configuration wizard
├── const.py                 # Constants and defaults
├── conversation.py          # Conversation entity + AI tool-calling loop
├── conversation_recorder.py # Persistent conversation history (SQLite)
├── views.py                 # REST API endpoints for chat panel
├── manifest.json            # Integration metadata
├── services.yaml            # Service definitions
├── frontend/                # Chat panel UI (HTML/JS/CSS)
├── translations/            # en.json, zh-Hant.json
├── ai_services/             # AI provider implementations
│   ├── anthropic.py         # Anthropic Claude
│   ├── openai.py            # OpenAI GPT
│   ├── ollama.py            # Ollama (local)
│   └── openai_compatible.py # OpenAI-compatible APIs
└── mcp/
    ├── server.py            # MCP SSE server for external clients
    └── tools/
        ├── registry.py      # 62 tool definitions + handlers
        └── helpers.py       # Tool implementation logic

需求

• 家庭助理2024.1+
• Python 3.11+
• 已配置受支持的AI提供商之一

许可证

MIT许可证

______________________________________________________________________

繁体中文

概览

HA MCP Client是一个Home Assistant自定义整合元件，为你的智慧家庭加入功能完整的AI聊天机器人。它连接大型语言模型（Anthropic Claude、OpenAI GPT、Ollama或任何OpenAI兼容API），并提供 62个工具，让AI透过自然对话查询、控制及管理你的Home Assistant系统。

主要功能

• AI 聊天面板 —专属的侧边栏面板（「AI聊天」），支持对话历史、搜寻与多对话管理
• 62个智慧家庭工具 —完整涵盖Home Assistant服务域，包括灯光、窗帘、空调、门锁、风扇、开关、媒体播放器、摄像机、阀门、定时器、计数器等
• CRUD 操作 —透过对话建立、读取、更新和删除区域、标签、自动化、脚本、情境、日历事件和待办事项
• 4种AI供应商 — Anthropic Claude、OpenAI、Ollama（本地）和 OpenAI 相容 API（LM Studio、vLLM 等）
• HA Assist 整合 —可作为Home Assistant内置Assist管道的对话代理使用
• MCP 伺服器 —透过Model Context Protocol（SSE）开放工具供外部MCP客户端使用
• 持久化历史 —对话历史储存于本地数据库，可设定保留天数
• 双语界面 —英文与繁体中文界面

构架

┌─────────────────────────────────────────────────┐
│                  Home Assistant                  │
│                                                  │
│  ┌──────────┐  ┌────────────┐  ┌─────────────┐  │
│  │ 聊天     │  │ HA Assist  │  │ MCP SSE     │  │
│  │ 面板     │  │ 管道       │  │ 伺服器      │  │
│  │ (iframe) │  │            │  │ (外部存取)  │  │
│  └────┬─────┘  └─────┬──────┘  └──────┬──────┘  │
│       │              │                │          │
│       └──────────────┼────────────────┘          │
│                      ▼                           │
│           ┌──────────────────┐                   │
│           │ 對話實體          │                   │
│           │ Conversation     │                   │
│           └────────┬─────────┘                   │
│                    ▼                             │
│  ┌─────────────────────────────────────────┐     │
│  │ AI 服務 (Anthropic/OpenAI/Ollama)       │     │
│  │ + 工具呼叫迴圈 (最多 N 次迭代)           │     │
│  └─────────────────┬───────────────────────┘     │
│                    ▼                             │
│  ┌─────────────────────────────────────────┐     │
│  │ 工具註冊表 — 62 個工具                    │     │
│  │ helpers.py (實作邏輯)                    │     │
│  │ registry.py (定義 + 處理器)              │     │
│  └─────────────────────────────────────────┘     │
└─────────────────────────────────────────────────┘

安装方式

HACS（建议）

1. 在HACS中新增此储存库为自定义储存库
2. 搜寻“HA MCP Client”并安装
3. 重启Home Assistant
4. 前往 设定>装置与服务>新增整合> HA MCP Client

手动安装

1. 将 custom_components/ha_mcp_client 文件夹复制到Home Assistant的 config/custom_components/ 目录
2. 重启Home Assistant
3. 前往 设定>装置与服务>新增整合> HA MCP Client

设定

设定精灵会引导你完成4个步骤：

支援的 AI 模型：

工具（共62个）

實體與服務 (4)

區域與標籤管理 (8)

實體指派 (3)

自動化 (6)

腳本 (5)

情境 (5)

日曆 (4)

待辦事項 (5)

裝置控制 (14)

工具程式 (8)

使用示例

透过聊天面板：

开启侧边栏的「AI聊天」项目，用自然语言开始对话：

• 「把客厅的灯全部关掉」
• 「卧室现在几度？」
• 「建立一个在日落时开启门廊灯的自动化」
• 「把牛奶加到购物清单」
• 「车库门最近一小时发生了什么？」
• 「把卧室窗帘设到50%开」

透过HA Assist：

在Assist设定中选择「HA MCP Client」作为对话代理，即可使用Assist对话框或语音指令。

透过MCP协定：

将任何MCP兼容客户端连接到 http://your-ha:8087/sse，即可程序化使用全部62个工具。

服务

项目结构

custom_components/ha_mcp_client/
├── __init__.py              # 整合設定、服務、面板註冊
├── config_flow.py           # 多步驟設定精靈
├── const.py                 # 常數與預設值
├── conversation.py          # 對話實體 + AI 工具呼叫迴圈
├── conversation_recorder.py # 持久化對話歷史（SQLite）
├── views.py                 # 聊天面板 REST API 端點
├── manifest.json            # 整合元資料
├── services.yaml            # 服務定義
├── frontend/                # 聊天面板 UI（HTML/JS/CSS）
├── translations/            # en.json, zh-Hant.json
├── ai_services/             # AI 供應商實作
│   ├── anthropic.py         # Anthropic Claude
│   ├── openai.py            # OpenAI GPT
│   ├── ollama.py            # Ollama（本地）
│   └── openai_compatible.py # OpenAI 相容 API
└── mcp/
    ├── server.py            # MCP SSE 伺服器（供外部客戶端使用）
    └── tools/
        ├── registry.py      # 62 個工具定義 + 處理器
        └── helpers.py       # 工具實作邏輯

系统需求

• 家庭助理2024.1+
• Python 3.11+
• 已设定其中一种支持的AI供应商

授权条款

MIT许可证