mcp-isolarcloud 0.1.0__tar.gz

mcp_isolarcloud-0.1.0/.github/dependabot.yml

@@ -0,0 +1,25 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "chore(deps)"
+    labels: ["dependencies", "github-actions"]
+    groups:
+      github-actions:
+        patterns: ["*"]
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "chore(deps)"
+      prefix-development: "chore(deps-dev)"
+    labels: ["dependencies", "python"]
+    groups:
+      python:
+        patterns: ["*"]

mcp_isolarcloud-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - name: Install uv
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+      - name: Install
+        run: |
+          uv venv --python 3.13
+          uv pip install -e '.[dev]'
+      - name: Lint
+        run: uv run ruff check src/ tests/ tools/
+      - name: Format check
+        run: uv run ruff format --check src/ tests/ tools/
+      - name: Test
+        run: uv run pytest -q
+      - name: Build (verify docs are packaged)
+        run: |
+          uv build
+          uv run python -c "import zipfile,glob; w=glob.glob('dist/*.whl')[0]; names=zipfile.ZipFile(w).namelist(); assert any('knowledge/documents.json' in n for n in names), 'knowledge not packaged'; print('knowledge bundled OK')"
+
+  openapi:
+    # Regenerate the OpenAPI spec from the live iSolarCloud doc portal and fail if
+    # the committed openapi.json/.yaml are out of date (run tools/build_openapi.py
+    # and commit the result).
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - name: Install uv
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+      - name: Install tooling
+        run: |
+          uv venv --python 3.13
+          uv pip install -e '.[tools]'
+      - name: Regenerate OpenAPI spec
+        run: uv run python tools/build_openapi.py
+      - name: Verify openapi.json / openapi.yaml are up to date
+        run: |
+          if ! git diff --exit-code openapi.json openapi.yaml; then
+            echo "::error::openapi.json/.yaml are stale. Run 'python tools/build_openapi.py' and commit the result."
+            exit 1
+          fi

mcp_isolarcloud-0.1.0/.github/workflows/release-please.yml

@@ -0,0 +1,89 @@
+name: Release Please
+
+# On push to main, release-please maintains a release PR (bumping pyproject.toml
+# and CHANGELOG.md from Conventional Commits). Merging it tags the release and,
+# via the release_created output, publishes to PyPI with trusted publishing.
+#
+# Build/publish are inlined (not a reusable workflow) because PyPI Trusted
+# Publishing does not support reusable workflows.
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: release-please
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        id: release
+        with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN || github.token }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  build:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.13"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    name: Publish release to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mcp-isolarcloud
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-dists
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          packages-dir: dist/
+
+  upload-openapi:
+    # Attach the committed OpenAPI spec to the GitHub release.
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - name: Attach OpenAPI spec to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.release-please.outputs.tag_name }}
+        run: gh release upload "$TAG" openapi.json openapi.yaml --clobber

mcp_isolarcloud-0.1.0/.gitignore

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

mcp_isolarcloud-0.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

