nickol-knx

nickol-knx-mcp

一款设计阶段的 KNX / ETS6 助手，以 MCP 服务的形式提供。

你可以用它完成四件事——全程无需接触运行中的 KNX 总线：

1. 根据规格设计项目 — 将设备清单／项目规格转化为完整且经过验证的组地址结构，以及全套实施文档（可导入 ETS 的 XML/CSV、人类可读的报告、Home Assistant YAML、验收测试方案、竣工交付资料包）。
2. 审计、修复并完善现有项目 — 验证命名 · DPT 和子 DPT · 命令↔状态 · KNX Secure · Matter 就绪情况，获取具体的修复建议（推断 DPT、合成状态 GA）、评定完整性，并比较两个项目版本的差异。
3. 生成智能家居层 — 组装 Home Assistant 实体（彩色灯、温控、遮阳设备、传感器），读取真实设备状态，并将所有含糊之处留待人工审核。
4. 使用参数化房间模板组合新项目 — 根据房间清单（每个槽位可选 basic／comfort 预设）组装一个全新且经过验证的项目 → 分配清单 + ETS GA XML/CSV + 设备 BOM 建议。仅支持试运行和新项目（R1）。

其底层是一个设备库，可将每个执行器扩展为其真实通信对象——从通用配方到直接从 ETS 应用程序中解析出的精确厂商对象模型。

🇷🇺 俄语版本： README.ru.md

---

🎬 探索在线交互式演示和仪表板 →

新增 — 一套完整的演示住宅。 examples/demo-home 提供一个合成的 239-GA / 47-Function 项目、该工具生成的报告 + Home Assistant 配置 + ETS 导出文件，以及一套完整的智能家居**“大脑”——昼夜节律照明、8 因子温控设定值、存在／季节／时间状态机和统计数据——驱动一个5 视图仪表板**。欢迎访问 在线网站 ↗ 查看全部内容。

---

🖥️ 仪表盘 — 在 Home Assistant 中实时运行

来自运行演示住宅的 Home Assistant 的真实截图。它们展示了该工具组装的实体如何运行：RGBW / RGB / CCT 彩色灯、六个地暖气候区域（目标值、模式和阀门百分比）、一条昼夜节律照明曲线，以及一个计算得出的气候设定值——并非手动设置。

气候	照明
能源与统计	人员存在情况

▶ 在实时网站上交互式探索 → · 配置位于 examples/demo-home/ha-brain

---

🧪 状态与测试者招募

这是一个公开测试版。完整流程已通过合成项目的端到端冒烟测试，并已针对真实的数千 GA ETS5/ETS6 项目（已匿名化）进行验证——但真实 ETS 项目千差万别、情况复杂，更多实测反馈能让它变得更好。

👉 如果你有 ETS5/ETS6 项目，请试用并告诉我们结果。 请提交一个真实项目测试报告。该工具为只读工具，不会连接总线，因此测试安全（请参阅安全模型）。详情请参阅 CONTRIBUTING.md。

💬 加入讨论 →——打声招呼、提出任何问题，或分享该工具在你的项目中发现了什么。

---

🗺️ 路线图——由实际集成商共同塑造

来自一线 KNX 集成商的近期评审（见 讨论）正在指引后续开发方向：

