# OpenWebNet-MCP Server

[![CI Pipeline](https://github.com/OpenWebNet-HA/openwebnet-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenWebNet-HA/openwebnet-mcp/actions/workflows/ci.yml)
[![Platform Validation](https://img.shields.io/badge/Platforms-Windows%20%7C%20macOS%20%7C%20Linux-success?logo=githubactions)](https://github.com/OpenWebNet-HA/openwebnet-mcp/actions/workflows/ci.yml)
[![Python Support](https://img.shields.io/badge/Python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue?logo=python)](https://github.com/OpenWebNet-HA/openwebnet-mcp/actions/workflows/ci.yml)
![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)

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

---

## 🚀 Quick Start

### 1. Add to your MCP Client Configuration

#### Claude Desktop / Cursor / VS Code (`mcp.json`):
```json
{
  "mcpServers": {
    "openwebnet-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/OpenWebNet-HA/openwebnet-mcp.git", "openwebnet-mcp"]
    }
  }
}
```

#### Local Development Run:
```json
{
  "mcpServers": {
    "openwebnet-mcp": {
      "command": "python",
      "args": ["-m", "openwebnet_mcp.server"],
      "cwd": "/path/to/openwebnet-mcp"
    }
  }
}
```

---

## 🤖 Agentic Interaction Examples

Once connected, your AI coding assistant can browse documentation, interpret frames, and generate verified code autonomously.

### Example 1: Decode a Bus Monitor Frame
**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:**
1. Calls `parse_and_validate_frame("*#4*1*#14*0215*1##")`.
2. Resolves WHO=4 (Heating/Thermoregulation), Dimension 14 (Target Temperature & Mode), Zone 1, Target 21.5°C, Mode 1 (Heating).
3. Returns human-readable breakdown and lists compatible thermostat units (3550, L4691).

### Example 2: Configure CEN+ Scenario Pushbuttons
**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:**
1. Calls `get_ha_guide("cen_scenarios")` to review the CEN vs CEN+ specifications and Home Assistant blueprint.
2. 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##`.
3. Calls `draft_ha_config(platform="light", ...)` to draft the complete automation YAML.

### Example 3: Solve Light Transition Inconsistencies
**User Prompt:**
> "My dimmable lights jump instantly to brightness instead of ramping smoothly when I pass `transition: 5`. Why?"

**AI Agent Action:**
1. Calls `search_documentation("transition stepped dimming")`.
2. Reads the technical design document explaining hardware ramp limitations in older F411/F418 actuators vs software-emulated stepped dimming.
3. Suggests the proper configuration and command sequence.

---

## 🛠️ Tools & Resources Reference

### MCP Tools (14)

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

### MCP Resources (5)

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

### MCP Prompts (1)

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

#### Using `/boost` in MCP Clients
In Claude Desktop, Cursor, or Antigravity, trigger the prompt by typing `/boost` or selecting it from the prompt menu:
```text
/boost topic: lighting
```
The server primes the LLM with strict frame grammar rules, hardware capabilities, and modern Home Assistant configuration standards, eliminating hallucinated syntax.

---

## 🧠 Machine KB (Encyclopedia knowledge base)

`search_knowledge`, `get_knowledge_record` and `get_knowledge_status` read the
[OpenWebNet Encyclopedia Machine KB](https://github.com/OpenWebNet-HA/OpenWebNet-Encyclopedia/tree/main/knowledge)
(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:

```bash
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.0
```

Hash 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](https://github.com/OpenWebNet-HA/OpenWebNet-Encyclopedia/issues/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`.

## 📚 Master WHO Family Inventory

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

---

## 🧪 Testing

Run unit tests and verify coverage with `pytest`:

```bash
pip install -e ".[dev]"
pytest --cov=src/openwebnet_mcp --cov-report=term-missing
```

---

## 📄 License

Apache License 2.0, the same license as Home Assistant Core. See [LICENSE](LICENSE). Copyright (c) 2026 OpenWebNet-HA Community.