aivy-mcp 0.1.0__tar.gz

aivy_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.env

aivy_mcp-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Ivy Energy
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

aivy_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: aivy-mcp
+Version: 0.1.0
+Summary: MCP server for the Aivy Developer API: let your AI assistant read and control your own solar + battery system.
+Project-URL: Homepage, https://github.com/IVYEnergy/aivy-mcp
+Project-URL: Documentation, https://bridge.ivyenergy.com.au/v1/docs
+Project-URL: API guide, https://bridge.ivyenergy.com.au/v1/llms.txt
+Author: Ivy Energy
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: amber,battery,energy,home-energy,mcp,sigenergy,solar,sungrow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2
+Description-Content-Type: text/markdown
+
+# aivy-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that lets your own AI assistant
+(Claude Code, Claude Desktop, ChatGPT, Codex, Cursor, ...) read and control
+**your own** solar + battery system through the
+[Aivy Developer API](https://bridge.ivyenergy.com.au/v1/docs) by Ivy Energy.
+
+Works with every brand Aivy runs: Sungrow, Sigenergy, FoxESS, AlphaESS, SolaX
+and more. The same tools, whatever the inverter.
+
+## 1. Get a key
+
+In the Aivy app (web or mobile) open the user menu, **API keys**, and create a
+key. Pick **Read only** to let an assistant look, or **Read and control** to
+let it change the energy mode and Ai+ settings. The key sees exactly what your
+account sees, nothing more.
+
+## 2. Add the server
+
+Claude Code:
+
+```bash
+claude mcp add aivy -e AIVY_API_KEY=aivy_sk_... -- uvx aivy-mcp
+```
+
+Claude Desktop / Cursor / any MCP client (`mcpServers` block):
+
+```json
+{
+  "mcpServers": {
+    "aivy": {
+      "command": "uvx",
+      "args": ["aivy-mcp"],
+      "env": { "AIVY_API_KEY": "aivy_sk_..." }
+    }
+  }
+}
+```
+
+No `uv`? `pipx run aivy-mcp` or `pip install aivy-mcp && aivy-mcp` work too.
+
+Assistants that cannot run local tools (ChatGPT in the browser) can use the
+HTTP API directly. Paste this into the chat:
+
+> Use the Aivy Developer API at https://bridge.ivyenergy.com.au/v1 with the
+> header `Authorization: Bearer aivy_sk_...`. Read
+> https://bridge.ivyenergy.com.au/v1/llms.txt first, then GET /sites.
+
+## 3. Ask
+
+- "How's my battery doing?"
+- "Why did it charge at 3am?"
+- "What are prices doing tonight? Should I sell?"
+- "Plan the best time to sell tonight, keep 20%, then apply it."
+- "Charge at 5 kW to 90% for the next two hours." (control key)
+- "Make Ai+ a bit more aggressive on exports." (control key)
+
+## Tools
+
+| Tool | Changes anything? | What it does |
+|---|---|---|
+| `whoami` | no | Who the key is, read or control |
+| `list_sites` | no | Your sites; ids look like `sungrow:1445844` |
+| `get_site` | no | Capacity, limits, timezone, mode, live SOC |
+| `get_status` | no | Live SOC and power flows |
+| `get_curve` | no | 5-minute or daily history |
+| `get_earnings` | no | A day's energy, priced at Amber's actual prices |
+| `get_operations` | no | What the platform did and why |
+| `get_prices` | no | Amber prices now and forecast |
+| `get_energy_mode` | no | Mode, windows, pending hand-back |
+| `set_energy_mode` | **yes** | selfConsumption / amber_smart (Ai+) / forced (time-boxed) |
+| `get_ai_plus` | no | Ai+ variant, settings and tunable ranges |
+| `update_ai_plus` | **yes** | Change Ai+ levers or variant |
+| `plan_best_price_discharge` | no | Propose a sell schedule from the forecast |
+| `plan_discharge_to_target` | no | Propose a discharge that lands on a SOC at a time |
+
+## What the server enforces, whatever the assistant does
+
+- A key sees only its owner's sites; writes need the control scope.
+- A forced (manual) mode set through the API **always reverts** to the previous
+  mode after `duration_minutes` (default 4 h, max 24 h).
+- The SOC floor and grid export limits cannot be overridden.
+- Every call is recorded with the key id and client; keys can be revoked in
+  the app at any time and stop working immediately.
+- Per-key rate limit (default 120/min). Readings refresh about once a minute.
+
+## Development
+
+```bash
+git clone https://github.com/IVYEnergy/aivy-mcp && cd aivy-mcp
+uv run --with pytest pytest
+uv run aivy-mcp            # needs AIVY_API_KEY
+```
+
+The package also lives in Ivy Energy's main repository under `sdk/aivy-mcp`;
+this public repository is where it is released from.
+
+Point at another deployment with `AIVY_API_URL=https://host/v1`.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).