• 跨设备参数一致性 （已发布——check_device_parameters）——标记出 N 个相同设备中 ETS 参数设置不同的那个设备：例如设定点／回差不同的温控器，或检测时间不同的存在传感器。直接从 .knxproj 中提取每台设备的参数，并在实际的 42–275 台设备项目中找出异类——只读，无需 ETS，也无需总线；对于干净的项目会正确报告无异常（不会因厂商或集成商流派不同而误报）。
• 项目策略配置文件 （已发布——check_policy）——根据你们自己约定的规则（命名、GA 分类体系、命令／状态豁免规则）验证项目，而非遵循一套通用的“专业标准”，因为不同集成商的惯例各不相同；如果没有配置文件，则根据项目自身推断出的分类体系进行验证。
• 房间模板库——通过参数化房间模板构建新项目。R1 已发布（compose_rooms + validate_room_template：新项目、试运行、分配清单 + ETS XML/CSV + 设备物料清单）。R2 计划中：整合到现有项目中 + 精确选择设备。
• Logic Machine 支持 （即将推出——正在调研）——将相同的只读、设计时模型引入 Logic Machine（Embedded Systems）安装环境：解析基于 LM 的 KNX 项目，执行相同的命名／DPT／状态／拓扑审计，并生成相同的交接输出，让 LM 集成商也能获得与原始 .knxproj 项目相同的证据化项目模型。目前正针对一台真实的 Logic Machine 5 设备进行范围评估。
• 对于 ETS 内的组地址链接，我们刻意不重复造轮子：目前 ETS App-Store 中已有用于在 ETS 内将 GA 链接到通信对象的插件，ETS7 也即将推出原生 Smart Linking——我们会引导你使用这些工具，并专注于只读审计和证据化项目模型。

有项目可供测试、遇到问题的工作流，或想参与塑造某项功能？→ 讨论。

---

为何开发此工具

截至 2026 年年中，还没有可直接使用的 ETS6 ↔ Claude / MCP 工具。KNX 社区一直在明确寻求一种集成方案，可通过 AI／命令行工作流检查并协助修改项目（添加／重命名设备和组地址）。本软件包恰好填补了设计时这一缺失环节。

推荐的完整方案分为四层；只有一层需要从头构建：

层级	用途	使用方案	是否需要构建？
1. 实时	状态、控制、调试正在运行的住宅	官方 Home Assistant MCP Server + KNX（XKNX）集成	否，已有
2. 设计时	解析 .knxproj，验证 DPT／命名／状态 + 降噪 GA 意图，生成 HA YAML（组装彩色灯光 + 气候控制）及 ETS XML/CSV	nickol-knx-mcp（本软件包）	是——这正是缺失的一环
3. 文件 + Git	YAML/CSV/XML、对地址架构进行版本管理	标准文件系统 + git MCP 服务	否，已有
4. 操作手册（可选）	AI 客户端读取的书面设计规则（GA 结构、命名、DPT、场景）+ HA 备份例程	普通文件：CLAUDE.md + skills/ha-git-backup。MCP 服务不会提供这些文件，而且不依赖它们也能工作	否，已包含

安全性是设计的一部分： 第 2 层（此服务）在物理上无法连接总线。它完全不依赖网络／总线——只会读取 .knxproj，并将文件写入受限工作区。“绝不写入运行中的总线”这一要求是通过架构强制保证的，而非口头承诺。任何与住宅的实际交互都只能通过第 1 层（Home Assistant）进行。

---

你可以用它做什么

📐 场景 1 — 根据规格设计项目（规格 → 实施套件）

将项目规格（设备表、电缆记录、设备清单）转化为完整且经过验证的组地址结构，并生成实施所需的完整文档集：

1. 设备清单 → 对象模型。 通过设备库（decompose_device），将每台设备展开为其实际通信对象：调光器通道包含开/关 + 状态 + 相对调光（3.007）+ 绝对值（5.001）+ 亮度状态，而不是“一个 GA”；地暖分区包含 8 个对象；脉冲表包含 6 个对象。
2. 专业逻辑层。 基础规格从不会列出让项目完整所需的内容：中央与分区宏、场景、存在检测逻辑、气候控制框架、日照/风力百叶窗逻辑、泄漏→关闭链路、天文/气象与日期时间源，以及每个范围内的预留地址。该方法论编码了这些完整性模式，内容提炼自 KNX Association 标准、制造商公开文档，以及对真实专业竣工 ETS 项目（已匿名化）的研究。
3. 结构与规范。 3 级寻址、按区域+功能命名、命令↔状态配对、每个地址都指定 DPT。
4. 交付物（每项各需一条命令）：可导入 ETS 的 XML/CSV · Markdown 报告 · Home Assistant YAML · 功能性 验收测试协议 · 竣工 移交包（设备清单、GA 映射、覆盖率、Secure 安全状况、QA 发现、拓扑 SVG）。

