nickol-knx-mcp

Un asistente de diseño para KNX / ETS6 expuesto como un servidor MCP.

Cuatro cosas que puedes hacer con él — todo sin tocar nunca el bus KNX en vivo:

1. Diseñar un proyecto desde una especificación — convertir una lista de equipos / especificación de proyecto en una estructura de direcciones de grupo completa y validada más el conjunto completo de documentos de implementación (XML/CSV importable en ETS, informe legible por humanos, YAML de Home Assistant, protocolo de prueba de aceptación, paquete de entrega as-built).

2. Auditar, reparar y finalizar un proyecto existente — validar nomenclatura · DPT y sub-DPT · comando↔estado · KNX Secure · preparación para Matter, obtener propuestas de reparación concretas (DPT inferidos, GAs de estado sintetizadas), calificar integridad y comparar dos versiones del proyecto.

3. Generar la capa de hogar inteligente — entidades de Home Assistant ensambladas (luces de color, climatización, persianas, sensores) que leen el estado real del dispositivo, con todo lo ambiguo diferido a revisión humana.

4. Componer un nuevo proyecto a partir de plantillas de habitación parametrizadas — a partir de una lista de habitaciones (con un preajuste básico/confort por ranura) ensamblar un proyecto nuevo y validado → un manifiesto de asignación + GA XML/CSV de ETS + una propuesta de lista de materiales de dispositivos. Ejecución en seco, solo proyectos nuevos (R1).

Bajo el capó: una biblioteca de dispositivos que expande cada actuador en sus objetos de comunicación reales — desde recetas genéricas hasta el modelo de objeto exacto del fabricante analizado directamente de los programas de aplicación de ETS.

🇷🇺 Versión en ruso: README.ru.md

Nuevo: una casa de demostración completa. examples/demo-home incluye un proyecto sintético de 239 GA / 47 Funciones, el informe generado por la herramienta + la configuración de Home Assistant + la exportación de ETS, y un "cerebro" completo de hogar inteligente — iluminación circadiana, un punto de consigna climático de 8 factores, una máquina de estados de presencia/estación/hora y estadísticas — que impulsa un panel de 5 vistas. Míralo todo en el sitio en vivo ↗.

🖥️ El panel de control — en vivo en Home Assistant

Capturas de pantalla reales de un Home Assistant en vivo ejecutando la casa de demostración. Muestran las entidades ensambladas de la herramienta en acción: luces de color RGBW / RGB / CCT, seis zonas de climatización por suelo radiante (consigna, modo y % de válvula), una curva de iluminación circadiana y un punto de consigna climático calculado — no ajustado a mano.

▶ Explóralo interactivamente en el sitio en vivo → · configuración en examples/demo-home/ha-brain

Related MCP server: mcp-codebase-oracle

🧪 Estado y llamada a evaluadores

Esta es una beta pública. El pipeline completo pasa una prueba de humo integral en un proyecto sintético y ha sido validado contra proyectos ETS5/ETS6 reales de miles de GAs (anonimizados) — pero los proyectos ETS reales son maravillosamente desordenados y diversos, y más informes de campo lo mejoran.

👉 Si tienes un proyecto ETS5/ETS6, pruébalo y cuéntanos qué pasa. Abre un issue de Informe de prueba de proyecto real. La herramienta es de solo lectura y nunca se conecta a un bus, por lo que las pruebas son seguras (ver Modelo de seguridad). Consulta CONTRIBUTING.md para más detalles.

💬 Únete a la discusión → — saluda, pregunta cualquier cosa o comparte lo que la herramienta encontró en tu proyecto.

🗺️ Hoja de ruta — moldeada por integradores reales

Revisiones recientes de integradores KNX en ejercicio (en Discussions) están guiando lo que viene a continuación:

• Consistencia de parámetros entre dispositivos (enviado — check_device_parameters) — señalar el único dispositivo cuya configuración de parámetros de ETS difiere de sus N hermanos idénticos: un termostato con un punto de consigna/histeresis diferente, un detector de presencia con un tiempo de detección diferente. Extrae los parámetros por dispositivo directamente del .knxproj y encuentra el atípico en proyectos reales de 42 a 275 dispositivos — solo lectura, sin ETS, sin bus — e informa correctamente nada en un proyecto limpio (sin falsos positivos en diferentes fabricantes/escuelas de integradores).

• Perfil de política de proyecto (enviado — check_policy) — validar un proyecto contra tus propias reglas acordadas (nomenclatura, taxonomía de GA, exenciones de comando/estado) en lugar de un único "estándar profesional", ya que las convenciones difieren según el integrador; sin perfil, valida contra la taxonomía inferida del propio proyecto.