aivy_mcp-0.1.0/README.md

@@ -0,0 +1,102 @@
+# aivy-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that lets your own AI assistant
+(Claude Code, Claude Desktop, ChatGPT, Codex, Cursor, ...) read and control
+**your own** solar + battery system through the
+[Aivy Developer API](https://bridge.ivyenergy.com.au/v1/docs) by Ivy Energy.
+
+Works with every brand Aivy runs: Sungrow, Sigenergy, FoxESS, AlphaESS, SolaX
+and more. The same tools, whatever the inverter.
+
+## 1. Get a key
+
+In the Aivy app (web or mobile) open the user menu, **API keys**, and create a
+key. Pick **Read only** to let an assistant look, or **Read and control** to
+let it change the energy mode and Ai+ settings. The key sees exactly what your
+account sees, nothing more.
+
+## 2. Add the server
+
+Claude Code:
+
+```bash
+claude mcp add aivy -e AIVY_API_KEY=aivy_sk_... -- uvx aivy-mcp
+```
+
+Claude Desktop / Cursor / any MCP client (`mcpServers` block):
+
+```json
+{
+  "mcpServers": {
+    "aivy": {
+      "command": "uvx",
+      "args": ["aivy-mcp"],
+      "env": { "AIVY_API_KEY": "aivy_sk_..." }
+    }
+  }
+}
+```
+
+No `uv`? `pipx run aivy-mcp` or `pip install aivy-mcp && aivy-mcp` work too.
+
+Assistants that cannot run local tools (ChatGPT in the browser) can use the
+HTTP API directly. Paste this into the chat:
+
+> Use the Aivy Developer API at https://bridge.ivyenergy.com.au/v1 with the
+> header `Authorization: Bearer aivy_sk_...`. Read
+> https://bridge.ivyenergy.com.au/v1/llms.txt first, then GET /sites.
+
+## 3. Ask
+
+- "How's my battery doing?"
+- "Why did it charge at 3am?"
+- "What are prices doing tonight? Should I sell?"
+- "Plan the best time to sell tonight, keep 20%, then apply it."
+- "Charge at 5 kW to 90% for the next two hours." (control key)
+- "Make Ai+ a bit more aggressive on exports." (control key)
+
+## Tools
+
+| Tool | Changes anything? | What it does |
+|---|---|---|
+| `whoami` | no | Who the key is, read or control |
+| `list_sites` | no | Your sites; ids look like `sungrow:1445844` |
+| `get_site` | no | Capacity, limits, timezone, mode, live SOC |
+| `get_status` | no | Live SOC and power flows |
+| `get_curve` | no | 5-minute or daily history |
+| `get_earnings` | no | A day's energy, priced at Amber's actual prices |
+| `get_operations` | no | What the platform did and why |
+| `get_prices` | no | Amber prices now and forecast |
+| `get_energy_mode` | no | Mode, windows, pending hand-back |
+| `set_energy_mode` | **yes** | selfConsumption / amber_smart (Ai+) / forced (time-boxed) |
+| `get_ai_plus` | no | Ai+ variant, settings and tunable ranges |
+| `update_ai_plus` | **yes** | Change Ai+ levers or variant |
+| `plan_best_price_discharge` | no | Propose a sell schedule from the forecast |
+| `plan_discharge_to_target` | no | Propose a discharge that lands on a SOC at a time |
+
+## What the server enforces, whatever the assistant does
+
+- A key sees only its owner's sites; writes need the control scope.
+- A forced (manual) mode set through the API **always reverts** to the previous
+  mode after `duration_minutes` (default 4 h, max 24 h).
+- The SOC floor and grid export limits cannot be overridden.
+- Every call is recorded with the key id and client; keys can be revoked in
+  the app at any time and stop working immediately.
+- Per-key rate limit (default 120/min). Readings refresh about once a minute.
+
+## Development
+
+```bash
+git clone https://github.com/IVYEnergy/aivy-mcp && cd aivy-mcp
+uv run --with pytest pytest
+uv run aivy-mcp            # needs AIVY_API_KEY
+```
+
+The package also lives in Ivy Energy's main repository under `sdk/aivy-mcp`;
+this public repository is where it is released from.
+
+Point at another deployment with `AIVY_API_URL=https://host/v1`.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).