完整方法论：docs/spec-to-structure.md。我们仅凭一份 42 页规格重建了一个真实的 14 房间竣工 ETS 项目，并进行了实地验证：96 % 的结构匹配度（662 对 687 个 GA），10 / 10 个领域分类，在零验证错误的情况下完成——完整报告见**案例研究**。剩余差异来自集成商对每台设备的参数配置，这些信息不会编码在任何规格中。

🔍 场景 2 — 审计、修复并完善现有项目

• 读取并分类。 通过 xknxproject 解析受密码保护的 ETS5/ETS6 .knxproj；根据 DPT 和多语言（EN/DE/RU）名称关键词，按类别（lighting / shutter / hvac / sensor / scene / energy / diagnostics）和类型（command / status / sensor）对每个 GA 进行分类。GA 用途标记（functional / reserve / logic / scratch）可将有意设置的占位项排除在错误列表之外，避免报告误报（在一个真实的 685-GA 项目中，误报从 29 个降至 6 个）。
• 验证（analyze_all 会运行所有检查）：命名与结构 · 缺少状态对象（优先使用 ETS-Function 角色，其次使用名称词元配对、位置配对——名称一一对应的并行状态中间地址，以及自报告型 R+T 对象）· 缺失/不一致的 DPT 及子 DPT 合理性检查（承载 5.001 的“温度”GA 会被标记）· 仅有相对调光的调光器 · KNX Secure 安全状况（安全保护与明文传输、混合组、密钥环检查清单——绝不会读取密钥材料）· Matter 就绪情况 · 能源领域覆盖情况。
• 修复，而不只是标记（suggest_repairs）：根据名称推断 DPT、纠正可疑的子 DPT、在空闲地址槽中合成缺失的状态 GA、添加绝对亮度 GA。这些都只是建议——由人工审核，获采纳的 GA 会用于 ETS 导出。在一个真实的 3,646-GA 项目中，系统提出了145 条具体建议（32 条 DPT 推断、112 个合成的状态 GA）。
• 完成全部工作：grade_completeness（从基础骨架到竣工评分）、suggest_names、diff_projects（对两个 .knxproj 修订版进行语义差异比较：新增 / 移除 / DPT 变更 / 重命名 / 安全状态变更），然后重新生成报告、移交包和测试协议。

🏠 场景 3 — 生成智能家居层（Home Assistant）

• 保守地组装实体：cover → 彩色／可调光灯（开／关 + 亮度 + RGBW／RGB／色温 + 状态）→ 开关 → climate（当前温度、目标温度状态、运行／控制器模式、阀门值）→ 传感器／二进制传感器。只要设备能够上报，每个实体都会设置 state_address — HA 读取的是真实状态，绝不自行假定。
• 优先审核：任何有歧义的内容（DPT 5.001 — 亮度还是百叶窗位置？）都不会靠猜测决定，而是会附带说明列入 review 清单（包括依赖执行器的 cover 标记，如 invert_position／行程时间；这些信息不会编码在任何 .knxproj 中）。
• 附加功能：用于日期／时间广播（DPT 19.001）的 expose 块、Matter 就绪度 lint、KNX IoT（Turtle／RDF）语义导出。
• 房屋的实时控制仍由 Home Assistant 官方集成（第 1 层）负责 — 此服务只准备其配置。
• 运维配套工具：skills/ha-git-backup — 配置部署之后的管理方式：为 /config 保留真实的 git 历史记录（部署密钥 + pre-commit 密钥扫描器），并在 GitHub Releases 中保存加密的异地备份，每月进行一次恢复演练。

🧱 场景 4 — 使用房间模板组合新项目

