HA开发工具MCP服务器

模型上下文协议（MCP）服务器，为家庭助理提供全面的开发工具。此服务器通过MCP协议实现文件管理、模板测试、实体/状态管理、服务调用、日志访问和系统信息检索。

特性

文件管理

配置文件发现：自动发现HA实例中的所有配置文件
读/写操作：通过验证读取和修改配置文件
YAML验证：写入更改前的语法和结构验证
自动备份：在修改配置文件之前创建备份
文件元数据：获取文件大小、修改时间和其他元数据
内容分页：通过高效的分页支持处理大文件
本地文件保存：将大文件保存到本地临时目录，以避免上下文窗口溢出

模板测试

模板渲染：使用真实的Home Assistant上下文测试Jinja2模板
模板验证：验证模板语法和实体引用
实体验证：验证模板中引用的实体是否存在
多行模板支持：正确处理复杂的多行模板

实体和国家管理

实体发现：列出Home Assistant实例中的所有实体
状态检索：获取任何实体的当前状态和属性
服务调用：以编程方式执行家庭助理服务

系统信息

日志访问：读取和搜索Home Assistant日志
系统信息：获取家庭助理版本、配置和系统详细信息

多实例支持

多个HA实例：同时管理多个家庭助理实例
上下文隔离：每个实例维护单独的状态和配置
实例切换：在不同的HA实例之间轻松切换

安装

通过pip（推荐）

pip install ha-dev-tools-mcp

通过uvx（适用于Kiro用户）

uvx --from ha-dev-tools-mcp ha-dev-tools-mcp

源自源头

git clone https://github.com/username/ha-dev-tools-mcp.git
cd ha-dev-tools-mcp
pip install -e .

快速开始

运行MCP服务器

# Start the server
ha-dev-tools-mcp

# Or with Python module syntax
python -m ha_dev_tools.server

配置

服务器通过以下方式连接到家庭助理 HA开发工具集成.先安装集成：

通过HACS（推荐）或手动安装
在Home Assistant中配置集成
注意API URL和身份验证令牌
配置MCP服务器以连接到HA实例

与Kiro一起使用

安装 HA发展动力与Kiro无缝集成：

打开Kiro Powers用户界面
搜索“家居助理发展”
安装电源
MCP服务器将自动配置

用法示例

文件管理

from ha_dev_tools import HADevTools

# Initialize client
client = HADevTools(ha_url="http://localhost:8123", token="your_token")

# List configuration files
files = await client.list_config_files()
print(f"Found {len(files)} configuration files")

# Read a configuration file (returns content directly)
content = await client.read_config_file("configuration.yaml")
print(content)

# Read a large file and save locally (recommended for files >50KB)
result = await client.read_config_file("configuration.yaml", save_local=True)
print(f"File saved to: {result['local_path']}")
print(f"File size: {result['file_size']} bytes")
# File is now available at the local path for direct access

# Read with pagination for viewing specific sections
partial = await client.read_config_file(
    "configuration.yaml",
    offset=0,
    length=1000
)
print(f"First 1000 bytes: {partial['content']}")

# Validate YAML before writing
is_valid = await client.validate_yaml(new_content)
if is_valid:
    # Create backup and write changes
    backup_path = await client.create_backup("configuration.yaml")
    await client.write_config_file("configuration.yaml", new_content)

处理大文件

这 save_local 参数旨在处理会溢出AI模型上下文窗口的大型配置文件：

何时使用 save_local=True:

大于50KB的文件
当您需要在本地处理整个文件时
当与大型企业合作时 configuration.yaml 文件

何时使用分页(offset/length):

小于50KB的文件
当您只需要查看特定部分时
用于快速检查文件内容

响应格式为 save_local=True:

{
    "saved": True,
    "local_path": "/tmp/ha-dev-tools/configuration.yaml",  # Unix/Linux/macOS
    # or "C:\\Users\\Username\\AppData\\Local\\Temp\\ha-dev-tools\\configuration.yaml"  # Windows
    "file_size": 125000,
    "remote_path": "configuration.yaml"
}