aivy_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aivy-mcp"
+version = "0.1.0"
+description = "MCP server for the Aivy Developer API: let your AI assistant read and control your own solar + battery system."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "Ivy Energy" }]
+keywords = ["mcp", "solar", "battery", "energy", "amber", "sungrow", "sigenergy", "home-energy"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: End Users/Desktop",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Home Automation",
+]
+dependencies = [
+  "mcp>=1.2",
+  "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/IVYEnergy/aivy-mcp"
+Documentation = "https://bridge.ivyenergy.com.au/v1/docs"
+"API guide" = "https://bridge.ivyenergy.com.au/v1/llms.txt"
+
+[project.scripts]
+aivy-mcp = "aivy_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aivy_mcp"]

aivy_mcp-0.1.0/src/aivy_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""aivy-mcp: an MCP server over the Aivy Developer API."""
+
+__version__ = "0.1.0"

aivy_mcp-0.1.0/src/aivy_mcp/client.py

@@ -0,0 +1,103 @@
+"""Thin HTTP client for the Aivy Developer API.
+
+Everything the MCP tools do is one HTTP call here. Kept separate so the same
+client can back a CLI or a notebook without the MCP machinery.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+DEFAULT_API_URL = "https://bridge.ivyenergy.com.au/v1"
+
+
+class AivyError(RuntimeError):
+    """The API refused or could not complete a request. The message carries
+    the server's `detail`, which is written to be read by a person or model."""
+
+
+class AivyClient:
+    def __init__(self, api_key: str | None = None, api_url: str | None = None, timeout: float = 30.0):
+        self.api_key = api_key or os.environ.get("AIVY_API_KEY", "")
+        self.api_url = (api_url or os.environ.get("AIVY_API_URL") or DEFAULT_API_URL).rstrip("/")
+        if not self.api_key:
+            raise AivyError("AIVY_API_KEY is not set. Create a key in the Aivy app (menu, API keys) and "
+                            "export AIVY_API_KEY=aivy_sk_...")
+        self._http = httpx.AsyncClient(
+            base_url=self.api_url, timeout=timeout,
+            headers={"Authorization": f"Bearer {self.api_key}", "User-Agent": f"aivy-mcp/{_version()}"},
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _call(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            response = await self._http.request(method, path, **kwargs)
+        except httpx.HTTPError as e:
+            raise AivyError(f"could not reach the Aivy API at {self.api_url}: {e}") from e
+        if response.status_code >= 400:
+            try:
+                detail = response.json().get("detail")
+            except ValueError:
+                detail = response.text
+            raise AivyError(f"{response.status_code}: {detail}")
+        return response.json()
+
+    # ── account / sites ──
+    async def me(self) -> dict:
+        return await self._call("GET", "/me")
+
+    async def sites(self) -> dict:
+        return await self._call("GET", "/sites")
+
+    async def site(self, site_id: str) -> dict:
+        return await self._call("GET", f"/sites/{site_id}")
+
+    async def status(self, site_id: str) -> dict:
+        return await self._call("GET", f"/sites/{site_id}/status")
+
+    async def curve(self, site_id: str, range_: str = "1d", day: str | None = None) -> dict:
+        params = {"range": range_}
+        if day:
+            params["day"] = day
+        return await self._call("GET", f"/sites/{site_id}/curve", params=params)
+
+    async def earnings(self, site_id: str, date: str | None = None, window_start: str | None = None,
+                       window_end: str | None = None) -> dict:
+        params = {k: v for k, v in {"date": date, "window_start": window_start, "window_end": window_end}.items() if v}
+        return await self._call("GET", f"/sites/{site_id}/earnings", params=params)
+
+    async def operations(self, site_id: str, limit: int = 20) -> dict:
+        return await self._call("GET", f"/sites/{site_id}/operations", params={"limit": limit})
+
+    async def prices(self, site_id: str, hours: int = 8, resolution: int = 30) -> dict:
+        return await self._call("GET", f"/sites/{site_id}/prices", params={"hours": hours, "resolution": resolution})
+
+    # ── control ──
+    async def energy_mode(self, site_id: str) -> dict:
+        return await self._call("GET", f"/sites/{site_id}/energy-mode")
+
+    async def set_energy_mode(self, site_id: str, body: dict) -> dict:
+        return await self._call("PUT", f"/sites/{site_id}/energy-mode", json=body)
+
+    async def ai_plus(self, site_id: str) -> dict:
+        return await self._call("GET", f"/sites/{site_id}/ai-plus")
+
+    async def patch_ai_plus(self, site_id: str, variant: str | None, settings: dict) -> dict:
+        return await self._call("PATCH", f"/sites/{site_id}/ai-plus", json={"variant": variant, "settings": settings})
+
+    # ── planning ──
+    async def plan_best_price_discharge(self, site_id: str, body: dict) -> dict:
+        return await self._call("POST", f"/sites/{site_id}/plans/best-price-discharge", json=body)
+
+    async def plan_discharge_to_target(self, site_id: str, body: dict) -> dict:
+        return await self._call("POST", f"/sites/{site_id}/plans/discharge-to-target", json=body)
+
+
+def _version() -> str:
+    from aivy_mcp import __version__
+    return __version__

aivy_mcp-0.1.0/src/aivy_mcp/server.py

@@ -0,0 +1,210 @@
+"""MCP server exposing the Aivy Developer API as tools.
+
+Run with `uvx aivy-mcp` (stdio). Configuration by environment:
+
+    AIVY_API_KEY   personal key from the Aivy app (required)
+    AIVY_API_URL   API base, default https://bridge.ivyenergy.com.au/v1
+
+Tool descriptions are the contract the model reads, so they say what a
+call changes, what it cannot change, and what the server will do on its
+own (hand a forced mode back after its duration).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+try:  # mcp 2.x
+    from mcp.server.mcpserver import MCPServer as _Server
+except ModuleNotFoundError:  # mcp 1.x
+    from mcp.server.fastmcp import FastMCP as _Server
+
+from aivy_mcp.client import AivyClient, AivyError
+
+mcp = _Server(
+    "aivy",
+    instructions=(
+        "Tools for the user's own solar + battery system through the Aivy platform (Ivy Energy, Australia). "
+        "Call list_sites first; every other tool takes one of its site ids (vendor:station_id). "
+        "Power is in watts (battery_w > 0 charging, grid_w > 0 exporting), SOC in percent, prices in "
+        "Australian cents per kWh. Readings refresh about once a minute: do not poll faster. "
+        "Changing the mode or Ai+ settings needs a control-scope key; a forced (manual) mode set here is "
+        "time-boxed and the server returns the site to its previous mode when the time is up."
+    ),
+)
+
+_client: AivyClient | None = None
+
+
+def _c() -> AivyClient:
+    global _client
+    if _client is None:
+        _client = AivyClient()
+    return _client
+
+
+def _dump(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, default=str)
+
+
+async def _run(coro) -> str:
+    try:
+        return _dump(await coro)
+    except AivyError as e:
+        return _dump({"error": str(e)})
+
+
+# ── account / sites ──
+
+@mcp.tool()
+async def whoami() -> str:
+    """Check the API key: who it belongs to and whether it may control (scope read or control)."""
+    return await _run(_c().me())
+
+
+@mcp.tool()
+async def list_sites() -> str:
+    """List the user's solar + battery sites across vendors. Returns id (vendor:station_id, used by every other
+    tool), vendor, name, online and the vendor's headline power in W. Start here."""
+    return await _run(_c().sites())
+
+
+@mcp.tool()
+async def get_site(site_id: str) -> str:
+    """Facts about one site: timezone, battery capacity (kWh) and where that figure came from, max charge/discharge
+    power (W), export limit (W), the SOC floor Ai+ keeps, live SOC and usable kWh, current energy mode and
+    forced windows, today's energy and income when the vendor reports them."""
+    return await _run(_c().site(site_id))
+
+
+@mcp.tool()
+async def get_status(site_id: str) -> str:
+    """Live reading: SOC (%), pv_w, load_w, grid_w (>0 exporting), battery_w (>0 charging). A null channel is one
+    the vendor does not report, not zero. `source` is vendor (fresh) or stored (last kept reading)."""
+    return await _run(_c().status(site_id))
+
+
+@mcp.tool()
+async def get_curve(site_id: str, range: str = "1d", day: str | None = None) -> str:
+    """Power and SOC history. range 1d = 5-minute points for one local day (day = YYYY-MM-DD, default today);
+    7d / 30d = daily values. Returns times (UTC), local_times, and series per channel (pv, load, battery, grid,
+    soc). Large: summarise before quoting."""
+    return await _run(_c().curve(site_id, range, day))
+
+
+@mcp.tool()
+async def get_earnings(site_id: str, date: str | None = None, window_start: str | None = None,
+                       window_end: str | None = None) -> str:
+    """Energy bought, sold and self-consumed for a day (YYYY-MM-DD, 'today' or 'yesterday'), priced at the actual
+    Amber half-hourly prices when Amber is linked. Optional HH:MM window for part of the day. An estimate from
+    vendor power samples, not the bill; read `coverage` and say so when it is partial."""
+    return await _run(_c().earnings(site_id, date, window_start, window_end))
+
+
+@mcp.tool()
+async def get_operations(site_id: str, limit: int = 20) -> str:
+    """What the platform did to the site and why, newest first: each automatic (Ai+) and manual command with its
+    reason and the prices at the time. Use it to explain 'why did it charge at 3am'."""
+    return await _run(_c().operations(site_id, limit))
+
+
+@mcp.tool()
+async def get_prices(site_id: str, hours: int = 8, resolution: int = 30) -> str:
+    """Amber Electric prices for the site: the current interval and the forecast as import price and feed-in earn
+    (c/kWh incl. GST), with a summary of cheapest/dearest periods. resolution 30 (up to 24 h) or 5 (up to 4 h).
+    Fails with 409 when no Amber account is linked to the site."""
+    return await _run(_c().prices(site_id, hours, resolution))
+
+
+# ── control ──
+
+@mcp.tool()
+async def get_energy_mode(site_id: str) -> str:
+    """Current energy mode (selfConsumption | amber_smart = Ai+ | forced), its forced windows, the SOC floor, the
+    Ai+ variant and settings when on Ai+, and any pending timed hand-back (reverts_at / reverts_to)."""
+    return await _run(_c().energy_mode(site_id))
+
+
+@mcp.tool()
+async def set_energy_mode(
+    site_id: str,
+    mode: str,
+    duration_minutes: int | None = None,
+    action: str | None = None,
+    power_w: int | None = None,
+    target_soc: int | None = None,
+    stop_soc: int | None = None,
+    time_slots: list[dict] | None = None,
+    variant: str | None = None,
+) -> str:
+    """CHANGES THE SITE (control scope). Confirm with the user before calling.
+
+    mode: selfConsumption (inverter default), amber_smart (Ai+, price-driven trading) or forced (manual windows).
+    forced is always time-boxed: duration_minutes (default 240, max 1440); afterwards the server returns the site
+    to the mode it had before. Shorthand for forced: action=charge|discharge with power_w and target_soc (charge)
+    or stop_soc (discharge) builds one window starting now. Or pass explicit time_slots:
+    [{type, start 'HH:MM', end 'HH:MM', target_soc|stop_soc, power, pace}] in site local time.
+    variant picks the Ai+ engine when mode is amber_smart. The SOC floor and export limits cannot be overridden.
+    Takes effect on the engine's next tick (about a minute)."""
+    body: dict[str, Any] = {"mode": mode}
+    for key, value in (("duration_minutes", duration_minutes), ("action", action), ("power_w", power_w),
+                       ("target_soc", target_soc), ("stop_soc", stop_soc), ("time_slots", time_slots),
+                       ("variant", variant)):
+        if value is not None:
+            body[key] = value
+    return await _run(_c().set_energy_mode(site_id, body))
+
+
+@mcp.tool()
+async def get_ai_plus(site_id: str) -> str:
+    """Ai+ (amber_smart) configuration: active or not, engine variant and options, effective settings, and
+    `tunable`: every lever with type, min, max, unit and default. Read before update_ai_plus."""
+    return await _run(_c().ai_plus(site_id))
+
+
+@mcp.tool()
+async def update_ai_plus(site_id: str, settings: dict[str, Any] | None = None, variant: str | None = None) -> str:
+    """CHANGES THE SITE (control scope). Confirm with the user before calling.
+
+    Set Ai+ levers (names and ranges from get_ai_plus `tunable`) and/or switch engine variant. Validated against
+    the variant that will run; if any value is rejected nothing changes and `rejected` says why. Does not switch
+    the mode: use set_energy_mode(mode='amber_smart') for that."""
+    return await _run(_c().patch_ai_plus(site_id, variant, settings or {}))
+
+
+# ── planning (nothing is applied) ──
+
+@mcp.tool()
+async def plan_best_price_discharge(site_id: str, window_start: str | None = None, window_end: str | None = None,
+                                    reserve_soc: int | None = None, min_sell_c: float | None = None,
+                                    battery_capacity_kwh: float | None = None) -> str:
+    """Propose when to sell: picks the best-paid Amber intervals in the window (HH:MM) for the battery's usable
+    energy above reserve_soc, optionally only above min_sell_c c/kWh. Returns intervals, expected revenue, the
+    average it beats and proposed time_slots. Nothing is applied; apply with set_energy_mode(mode='forced',
+    time_slots=...) after the user agrees."""
+    body = {k: v for k, v in {"window_start": window_start, "window_end": window_end, "reserve_soc": reserve_soc,
+                              "min_sell_c": min_sell_c, "battery_capacity_kwh": battery_capacity_kwh}.items()
+            if v is not None}
+    return await _run(_c().plan_best_price_discharge(site_id, body))
+
+
+@mcp.tool()
+async def plan_discharge_to_target(site_id: str, end: str, target_soc: int, start: str | None = None,
+                                   battery_capacity_kwh: float | None = None) -> str:
+    """Propose a steady discharge that lands on target_soc at end (HH:MM, site local), from the real capacity, SOC
+    and power limits. Returns power_w and proposed time_slots. Nothing is applied."""
+    body: dict[str, Any] = {"end": end, "target_soc": target_soc}
+    if start:
+        body["start"] = start
+    if battery_capacity_kwh:
+        body["battery_capacity_kwh"] = battery_capacity_kwh
+    return await _run(_c().plan_discharge_to_target(site_id, body))
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

aivy_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,63 @@
+"""The MCP tool set mirrors the Developer API, and errors come back as data."""
+import asyncio
+import json
+
+import httpx
+import pytest
+
+from aivy_mcp import client as client_mod
+from aivy_mcp import server
+
+
+def _client_with(handler) -> client_mod.AivyClient:
+    c = client_mod.AivyClient(api_key="aivy_sk_test", api_url="https://example.test/v1")
+    c._http = httpx.AsyncClient(base_url="https://example.test/v1", transport=httpx.MockTransport(handler),
+                                headers={"Authorization": "Bearer aivy_sk_test"})
+    return c
+
+
+def test_every_tool_is_listed_and_writes_say_so():
+    tools = asyncio.run(server.mcp.list_tools())
+    names = {t.name for t in tools}
+    assert names == {"whoami", "list_sites", "get_site", "get_status", "get_curve", "get_earnings", "get_operations",
+                     "get_prices", "get_energy_mode", "set_energy_mode", "get_ai_plus", "update_ai_plus",
+                     "plan_best_price_discharge", "plan_discharge_to_target"}
+    for t in tools:
+        if t.name in ("set_energy_mode", "update_ai_plus"):
+            assert "CHANGES THE SITE" in t.description and "Confirm with the user" in t.description
+        else:
+            assert "CHANGES THE SITE" not in t.description
+
+
+def test_set_energy_mode_sends_only_the_given_fields_and_bearer_auth(monkeypatch):
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["auth"] = request.headers["authorization"]
+        seen["body"] = json.loads(request.content)
+        seen["url"] = str(request.url)
+        return httpx.Response(200, json={"energy_mode": "forced", "reverts_to": "amber_smart"})
+
+    monkeypatch.setattr(server, "_client", _client_with(handler))
+    out = json.loads(asyncio.run(server.set_energy_mode("sungrow:1", "forced", duration_minutes=60,
+                                                        action="charge", power_w=5000, target_soc=90)))
+    assert out["reverts_to"] == "amber_smart"
+    assert seen["auth"] == "Bearer aivy_sk_test"
+    assert seen["url"].endswith("/sites/sungrow:1/energy-mode")
+    assert seen["body"] == {"mode": "forced", "duration_minutes": 60, "action": "charge", "power_w": 5000,
+                            "target_soc": 90}
+
+
+def test_api_errors_are_returned_as_data_not_raised(monkeypatch):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(403, json={"detail": {"error": "this API key is read-only"}})
+
+    monkeypatch.setattr(server, "_client", _client_with(handler))
+    out = json.loads(asyncio.run(server.update_ai_plus("sungrow:1", {"hard_floor": 20})))
+    assert out["error"].startswith("403") and "read-only" in out["error"]
+
+
+def test_missing_key_is_a_clear_message(monkeypatch):
+    monkeypatch.delenv("AIVY_API_KEY", raising=False)
+    with pytest.raises(client_mod.AivyError, match="AIVY_API_KEY"):
+        client_mod.AivyClient(api_key=None)