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 컬러 조명, 6개 바닥 난방 기후 구역(목표, 모드 및 밸브 %), 일주기 조명 곡선 및 계산된 기후 설정값 — 수동으로 설정하지 않았습니다.

▶ 라이브 사이트에서 대화형으로 살펴보기 → · 구성 파일은 examples/demo-home/ha-brain에 있습니다.

Related MCP server: mcp-codebase-oracle

🧪 상태 및 테스터 모집

이것은 공개 베타입니다. 전체 파이프라인은 합성 프로젝트에서 종단 간 스모크 테스트를 통과했으며 실제 수천 개 GA 규모의 ETS5/ETS6 프로젝트(익명화)에 대해 검증되었습니다. 하지만 실제 ETS 프로젝트는 매우 다양하고 복잡하며, 더 많은 현장 보고가 도구를 개선합니다.

👉 ETS5/ETS6 프로젝트가 있다면 꼭 시도해보고 결과를 알려주세요. Real-project test report 이슈를 열어주세요. 도구는 읽기 전용이며 버스에 연결되지 않으므로 테스트는 안전합니다(참조: 안전 모델). 자세한 내용은 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(Embedded Systems) 설치에 적용: LM 기반 KNX 프로젝트를 파싱하고 동일한 명명/DPT/상태/토폴로지 감사를 수행하며 동일한 인계 출력물을 생성하여, LM 통합업체도 원시 .knxproj에서 얻을 수 있는 것과 동일한 증거 기반 프로젝트 모델을 얻을 수 있도록 합니다. 현재 실제 Logic Machine 5 장치를 대상으로 범위를 설정 중입니다.

• ETS 내 그룹 주소 연결에 대해서는 의도적으로 바퀴를 재발명하지 않습니다. ETS 내에서 GA를 통신 객체에 연결하기 위해 이미 현재 ETS 앱 스토어 애드인이 있으며, ETS7에서 Smart Linking이 기본 제공될 예정입니다 — 이 도구는 해당 도구들을 안내하고, 읽기 전용 감사와 증거 기반 프로젝트 모델에 집중합니다.

테스트할 프로젝트, 문제가 있는 워크플로우, 또는 기능 제안이 있으신가요? → 토론.

이 도구가 필요한 이유

2026년 중반 기준으로 기성품 ETS6 ↔ Claude / MCP 도구는 없습니다. KNX 커뮤니티는 AI/CLI 워크플로우를 통해 프로젝트를 검사하고 수정(장치 및 그룹 주소 추가/이름 변경)할 수 있는 통합을 명시적으로 요청해 왔습니다. 이 패키지는 바로 그 설계 단계 레이어를 채웁니다 — 누락된 부분입니다.

권장되는 전체 구성은 4개 레이어이며, 하나만 처음부터 구축하면 됩니다:

안전한 설계: 레이어 2(이 서버)는 물리적으로 버스에 연결할 수 없습니다. 네트워크/버스 종속성이 전혀 없으며, 오직 .knxproj를 읽고 제한된 작업 공간에 파일을 씁니다. "운영 버스에 쓰지 않음" 요구 사항은 약속이 아닌 구조적으로 강제됩니다. 주택과의 실제 상호작용은 항상 레이어 1(Home Assistant)을 통해서만 이루어집니다.

이 도구로 할 수 있는 작업

📐 시나리오 1 — 사양서로부터 프로젝트 설계 (사양 → 구현 키트)

프로젝트 사양(장비 목록, 케이블 저널, 장치 목록)을 완전하고 검증된 그룹 주소 구조로 변환합니다. 그리고 이를 구현하기 위한 전체 문서 세트를 생성합니다:

1. 장치 목록 → 객체 모델. 각 장치는 장치 라이브러리(decompose_device)를 통해 실제 통신 객체로 확장됩니다. 조광 채널은 on/off + 상태 + 상대 조광(3.007) + 절댓값(5.001) + 밝기 상태로 구성되며, "하나의 GA"가 아닙니다. 바닥 난방 구역은 8개의 객체, 펄스 미터는 6개의 객체로 구성됩니다.

2. 전문 로직 계층. 단순한 명세는 프로젝트를 완성하는 요소(중앙 및 구역 매크로, 씬, 재실 로직, 기후 제어 스캐폴딩, 태양/바람 셔터 로직, 누수→차단 체인, 천문/기상 및 날짜-시간 소스, 모든 범위의 예약)를 언급하지 않습니다. 이 방법론은 이러한 완전성 패턴을 인코딩하며, KNX 협회 표준, 공개 제조업체 문서, 실제 전문 시공 ETS 프로젝트(익명화) 연구에서 추출되었습니다.

3. 구조 및 규율. 3레벨 주소 지정, 구역+기능 명명, 명령↔상태 페어링, 모든 주소에 DPT 할당.

4. 산출물(각각 하나의 명령): ETS 가져오기 가능 XML/CSV · Markdown 보고서 · Home Assistant YAML · 기능 승인 테스트 프로토콜 · 시공 인계 패키지(인벤토리, GA 맵, 커버리지 %, 보안 상태, QA 결과, 토폴로지 SVG).

전체 방법론: docs/spec-to-structure.md. 실제 시공 ETS 프로젝트(3,600개 이상의 그룹 주소)를 명세만으로 재구성하여 현장 검증 완료: ~92% 구조적 일치(분류 체계, 도메인, 자동화 로직, DPT 분포)에 검증 오류 0개 — 나머지 차이는 통합업체의 장치별 파라미터화로, 어떤 명세도 이를 인코딩하지 않습니다.

🔍 시나리오 2 — 기존 프로젝트 감사, 수리 및 완료

• 읽기 및 분류. xknxproject를 통해 비밀번호로 보호된 ETS5/ETS6 .knxproj를 파싱합니다. 모든 GA를 DPT + 다국어(EN/DE/RU) 이름 키워드로 범주(조명 / 셔터 / HVAC / 센서 / 씬 / 에너지 / 진단)와 종류(명령 / 상태 / 센서)별로 분류합니다. GA 목적 태깅(functional / reserve / logic / scratch)을 통해 의도된 자리 표시자를 오류 목록에서 제외하므로 보고서가 허위 경고를 하지 않습니다(실제 685-GA 프로젝트에서 허위 오류 29 → 6).

• 검증(analyze_all이 모든 것을 실행): 명명 및 구조 · 누락된 상태 객체(ETS-Function 역할 우선, 그 다음 이름-토큰 페어링, 위치 기반 페어링 — 1:1 이름으로 병렬 상태 중간 및 자체 보고 R+T 객체) · 누락/불일치 DPT + 하위 DPT 건전성(5.001을 가진 "온도" GA는 플래그 지정) · 상대 조광만 있는 디머 · KNX 보안 상태(보안 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)

• 엔티티를 보수적으로 조합: 커버 → 색상/조광 가능 조명(on/off + 밝기 + 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 — 방 템플릿으로 새 프로젝트 구성

• 빈 시트가 아닌 방에서 시작: 6개의 내장 파라미터화된 방 템플릿(침실, 어린이방, 거실, 주방, 욕실, 복도) 중 선택, 슬롯별로 basic / comfort 프리셋 선택(집은 기본 조명과 편안한 기후를 혼합할 수 있음), compose_rooms가 새 프로젝트를 조합합니다.

• 결과물: 할당 manifest(메인 = 도메인, 중간 = 역할, 서브 순차), 기존 생성기를 통한 ETS 가져오기 가능 GA XML/CSV, 장치 라이브러리의 장치 BOM 제안.

• 실제 리더로 검증: 생성된 .knxproj는 표준 load_project를 통해 다시 읽히며(타사 프로젝트와 동일한 경로), 4개의 린터(명명/누락 상태/DPT/정책)를 오류 0개 / 경고 0개로 통과합니다.

• 기본적으로 드라이 런, 새 프로젝트만. 템플릿 형식은 공개 계약입니다(room_templates/SCHEMA.md): ID는 로캘 중립적인 slot_id이며, 사람 이름이 아닙니다.

• R2: 기존 프로젝트에 도킹 + 정확한 장치 선택 — 계획 중.

🧩 기반 — 성장하는 장치 라이브러리

• parse_devices_from_project는 .knxproj / .knxprod 내부의 제조업체 애플리케이션 프로그램에서 정확한 벤더 객체 모델을 추출합니다(HDL/Ekinex와 같은 ref-level(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를 프로젝트 루트에 넣으면 ETS Assistant 스킬(설계 규칙, 안전 규칙, 3레벨 GA 구조, 명령/상태 페어링, DPT 규율, 명명, KNX 보안 키링 처리 및 권장 워크플로) 역할을 합니다.

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 Functions)입니다. Functions가 없고 비표준 이름이 있는 복잡한 프로젝트에서는 거짓 음성/양성이 발생할 수 있습니다. 따라서 보고서는 항상 사람이 검토하도록 되어 있으며, 모호한 항목은 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-of-XML이므로 구문 분석은 safexml.py를 통해 실행됩니다: DTD/엔티티 XML은 거부되고(billion-laughs / XXE), 아카이브는 크기/항목/압축 해제 비율 제한에 대해 사전 점검되며 경로 탐색 이름은 거부됩니다(압축 폭탄 방어).

• 사람이 개입. 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 Nikolay Miroshnichenko

KNX Association과 제휴하거나 보증하지 않습니다. "KNX" 및 "ETS"는 KNX Association cc의 상표입니다. 이는 독립적인 커뮤니티 도구입니다.