mcp_isolarcloud-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 (2026-07-03)
+
+
+### Features
+
+* iSolarCloud docs MCP server ([b9b9029](https://github.com/KRoperUK/mcp-isolarcloud/commit/b9b90290c513a4e8b87dd2cbd7a7c81794adb6ec))
+* OpenAPI spec and doc/OpenAPI refresh tooling ([d24a4fb](https://github.com/KRoperUK/mcp-isolarcloud/commit/d24a4fbd20d3cc860c25ba1db3762feb69604750))

mcp_isolarcloud-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KRoperUK
+
+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.

mcp_isolarcloud-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: mcp-isolarcloud
+Version: 0.1.0
+Summary: MCP server serving Sungrow iSolarCloud OpenAPI documentation, control-parameter reference and how-to skills.
+Project-URL: Homepage, https://github.com/KRoperUK/mcp-isolarcloud
+Project-URL: Issues, https://github.com/KRoperUK/mcp-isolarcloud/issues
+Author: KRoperUK
+License: MIT
+License-File: LICENSE
+Keywords: documentation,isolarcloud,mcp,solar,sungrow
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff==0.15.16; extra == 'dev'
+Provides-Extra: tools
+Requires-Dist: cryptography; extra == 'tools'
+Requires-Dist: markdownify; extra == 'tools'
+Requires-Dist: pyyaml; extra == 'tools'
+Description-Content-Type: text/markdown
+
+# mcp-isolarcloud
+
+An [MCP](https://modelcontextprotocol.io) server that serves the **Sungrow iSolarCloud OpenAPI documentation** — the official developer docs, control-parameter reference, device-type dictionary, error codes and measuring-point tables — as searchable tools, resources and how-to "skill" prompts.
+
+The full documentation set is **bundled with the package**, so the server needs no network access or credentials at runtime.
+
+## Why
+
+Building against the iSolarCloud API (e.g. the [`sungrow-isolarcloud`](https://github.com/KRoperUK/pysolarcloud) client or the [Home Assistant integration](https://github.com/KRoperUK/sungrow-hass)) means constantly cross-referencing the developer portal — whose docs live behind a JavaScript app. This server puts them one tool call away for any MCP-capable assistant, including the authoritative **Appendix 10: Control Parameter Definitions** (param codes, units and value encodings — e.g. SOC is sent as tenths of a percent, power in watts).
+
+## Run it
+
+With [`uv`](https://docs.astral.sh/uv/) (recommended — no install step):
+
+```bash
+uvx mcp-isolarcloud
+```
+
+Or add it to an MCP client (Claude Desktop / Claude Code / etc.):
+
+```json
+{
+  "mcpServers": {
+    "isolarcloud": {
+      "command": "uvx",
+      "args": ["mcp-isolarcloud"]
+    }
+  }
+}
+```
+
+For Claude Code: `claude mcp add isolarcloud -- uvx mcp-isolarcloud`
+
+## What it exposes
+
+**Tools**
+- `list_docs()` — every documentation page (slug, title, type)
+- `read_doc(slug)` — the full markdown of one page
+- `search_docs(query, limit=8)` — keyword search, title-weighted, with snippets
+
+**Resources**
+- `isolarcloud://docs/{slug}` — each page as an MCP resource
+
+**Prompts (skills)**
+- `find_control_parameter(what)` — locate a dispatch/control parameter and its value encoding
+- `api_call_walkthrough(endpoint)` — walk through calling a specific API endpoint
+
+## Updating the docs
+
+The bundled docs are refreshed from the portal with:
+
+```bash
+pip install cryptography markdownify
+python tools/refresh_docs.py
+```
+
+The portal's doc API is public (no login); `refresh_docs.py` reproduces its request-encryption scheme using the public keys embedded in the portal's own web app.
+
+## Development
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+ruff check src/ tests/
+pytest
+```
+
+## License
+
+MIT

mcp_isolarcloud-0.1.0/README.md

@@ -0,0 +1,69 @@
+# mcp-isolarcloud
+
+An [MCP](https://modelcontextprotocol.io) server that serves the **Sungrow iSolarCloud OpenAPI documentation** — the official developer docs, control-parameter reference, device-type dictionary, error codes and measuring-point tables — as searchable tools, resources and how-to "skill" prompts.
+
+The full documentation set is **bundled with the package**, so the server needs no network access or credentials at runtime.
+
+## Why
+
+Building against the iSolarCloud API (e.g. the [`sungrow-isolarcloud`](https://github.com/KRoperUK/pysolarcloud) client or the [Home Assistant integration](https://github.com/KRoperUK/sungrow-hass)) means constantly cross-referencing the developer portal — whose docs live behind a JavaScript app. This server puts them one tool call away for any MCP-capable assistant, including the authoritative **Appendix 10: Control Parameter Definitions** (param codes, units and value encodings — e.g. SOC is sent as tenths of a percent, power in watts).
+
+## Run it
+
+With [`uv`](https://docs.astral.sh/uv/) (recommended — no install step):
+
+```bash
+uvx mcp-isolarcloud
+```
+
+Or add it to an MCP client (Claude Desktop / Claude Code / etc.):
+
+```json
+{
+  "mcpServers": {
+    "isolarcloud": {
+      "command": "uvx",
+      "args": ["mcp-isolarcloud"]
+    }
+  }
+}
+```
+
+For Claude Code: `claude mcp add isolarcloud -- uvx mcp-isolarcloud`
+
+## What it exposes
+
+**Tools**
+- `list_docs()` — every documentation page (slug, title, type)
+- `read_doc(slug)` — the full markdown of one page
+- `search_docs(query, limit=8)` — keyword search, title-weighted, with snippets
+
+**Resources**
+- `isolarcloud://docs/{slug}` — each page as an MCP resource
+
+**Prompts (skills)**
+- `find_control_parameter(what)` — locate a dispatch/control parameter and its value encoding
+- `api_call_walkthrough(endpoint)` — walk through calling a specific API endpoint
+
+## Updating the docs
+
+The bundled docs are refreshed from the portal with:
+
+```bash
+pip install cryptography markdownify
+python tools/refresh_docs.py
+```
+
+The portal's doc API is public (no login); `refresh_docs.py` reproduces its request-encryption scheme using the public keys embedded in the portal's own web app.
+
+## Development
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+ruff check src/ tests/
+pytest
+```
+
+## License
+
+MIT