响应格式为 save_local=False （默认）：

{
    "saved": False,
    "content": "homeassistant:\n  name: Home\n  ...",
    "file_size": 1024,
    "file_path": "configuration.yaml"
}

重要提示：

save_local 以及分页参数(offset, length)相互排斥
文件以保留的目录结构保存到系统临时目录
保存的文件会覆盖以前的版本（最新版本获胜）
最大文件大小可配置（默认10MB，最大100MB）

模板测试

# Render a template with HA context
template = "The temperature is {{ states('sensor.temperature') }}°C"
result = await client.render_template(template)
print(result)

# Validate template syntax
is_valid = await client.validate_template(template)

# Validate entity references
entities = ["sensor.temperature", "sensor.humidity"]
validation = await client.validate_entities(entities)

实体和国家管理

# List all entities
entities = await client.list_entities()

# Get entity state
state = await client.get_entity_state("sensor.temperature")
print(f"Temperature: {state['state']}°C")

# Call a service
await client.call_service("light", "turn_on", {
    "entity_id": "light.living_room",
    "brightness": 255
})

日志访问

# Read recent logs
logs = await client.get_logs(lines=100)

# Search logs for errors
errors = await client.search_logs("ERROR")

MCP工具

服务器公开了以下MCP工具：

文件操作

list_config_files -列出所有配置文件
read_config_file -使用可选的本地保存或分页读取配置文件

- 参数： - instance_id （必填）：家庭助理实例标识符 - file_path （必需）：配置文件的路径 - save_local （可选）：保存到本地临时目录，而不是返回内容（对于大于50KB的大文件） - offset （可选）：部分读取的起始字节偏移量（与save_local互斥） - length （可选）：要读取的字节数（与save_local互斥）

write_config_file -写入配置文件
create_backup -创建文件的备份
get_file_metadata -获取文件元数据（大小、mtime等）

模板操作

render_template -渲染Jinja2模板
validate_template -验证模板语法
validate_entities -验证实体引用

实体运营

list_entities -列出所有实体
get_entity_state -获取实体状态和属性
call_service -执行家庭助理服务

系统操作

get_logs -读取家庭助理日志
get_system_info -获取系统信息

建筑

┌─────────────────────────────────────────────────────────────┐
│                      MCP Client (Kiro)                       │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                   HA Dev Tools MCP Server                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ File Manager │  │   Template   │  │    Entity    │      │
│  │              │  │   Validator  │  │   Manager    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Log Manager  │  │   Workflow   │  │   Conflict   │      │
│  │              │  │     State    │  │  Resolution  │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP API
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                  HA Dev Tools Integration                    │
│                    (Home Assistant)                          │
└─────────────────────────────────────────────────────────────┘

发展

先决条件

Python 3.12或更高版本
家庭助理2024.1.0或更高版本
已安装HA开发工具集成

设置开发环境

# Clone the repository
git clone https://github.com/username/ha-dev-tools-mcp.git
cd ha-dev-tools-mcp

# Create virtual environment
python3.12 -m venv .venv
source .venv/bin/activate

# Install development dependencies
pip install -e ".[dev]"

运行测试

# Run all tests
pytest tests/ -v

# Run unit tests only
pytest tests/test_*.py -v

# Run property-based tests
pytest tests/test_*_properties.py -v

# Run integration tests
pytest tests/integration/ -v

# Run with coverage
pytest tests/ --cov=ha_dev_tools --cov-report=html

代码质量

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/

基于属性的测试

本项目使用基于属性的测试和假设来验证正确性属性：

文件操作属性

保存：读取文件会返回其完整内容
备份完整性：备份保留了精确的原始内容
写一致性：书面内容可以原封不动地读回

模板属性

