geosphere-mcp-server 0.1.0__tar.gz

geosphere_mcp_server-0.1.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  # Python dependencies (managed via uv / uv.lock)
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+
+  # GitHub Actions used in workflows
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

geosphere_mcp_server-0.1.0/.github/workflows/auto-release.yml

@@ -0,0 +1,48 @@
+name: Auto Release (Dependabot)
+
+on:
+  pull_request:
+    types: [closed]
+  workflow_dispatch: {} # manual "cut the next patch release" trigger
+
+jobs:
+  tag:
+    # Runs for a manual dispatch, or for a merged Dependabot PR from the uv
+    # (Python dependency) ecosystem — those change the published package.
+    # github-actions bumps do not, so they merge without cutting a release.
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.pull_request.merged == true &&
+      github.event.pull_request.user.login == 'dependabot[bot]' &&
+      startsWith(github.event.pull_request.head.ref, 'dependabot/uv/'))
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.GH_ACTION_APP_ID }}
+          private-key: ${{ secrets.GH_ACTION_APP_PRIVATE_KEY }}
+      - uses: actions/checkout@v7
+        with:
+          ref: main
+          fetch-depth: 0 # need all tags + the merge commit
+          token: ${{ steps.app-token.outputs.token }}
+      - name: Compute next patch version
+        id: ver
+        run: |
+          latest=$(git tag -l 'v*' --sort=-v:refname | head -n1)
+          latest=${latest:-v0.0.0}
+          IFS=. read -r major minor patch <<< "${latest#v}"
+          next="v${major}.${minor}.$((patch + 1))"
+          echo "next=$next" >> "$GITHUB_OUTPUT"
+          echo "Next release: $next (from ${latest})"
+      - name: Create and push tag
+        env:
+          NEXT: ${{ steps.ver.outputs.next }}
+          REASON: ${{ github.event_name == 'workflow_dispatch' && 'manual dispatch' || format('Dependabot PR {0}', github.event.pull_request.number) }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "$NEXT" -m "Automated release $NEXT ($REASON)"
+          git push origin "$NEXT"

geosphere_mcp_server-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,90 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # hatch-vcs needs full history + tags to derive the version
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Verify tag matches built version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          BUILT=$(ls dist/geosphere_mcp_server-*.tar.gz | sed -E 's|.*/geosphere_mcp_server-(.*)\.tar\.gz|\1|')
+          echo "tag=$TAG_VERSION built=$BUILT"
+          if [ "$TAG_VERSION" != "$BUILT" ]; then
+            echo "::error::Tag $TAG_VERSION does not match built version $BUILT"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  pypi-publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC for PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: pypi-publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --repo "$GITHUB_REPOSITORY" \
+            --title "$GITHUB_REF_NAME" \
+            --generate-notes \
+            dist/*
+
+  mcp-registry:
+    name: Publish to MCP Registry
+    needs: pypi-publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # OIDC proves ownership of the io.github.<owner> namespace
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set server.json version from tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          jq --arg v "$VERSION" '.version = $v | .packages[0].version = $v' \
+            server.json > server.tmp && mv server.tmp server.json
+          cat server.json
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - name: Authenticate to MCP Registry
+        run: ./mcp-publisher login github-oidc
+      - name: Publish to MCP Registry
+        run: ./mcp-publisher publish

geosphere_mcp_server-0.1.0/.github/workflows/validate.yml

@@ -0,0 +1,49 @@
+name: Validate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ruff:
+    name: Ruff (lint + format)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format . --check
+
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # hatch-vcs derives the version from git history + tags
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: pip install hatchling && pip install -e . && pip install pytest pytest-asyncio
+      - run: pytest tests/ -v -m "not integration"
+
+  gate:
+    name: gate
+    needs: [ruff, test]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check validation results
+        run: |
+          if [[ "${{ needs.ruff.result }}" == "success" && \
+                "${{ needs.test.result }}" == "success" ]]; then
+            echo "All checks passed"
+            exit 0
+          else
+            echo "One or more checks failed"
+            exit 1
+          fi

geosphere_mcp_server-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+_version.py
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Environment
+.venv/
+
+# macOS
+.DS_Store
+._*
+
+# IDE
+.vscode/
+.idea/

geosphere_mcp_server-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 - 2026-07-22
+
+- Initial release
+- MCP server with 3 tools: `get_current_weather`, `get_hourly_forecast`, `get_daily_forecast`
+- High-resolution weather for Austria and the Alps from the GeoSphere Austria Dataset API: AROME forecast (~60 h hourly), INCA analysis, INCA nowcast, and C-LAEF ensemble precipitation probability
+- Automatic worldwide fallback to Open-Meteo when a point is outside GeoSphere coverage (current + hourly tools); daily forecast (1-16 days) always via Open-Meteo
+- Location input is plain decimal `latitude`/`longitude` (the calling LLM geocodes place names)
+- HA-style condition vocabulary derived physically on the GeoSphere path and mapped from WMO weather codes on the Open-Meteo path
+- Compact emoji-markdown output (metric units), each response naming its data source
+- First public distribution: published to [PyPI](https://pypi.org/project/geosphere-mcp-server/) (installable via `uvx geosphere-mcp-server`) and listed in the [official MCP Registry](https://registry.modelcontextprotocol.io)
+- Tag-driven release pipeline: PyPI Trusted Publishing (OIDC), GitHub Release, and MCP Registry publish on `v*` tags
+- Version single-sourced from git tags via `hatch-vcs`; PyPI metadata (authors, URLs, classifiers, keywords) and a `py.typed` marker

geosphere_mcp_server-0.1.0/CLAUDE.md

@@ -0,0 +1,62 @@
+# GeoSphere MCP Server
+> MCP server for weather forecasts, usable by LLMs via the Model Context Protocol. High-resolution GeoSphere Austria data (AROME/INCA/C-LAEF) for Austria and the Alps, Open-Meteo worldwide.
+
+## Quick Reference
+- **Lint**: `ruff check .`
+- **Format**: `ruff format .`
+- **Test (unit)**: `pytest tests/ -v -m "not integration"`
+- **Test (integration, live APIs)**: `pytest tests/ -v -m integration`
+- **Run server**: `uvx --from . geosphere-mcp-server` or `python -m geosphere_mcp_server.server`
+- **Validate (CI)**: Ruff + pytest unit tests (all must pass via `gate` job)
+
+## Architecture Overview
+FastMCP presentation layer over pure async API clients and pure derivation/rendering helpers. Purely functional -- no classes outside the `FastMCP` instance. All code in `src/geosphere_mcp_server/`.
+
+- `server.py` -- FastMCP tool registration (3 tools), session lifecycle, stdio entry point, sentinel error lines
+- `weather.py` -- merge chain, hourly assembly, POP mapping, unit conversions (orchestration)
+- `geosphere_api.py` -- pure async client for the GeoSphere Dataset API
+- `openmeteo_api.py` -- pure async client for Open-Meteo (current/hourly/daily)
+- `condition.py` -- pure condition derivation (ported from ha-geosphere-next)
+- `format.py` -- emoji-markdown renderers for the three tools
+- `const.py` -- all constants (URLs, resource IDs, parameter lists, thresholds, WMO->condition map)
+
+Data flow: MCP tool call -> `server.py` handler -> `weather.py` orchestration -> `geosphere_api`/`openmeteo_api` -> live API -> derived via `condition.py` -> rendered by `format.py` -> markdown string.
+
+See [Architecture](docs/tech/ARCHITECTURE.md) for module boundaries and data flow detail.
+
+## Tech Stack
+- Python 3.12+, `from __future__ import annotations` in every file
+- `mcp[cli]` (FastMCP) for MCP server framework
+- `aiohttp` for async HTTP, `astral` for day/night
+- `ruff` for linting/formatting, `pytest` + `pytest-asyncio` for testing
+- `uv` for environment management, `hatchling` + `hatch-vcs` build backend
+- GitHub Actions CI (validate on push/PR)
+
+See [Tech Stack](docs/tech/TECH-STACK.md) for full detail.
+
+## Core Conventions
+- Module-level async functions -- no client classes
+- Constants in `const.py` only -- no inline magic values
+- Logger: `_LOGGER = logging.getLogger(__name__)` with `%s` formatting (not f-strings)
+- Import order: `__future__` -> stdlib -> third-party -> local
+- API modules raise typed exceptions; the server layer catches them and returns a short markdown error line -- tools never raise
+- GeoSphere out-of-domain is not an error: it triggers the transparent Open-Meteo fallback
+
+See [Conventions](docs/tech/CONVENTIONS.md) for naming tables and full rules.
+
+## Business Domain
+Weather MCP gateway. Three tools -- `get_current_weather`, `get_hourly_forecast`, `get_daily_forecast` -- matching the OWM server surface they replace. GeoSphere Austria's gridded datasets (AROME ~60 h, INCA analysis/nowcast, C-LAEF ensemble) drive current + hourly for Austria/the Alps; points outside coverage fall back to Open-Meteo automatically, and daily is always Open-Meteo (worldwide, 1-16 days). A shared HA-style condition vocabulary is derived physically on the GeoSphere path and mapped from WMO codes on the Open-Meteo path.
+
+See [Domain Overview](docs/domain/OVERVIEW.md) for datasets, coverage, condition derivation, and attribution.
+
+## Structural Risks
+- GeoSphere dataset resource IDs are versioned -- a catalog rotation breaks the server until IDs in `const.py` are bumped
+- No GeoSphere forecast beyond ~60 h -- longer horizons must go through Open-Meteo
+- Per-call `aiohttp.ClientSession` creation -- no connection pooling
+- `condition.py` duplicates HA `ATTR_CONDITION_*` string literals (to stay import-free) -- could drift if HA renames a condition
+- Rate limits (GeoSphere 5 req/s, 240 req/h) shared across all callers -- no server-side quota tracking
+
+## Detailed Guides
+- [Technical Context](docs/tech/README.md) -- architecture, tech stack, conventions, testing
+- [Domain Context](docs/domain/README.md) -- datasets, coverage, condition derivation, integrations
+- [Documentation Guide](docs/README.md) -- how to maintain these docs

geosphere_mcp_server-0.1.0/LICENSE

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

geosphere_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: geosphere-mcp-server
+Version: 0.1.0
+Summary: MCP server for weather forecasts: GeoSphere Austria high-resolution data (AROME/INCA/C-LAEF) for Austria and the Alps, Open-Meteo worldwide.
+Project-URL: Homepage, https://github.com/slettmayer/geosphere-mcp-server
+Project-URL: Repository, https://github.com/slettmayer/geosphere-mcp-server
+Project-URL: Issues, https://github.com/slettmayer/geosphere-mcp-server/issues
+Project-URL: Changelog, https://github.com/slettmayer/geosphere-mcp-server/blob/main/CHANGELOG.md
+Author: Stefan Lettmayer
+License-Expression: MIT
+License-File: LICENSE
+Keywords: austria,forecast,geosphere,home-assistant,mcp,open-meteo,weather
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.0.0
+Requires-Dist: astral>=3.2
+Requires-Dist: mcp[cli]>=1.28.1
+Description-Content-Type: text/markdown
+
+# geosphere-mcp-server
+
+<!-- mcp-name: io.github.slettmayer/geosphere-mcp-server -->
+
+[![PyPI](https://img.shields.io/pypi/v/geosphere-mcp-server.svg)](https://pypi.org/project/geosphere-mcp-server/)
+[![Python](https://img.shields.io/pypi/pyversions/geosphere-mcp-server.svg)](https://pypi.org/project/geosphere-mcp-server/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+MCP server for weather: current conditions, hourly forecasts, and multi-day outlooks for **any location worldwide**, via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+In **Austria and the Alpine region** it serves high-resolution [GeoSphere Austria](https://www.geosphere.at) data — the AROME numerical forecast, the INCA analysis/nowcast, and the C-LAEF ensemble for precipitation probability. **Everywhere else** it falls back automatically to [Open-Meteo](https://open-meteo.com), so it is a drop-in worldwide weather source. Every response states which source produced it.
+
+Output is compact emoji-markdown with metric units — built for smart-home and voice-assistant LLM pipelines where a terse, readable answer beats a JSON blob. Weather conditions are derived from physical parameters and reported with the Home Assistant condition vocabulary (`sunny`, `partlycloudy`, `rainy`, `snowy`, …).
+
+## Coverage
+
+| Where | `get_current_weather` | `get_hourly_forecast` | `get_daily_forecast` |
+|-------|-----------------------|-----------------------|----------------------|
+| Austria | GeoSphere INCA + nowcast + AROME | GeoSphere AROME (≤60 h) + C-LAEF probability | Open-Meteo (1–16 days) |
+| Alps (non-AT) | GeoSphere AROME only | GeoSphere AROME (≤60 h) + C-LAEF probability | Open-Meteo (1–16 days) |
+| Rest of world | Open-Meteo | Open-Meteo (≤48 h) | Open-Meteo (1–16 days) |
+
+Coverage is detected automatically: the server tries GeoSphere first and falls back to Open-Meteo when the point is outside the AROME grid — no bounding box to configure. The daily forecast always uses Open-Meteo (GeoSphere publishes no forecasts beyond ~60 h).
+
+## Installation
+
+Pass **decimal latitude/longitude** to every tool. There is no geocoder in the server — the calling LLM geocodes city names to coordinates itself.
+
+### Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "geosphere": {
+      "command": "uvx",
+      "args": ["geosphere-mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add geosphere -- uvx geosphere-mcp-server
+```
+
+### From source (development)
+
+```json
+{
+  "mcpServers": {
+    "geosphere": {
+      "command": "uvx",
+      "args": ["--from", "/path/to/geosphere-mcp-server", "geosphere-mcp-server"]
+    }
+  }
+}
+```
+
+### Home Assistant
+
+It is a standard stdio MCP server, so it runs anywhere an stdio MCP server can be hosted — including alongside Home Assistant's Assist pipeline (register it the same way as any other stdio MCP server). Give the voice agent the coordinates of the places it should answer for, or let it geocode names.
+
+## Tools
+
+### `get_current_weather`
+
+Current conditions for a point. GeoSphere (INCA/AROME) inside coverage, Open-Meteo elsewhere.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `latitude` | float | required | Decimal latitude (e.g. `48.2208`) |
+| `longitude` | float | required | Decimal longitude (e.g. `16.3738`) |
+
+```
+# Current Weather at 48.2208, 16.3738
+
+🌡️ Temperature: 24.7°C (feels like 24.2°C)
+🌤️ Condition: partlycloudy
+💧 Humidity: 52%
+💨 Wind: 2.9 m/s from 135° (gusts 7 m/s)
+🌧️ Precipitation (last hour): 0 mm
+📊 Pressure: 1016 hPa
+☁️ Cloud cover: 30%
+🕐 Timezone: Europe/Vienna (CEST)
+📡 Source: GeoSphere (INCA + nowcast + AROME) — observed 15:20
+```
+
+Outside GeoSphere coverage the same tool answers from Open-Meteo (sunrise/sunset and the point's own timezone included):
+
+```
+# Current Weather at 38.7223, -9.1393
+
+🌡️ Temperature: 26.1°C (feels like 27.0°C)
+🌤️ Condition: cloudy
+💧 Humidity: 58%
+💨 Wind: 4.5 m/s from 315° (gusts 9 m/s)
+📊 Pressure: 1014 hPa
+☁️ Cloud cover: 90%
+🌅 Sunrise: 06:24
+🌇 Sunset: 20:52
+🕐 Timezone: Europe/Lisbon (WEST)
+📡 Source: Open-Meteo — observed 14:00
+```
+
+### `get_hourly_forecast`
+
+Hour-by-hour forecast. GeoSphere AROME (with C-LAEF precipitation probability) up to ~60 h inside coverage; Open-Meteo up to 48 h elsewhere.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `latitude` | float | required | Decimal latitude (e.g. `48.2208`) |
+| `longitude` | float | required | Decimal longitude (e.g. `16.3738`) |
+| `hours` | int | 24 | Forecast hours (clamped to 1–60 on GeoSphere, 1–48 on the fallback) |
+| `start` | string | now | Optional ISO 8601 start (e.g. `2026-07-22T15:00`); forecast begins at/after this instant |
+
+```
+# 3-Hour Forecast for 48.2208, 16.3738
+
+AROME model, reference 2026-07-22 12:00 CEST · Source: GeoSphere (AROME + C-LAEF ensemble)
+
+15:00: 24.7°C — partlycloudy, wind 3 m/s
+16:00: 23.9°C — rainy, 1.2 mm (70% chance), wind 4 m/s
+17:00: 22.5°C — cloudy, wind 3 m/s
+```
+
+Requesting more hours than the AROME horizon provides appends a note suggesting `get_daily_forecast` for days further ahead. Dry hours omit the precipitation and probability parts.
+
+### `get_daily_forecast`
+
+Multi-day outlook, always from Open-Meteo (worldwide, including Austria).
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `latitude` | float | required | Decimal latitude (e.g. `48.2208`) |
+| `longitude` | float | required | Decimal longitude (e.g. `16.3738`) |
+| `days` | int | 7 | Forecast days (clamped to 1–16) |
+
+```
+# 3-Day Forecast for 48.2208, 16.3738
+
+Source: Open-Meteo (Europe/Vienna)
+
+Wed 2026-07-22: 16–27°C — partlycloudy, wind up to 9 m/s
+Thu 2026-07-23: 15–22°C — rainy, 4.2 mm (80% chance), wind up to 15 m/s
+Fri 2026-07-24: 14–26°C — sunny, wind up to 8 m/s
+```
+
+## Data sources & attribution
+
+- **GeoSphere Austria Dataset API** — AROME forecast, INCA analysis/nowcast, C-LAEF ensemble. Data licensed under [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/). © GeoSphere Austria.
+- **Open-Meteo** — worldwide forecast API. Data licensed under [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/). © Open-Meteo.
+
+Both APIs are keyless and intended for **non-commercial** use. When you redistribute their data, keep the attribution.
+
+## Rate limits
+
+The GeoSphere Dataset API allows **5 requests/second and 240 requests/hour**. Each current/hourly call issues a small burst of concurrent requests; on an HTTP 429 the server retries once (when the API asks for a short wait) and otherwise returns a rate-limit notice — `get_daily_forecast` keeps working through Open-Meteo in that case. Open-Meteo has its own generous free-tier limits.
+
+## Development
+
+```bash
+# Install dependencies (creates .venv from the locked versions)
+uv sync
+
+# Lint & format
+ruff check .
+ruff format .
+
+# Run unit tests
+pytest -m "not integration"
+
+# Run integration tests (hits the live GeoSphere + Open-Meteo APIs)
+pytest -m integration
+```
+
+## License
+
+MIT