uba-mcp 0.1.0__tar.gz

uba_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # required for PyPI trusted publishing (OIDC)
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

uba_mcp-0.1.0/.github/workflows/registry.yml

@@ -0,0 +1,95 @@
+name: Publish to MCP Registry
+
+# Official MCP Registry (registry.modelcontextprotocol.io) via GitHub OIDC.
+# No secret, no interactive login: the runner's OIDC token proves ownership
+# of the io.github.mohammad-abbasi-sh/* namespace.
+# Refs: https://github.com/modelcontextprotocol/registry
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # required for OIDC -> MCP Registry
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Sync server.json version to tag
+        # Only sync when running on a version tag (v*). On workflow_dispatch
+        # (ref = refs/heads/main) keep the version committed in server.json.
+        run: |
+          VER=""
+          if [[ "$GITHUB_REF" == refs/tags/* ]]; then
+            TAG="${GITHUB_REF#refs/tags/}"
+            VER="${TAG#v}"
+          fi
+          if [ -n "$VER" ]; then
+            python3 - "$VER" << 'EOF'
+          import json, sys
+          ver = sys.argv[1]
+          d = json.load(open('server.json'))
+          d['version'] = ver
+          for pkg in d.get('packages', []):
+              pkg['version'] = ver
+          json.dump(d, open('server.json', 'w'), indent=2, ensure_ascii=False)
+          print('server.json version ->', ver)
+          EOF
+          else
+            echo "No version tag ($GITHUB_REF); keeping server.json version as-is"
+          fi
+
+      - name: Wait for PyPI
+        # The registry validates that the PyPI package + version exists,
+        # but the PyPI publish workflow runs in parallel with this one.
+        # Poll until the version appears instead of racing it: a 400 here
+        # used to fail silently under continue-on-error and left 40/43
+        # servers unlisted in the registry (2026-11-11).
+        run: |
+          python3 - << 'EOF'
+          import json, sys, time, urllib.request, urllib.error
+          d = json.load(open('server.json'))
+          pkg = d['packages'][0]
+          name = pkg.get('identifier') or pkg.get('name')
+          ver = pkg['version']
+          if not name:
+              print('ERROR: no package identifier/name in server.json')
+              sys.exit(1)
+          url = f'https://pypi.org/pypi/{name}/json'
+          for attempt in range(1, 21):
+              try:
+                  with urllib.request.urlopen(url, timeout=30) as r:
+                      data = json.load(r)
+                  if ver in data.get('releases', {}):
+                      print(f'PyPI {name}=={ver} is live (attempt {attempt})')
+                      sys.exit(0)
+              except urllib.error.HTTPError as e:
+                  print(f'attempt {attempt}: PyPI returned {e.code}')
+              except Exception as e:
+                  print(f'attempt {attempt}: {e}')
+              print(f'attempt {attempt}: {name}=={ver} not on PyPI yet, waiting 30s...')
+              time.sleep(30)
+          print(f'ERROR: {name}=={ver} did not appear on PyPI after 10 minutes')
+          sys.exit(1)
+          EOF
+
+      - name: Install mcp-publisher
+        run: |
+          curl -sL "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.7/mcp-publisher_linux_amd64.tar.gz" -o /tmp/mcp-publisher.tar.gz
+          tar -xzf /tmp/mcp-publisher.tar.gz -C /tmp
+          sudo mv /tmp/mcp-publisher /usr/local/bin/mcp-publisher
+          mcp-publisher --version
+
+      - name: Validate server.json
+        run: mcp-publisher validate server.json
+
+      - name: Publish to MCP Registry (OIDC)
+        # Failures must fail the run visibly: a silent publish failure
+        # once left 40/43 servers unlisted in the registry (2026-11-11).
+        run: |
+          mcp-publisher login github-oidc
+          mcp-publisher publish server.json

uba_mcp-0.1.0/.github/workflows/smoke.yml

@@ -0,0 +1,21 @@
+name: Daily live smoke
+
+# One fixed probe per day: catches fingerprint rot / bot-wall changes
+# before users hit them. Fails visibly on 403/timeout.
+on:
+  schedule:
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e .
+      - name: Smoke probe
+        run: python tests/smoke_live.py

uba_mcp-0.1.0/LICENSE

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

uba_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: uba-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for UBA German air quality — hourly measurements and LQI from 400+ stations
+Author: Mohammad Abbasi
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2
+Description-Content-Type: text/markdown
+
+# uba-mcp 🌬️
+
+mcp-name: io.github.mohammad-abbasi-sh/uba-mcp
+
+Unofficial **read-only** MCP server for **[UBA air quality](https://www.umweltbundesamt.de/en/data/air/air-data)** — the Umweltbundesamt (German Federal Environment Agency) Air Data API v4: hourly measurements from ~400 German stations (PM10, PM2.5, NO2, O3, SO2, CO, benzene …) since 2016, with the official UBA air-quality index (LQI). No key, no login.
+
+> Built by Mohammad Abbasi as part of the "Germany MCP factory". Not affiliated with the Umweltbundesamt.
+
+## For AI agents
+
+Add to your MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "uba": {
+      "command": "uvx",
+      "args": ["uba-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+Or run locally: `python -m uba_mcp.server` (needs `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `uba_list_stations` | Measuring stations, filterable by city, state, type, area or name |
+| `uba_station_detail` | One station: address, coordinates, type, data window, recent pollutants |
+| `uba_current_air_quality` | Latest hourly values + LQI at a station (code, id or city name) |
+| `uba_measurements` | Hourly values over a date range (max 31 days) + min/max/mean & daily means |
+| `uba_list_components` | All 12 pollutants: code, symbol, unit, name |
+| `uba_list_networks` | The 17 measuring networks (16 Länder + UBA) |
+| `uba_health` | Reachability check (ok / blocked / error) — one polite request |
+
+Example output (`uba_current_air_quality` / Berlin Neukölln, 2026-11-11 09:00 CET):
+
+```json
+{"station": {"code": "DEBE034", "name": "Berlin Neukölln", "city": "Berlin"},
+ "hour": {"start": "2026-11-11 09:00:00", "total_index": 2, "total_label": "moderate",
+  "values": [{"code": "PM2", "value": 17.0, "unit": "µg/m³", "label": "moderate"},
+             {"code": "PM10", "value": 23.0, "unit": "µg/m³", "label": "good"},
+             {"code": "O3", "value": 24.0, "unit": "µg/m³", "label": "very good"},
+             {"code": "NO2", "value": 15.0, "unit": "µg/m³", "label": "good"}]}}
+```
+
+Notes:
+- Stations are found by code (`DEBE010` = Berlin Wedding), numeric id, or city name (first active station in that city).
+- The `index` / `total_index` (0–4) and labels come from the API itself; they follow the UBA LQI, 2025 revision (hourly means, µg/m³):
+
+| Class | NO2 | PM10 | PM2.5 | O3 | SO2 |
+|-------|-----|------|-------|----|-----|
+| 0 very good | 0–10 | 0–9 | 0–5 | 0–24 | 0–10 |
+| 1 good | 11–30 | 10–27 | 6–15 | 25–72 | 11–30 |
+| 2 moderate | 31–60 | 28–54 | 16–30 | 73–144 | 31–60 |
+| 3 poor | 61–100 | 55–90 | 31–50 | 145–240 | 61–100 |
+| 4 very poor | >100 | >90 | >50 | >240 | >100 |
+
+- All times are CET/CEST as returned by the API. Data: UBA Air Data API v4 `umweltbundesamt.de/api/air_data/v4` — no key, no login, read-only.
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/pip install -e .
+.venv/bin/python -m pytest tests/ -q
+```
+
+- `tests/test_domain.py` — offline, parses real captured API fixtures
+- `tests/test_live.py` — 7 cautious live requests against the UBA API
+
+## License
+
+MIT
+
+---
+
+Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)

uba_mcp-0.1.0/README-de.md

@@ -0,0 +1,57 @@
+# uba-mcp 🌬️
+
+mcp-name: io.github.mohammad-abbasi-sh/uba-mcp
+
+Inoffizieller **nur lesender** MCP-Server für **[UBA-Luftqualität](https://www.umweltbundesamt.de/en/data/air/air-data)** — die Air-Data-API v4 des Umweltbundesamtes: stündliche Messwerte von rund 400 deutschen Messstationen (PM10, PM2,5, NO2, O3, SO2, CO, Benzol …) seit 2016, mit dem amtlichen Luftqualitätsindex (LQI) des UBA. Kein Schlüssel, keine Anmeldung.
+
+> Gebaut von Mohammad Abbasi als Teil der "Germany MCP factory". Nicht mit dem Umweltbundesamt verbunden.
+
+## Für KI-Agenten
+
+Zur MCP-Client-Konfiguration hinzufügen (stdio):
+
+```json
+{
+  "mcpServers": {
+    "uba": {
+      "command": "uvx",
+      "args": ["uba-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+Oder lokal starten: `python -m uba_mcp.server` (benötigt `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Beschreibung |
+|------|-------------|
+| `uba_list_stations` | Messstationen, filterbar nach Stadt, Bundesland, Typ, Gebiet oder Name |
+| `uba_station_detail` | Eine Station: Adresse, Koordinaten, Typ, Datenzeitraum, aktuelle Schadstoffe |
+| `uba_current_air_quality` | Aktuelle Stundenwerte + LQI an einer Station (Code, ID oder Stadtname) |
+| `uba_measurements` | Stundenwerte über einen Zeitraum (max. 31 Tage) + Min/Max/Mittel & Tagesmittel |
+| `uba_list_components` | Alle 12 Schadstoffe: Code, Symbol, Einheit, Name |
+| `uba_list_networks` | Die 17 Messnetze (16 Bundesländer + UBA) |
+| `uba_health` | Erreichbarkeitsprüfung (ok / blocked / error) — eine höfliche Anfrage |
+
+Hinweise:
+- Stationen werden über Code (`DEBE010` = Berlin Wedding), numerische ID oder Stadtname gefunden (erste aktive Station der Stadt).
+- `index` / `total_index` (0–4) und Labels kommen direkt aus der API; sie folgen dem UBA-LQI, Revision 2025 (Stundenmittelwerte, µg/m³): sehr gut / gut / mäßig / schlecht / sehr schlecht.
+- Alle Zeiten sind MEZ/MESZ, wie von der API geliefert. Daten: UBA Air Data API v4 — kein Schlüssel, keine Anmeldung, nur lesend.
+
+## Entwicklung
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/pip install -e .
+.venv/bin/python -m pytest tests/ -q
+```
+
+## Lizenz
+
+MIT
+
+---
+
+Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)

uba_mcp-0.1.0/README-fa.md

@@ -0,0 +1,57 @@
+# uba-mcp 🌬️
+
+mcp-name: io.github.mohammad-abbasi-sh/uba-mcp
+
+سرور MCP غیررسمی و **فقط‌خواندنی** برای **[کیفیت هوای UBA](https://www.umweltbundesamt.de/en/data/air/air-data)** — API نسخهٔ ۴ داده‌های هوای آژانس فدرال محیط زیست آلمان (Umweltbundesamt): اندازه‌گیری‌های ساعتی از حدود ۴۰۰ ایستگاه آلمان (PM10، PM2.5، NO2، O3، SO2، CO، بنزن و…) از سال ۲۰۱۶، همراه با شاخص رسمی کیفیت هوا (LQI) از UBA. بدون کلید، بدون ورود.
+
+> ساختهٔ محمد عباسی، بخشی از «کارخانهٔ MCP آلمان». وابسته به Umweltbundesamt نیست.
+
+## برای ایجنت‌های هوش مصنوعی
+
+به پیکربندی MCP کلاینت اضافه کنید (stdio):
+
+```json
+{
+  "mcpServers": {
+    "uba": {
+      "command": "uvx",
+      "args": ["uba-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+یا به‌صورت محلی اجرا کنید: `python -m uba_mcp.server` (نیازمند `mcp<2` و `httpx`).
+
+## ابزارها
+
+| ابزار | توضیح |
+|------|-------|
+| `uba_list_stations` | ایستگاه‌های اندازه‌گیری، قابل فیلتر بر اساس شهر، ایالت، نوع، منطقه یا نام |
+| `uba_station_detail` | یک ایستگاه: آدرس، مختصات، نوع، بازهٔ داده‌ها، آلاینده‌های اخیر |
+| `uba_current_air_quality` | آخرین مقادیر ساعتی + شاخص LQI در یک ایستگاه (کد، شناسه یا نام شهر) |
+| `uba_measurements` | مقادیر ساعتی در یک بازه (حداکثر ۳۱ روز) + کمینه/بیشینه/میانگین و میانگین روزانه |
+| `uba_list_components` | هر ۱۲ آلاینده: کد، نماد، واحد، نام |
+| `uba_list_networks` | ۱۷ شبکهٔ اندازه‌گیری (۱۶ ایالت + UBA) |
+| `uba_health` | بررسی دسترس‌پذیری (ok / blocked / error) — یک درخواست مؤدبانه |
+
+نکته‌ها:
+- ایستگاه‌ها با کد (`DEBE010` = برلین ودینگ)، شناسهٔ عددی یا نام شهر پیدا می‌شوند (اولین ایستگاه فعال آن شهر).
+- `index` / `total_index` (۰ تا ۴) و برچسب‌ها مستقیم از API می‌آیند و از شاخص LQI بازبینی‌شدهٔ ۲۰۲۵ پیروی می‌کنند: بسیار خوب / خوب / متوسط / بد / بسیار بد.
+- همهٔ زمان‌ها CET/CEST هستند، همان‌طور که API برمی‌گرداند. داده‌ها: UBA Air Data API v4 — بدون کلید، بدون ورود، فقط‌خواندنی.
+
+## توسعه
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/pip install -e .
+.venv/bin/python -m pytest tests/ -q
+```
+
+## لایسنس
+
+MIT
+
+---
+
+Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)

uba_mcp-0.1.0/README.md

@@ -0,0 +1,80 @@
+# uba-mcp 🌬️
+
+mcp-name: io.github.mohammad-abbasi-sh/uba-mcp
+
+Unofficial **read-only** MCP server for **[UBA air quality](https://www.umweltbundesamt.de/en/data/air/air-data)** — the Umweltbundesamt (German Federal Environment Agency) Air Data API v4: hourly measurements from ~400 German stations (PM10, PM2.5, NO2, O3, SO2, CO, benzene …) since 2016, with the official UBA air-quality index (LQI). No key, no login.
+
+> Built by Mohammad Abbasi as part of the "Germany MCP factory". Not affiliated with the Umweltbundesamt.
+
+## For AI agents
+
+Add to your MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "uba": {
+      "command": "uvx",
+      "args": ["uba-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+Or run locally: `python -m uba_mcp.server` (needs `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `uba_list_stations` | Measuring stations, filterable by city, state, type, area or name |
+| `uba_station_detail` | One station: address, coordinates, type, data window, recent pollutants |
+| `uba_current_air_quality` | Latest hourly values + LQI at a station (code, id or city name) |
+| `uba_measurements` | Hourly values over a date range (max 31 days) + min/max/mean & daily means |
+| `uba_list_components` | All 12 pollutants: code, symbol, unit, name |
+| `uba_list_networks` | The 17 measuring networks (16 Länder + UBA) |
+| `uba_health` | Reachability check (ok / blocked / error) — one polite request |
+
+Example output (`uba_current_air_quality` / Berlin Neukölln, 2026-11-11 09:00 CET):
+
+```json
+{"station": {"code": "DEBE034", "name": "Berlin Neukölln", "city": "Berlin"},
+ "hour": {"start": "2026-11-11 09:00:00", "total_index": 2, "total_label": "moderate",
+  "values": [{"code": "PM2", "value": 17.0, "unit": "µg/m³", "label": "moderate"},
+             {"code": "PM10", "value": 23.0, "unit": "µg/m³", "label": "good"},
+             {"code": "O3", "value": 24.0, "unit": "µg/m³", "label": "very good"},
+             {"code": "NO2", "value": 15.0, "unit": "µg/m³", "label": "good"}]}}
+```
+
+Notes:
+- Stations are found by code (`DEBE010` = Berlin Wedding), numeric id, or city name (first active station in that city).
+- The `index` / `total_index` (0–4) and labels come from the API itself; they follow the UBA LQI, 2025 revision (hourly means, µg/m³):
+
+| Class | NO2 | PM10 | PM2.5 | O3 | SO2 |
+|-------|-----|------|-------|----|-----|
+| 0 very good | 0–10 | 0–9 | 0–5 | 0–24 | 0–10 |
+| 1 good | 11–30 | 10–27 | 6–15 | 25–72 | 11–30 |
+| 2 moderate | 31–60 | 28–54 | 16–30 | 73–144 | 31–60 |
+| 3 poor | 61–100 | 55–90 | 31–50 | 145–240 | 61–100 |
+| 4 very poor | >100 | >90 | >50 | >240 | >100 |
+
+- All times are CET/CEST as returned by the API. Data: UBA Air Data API v4 `umweltbundesamt.de/api/air_data/v4` — no key, no login, read-only.
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/pip install -e .
+.venv/bin/python -m pytest tests/ -q
+```
+
+- `tests/test_domain.py` — offline, parses real captured API fixtures
+- `tests/test_live.py` — 7 cautious live requests against the UBA API
+
+## License
+
+MIT
+
+---
+
+Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)

uba_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "uba-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for UBA German air quality — hourly measurements and LQI from 400+ stations"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "mcp<2",
+    "httpx>=0.27",
+]
+authors = [{ name = "Mohammad Abbasi" }]
+
+[project.scripts]
+uba-mcp = "uba_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/uba_mcp"]

uba_mcp-0.1.0/server.json

@@ -0,0 +1 @@
+{"$schema":"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json","description":"Unofficial read-only MCP server for German air quality (UBA) — hourly values + LQI, 400 stations.","name":"io.github.mohammad-abbasi-sh/uba-mcp","packages":[{"identifier":"uba-mcp","registryBaseUrl":"https://pypi.org","registryType":"pypi","transport":{"type":"stdio"},"version":"0.1.0"}],"repository":{"source":"github","url":"https://github.com/mohammad-abbasi-sh/uba-mcp"},"title":"UBA Air Quality","version":"0.1.0","websiteUrl":"https://github.com/mohammad-abbasi-sh/uba-mcp"}

uba_mcp-0.1.0/src/uba_mcp/__init__.py

@@ -0,0 +1 @@
+"""uba_mcp package — unofficial read-only MCP access to UBA air data."""