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

Related MCP server: mcp-codebase-oracle

🧪 状态与测试者招募

这是一个公开 beta。完整流程在一个合成项目上通过了端到端冒烟测试，并已针对真实的数千个 GA 的 ETS5/ETS6 项目（已匿名化）进行验证 — 但真实的 ETS 项目总是千奇百怪、五花八门，更多的实测报告会让它变得更好。

👉 如果你有 ETS5/ETS6 项目，请试用它并告诉我们结果。 打开一个 真实项目测试报告 issue。该工具是只读的，从不连接总线，因此测试是安全的（参见 安全模型）。更多细节见 CONTRIBUTING.md。

💬 加入讨论 → — 说声你好、随便提问，或分享这个工具在你的项目上发现了什么。

🗺️ 路线图 — 由真实集成商塑造

来自从业 KNX 集成商的近期评论（见 讨论区）正在指引接下来的方向：

• 跨设备参数一致性 (已发布 — check_device_parameters) — 标记出 ETS 参数设置与其 N 台完全相同的同类设备不同的那一台设备：一台设定点/迟滞不同的恒温器，一台检测时间不同的存在检测器。直接从 .knxproj 提取每台设备的参数，并在真实的 42–275 台设备项目上找出异常者 — 只读、无需 ETS、无需总线 — 并且在干净的项目上正确报告无异常（在不同厂商 / 集成商风格之间无误报）。

• 项目策略配置文件 (已发布 — check_policy) — 根据你们自己约定的规则（命名、GA 分类体系、命令/状态豁免）来校验项目，而不是某个放之四海而皆准的“专业标准”，因为各家集成商的惯例各不相同；在没有配置文件时，则根据项目本身推断出的分类体系进行校验。

• 房间模板库 — 从参数化的房间模板组合一个新的项目。R1 已发布（compose_rooms + validate_room_template：仅新项目、干跑、分配清单 + ETS XML/CSV + 设备 BOM）。R2 计划中：接入现有项目 + 精确设备选型。

• Logic Machine 支持 (即将推出 — 研究中) — 将同样的只读、设计期模型带给 Logic Machine（Embedded Systems）安装：解析基于 LM 的 KNX 项目，运行相同的命名 / DPT / 状态 / 拓扑审计，并生成相同的移交输出，让 LM 集成商获得与从原始 .knxproj 获得的相同的可验证项目模型。目前正在针对一台真实的 Logic Machine 5 设备进行范围界定。

• 关于 ETS 内的组地址连接，我们刻意不重复造轮子：要在 ETS 内把 GA 连接到通信对象，如今已经有 ETS App-Store 插件可用，原生的 Smart Linking 也将在 ETS7 中推出 — 我们会为你指明方向，同时继续专注于只读审计和可验证的项目模型。

有想测试的项目、跑不通的流程，或想一起塑造的功能？→ 讨论区。

为什么会有这个项目

截至 2026 年年中，还没有现成的 ETS6 ↔ Claude / MCP 工具。KNX 社区一直在明确要求这样一个集成：能够通过 AI/CLI 工作流检查并帮助修改项目（添加 / 重命名设备和组地址）。这个包恰恰填补了设计期这一层 — 缺失的那一层。

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

1. 设备列表 → 对象模型。每个设备通过设备库（decompose_device）展开为其真实的通信对象：一个调光通道包含开/关 + 状态 + 相对调光（3.007）+ 绝对值（5.001）+ 亮度状态——而非"一个GA"；一个地暖区域包含8个对象；一个脉冲表包含6个。

2. 专业逻辑层。一份裸规格说明永远不会提及构成一个完整项目的要素：中央及区域宏、场景、存在逻辑、气候控制框架、太阳/风百叶逻辑、泄漏→关断链、天文/气象及日期时间源、各范围内的预留地址。该方法论编码了这些完整性模式——提炼自KNX协会标准、公开的制造商文档以及对真实专业竣工ETS项目（已匿名化）的研究。

3. 结构与规范。3级寻址、区域+功能命名、命令↔状态配对、每个地址一个DPT。

4. 交付物（各一条命令）：可导入ETS的XML/CSV · Markdown报告 · Home Assistant YAML · 功能验收测试协议 · 竣工移交包（清单、GA映射图、覆盖率%、Secure状态、QA发现、拓扑SVG）。

完整方法论：docs/spec-to-structure.md。已通过仅凭规格说明重建一个真实竣工ETS项目（3,600+个组地址）进行现场验证：约92%的结构匹配度（分类法、域、自动化逻辑、DPT分布），零验证错误——剩余差异是集成商的每设备参数化设置，这是任何规格说明都无法编码的。

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

• 读取与分类。通过xknxproject解析受密码保护的ETS5/ETS6 .knxproj；根据DPT及多语言（EN/DE/RU）名称关键词，将每个GA按类别（照明/百叶/HVAC/传感器/场景/能源/诊断）和种类（命令/状态/传感器）进行分类。GA用途标记（functional/reserve/logic/scratch）将有意保留的占位符排除在错误列表之外，使报告不会虚报（在一个真实的685-GA项目中：误报从29降至6）。

• 验证（analyze_all运行所有内容）：命名与结构 · 缺失状态对象（先ETS-Function角色，再名称标记配对，位置配对——名称1:1对应的并行状态中间件，以及自报R+T对象） · 缺失/不一致的DPT + 子DPT合理性检查（携带5.001的"温度"GA会被标记） · 仅相对调光 · KNX Secure状态（已加密vs明文、混合组、密钥环检查清单——密钥材料从不读取） · 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）