• 从房间出发，而非从空白开始：从六种内置的可参数化房间模板（卧室、儿童房、客厅、厨房、浴室、走廊）中选择，为每个插槽选择 basic／comfort 预设（一个房屋可以混用舒适型气候控制和基础照明），再由 compose_rooms 组装一个新项目。
• 输出内容：分配 manifest（主组 = 域，中组 = 角色，子组顺序递增）、可导入 ETS 的 GA XML/CSV（通过现有生成器生成），以及设备库提供的设备 BOM建议。
• 由真实读取器验证：生成的 .knxproj 会通过标准 load_project 重新读取 — 与读取第三方项目所用的路径相同 — 并通过全部四项 lint（命名／缺少状态／DPT／策略），达到 0 个错误／0 条警告。
• 默认进行试运行，且仅支持新项目。 模板格式是一项公开契约（room_templates/SCHEMA.md）：标识使用与区域设置无关的 slot_id，绝不使用人类可读的名称。
• _{R2：接入现有项目 + 精确选择设备 — 计划中。}

🧩 基础 — 不断扩展的设备库

• parse_devices_from_project 会从任何 .knxproj／.knxprod 内的制造商应用程序中提取精确的厂商对象型号 — 包括 HDL／Ekinex 等厂商以引用级（ComObjectRef）方式发布的对象：对象编号、名称、大小、DPT、C/R/W/T/U 标志、每通道块步长 — 提取过程可确定且保护 PII（仅使用厂商目录数据；绝不读取文件中的客户端项目部分）。
• 将 NICKOL_KNX_CATALOG 指向你的目录，decompose_device 就会返回精确型号（catalog-exact），而非通用方案 — 目录会根据你提供的项目和产品数据库按需扩展。
• 对于厂商提供时未声明 DPT 的对象，会如实标记为 unverified — 绝不猜测。

所有写入操作仅限工作区目录（NICKOL_KNX_WORKSPACE，默认值为 ./knx-workspace）； 写入该目录之外的操作会被拒绝。

---

安装

需要 Python 3.10+。

git clone https://github.com/NickoScope/nickol-knx-mcp.git
cd nickol-knx-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

依赖项：mcp>=1.10、xknxproject>=3.8、PyYAML>=6.0。

在 Debian／Ubuntu 上，如果 pip 提示环境由外部管理，请使用 venv（如上所示）， 或运行 pip install -e . --break-system-packages。如果 PyJWT 发生冲突，请先运行 pip install mcp --ignore-installed PyJWT。

验证：

python tests/test_pipeline.py     # synthetic 16-GA project, end-to-end smoke test
nickol-knx-mcp                    # start the MCP server (stdio)

---

连接到 Claude

Claude Desktop

examples/claude_desktop_config.json 会配置 nickol-knx + filesystem + git + home-assistant。 最小配置片段（macOS 配置路径：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "nickol-knx": {
      "command": "nickol-knx-mcp",
      "env": { "NICKOL_KNX_WORKSPACE": "/path/to/your/knx-workspace" }
    }
  }
}

Claude Code

claude mcp add nickol-knx \
  -e NICKOL_KNX_WORKSPACE="$HOME/knx-workspace" \
  -- /absolute/path/to/.venv/bin/nickol-knx-mcp

也可以选择将 CLAUDE.md 放入项目根目录。这是一份纯文本操作手册，AI 客户端会读取其中的内容（设计规则、安全规则、3 级 GA 结构、命令/状态配对、DPT 规范、命名、KNX Secure 密钥环处理以及推荐工作流）。服务无需此文件：解析、检查和生成都以代码形式在 MCP 服务内运行。

---

MCP 工具（32）

读取

