内容
# nickol-knx-mcp
**一个设计时KNX / ETS6助手，以MCP服务器的形式暴露。**
它读取您的`.knxproj`文件，分析组地址 / DPT / 拓扑结构，生成Home Assistant KNX YAML和可导入ETS的组地址文件（XML / CSV），并生成人类可读的报告 - **而无需触及实时KNX总线。**
[](https://github.com/NickoScope/nickol-knx-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
[](#-status--call-for-testers)
🇷🇺 **俄语版本：** [README.ru.md](README.ru.md)
---
## 🧪 状态与测试者召集
这是一个 **公开测试版**。完整的流水线在一 synthetic 16组地址项目上通过了端到端的烟雾测试，但它 **仅限于对真实`.knxproj`文件的有限测试** - 而真正的ETS项目非常复杂多样。
**👉 如果您有ETS5 / ETS6项目，请尝试它并告诉我们发生了什么。** 打开一个 [真实项目测试报告](https://github.com/NickoScope/nickol-knx-mcp/issues/new?template=real_project_test.yml) 问题。该工具是只读的，从不连接到总线，因此测试是安全的（参见 [安全模型](#-safety-model)）。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取详细信息。
---
## 为什么存在
截至2026年中期，**没有现成的ETS6 ↔ Claude / MCP工具**。KNX社区明确要求一个可以通过AI / CLI工作流检查和帮助修改项目（添加/重命名设备和组地址）的集成。该软件包恰好填补了 **设计时** 层 - 即缺失的一层。
推荐的完整设置是四层；只需要从头开始构建一层：
| 层 | 目的 | 使用什么 | 需要构建？ |
| --- | --- | --- | --- |
| 1. 实时 | 状态，控制，调试运行中的房屋 | **官方Home Assistant MCP Server** + KNX（XKNX）集成 | 否，已经存在 |
| 2. **设计时** | 解析`.knxproj`，验证DPT /命名/状态，生成HA YAML和ETS XML / CSV | **`nickol-knx-mcp`（此软件包）** | **是 - 这是空白点** |
| 3. 文件+Git | YAML / CSV / XML，版本控制地址模式 | 标准文件系统+git MCP服务器 | 否，已经存在 |
| 4. 技能 | 设计规则（GA结构，命名，DPT，场景） | `CLAUDE.md`在此软件包中 | 否，已包含 |
> **设计安全性：** 层2（此服务器）**无法物理连接到总线**。它根本没有网络/总线依赖 - 它只读取`.knxproj`并将文件写入封闭的工作区。 **绝不写入实时总线** 的要求在**结构上**强制执行，而不是通过承诺。任何与房屋的实际交互都仅通过层1（Home Assistant）进行。
---
## 服务器执行的操作
- **解析** 受密码保护的ETS5 / ETS6 `.knxproj` 文件通过 [`xknxproject`](https://github.com/XKNX/xknxproject) （3.9.x）。
- **提取** 组地址，DPT，设备，拓扑，描述和ETS功能。
- **分类** 每个GA：类别（照明/遮帘/暖通空调/传感器/场景/能源/诊断）和类型（命令/状态/传感器） - 从DPT和名称中的多语言（EN / DE / RU）关键字。
- **验证命名** 针对3级结构和可配置的正则表达式。
- **查找缺少的状态地址** - 主要从ETS功能角色，fallback到名称令牌配对（命令在`…/0/…`，反馈在`…/4/…`中常见，因此通过名称令牌而不是中间组邻接匹配）。
- **捕获DPT问题**：缺少DPT，通信对象与其GA之间的不匹配，以及相同的逻辑名称承载不同的DPT。
- **生成Home Assistant KNX YAML** - 按类别保守：涵盖→灯光→开关→传感器/二进制。模糊项（例如DPT 5.001 - 亮度vs盲板位置） **不被猜测**；它们进入 **审查** 列表。
- **生成可导入ETS的组地址** XML（推荐的`knx.org/xml/ga-export/01`模式）和 **CSV** （ETS的原生布局）。
- **编写Markdown报告** （库存+ 🔴🟡🔵 发现+ HA映射预览+下一步骤）供人类审查 **在** 任何导入之前。
所有写入操作仅进入工作目录（`NICKOL_KNX_WORKSPACE`，默认为`./knx-workspace`）；写入该目录之外的操作被拒绝。
---
## 安装
需要 **Python 3.10+**。
```bash
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`。
验证：
```bash
python tests/test_pipeline.py # 合成16-GA项目，端到端烟雾测试
nickol-knx-mcp # 启动MCP服务器（stdio）
```
---
## 连接到Claude
### Claude Desktop
`examples/claude_desktop_config.json` 将nickol-knx + 文件系统+ git + home-assistant连接起来。最小片段（macOS配置路径：`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"nickol-knx": {
"command": "nickol-knx-mcp",
"env": { "NICKOL_KNX_WORKSPACE": "/path/to/your/knx-workspace" }
}
}
}
```
### Claude Code
```bash
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安全密钥环处理和推荐的工作流程）。
---
## MCP工具（12）
| 工具 | 目的 |
| --- | --- |
| `load_project(path, password?, language?)` | 解析`.knxproj`（只读）并缓存它 |
| `list_group_addresses(category?, kind?)` | 列出具有分类和筛选器的GA |
| `get_devices()` | 设备+其通信对象 |
| `get_topology()` | 拓扑结构（区域/线路/设备） |
| `check_naming(name_regex?)` | 验证命名/结构 |
| `check_missing_status()` | 执行器缺少状态对象 |
| `check_dpt()` | 缺失/不一致的DPT |
| `analyze_all(name_regex?)` | 一次运行所有检查 |
| `generate_ha_package(output_path?)` | HA KNX YAML + 审查列表 |
| `generate_ets_group_addresses(fmt="xml"\|"csv", output_path?)` | 可导入ETS的GA |
| `project_report(output_path?, name_regex?)` | Markdown报告 |
| `workspace_info()` | 工作空间路径+安全保证 |
---
## 典型工作流程
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的文件导入/导出。
---
## 🔒 安全模型
- **无总线访问，结构上**。依赖树中没有网络或总线库。`workspace_info()`报告`bus_access: false`。
- **只读您的项目**。`project.py`是唯一触摸`.knxproj`的模块，并且它 **只读**。
- **写入受限**。所有输出仅限于`NICKOL_KNX_WORKSPACE`；该目录之外的路径被拒绝。
- **人为干预**。生成`project_report`并在导入ETS或部署到Home Assistant **之前**审查它。
发现安全问题？参见 [SECURITY.md](SECURITY.md)。
---
## 软件包布局
```
nickol-knx-mcp/
├── nickol_knx_mcp/
│ ├── dpt_map.py # DPT → 类别 / 类型 / HA平台 / value_type
│ ├── project.py # 唯一读取.knxproj的模块（只读）
│ ├── pairing.py # 命令↔状态配对按名称令牌
│ ├── analyze.py # 命名 / 缺失状态 / DPT检查
│ ├── generate_ha.py # Home Assistant KNX YAML生成
│ ├── generate_ets.py # ETS XML + CSV生成
│ ├── report.py # Markdown报告
│ └── server.py # FastMCP服务器，12种工具，写入受限
├── tests/test_pipeline.py
├── examples/claude_desktop_config.json
├── CLAUDE.md # ETS助手技能/剧本
├── pyproject.toml
└── README.md
```
---
## 贡献
测试者和贡献者非常受欢迎 - 特别是 **真实项目测试报告**。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [问题模板](.github/ISSUE_TEMPLATE)。
## 许可证
[MIT](LICENSE) © 2026 Nikolay Miroshnichenko
> 不隶属于或得到KNX协会的认可。“KNX”和“ETS”是KNX协会cc的商标。这是独立的社区工具。
