Developer MCP Tool for OpenWebNet Protocol Validation, WHO Specifications, and Home Assistant Integration Knowledge. Deterministic syntax checking, formal WHO catalog reference, and AST signature introspection for AI coding assistants.
openwebnet-mcp is an offline, read-only Model Context Protocol (MCP) server built with Python 3.11+ using the FastMCP framework. It provides AI coding assistants (Claude Desktop, Cursor, VS Code, Antigravity) with fast semantic lookups, deterministic frame grammar validation, and reference documentation for OpenWebNet WHO families and Home Assistant myhome configuration patterns.
{
"mcpServers": {
"openwebnet-mcp": {
"command": "uvx",
"args": ["--from", "git+https://github.com/OpenWebNet-HA/openwebnet-mcp.git", "openwebnet-mcp"]
}
}
}{
"mcpServers": {
"openwebnet-mcp": {
"command": "python",
"args": ["-m", "openwebnet_mcp.server"],
"cwd": "/path/to/openwebnet-mcp"
}
}
}Once connected, your AI coding assistant can browse documentation, interpret frames, and generate verified code autonomously.
User Prompt:
"I saw this frame on my SCS bus trace:
*#4*1*#14*0215*1##. What does it mean and which hardware is involved?"
AI Agent Action:
- Calls
parse_and_validate_frame("*#4*1*#14*0215*1##"). - Resolves WHO=4 (Heating/Thermoregulation), Dimension 14 (Target Temperature & Mode), Zone 1, Target 21.5°C, Mode 1 (Heating).
- Returns human-readable breakdown and lists compatible thermostat units (3550, L4691).
User Prompt:
"How do I configure my BTicino 3477 CEN+ interface to toggle a light when button 2 is pressed, and what OpenWebNet frames are sent?"
AI Agent Action:
- Calls
get_ha_guide("cen_scenarios")to review the CEN vs CEN+ specifications and Home Assistant blueprint. - Calls
draft_own_frame(who=25, command_type="command", where="11", what="21#2")to show the short-press pulse frame*25*21#2*11##. - Calls
draft_ha_config(platform="light", ...)to draft the complete automation YAML.
User Prompt:
"My dimmable lights jump instantly to brightness instead of ramping smoothly when I pass
transition: 5. Why?"
AI Agent Action:
- Calls
search_documentation("transition stepped dimming"). - Reads the technical design document explaining hardware ramp limitations in older F411/F418 actuators vs software-emulated stepped dimming.
- Suggests the proper configuration and command sequence.
| Tool | Description |
|---|---|
search_documentation |
Ranked keyword and fuzzy search across all protocol specs, guides, and design docs. |
get_who_spec |
Retrieve full technical specification, WHAT commands, and DIMENSIONS for a WHO family. |
list_who_catalog |
Summary inventory table of all 20+ OpenWebNet WHO families with archive status. |
get_ha_guide |
Full markdown guide for configuring and troubleshooting Home Assistant MyHOME platforms. |
lookup_frame_syntax |
Grammar, regex templates, and parameter formats for OpenWebNet message types. |
parse_and_validate_frame |
Deep syntax and semantic validation of any raw OpenWebNet frame string. |
draft_own_frame |
Construct and validate a syntactically correct OpenWebNet frame string. |
draft_sound_source_selection |
Build the WHO=16 frame pair that switches a room's audio source, including which amplifiers the change reaches and how far the evidence for it goes. |
draft_ha_config |
Generate production-ready Home Assistant configuration YAML for MyHOME entities. |
get_code_signature |
Inspect Python AST signatures and docstrings from custom_components/myhome or OWNd. |
search_knowledge |
Ranked search over the Encyclopedia's Machine KB (atomic claims and retrieval chunks). Every hit keeps its epistemic status, applicability, provenance, cautions and open questions. |
get_knowledge_record |
Resolve any Machine KB stable ID (ownkb:claim:…, ownkb:chunk:…, ownkb:caution:…, …) with cautions and questions hydrated. |
get_knowledge_status |
Which Machine KB snapshot backs the answers: versions, artifact-hash verification, counts. |
rescan_documentation |
Flush caches and reload all OpenWebNet specifications, documents, and AST models, and the Machine KB. |
| URI | Description |
|---|---|
spec://who-catalog |
Read-only catalog of all OpenWebNet WHO families. |
spec://protocol-grammar |
Read-only formal OpenWebNet grammar, regex patterns, and session specs. |
docs://toc |
Master Table of Contents for all indexed OpenWebNet & MyHOME documentation. |
docs://guide/{topic} |
Read-only full text of a specific documentation guide. |
kb://manifest |
Read-only Machine KB manifest: exact dataset, compatibility versions and artifact hashes. |
| Prompt / Slash Command | Description |
|---|---|
/boost [topic] |
Injects authoritative OpenWebNet protocol architecture, WHO subsystem mappings, frame delimiters, and modern Home Assistant /config/myhome.yaml standards directly into the AI agent context window. |
In Claude Desktop, Cursor, or Antigravity, trigger the prompt by typing /boost or selecting it from the prompt menu:
/boost topic: lighting
The server primes the LLM with strict frame grammar rules, hardware capabilities, and modern Home Assistant configuration standards, eliminating hallucinated syntax.
search_knowledge, get_knowledge_record and get_knowledge_status read the
OpenWebNet Encyclopedia Machine KB
(release machine-kb-v0.1.0), following its consumer guide: manifest first, schema-version check,
SHA-256 verification, stable-ID maps, and every qualification returned with the text.
The KB is located, in order, from OPENWEBNET_KB_PATH (the knowledge directory or an Encyclopedia checkout),
the hash-verified download cache, or a sibling OpenWebNet-Encyclopedia/knowledge checkout (an unverified working tree).
The default uvx install ships without the corpus. Fill the cache with a hash-verified release (no checkout needed);
the tools pick it up on the next call, no restart required:
uvx --from git+https://github.com/OpenWebNet-HA/openwebnet-mcp.git openwebnet-mcp-kb-fetch machine-kb-v0.1.0
# or, from a clone: python -m openwebnet_mcp.kb_fetch machine-kb-v0.1.0Hash mismatches (for example a checkout of a branch newer than the tag) are reported by get_knowledge_status
and logged; set OPENWEBNET_KB_STRICT=1 to refuse to load instead. Without a KB the three tools return a clear
error and the rest of the server is unaffected.
Known 0.1.0 limits, surfaced rather than hidden: 1,120 claim statements are truncated by an upstream rendering
defect (Encyclopedia#37) and point to their
intact source chunk; DALI / WHO 24 is not in the corpus yet. Ranking is lexical (BM25) and is not evidence strength; exact
WHO n / WHAT n / DIMENSION n references in a query get a flat bonus so they outrank documents that merely contain the number.
A live test of kb_fetch against the real release is opt-in: OPENWEBNET_LIVE_TESTS=1 pytest -m network.
| WHO | Subsystem | Official Title | Status | HA Platform |
|---|---|---|---|---|
| 0 | Scenarios (Basic) | WHO_0.pdf |
🟢 Archived | event |
| 1 | Lighting | WHO_1.pdf |
🟢 Archived | light |
| 2 | Automation (Covers) | WHO_2.pdf |
🟢 Archived | cover |
| 3 | Load Control | WHO_3.pdf |
🟡 Legacy | switch, sensor |
| 4 | Thermoregulation | WHO_4 2.pdf |
🟢 Archived | climate, sensor |
| 5 | Burglar Alarm | WHO_5.pdf |
🟢 Archived | alarm_control_panel |
| 6 | Door Entry Call & Lock | WHO_6.pdf |
🟡 Legacy | lock, event |
| 7 | Video Door Entry | WHO_7.pdf |
🟢 Archived | camera |
| 9 | Auxiliary | WHO_9.pdf |
🟡 Legacy | switch |
| 13 | Gateway Management | WHO_13.pdf |
🟢 Archived | Diagnostics |
| 14 | Actuators & Lock | (Reverse-Engineered) | 🟢 Documented | Diagnostics, lock |
| 15 | CEN Pushbuttons | WHO_15.pdf |
🟢 Archived | event |
| 16 | Sound System | WHO_16.pdf |
🟢 Archived | media_player |
| 17 | MH200N Scenarios | WHO_17.pdf |
🟢 Archived | event |
| 18 | Energy Management | WHO_18.pdf |
🟢 Archived | sensor |
| 22 | Sound Diffusion (Ext) | WHO_22.pdf |
🟢 Archived | media_player |
| 24 | Lighting / DALI | WHO_24.pdf |
🟢 Archived | light |
| 25 | CEN+ / Dry Contacts | WHO_25.pdf |
🟢 Archived | event, binary_sensor |
| 1001 | Bus Diagnostics | WHO_1001.pdf |
🟢 Archived | Diagnostics |
| 1004 | Heating Diagnostics | WHO_1004.pdf |
🟢 Archived | Diagnostics |
| 1013 | Gateway Diagnostics | WHO_1013.pdf |
🟢 Archived | Diagnostics |
Run unit tests and verify coverage with pytest:
pip install -e ".[dev]"
pytest --cov=src/openwebnet_mcp --cov-report=term-missingMIT License. Copyright (c) 2026 OpenWebNet-HA Community.