• 保守组装实体：遮阳帘 → 彩色/可调光灯（开/关 + 亮度 + RGBW/RGB/色温 + 状态）→ 开关 → 气候（当前温度、目标温度状态、运行/控制器模式、阀门值）→ 传感器/二进制传感器。每个实体在设备可报告的地方都获得一个state_address——HA读取真实状态，从不假设。

• 先审查：任何模棱两可的内容（DPT 5.001——亮度还是百叶位置？）不会被猜测——它会进入一个review列表并附上解释（包括执行器相关的遮阳帘标志，如invert_position/行程时间，这些是任何.knxproj都无法编码的）。

• 额外功能：用于日期/时间广播（DPT 19.001）的expose块、Matter就绪性检查、KNX IoT（Turtle/RDF）语义导出。

• 对房屋的实时控制保留在官方的Home Assistant集成（第1层）中——此服务器仅准备其配置。

• 运维伴侣：skills/ha-git-backup——部署之后配置的生命周期：/config的真实git历史（部署密钥 + 预提交秘密扫描器）加上GitHub Releases中的加密异地备份，每月进行一次恢复演练。

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

• 从房间开始，而非空白页：从六个内置的参数化房间模板（卧室、儿童房、客厅、厨房、浴室、走廊）中选择，为每个槽位选择basic/comfort预设（一个房子可以混合舒适气候与基础照明），然后compose_rooms组装一个新项目。

• 输出：一个分配manifest（主=域，中=角色，子=顺序），通过现有生成器生成可导入ETS的GA XML/CSV，以及来自设备库的设备BOM建议。

• 通过真实读取器验证：生成的.knxproj通过标准的load_project重新读取——与用于第三方项目的相同路径——并通过所有四个检查器（命名/缺失状态/DPT/策略），0错误/0警告。

• 默认试运行，仅限新项目。 模板格式是一个公共契约（room_templates/SCHEMA.md）：标识是区域中立的slot_id，绝不是人类名称。

• R2：接入现有项目 + 精确设备选择——计划中。

🧩 基础——不断增长的设备库

• parse_devices_from_project从任何.knxproj/.knxprod内的制造商应用程序程序中提取精确的供应商对象模型——包括引用级（ComObjectRef）发布者（如HDL/Ekinex）：对象编号、名称、大小、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放入您的项目根目录——它充当ETS助手技能（设计规则、安全规则、3级GA结构、命令/状态配对、DPT规范、命名、KNX Secure密钥环处理以及推荐工作流程）。

MCP工具（31个）

读取

验证

修复与设计

生成

房间库 (R1 — 从房间模板构建新项目)

典型工作流程

1. load_project → 指向你的.knxproj文件（如受保护需提供密码）。

2. analyze_all或project_report → 查看检查结果；首选人工审核。

3. 在ETS中修复命名/DPT/状态（通过导入生成的GA或手动操作）。

4. generate_ets_group_addresses(fmt="xml") → 将缺失的GA导入ETS。

5. generate_ha_package → 将YAML文件放入Home Assistant；手动处理review项。

6. 将所有内容（.knxproj导出、HA配置、地址架构）纳入Git管理。

7. 仅通过Home Assistant MCP（第1层）接触实际运行的设备。

局限性（坦诚说明）

• 命令/状态及类别分类基于启发式方法（DPT + 名称 + ETS功能）。对于无功能定义且命名不规范的项目，可能出现误报/漏报——因此报告始终需要人工审核，且不确定项会归入review而非配置。

• DPT 5.001在结构上具有歧义性（亮度 vs 位置）；通过关键词进行消歧——对于非标准命名请仔细核对。

• HA生成器采用保守策略：宁愿将项目推迟至review，也不生成错误的实体。

• 服务器绝不向总线写入数据，也不直接与ETS通信——ETS交互仅限于GA文件的导入/导出。

• 已在合成演示项目和实际数千GA的ETS5/ETS6项目（已匿名处理）上验证——但真实的.knxproj文件差异极大，仍处于测试阶段。因此诚邀测试者。

🔒 安全模型

• 结构上无总线访问。 依赖树中不包含任何网络或总线库。workspace_info()报告bus_access: false。

• 项目文件只读。 project.py是唯一处理.knxproj的模块，且仅执行读取操作。

• 受限写入。 所有输出限制在NICKOL_KNX_WORKSPACE内；拒绝该路径之外的写入请求。

• 抵御恶意项目文件。 .knxproj是不可信的ZIP-XML格式，因此解析通过safexml.py进行：拒绝DTD/实体XML（防止十亿笑/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, 31 tools, confined writes
├── tests/test_pipeline.py
├── examples/claude_desktop_config.json
├── skills/
│   └── ha-git-backup/    # ops companion: 2-circuit HA backup (git history + encrypted offsite)
├── CLAUDE.md             # ETS Assistant skill / playbook
├── pyproject.toml
└── README.md

贡献

非常欢迎测试者和贡献者——尤其是真实项目的测试报告。请参见CONTRIBUTING.md和问题模板。

许可证

MIT © 2026 尼古拉·米罗什尼琴科

与KNX协会无关联且未经其认可。"KNX"和"ETS"是KNX协会的商标。这是一个独立的社区工具。