验证一致性：接受有效模板，拒绝无效模板
实体验证：实体引用已正确验证
呈现决定论：相同的模板+状态=相同的结果

工作流属性

状态转换：工作流状态转换正确
冲突检测：正确检测和解决冲突
幂等性：可以安全地重试操作

看测试/保护_业主.md 了解详细的性能规格。

故障排除

连接问题

问题：无法连接到家庭助理

Error: Connection refused to http://localhost:8123

解决方案:

验证是否安装并配置了HA开发工具集成
检查API URL是否正确
验证身份验证令牌是否有效
确保家庭助理正在运行

模板渲染错误

问题：模板无法呈现

Error: TemplateError: entity 'sensor.unknown' not found

解决方案:

使用验证实体引用 validate_entities 第一
检查实体ID是否正确（区分大小写）
确保实体存在于HA实例中

文件写入失败

问题：无法写入配置文件

Error: Permission denied

解决方案:

检查家庭助理中的文件权限
验证集成是否配置了写访问权限
检查集成设置中的安全列表

大文件处理

问题：读取大文件时超时

Error: Request timeout

解决方案:

使用 save_local=True 对于大于50KB的文件
使用分页 offset 和 length 查看特定部分的参数
增加客户端配置中的超时设置
考虑将大文件拆分为小文件

文件保存问题

问题：无法在本地保存文件

Error: PERMISSION_DENIED - Permission denied writing to temp directory

解决方案:

- Unix/Linux/macOS： /tmp/ha-dev-tools/ - 窗户： %TEMP%\ha-dev-tools\

确保有足够的可用磁盘空间
检查临时目录是否不是只读的

问题：文件太大，无法保存

Error: FILE_TOO_LARGE - File size exceeds limit

解决方案:

默认限制为10MB，最大为100MB
配置 max_file_size 如果需要，在服务器设置中
考虑使用分页来处理特定部分
将大型配置文件拆分为较小的包含文件

问题：互斥参数错误

Error: MUTUALLY_EXCLUSIVE_PARAMETERS - save_local and pagination are mutually exclusive

解决方案:

选择其中之一 save_local=True 或分页(offset/length)，不是两者都有
使用 save_local 用于需要完全处理的大文件（>50KB）
使用分页查看任何文件的特定部分

临时文件位置

保存的文件存储在系统临时目录中：

Unix/Linux/macOS: /tmp/ha-dev-tools/
视窗: %TEMP%\ha-dev-tools\ （通常 C:\Users\Username\AppData\Local\Temp\ha-dev-tools\)

文件被组织为镜像远程目录结构：

/tmp/ha-dev-tools/
├── configuration.yaml
├── automations.yaml
├── scripts.yaml
└── packages/
    ├── lights.yaml
    └── sensors.yaml

操作系统会定期自动清理临时文件。文件在后续保存时会被覆盖（最新版本获胜）。

贡献

欢迎投稿！请参阅贡献.md 作为指导方针。

许可证

MIT许可证-请参阅许可证了解详情。

支持

问题:
讨论:
文档: 全部文件

更新日志

看更改日志.md 查看版本历史和发行说明。

Ha Dev Tools MCP

快速接入

详细介绍

HA开发工具MCP服务器

特性

文件管理

模板测试

实体和国家管理

系统信息

多实例支持

安装

通过pip（推荐）

通过uvx（适用于Kiro用户）

源自源头

快速开始

运行MCP服务器

配置

与Kiro一起使用

用法示例

文件管理

处理大文件

模板测试

实体和国家管理

日志访问

MCP工具

文件操作

模板操作

实体运营

系统操作

建筑

发展

先决条件

设置开发环境

运行测试

代码质量

基于属性的测试

文件操作属性

模板属性

工作流属性

故障排除

连接问题

模板渲染错误

文件写入失败

大文件处理

文件保存问题

临时文件位置

相关项目

贡献

许可证

支持

更新日志

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP