nickol-knx-mcp

設計時のKNX / ETS6アシスタントをMCPサーバーとして公開。

以下の4つのことができます — すべて実際のKNXバスに触れることなく：

1. 仕様からプロジェクトを設計 — 機器リスト/プロジェクト仕様を、完全で検証済みのグループアドレス構造および完全な実装ドキュメント一式（ETSインポート可能なXML/CSV、人間が読めるレポート、Home Assistant YAML、受け入れテストプロトコル、アズビルド引継ぎパック）に変換します。

2. 既存プロジェクトの監査、修復、完成 — 命名規則・DPT & サブDPT・コマンド↔ステータス・KNX Secure・Matter対応を検証し、具体的な修正提案（推定DPT、合成ステータスGA）を取得、完全性を評価し、2つのプロジェクトバージョンを比較します。

3. スマートホームレイヤーの生成 — 実際のデバイス状態を読み取る、組み立てられたHome Assistantエンティティ（カラーライト、空調、カバー、センサー）を生成し、曖昧なものはすべて人間のレビューに委ねます。

4. パラメータ化されたルームテンプレートから新しいプロジェクトを構成 — 部屋のリスト（スロットごとにbasic/comfortプリセット付き）から、新しい検証済みプロジェクトを組み立て → 割り当てマニフェスト + ETS GA XML/CSV + デバイスBOM提案。ドライラン、新規プロジェクトのみ（R1）。

内部構造：デバイスライブラリにより、各アクチュエータを実際の通信オブジェクトに展開 — 汎用レシピから、ETSアプリケーションプログラムから直接解析された正確なベンダーオブジェクトモデルまで。

🇷🇺 Русская версия: README.ru.md

新機能 — デモハウス全体。 examples/demo-home には、合成された 239-GA / 47-機能 プロジェクト、ツールが生成したレポート + 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 のIssueを開いてください。このツールは読み取り専用で、バスに接続することはありませんので、テストは安全です（安全モデルを参照）。詳細は CONTRIBUTING.md をご覧ください。

💬 ディスカッションに参加 → — 挨拶、質問、ツールがあなたのプロジェクトで見つけたことの共有など、お気軽にどうぞ。

🗺️ ロードマップ — 実際のインテグレーターの声から

実際のKNXインテグレーターからの最近のレビュー（Discussions内）が今後の方向性を決めています：

• デバイス間のパラメータ一貫性 (出荷済み — check_device_parameters) — ETSのパラメータ設定が同一の兄弟機と異なるデバイスをフラグ付け：設定値/ヒステリシスが異なるサーモスタット、検出時間が異なる在室検知器。.knxprojから直接デバイスごとのパラメータを抽出し、実際の42～275デバイスプロジェクトで異常値を検出 — 読み取り専用、ETS不要、バス不要 — クリーンなプロジェクトでは何も報告しません（異なるベンダー/インテグレーター流派間での誤検出なし）。

• プロジェクトポリシープロファイル (出荷済み — check_policy) — プロジェクトをあなた自身の合意されたルール（命名規則、GA分類、コマンド/ステータス例外）に対して検証。インテグレーターごとに慣習が異なるため、普遍的な「プロフェッショナル標準」ではなく、プロファイルがない場合はプロジェクト自体から推測された分類に対して検証します。

• ルームテンプレートライブラリ — パラメータ化されたルームテンプレートから新しいプロジェクトを構成。R1出荷済み（compose_rooms + validate_room_template：新規プロジェクト、ドライラン、割り当てマニフェスト + ETS XML/CSV + デバイスBOM）。R2計画中：既存プロジェクトへのドッキング + 正確なデバイス選択。

• ロジックマシン対応 (近日公開 — 研究中) — 同じ読み取り専用の設計時モデルをロジックマシン（Embedded Systems）のインストールにも適用：LMベースのKNXプロジェクトを解析し、同じ命名/DPT/ステータス/トポロジ監査を実行し、同じ引継ぎ出力を生成。これによりLMインテグレーターも、生の.knxprojから得られるのと同じ証拠に基づくプロジェクトモデルを得られます。現在、実際のLogic Machine 5ユニットに対してスコープを検討中。

• ETS内のグループアドレスリンクについては、意図的に車輪の再発明はしません：ETS内でGAを通信オブジェクトにリンクするには、現在すでにETS App Storeのアドインが存在し、ネイティブのスマートリンキングがETS7で登場予定です — それらを紹介し、読み取り専用の監査と証拠に基づくプロジェクトモデルに焦点を当てます。

テストしたいプロジェクト、壊れるワークフロー、形にしたい機能がありますか？ → Discussions。

なぜこれが存在するのか

2026年半ば現在、既製のETS6 ↔ Claude / MCPツールは存在しません。KNXコミュニティは、AI/CLIワークフローを通じてプロジェクトを検査・修正（デバイスやグループアドレスの追加/名前変更）できる統合を明示的に求めています。このパッケージは、まさにその設計時レイヤー — 欠けていた部分 — を埋めます。

推奨される完全なセットアップは4つのレイヤーです。そのうち1つだけをゼロから構築する必要があります：

設計による安全性： レイヤー2（このサーバー）は物理的にバスに接続できません。ネットワーク/バス依存性はまったくなく、.knxprojを読み取り、制限されたワークスペースにファイルを書き込むだけです。「ライブバスに書き込まない」要件は、約束ではなく構造的に強制されています。家との実際のやり取りは、レイヤー1（Home Assistant）を通じてのみ行われます。

これでできること

📐 シナリオ1 — 仕様からプロジェクトを設計（仕様 → 実装キット）

プロジェクト仕様（機器スケジュール、ケーブルジャーナル、デバイスリスト）を、完全で検証済みのグループアドレス構造に変換 — そしてそれを実装するための完全なドキュメント一式：

1. デバイスリスト → オブジェクトモデル。 各デバイスは、デバイスライブラリ（decompose_device）を介して実際の通信オブジェクトに展開されます。調光チャンネルは、オン/オフ + ステータス + 相対調光 (3.007) + 絶対値 (5.001) + 輝度ステータス — 「1つのGA」ではありません。床暖房ゾーンは8オブジェクト、パルスメーターは6オブジェクトです。

2. プロフェッショナルロジックレイヤー。 仕様書だけでは、プロジェクトを完全にする要素（中央＆ゾーンマクロ、シーン、在室ロジック、気候制御の骨組み、太陽/風によるシャッターロジック、漏水→遮断チェーン、天文/気象および日時ソース、全範囲の予約）については決して言及されません。この方法論は、KNX協会標準、公開されているメーカーのドキュメント、実際のプロフェッショナルな施工済みETSプロジェクト（匿名化）の研究から抽出された、これらの完全性パターンをエンコードしています。

3. 構造と規律。 3レベルのアドレッシング、ゾーン+機能の命名、コマンド↔ステータスのペアリング、すべてのアドレスにDPT。

4. 成果物（各コマンド1つ）：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（2つの.knxprojリビジョンのセマンティック差分：追加/削除/DPT変更/名前変更/セキュア変更）、その後レポート、引渡しパック、テストプロトコルを再生成。

🏠 シナリオ3 — スマートホームレイヤーの生成（Home Assistant）

• 控えめにエンティティを組み立て：カバー → カラー/調光可能ライト（オン/オフ + 輝度 + RGBW/RGB/色温度 + ステータス） → スイッチ → 気候（現在温度、目標温度ステータス、運転/コントローラーモード、バルブ値） → センサー/バイナリ。すべてのエンティティは、デバイスが報告可能な場所に state_address を取得 — HAは実際の状態を読み取り、決して推測しません。

• レビュー優先：あいまいなもの（DPT 5.001 — 輝度かブラインド位置か？）は推測されません — 説明とともにreviewリストに送られます（invert_position / 走行時間など、どの.knxprojもエンコードしないアクチュエータ依存のカバーフラグを含む）。

• 追加機能：日時ブロードキャスト用のexposeブロック（DPT 19.001）、Matter対応リント、KNX IoT（Turtle/RDF）セマンティックエクスポート。

• 家のライブ制御は公式のHome Assistant統合（レイヤー1）に残ります — このサーバーはその設定を準備するだけです。

• 運用コンパニオン：skills/ha-git-backup — デプロイ後の設定のライフ：/configの実際のgit履歴（デプロイキー + pre-commitシークレットスキャナー）に加え、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）：識別子はロケールに依存しない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をプロジェクトルートに配置します — これは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 Functions）です。 Functionsがなく非標準の名前が使われている複雑なプロジェクトでは、偽陰性/偽陽性が発生する可能性があります — そのためレポートは常に人間によるレビュー用であり、曖昧なものは設定に含めずreviewに回します。

• DPT 5.001は構造的に曖昧です（輝度か位置か）；キーワードで判別します — 非標準の命名の場合は再確認してください。

• 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攻撃対策）、アーカイブは サイズ/エントリ数/展開率の上限とパストラバーサル名の拒否により事前チェックされます（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およびissueテンプレートを参照してください。

ライセンス

MIT © 2026 Nikolay Miroshnichenko

KNX Associationとの提携や推奨はありません。「KNX」および「ETS」はKNX Association ccの商標です。 これは独立したコミュニティツールです。