• Biblioteca de plantillas de habitación — componer un proyecto nuevo a partir de plantillas de habitación parametrizadas. R1 enviado (compose_rooms + validate_room_template: proyectos nuevos, ejecución en seco, manifiesto de asignación + XML/CSV de ETS + lista de materiales de dispositivos). R2 planificada: acoplamiento a un proyecto existente + selección exacta de dispositivos.

• Soporte para Logic Machine (próximamente — en investigación) — llevar el mismo modelo de solo lectura y tiempo de diseño a instalaciones de Logic Machine (Embedded Systems): analizar un proyecto KNX basado en LM y ejecutar las mismas auditorías de nomenclatura/DPT/estado/topología y producir la misma salida de entrega, para que los integradores de LM obtengan el mismo modelo de proyecto probatorio que ya obtienen de un .knxproj sin procesar. Actualmente en alcance contra una unidad real de Logic Machine 5.

• En cuanto al enlace de direcciones de grupo dentro de ETS, deliberadamente no reinventamos la rueda: para enlazar GAs a objetos de comunicación dentro de ETS ya existen complementos de la Tienda de Aplicaciones de ETS hoy en día, y el Smart Linking nativo llegará en ETS7 — te dirigimos a esos y mantenemos nuestro enfoque en la auditoría de solo lectura y un modelo de proyecto probatorio.

¿Tienes un proyecto para probar, un flujo de trabajo que falla, o una característica que dar forma? → Discussions.

Por qué existe esto

A mediados de 2026 no hay ninguna herramienta ETS6 ↔ Claude / MCP lista para usar. La comunidad KNX ha estado pidiendo explícitamente una integración que pueda inspeccionar y ayudar a modificar proyectos (añadiendo / renombrando dispositivos y direcciones de grupo) a través de un flujo de trabajo de IA/CLI. Este paquete llena exactamente la capa de tiempo de diseño — la que faltaba.

La configuración completa recomendada es de cuatro capas; solo una necesita construirse desde cero:

Seguridad por diseño: la capa 2 (este servidor) físicamente no puede conectarse a un bus. No tiene ninguna dependencia de red/bus — solo lee .knxproj y escribe archivos en un espacio de trabajo confinado. El requisito de "nunca escribir en un bus en vivo" se aplica estructuralmente, no por promesa. Cualquier interacción real con la casa pasa solo a través de la capa 1 (Home Assistant).

Qué puedes hacer con él

📐 Escenario 1 — Diseñar un proyecto desde una especificación (especificación → kit de implementación)

Convertir una especificación de proyecto (programas de equipos, diarios de cableado, una lista de dispositivos) en una estructura de direcciones de grupo completa y validada — y el conjunto completo de documentos para implementarlo:

1. Lista de dispositivos → modelo de objetos. Cada dispositivo se expande en sus objetos de comunicación reales a través de la biblioteca de dispositivos (decompose_device): un canal de regulador de intensidad es encendido/apagado + estado + regulación relativa (3.007) + valor absoluto (5.001) + estado de brillo — no «un GA»; una zona de calefacción por suelo radiante son 8 objetos; un contador de pulsos son 6.

2. La capa de lógica profesional. Una especificación básica nunca menciona lo que hace que un proyecto esté completo: macros centrales y de zona, escenas, lógica de presencia, andamiaje de control climático, lógica de persianas sol/viento, cadenas de fuga→cierre, fuentes astro/meteo y fecha-hora, reservas en cada rango. La metodología codifica estos patrones de completitud — destilados del estándar de la Asociación KNX, documentación pública de fabricantes y el estudio de proyectos ETS reales profesionales «as-built» (anonimizados).

3. Estructura y disciplina. Direccionamiento de 3 niveles, nomenclatura zona+funcion, emparejamiento comando↔estado, un DPT en cada dirección.

4. Entregables (un comando cada uno): XML/CSV importable en ETS · Informe Markdown · YAML de Home Assistant · protocolo de prueba de aceptación funcional · paquete de entrega as-built (inventario, mapa GA, cobertura %, postura Secure, hallazgos QA, SVG de topología).

Metodología completa: docs/spec-to-structure.md. Verificado en campo reconstruyendo un proyecto ETS real «as-built» (más de 3600 direcciones de grupo) a partir de su especificación únicamente: ~92 % de coincidencia estructural (taxonomía, dominios, lógica de automatización, distribución DPT) con cero errores de validación — el delta restante es la parametrización por dispositivo del integrador, que ninguna especificación codifica.

🔍 Escenario 2 — Auditar, reparar y finalizar un proyecto existente

• Leer y clasificar. Analiza proyectos .knxproj protegidos por contraseña de ETS5/ETS6 mediante xknxproject; clasifica cada GA por categoría (iluminación / persiana / climatización / sensor / escena / energía / diagnóstico) y tipo (comando / estado / sensor) a partir del DPT + palabras clave multilingües (EN/DE/RU) en el nombre. Etiquetado de propósito de GA (functional / reserve / logic / scratch) mantiene los marcadores de posición intencionales fuera de las listas de errores, para que el informe no dé falsas alarmas (en un proyecto real de 685 GA: errores falsos 29 → 6).

