zont-mcp 1.3.2__tar.gz

zont_mcp-1.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zont-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zont_mcp-1.3.2/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: zont-mcp
+Version: 1.3.2
+Summary: MCP server for ZONT heating system control via AI / MCP-сервер для управления системой отопления ZONT через ИИ
+Author: MAB2908
+License: MIT License
+        
+        Copyright (c) 2026 zont-mcp contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/MAB2908/zont-mcp
+Project-URL: Issues, https://github.com/MAB2908/zont-mcp/issues
+Project-URL: Changelog, https://github.com/MAB2908/zont-mcp/blob/main/CHANGELOG.md
+Keywords: zont,mcp,heating,smart-home,baxi,opentherm,claude
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]<2,>=1.3.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-dotenv>=1.0.0
+Dynamic: license-file
+
+# zont-mcp
+
+**[README на русском](README.ru.md)**
+
+A local MCP server that gives AI assistants natural-language control over ZONT heating systems (BAXI Connect+ and compatible controllers) — reading state, switching modes, boiler telemetry, diagnostics and configuration writes.
+
+## Demo
+
+A conversation once the server is connected to any MCP client (Claude, Cursor, VS Code, …):
+
+```
+You:      Any boiler errors right now? If yes — what should I do?
+Assistant: (calls get_boiler_errors)
+          No active faults. Fault flags: none.
+          Telemetry: flow temp 54.2 °C, setpoint 55 °C, modulation 34%, status: ch, flame.
+
+You:      We're cold. Run a diagnosis.
+Assistant: (calls diagnose_heating)
+          Status: warning. The "Boiler circuit" has no active mode — it was
+          lost after a controller reboot. Fix: enable the mode.
+          (calls set_heating_mode, then get_device_state to verify)
+          Done — mode "Comfort" is active, target 21.5 °C.
+```
+
+How it works:
+
+```
+┌─────────────┐   MCP (stdio)   ┌──────────┐   HTTPS    ┌─────────────────┐
+│ AI assistant │ ◄──────────────► │ zont-mcp │ ─────────► │  ZONT cloud API │
+└─────────────┘                  └──────────┘            └────────┬────────┘
+                                                                     │
+                                                            ┌────────▼────────┐
+                                                            │  ZONT controller │
+                                                            │  + boiler (bus)  │
+                                                            └─────────────────┘
+```
+
+The server runs locally, opens no network ports and talks to exactly two official
+ZONT endpoints over HTTPS (`my.zont.online/api` and `lk.zont-online.ru/api`).
+
+## Quick start
+
+Requirements: Python 3.11+, a ZONT account (zont-online.ru) with a registered device,
+any MCP-compatible client.
+
+```bash
+pip install zont-mcp        # from PyPI (Python Package Index)
+# — or from source —
+git clone https://github.com/MAB2908/zont-mcp.git && cd zont-mcp
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+Get your API token: set `ZONT_LOGIN` + `ZONT_PASSWORD`, run `zont-mcp` once —
+the token is printed to stderr; then keep only the token.
+
+Add to your MCP client (Claude Desktop `claude_desktop_config.json` shown; Cursor,
+VS Code and others use the same fields — see [docs/setup.md](docs/setup.md) for all snippets):
+
+```json
+{
+  "mcpServers": {
+    "zont": {
+      "command": "zont-mcp",
+      "env": {
+        "ZONT_CLIENT_EMAIL": "your@email.com",
+        "ZONT_TOKEN": "your_token"
+      }
+    }
+  }
+}
+```
+
+Ask your assistant:
+
+```
+Show the list of my ZONT devices.
+```
+
+Credentials live only in environment variables / a local `.env` file — never in
+code. Full installation and configuration guide: [docs/setup.md](docs/setup.md)
+([по-русски](docs/setup.ru.md)).
+
+## Features
+
+- **38 tools in 7 groups**: device state, heating control, I/O and guard zones, history, analytics, configuration, commands & archives
+- **Boiler OpenTherm telemetry** — flow temperature, setpoint, burner modulation, status flags
+- **Diagnostics with recommendations** — known failure signatures: lost bus connection, mode reset after reboot, low pressure, dead radio sensors
+- **Configuration writes at web-cabinet level** — circuits, modes, sensors, weather-compensation curve; every write is backed up and verified by re-reading
+- **Works with any MCP client** — Claude Desktop, Claude Code, Cursor, VS Code, ZCode
+- **Safety by design** — dangerous firmware commands (restart, deletion, SMS/calls) deliberately excluded; device passwords masked in responses
+
+## Comparison
+
+The closest analogue is [`defanator/zont_api`](https://github.com/defanator/zont_api) —
+a Python library for the ZONT API. `zont-mcp` used it as a knowledge source for the
+`z3k_boiler_adapter` data format.
+
+| Aspect | defanator/zont_api | zont-mcp |
+|--------|--------------------|----------|
+| Purpose | Python library for developers | MCP server for AI assistants |
+| Interface | `import zont_api` in code | Natural language via any MCP client |
+| Boiler control | No | Yes — modes, temperatures, relays |
+| Configuration writes | No | Yes — circuits, modes, sensors, weather curve |
+| Radio sensor history | No | Yes |
+| Diagnostics & analytics | No | Yes |
+| Event journal | No | Yes |
+| Prometheus exporter / CSV | Yes | No |
+| Tests | pytest, tox, CI | unittest + GitHub Actions |
+
+Choose `zont-mcp` when you want to *talk* to your heating system; choose
+`zont_api` when you build your own Python software against the API.
+
+## Documentation & more examples
+
+| Document | Purpose |
+|----------|---------|
+| [docs/setup.md](docs/setup.md) | Full installation guide: token, all MCP clients, troubleshooting ([по-русски](docs/setup.ru.md)) |
+| [AGENTS.md](AGENTS.md) | Working rules for AI agents (English + [Russian](AGENTS.ru.md)) |
+| [CAPABILITIES.md](CAPABILITIES.md) | Everything the server can and cannot do; z3k command dictionary |
+| [examples/heating-check/](examples/heating-check/) | Example: full diagnostic session |
+| [examples/vacation-mode/](examples/vacation-mode/) | Example: "leaving for a week" scenario |
+| [examples/python-client/](examples/python-client/) | Example: use the API client directly from Python |
+| [CHANGELOG.md](CHANGELOG.md) | Release history (English + Russian) |
+| [SECURITY.md](SECURITY.md) | Credential handling, vulnerability reporting |
+
+## Badges
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://github.com/MAB2908/zont-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/MAB2908/zont-mcp/actions/workflows/tests.yml)
+[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) — how to set up the project, run tests and
+submit changes. Simple starter tasks are marked
+[`good first issue`](https://github.com/MAB2908/zont-mcp/labels/good%20first%20issue).
+
+## License
+
+MIT — see [LICENSE](LICENSE). This is an independent project, not affiliated with
+ZONT or Micro Line; it uses only the official public ZONT API.

zont_mcp-1.3.2/README.md

@@ -0,0 +1,143 @@
+# zont-mcp
+
+**[README на русском](README.ru.md)**
+
+A local MCP server that gives AI assistants natural-language control over ZONT heating systems (BAXI Connect+ and compatible controllers) — reading state, switching modes, boiler telemetry, diagnostics and configuration writes.
+
+## Demo
+
+A conversation once the server is connected to any MCP client (Claude, Cursor, VS Code, …):
+
+```
+You:      Any boiler errors right now? If yes — what should I do?
+Assistant: (calls get_boiler_errors)
+          No active faults. Fault flags: none.
+          Telemetry: flow temp 54.2 °C, setpoint 55 °C, modulation 34%, status: ch, flame.
+
+You:      We're cold. Run a diagnosis.
+Assistant: (calls diagnose_heating)
+          Status: warning. The "Boiler circuit" has no active mode — it was
+          lost after a controller reboot. Fix: enable the mode.
+          (calls set_heating_mode, then get_device_state to verify)
+          Done — mode "Comfort" is active, target 21.5 °C.
+```
+
+How it works:
+
+```
+┌─────────────┐   MCP (stdio)   ┌──────────┐   HTTPS    ┌─────────────────┐
+│ AI assistant │ ◄──────────────► │ zont-mcp │ ─────────► │  ZONT cloud API │
+└─────────────┘                  └──────────┘            └────────┬────────┘
+                                                                     │
+                                                            ┌────────▼────────┐
+                                                            │  ZONT controller │
+                                                            │  + boiler (bus)  │
+                                                            └─────────────────┘
+```
+
+The server runs locally, opens no network ports and talks to exactly two official
+ZONT endpoints over HTTPS (`my.zont.online/api` and `lk.zont-online.ru/api`).
+
+## Quick start
+
+Requirements: Python 3.11+, a ZONT account (zont-online.ru) with a registered device,
+any MCP-compatible client.
+
+```bash
+pip install zont-mcp        # from PyPI (Python Package Index)
+# — or from source —
+git clone https://github.com/MAB2908/zont-mcp.git && cd zont-mcp
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+Get your API token: set `ZONT_LOGIN` + `ZONT_PASSWORD`, run `zont-mcp` once —
+the token is printed to stderr; then keep only the token.
+
+Add to your MCP client (Claude Desktop `claude_desktop_config.json` shown; Cursor,
+VS Code and others use the same fields — see [docs/setup.md](docs/setup.md) for all snippets):
+
+```json
+{
+  "mcpServers": {
+    "zont": {
+      "command": "zont-mcp",
+      "env": {
+        "ZONT_CLIENT_EMAIL": "your@email.com",
+        "ZONT_TOKEN": "your_token"
+      }
+    }
+  }
+}
+```
+
+Ask your assistant:
+
+```
+Show the list of my ZONT devices.
+```
+
+Credentials live only in environment variables / a local `.env` file — never in
+code. Full installation and configuration guide: [docs/setup.md](docs/setup.md)
+([по-русски](docs/setup.ru.md)).
+
+## Features
+
+- **38 tools in 7 groups**: device state, heating control, I/O and guard zones, history, analytics, configuration, commands & archives
+- **Boiler OpenTherm telemetry** — flow temperature, setpoint, burner modulation, status flags
+- **Diagnostics with recommendations** — known failure signatures: lost bus connection, mode reset after reboot, low pressure, dead radio sensors
+- **Configuration writes at web-cabinet level** — circuits, modes, sensors, weather-compensation curve; every write is backed up and verified by re-reading
+- **Works with any MCP client** — Claude Desktop, Claude Code, Cursor, VS Code, ZCode
+- **Safety by design** — dangerous firmware commands (restart, deletion, SMS/calls) deliberately excluded; device passwords masked in responses
+
+## Comparison
+
+The closest analogue is [`defanator/zont_api`](https://github.com/defanator/zont_api) —
+a Python library for the ZONT API. `zont-mcp` used it as a knowledge source for the
+`z3k_boiler_adapter` data format.
+
+| Aspect | defanator/zont_api | zont-mcp |
+|--------|--------------------|----------|
+| Purpose | Python library for developers | MCP server for AI assistants |
+| Interface | `import zont_api` in code | Natural language via any MCP client |
+| Boiler control | No | Yes — modes, temperatures, relays |
+| Configuration writes | No | Yes — circuits, modes, sensors, weather curve |
+| Radio sensor history | No | Yes |
+| Diagnostics & analytics | No | Yes |
+| Event journal | No | Yes |
+| Prometheus exporter / CSV | Yes | No |
+| Tests | pytest, tox, CI | unittest + GitHub Actions |
+
+Choose `zont-mcp` when you want to *talk* to your heating system; choose
+`zont_api` when you build your own Python software against the API.
+
+## Documentation & more examples
+
+| Document | Purpose |
+|----------|---------|
+| [docs/setup.md](docs/setup.md) | Full installation guide: token, all MCP clients, troubleshooting ([по-русски](docs/setup.ru.md)) |
+| [AGENTS.md](AGENTS.md) | Working rules for AI agents (English + [Russian](AGENTS.ru.md)) |
+| [CAPABILITIES.md](CAPABILITIES.md) | Everything the server can and cannot do; z3k command dictionary |
+| [examples/heating-check/](examples/heating-check/) | Example: full diagnostic session |
+| [examples/vacation-mode/](examples/vacation-mode/) | Example: "leaving for a week" scenario |
+| [examples/python-client/](examples/python-client/) | Example: use the API client directly from Python |
+| [CHANGELOG.md](CHANGELOG.md) | Release history (English + Russian) |
+| [SECURITY.md](SECURITY.md) | Credential handling, vulnerability reporting |
+
+## Badges
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://github.com/MAB2908/zont-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/MAB2908/zont-mcp/actions/workflows/tests.yml)
+[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) — how to set up the project, run tests and
+submit changes. Simple starter tasks are marked
+[`good first issue`](https://github.com/MAB2908/zont-mcp/labels/good%20first%20issue).
+
+## License
+
+MIT — see [LICENSE](LICENSE). This is an independent project, not affiliated with
+ZONT or Micro Line; it uses only the official public ZONT API.

zont_mcp-1.3.2/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zont-mcp"
+version = "1.3.2"
+description = "MCP server for ZONT heating system control via AI / MCP-сервер для управления системой отопления ZONT через ИИ"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [{ name = "MAB2908" }]
+keywords = ["zont", "mcp", "heating", "smart-home", "baxi", "opentherm", "claude"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+]
+dependencies = [
+    "mcp[cli]>=1.3.0,<2",
+    "httpx>=0.27.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.scripts]
+zont-mcp = "server:main"
+
+[project.urls]
+Homepage = "https://github.com/MAB2908/zont-mcp"
+Issues = "https://github.com/MAB2908/zont-mcp/issues"
+Changelog = "https://github.com/MAB2908/zont-mcp/blob/main/CHANGELOG.md"
+
+[tool.setuptools]
+py-modules = ["server", "zont_client"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

zont_mcp-1.3.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zont_mcp-1.3.2/src/server.py

@@ -0,0 +1,127 @@
+r"""
+ZONT MCP Server
+===============
+MCP server for controlling the ZONT heating system via AI assistants.
+MCP-сервер для управления системой отопления ZONT через ИИ.
+
+Transport:      stdio (standard for local MCP servers)
+Authentication: ZONT auth token via environment variables
+
+Environment variables:
+    ZONT_CLIENT_EMAIL — account email address (required)
+    ZONT_TOKEN        — auth token (preferred; avoids login on each run)
+    ZONT_LOGIN        — login (used only for initial token retrieval)
+    ZONT_PASSWORD     — password (used only for initial token retrieval)
+
+Claude Desktop configuration (add to claude_desktop_config.json):
+    {
+        "mcpServers": {
+            "zont": {
+                "command": "/path/to/.venv/bin/python",
+                "args": ["/path/to/zont-mcp/src/server.py"],
+                "env": {
+                    "ZONT_CLIENT_EMAIL": "your@email.com",
+                    "ZONT_TOKEN": "your_token"
+                }
+            }
+        }
+    }
+
+Windows note: Claude Desktop installed from the Microsoft Store (MSIX) reads its
+config from a virtualised path, NOT from %APPDATA%\Claude\:
+    %LOCALAPPDATA%/Packages/Claude_pzs8sxrjxfjjc/LocalCache/Roaming/Claude/claude_desktop_config.json
+"""
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+# Load .env from project root (one level above src/)
+load_dotenv(Path(__file__).parent.parent / ".env")
+
+# Add src/ to sys.path so tool modules can import zont_client without a package install
+sys.path.insert(0, os.path.dirname(__file__))
+
+from mcp.server.fastmcp import FastMCP
+
+from tools import analytics, commands, config, control, devices, heating, history
+from zont_client import ZontAPIError, ZontClient
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    stream=sys.stderr,
+)
+logger = logging.getLogger("zont-mcp")
+
+
+def create_server() -> FastMCP:
+    """
+    Initialise and configure the MCP server.
+
+    Creates the FastMCP instance, authenticates the ZONT client, and registers
+    all tool groups. Exits with status 1 if authentication fails.
+    """
+    mcp = FastMCP(
+        name="zont-mcp",
+        instructions=(
+            "MCP server for controlling the ZONT heating system via AI. "
+            "Supports all ZONT devices: BAXI Connect+, H-2000+, SMART NEW, Climatic, etc. "
+            "Tools: state reading, heating control, history, guard zones, diagnostics."
+        ),
+    )
+
+    # Initialise the API client from environment variables
+    try:
+        client = ZontClient.from_env()
+    except ZontAPIError as e:
+        logger.error("Failed to initialise ZONT client: %s", e)
+        sys.exit(1)
+
+    # Obtain token via login/password if no token is configured
+    if not client.token:
+        if client.login and client.password:
+            logger.info("No token set, requesting via get_authtoken...")
+            try:
+                token = client.get_authtoken()
+                logger.info("Token obtained successfully.")
+                # Print to stderr so the user can persist it in ZONT_TOKEN
+                print(
+                    f"[ZONT MCP] Token obtained: {token}\n"
+                    f"Save it to ZONT_TOKEN to avoid re-authenticating on each start.",
+                    file=sys.stderr,
+                )
+            except ZontAPIError as e:
+                logger.error("Failed to obtain token: %s", e)
+                sys.exit(1)
+        else:
+            logger.error(
+                "Neither ZONT_TOKEN nor ZONT_LOGIN+ZONT_PASSWORD are set."
+            )
+            sys.exit(1)
+
+    # Register tool groups. Each module's register() function attaches its
+    # @mcp.tool() decorated functions to the FastMCP instance.
+    devices.register(mcp, client)   # Group 1: device state
+    heating.register(mcp, client)   # Group 2: heating control
+    control.register(mcp, client)   # Group 3: I/O and guard zones
+    history.register(mcp, client)   # Group 4: history and events
+    analytics.register(mcp, client) # Group 5: analytics and diagnostics
+    config.register(mcp, client)    # Group 6: configuration read/write
+    commands.register(mcp, client)  # Group 7: extra commands and archives
+
+    logger.info("ZONT MCP server started. Client: %s.", client.client_email)
+    return mcp
+
+
+def main():
+    """Entry point. Creates the server and runs it over stdio transport."""
+    mcp = create_server()
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

zont_mcp-1.3.2/src/tools/__init__.py

@@ -0,0 +1,4 @@
+# ZONT MCP Tools
+from tools import analytics, commands, config, control, devices, heating, history
+
+__all__ = ["analytics", "commands", "config", "control", "devices", "heating", "history"]