工具	用途
load_project(path, password?, language?)	解析 .knxproj（只读）并缓存
load_ga_export(path)	将 ETS 组地址导出文件（ga-export/01 XML，例如来自 ETS 或 TapPlan）作为无设备的项目加载
list_group_addresses(category?, kind?)	列出带有分类和筛选条件的 GA
get_devices()	设备及其通信对象
get_topology()	拓扑（区域/线路/设备）
explain_ga(address)	一个 GA 的来源依据：说明其分类原因——每项判断的证据及置信度等级（权威 ETS Function > 结构性 DPT > 启发式名称）、其状态如何配对，以及冲突（名称显示“AC”，DPT 表示照明 → contested）

验证

工具	用途
check_naming(name_regex?)	验证命名/3 级结构
check_missing_status()	检查缺少状态对象的执行器
check_dpt()	检查缺失/不一致的 DPT 以及子 DPT 合理性（温度→9.001，功率→14.056……）
check_topology()	检查拓扑容量和个体地址有效性（TP1 每段 64 个、每条线路 256 个；A.L.D 有效且唯一；存在耦合器——KNX Handbook）
check_secure()	检查 KNX Data Secure 安全状况及密钥环交接清单
check_matter()	Matter 就绪情况检查（可与 Matter 集群双向转换的功能）
check_energy()	检查计量/能源 DPT 以及 PV/电池/EVSE 脚手架
analyze_all(name_regex?)	一次运行所有检查
check_policy(profile_path?, write_example_to?)	根据项目策略配置文件（主组分类、命名、配对）验证；如果未提供配置文件，则根据从项目本身推断的分类验证；标记偏离你自己的约定的 GA，而非通用标准。write_example_to 会写入一个示例配置文件，以已加载项目自身的主组为种子（项目中不存在的主组不会列出）

修复与设计

工具	用途
suggest_repairs()	提出修复建议，而不只是标记问题——推断 DPT、合成状态/亮度 GA
suggest_names()	提供命名规范建议
decompose_device(order_number, channels?)	设备 → GA 分解：从本地目录（NICKOL_KNX_CATALOG）获取精确厂商型号，或使用通用方案
list_device_recipes()	内置设备库（Zennio + ABB 系列）
parse_devices_from_project(path, output_path?, password?)	从 .knxproj/.knxprod 内的应用程序中提取精确的设备对象型号 → 设备库 YAML（用于填充本地目录）
check_device_parameters(path, password?, min_group?)	跨设备参数 QA：找出 ETS 参数与其他 N 个相同同类设备不同的设备（与众不同的恒温器/传感器）——clear_outliers（很可能是错误）+ split_configs（平衡的变体，需审核）
grade_completeness()	为项目评级：从基础骨架到竣工项目
diff_projects(path_a, path_b, …)	对比两个 .knxproj 版本的语义差异
生成
工具	用途
------	---------
generate_ha_package(output_path?)	HA KNX YAML（颜色 + 气候 + 暴露）+ 审核列表
generate_ets_group_addresses(fmt="xml"|"csv", output_path?)	可导入 ETS 的组地址
generate_handover_pack(output_dir?)	竣工交接包：清单、组地址映射、覆盖情况、安全、QA、topology.svg
generate_test_protocol(output_path?)	功能验收协议（命令 → 预期状态）
generate_knx_iot(output_path?)	KNX IoT 语义导出（Turtle/RDF）
project_report(output_path?, name_regex?)	Markdown 报告
workspace_info()	工作区路径 + 安全保障

房间库（R1 — 使用房间模板组合新项目）

工具	用途
validate_room_template(template?, path?)	根据 R1 架构验证房间模板（内置 slot_id 或自定义 YAML）
compose_rooms(rooms, language="ru", project_name?, output_dir?, dry_run=true)	根据房间列表构建新项目 → 分配 manifest、ETS 组地址 XML/CSV、设备 bom 方案；生成的 .knxproj 会由标准加载器重新读取并进行 lint 检查（0 个错误 / 0 个警告）。仅限新项目，默认进行试运行。

---

典型工作流