• Validar (analyze_all ejecuta todo): nomenclatura y estructura · objetos de estado faltantes (roles de ETS-Function primero, luego emparejamiento de tokens de nombre, emparejamiento posicional — estados paralelos intermedios con nombres 1:1 — y objetos R+T de auto-reporte) · DPT faltantes/inconsistentes + cordura de sub-DPT (un GA de «temperatura» que lleva 5.001 se marca) · reguladores de intensidad solo relativos · postura KNX Secure (asegurado vs texto plano, grupos mixtos, lista de verificación del keyring — el material clave nunca se lee) · preparación para Matter · cobertura del dominio energético.

• Reparar, no solo marcar (suggest_repairs): inferir un DPT a partir del nombre, corregir un sub-DPT sospechoso, sintetizar un GA de estado faltante en una ranura de dirección libre, añadir un GA de brillo absoluto. Solo sugerencias — un humano revisa, los GA aceptados alimentan la exportación ETS. En un proyecto real de 3646 GA: 145 propuestas concretas (32 inferencias DPT, 112 GA de estado sintetizados).

• Finalizar el trabajo: grade_completeness (esqueleto desnudo → puntuación «as-built»), suggest_names, diff_projects (diff semántico de dos revisiones .knxproj: añadido / eliminado / DPT cambiado / renombrado / secure cambiado), luego regenerar el informe, el paquete de entrega y el protocolo de prueba.

🏠 Escenario 3 — Generar la capa de hogar inteligente (Home Assistant)

• Entidades ensambladas, de forma conservadora: cubiertas → luces de color / regulables (encendido/apagado + brillo + RGBW/RGB/temperatura de color + estados) → interruptores → climatización (temperatura actual, estado de temperatura objetivo, modo de operación/control, valor de válvula) → sensores/binarios. Cada entidad recibe una state_address siempre que el dispositivo pueda informar — HA lee el estado real, nunca asume.

• Revisión primero: cualquier cosa ambigua (DPT 5.001 — ¿brillo o posición de persiana?) no se adivina — va a una lista de review con una explicación (incluyendo banderas de cubierta dependientes del actuador como invert_position / tiempos de recorrido, que ningún .knxproj codifica).

• Extras: bloque expose para difusión de fecha/hora (DPT 19.001), lint de preparación para Matter, exportación semántica KNX IoT (Turtle/RDF).

• El control en vivo de la casa permanece en la integración oficial de Home Assistant (capa 1) — este servidor solo prepara su configuración.

• Compañero de operaciones: skills/ha-git-backup — la vida de tu configuración después del despliegue: un historial git real de /config (clave de despliegue + escáner de secretos pre-commit) más copias de seguridad cifradas fuera del sitio en GitHub Releases, con un simulacro de restauración mensual.

🧱 Escenario 4 — Componer un nuevo proyecto a partir de plantillas de habitaciones

• Desde habitaciones, no desde una hoja en blanco: elige entre seis plantillas de habitaciones parametrizadas integradas (dormitorio, infantil, salón, cocina, baño, pasillo), elige un preajuste basic / comfort por ranura (una casa puede mezclar climatización comfort con iluminación básica), y compose_rooms ensambla un proyecto nuevo.

• Sale: un manifest de asignación (principal = dominio, medio = rol, sub secuencial), GA XML/CSV importable en ETS a través de los generadores existentes, y una lista de materiales (BOM) de dispositivos propuesta desde la biblioteca de dispositivos.

• Validado por el lector real: el .knxproj generado se vuelve a leer a través del load_project estándar — el mismo camino utilizado para proyectos de terceros — y pasa los cuatro linters (nomenclatura / estado faltante / DPT / política) con 0 errores / 0 advertencias.

• Simulación por defecto, solo proyectos nuevos. El formato de plantilla es un contrato público (room_templates/SCHEMA.md): la identidad es un slot_id neutro en cuanto a idioma, nunca un nombre humano.

• R2: integración en un proyecto existente + selección exacta de dispositivos — planificado.

🧩 La base — una biblioteca de dispositivos en crecimiento

• parse_devices_from_project extrae modelos de objetos de proveedor exactos — incluyendo publicadores a nivel de referencia (ComObjectRef) como HDL/Ekinex — de los programas de aplicación del fabricante dentro de cualquier .knxproj / .knxprod: números de objeto, nombres, tamaños, DPTs, banderas C/R/W/T/U, pasos de bloque por canal — de forma determinista y segura para PII (solo datos del catálogo del proveedor; la parte del proyecto cliente del archivo nunca se lee).