1. load_project → 指定 .knxproj（如果受密码保护，还需提供密码）。
2. analyze_all 或 project_report → 查看分析结果；先由人工审核。
3. 在 ETS 中修正名称/DPT/状态（通过导入生成的组地址或手动修正）。
4. generate_ets_group_addresses(fmt="xml") → 将缺失的组地址导入 ETS。
5. generate_ha_package → 将 YAML 放入 Home Assistant；手动处理 review 项。
6. 将所有内容（.knxproj 导出文件、HA 配置、地址架构）保存在 Git 中。
7. 仅通过 Home Assistant MCP 操作真实住宅（第 1 层）。

---

限制（如实说明）

• 命令/状态和类别分类属于启发式判断（基于 DPT、名称和 ETS Functions）。对于没有 Functions 且名称不规范的混乱项目，可能出现误报或漏报——因此报告始终供人工审核，存在歧义的内容会放入 review，而不会写入配置。
• DPT 5.001 在结构上存在歧义（亮度或位置）；系统会根据关键词消除歧义——名称不规范时请仔细检查。
• HA 生成器较为保守：宁可将项目交由 review，也不会生成错误实体。
• 服务不会写入总线，也不会直接与 ETS 通信——与 ETS 的数据交换仅通过组地址文件导入/导出完成。
• 已在合成演示项目和真实的数千组地址 ETS5/ETS6 项目上验证 （已匿名化）——但真实 .knxproj 文件差异很大，且该项目仍处于测试阶段。因此请参阅 测试人员招募。

---

🔒 安全模型

• 从结构上杜绝总线访问。 依赖树中没有网络或总线库。 workspace_info() 会报告 bus_access: false。
• 对项目只读。 project.py 是唯一会访问 .knxproj 的模块，且仅进行读取。
• 写入受限。 所有输出均限制在 NICKOL_KNX_WORKSPACE 内；超出范围的路径会被拒绝。
• 防范恶意项目文件。 .knxproj 是不可信的 ZIP/XML 文件，因此解析会通过 safexml.py 执行：拒绝 DTD/实体 XML（防范 Billion Laughs / XXE），并在处理归档前检查大小、条目数和解压缩比上限，同时拒绝包含路径遍历名称的文件（防范 ZIP 炸弹）。
• 人在回路。 生成 project_report，并在导入 ETS 或部署到 Home Assistant 之前进行审核。

发现安全问题？请参阅 SECURITY.md。

---

软件包布局

nickol-knx-mcp/
├── nickol_knx_mcp/
│   ├── dpt_map.py        # DPT → category / kind / HA platform / value_type
│   ├── project.py        # the ONLY module that reads .knxproj (read-only)
│   ├── safexml.py        # hardened ZIP/XML parsing of untrusted .knxproj (zip-bomb / XXE defense)
│   ├── pairing.py        # command↔status pairing by name tokens
│   ├── analyze.py        # naming / missing-status / DPT checks
│   ├── generate_ha.py    # Home Assistant KNX YAML generation
│   ├── generate_ets.py   # ETS XML + CSV generation
│   ├── report.py         # Markdown report
│   ├── room_library.py   # Room Library R1 — compose a new project from templates
│   ├── room_templates/   # built-in room YAML templates + SCHEMA.md (public contract)
│   └── server.py         # FastMCP server, 32 tools, confined writes
├── tests/test_pipeline.py
├── examples/claude_desktop_config.json
├── skills/
│   └── ha-git-backup/    # optional ops skill for your AI client: HA backup (git history + encrypted offsite)
├── CLAUDE.md             # optional playbook for your AI client (not part of the server)
├── pyproject.toml
└── README.md

---

贡献

欢迎测试人员和贡献者，尤其欢迎提交真实项目测试报告。请参阅 CONTRIBUTING.md 和 问题模板。

许可证

MIT © 2026 Nikolay Miroshnichenko

与 KNX Association 无关联，也未获得其认可。“KNX”和“ETS”是 KNX Association cc 的商标。这是一款独立的社区工具。