• Apunte NICKOL_KNX_CATALOG a su catálogo y decompose_device responde con el modelo exacto (catalog-exact) en lugar de una receta genérica — el catálogo crece bajo demanda, a partir de los proyectos y bases de datos de productos que usted le alimente.

• Los objetos que el proveedor envía sin un DPT declarado se quedan honestamente como unverified — nunca se adivinan.

Todas las escrituras van solo al directorio del espacio de trabajo (NICKOL_KNX_WORKSPACE, por defecto ./knx-workspace); las escrituras fuera de él son rechazadas.

Instalación

Requiere 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 .

Dependencias: mcp>=1.10, xknxproject>=3.8, PyYAML>=6.0.

En Debian/Ubuntu, si pip se queja de un entorno gestionado externamente, use un venv (como arriba) o pip install -e . --break-system-packages. Si PyJWT entra en conflicto, ejecute primero pip install mcp --ignore-installed PyJWT.

Verificar:

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

Conexión con Claude

Claude Desktop

examples/claude_desktop_config.json conecta nickol-knx + filesystem + git + home-assistant. Fragmento mínimo (ruta de configuración 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

Luego coloque CLAUDE.md en la raíz de su proyecto — actúa como una habilidad de Asistente ETS (reglas de diseño, reglas de seguridad, estructura GA de 3 niveles, emparejamiento comando/estado, disciplina DPT, nomenclatura, manejo del keyring KNX Secure y el flujo de trabajo recomendado).

Herramientas MCP (31)

Lectura

Validar

Reparación y diseño

Generar

Biblioteca de Salas (R1 — componer un nuevo proyecto a partir de plantillas de sala)

Flujo de trabajo típico

1. load_project → apúntelo a su .knxproj (+ contraseña si está protegido).

2. analyze_all o project_report → lea los hallazgos; revise primero manualmente.

3. Corrija nomenclatura/DPT/estado en ETS (importando las GAs generadas o manualmente).

4. generate_ets_group_addresses(fmt="xml") → importe las GAs faltantes en ETS.

5. generate_ha_package → coloque el YAML en Home Assistant; resuelva los elementos de review a mano.

6. Mantenga todo (exportación .knxproj, configuraciones de HA, esquema de direcciones) en Git.

7. Toque la casa real solo a través del MCP de Home Assistant (capa 1).

Limitaciones (honestas)

• La clasificación de comando/estado y de categoría es una heurística (DPT + nombres + Funciones de ETS). En proyectos desordenados sin Funciones y con nombres no estándar, son posibles falsos negativos/positivos — por eso el informe siempre es para revisión humana, y la ambigüedad va a review, no a la configuración.

• El DPT 5.001 es estructuralmente ambiguo (brillo vs. posición); se desambigua mediante palabras clave — verifique con nombres no estándar.

• El generador de HA es conservador: prefiere diferir un elemento a review antes que emitir una entidad incorrecta.

• El servidor nunca escribe en el bus y nunca habla con ETS directamente — el intercambio con ETS es solo importación/exportación de archivos de GAs.

• Validado en un proyecto de demostración sintético y en proyectos reales de ETS5/ETS6 con miles de GAs (anonimizados) — pero los archivos .knxproj reales varían enormemente, y sigue siendo una beta. Por eso la solicitud de probadores.

🔒 Modelo de seguridad

• Sin acceso al bus, estructuralmente. No hay redes ni bibliotecas de bus en el árbol de dependencias. workspace_info() reporta bus_access: false.

• Solo lectura en su proyecto. project.py es el único módulo que toca .knxproj, y solo lee.

• Escrituras confinadas. Toda la salida se restringe a NICKOL_KNX_WORKSPACE; las rutas fuera de él se rechazan.

• Endurecido contra archivos de proyecto hostiles. Un .knxproj es un ZIP-de-XML no confiable, por lo que el análisis se ejecuta a través de safexml.py: se rechaza XML con DTD/entidad (billion-laughs / XXE), y los archivos se prefiltran contra límites de tamaño / número de entradas / relación de descompresión, con nombres de ruta de traversal rechazados (defensa contra zip-bomb).

• Humano en el ciclo. Genere un project_report y revíselo antes de importarlo a ETS o desplegarlo en Home Assistant.

¿Encontró un problema de seguridad? Consulte SECURITY.md.

Estructura del paquete

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

Contribuciones

Los probadores y colaboradores son muy bienvenidos — especialmente informes de pruebas con proyectos reales. Consulte CONTRIBUTING.md y las plantillas de incidencia.

Licencia

MIT © 2026 Nikolay Miroshnichenko

No está afiliado ni respaldado por la KNX Association. "KNX" y "ETS" son marcas comerciales de la KNX Association cc. Esta es una herramienta comunitaria independiente.