feiertage-mcp 0.1.0__tar.gz

feiertage_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

feiertage_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

feiertage_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

feiertage_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.

feiertage_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: feiertage-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for German public holidays (feiertage-api.de) — holidays by year & state, is-it-a-holiday, next holiday & date ranges
+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
+
+# feiertage-mcp 📅
+
+mcp-name: io.github.mohammad-abbasi-sh/feiertage-mcp
+
+Unofficial **read-only** MCP server for **German public holidays** (gesetzliche Feiertage) via the [feiertage-api.de API](https://feiertage-api.de) (bundesAPI project): holidays per year and federal state, is-it-a-holiday checks, the next holiday from a date, and holidays in a date range. No key, no login.
+
+> Built by Mohammad Abbasi as part of the "Germany MCP factory". Not affiliated with feiertage-api.de / the bundesAPI project.
+
+## For AI agents
+
+Add to your MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "feiertage": {
+      "command": "uvx",
+      "args": ["feiertage-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+Or run locally: `python -m feiertage_mcp.server` (needs `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `feiertage_list_holidays` | Public holidays of one year in one federal state (optional month filter) |
+| `feiertage_is_holiday` | Is a date (YYYY-MM-DD) a public holiday in one state? |
+| `feiertage_next_holiday` | The next public holiday on or after a date (looks into the next year) |
+| `feiertage_holidays_between` | Public holidays in a date range (max ~2 years) |
+| `feiertage_list_states` | All 16 federal states + NATIONAL (nationwide holidays) |
+| `feiertage_health` | Reachability check (ok / blocked / error) — one polite request |
+
+Example output (`feiertage_is_holiday` / 2026-10-03, NATIONAL):
+
+```json
+{"date": "2026-10-03", "weekday": "Saturday", "weekday_de": "Samstag",
+ "state": "NATIONAL", "is_holiday": true,
+ "holidays": ["Tag der Deutschen Einheit"],
+ "details": [{"name": "Tag der Deutschen Einheit", "date": "2026-10-03",
+   "note": null, "note_only": false, "weekday": "Saturday",
+   "weekday_de": "Samstag"}]}
+```
+
+Notes:
+- State codes are the 2-letter codes: BW, BY, BE, BB, HB, HH, HE, MV, NI, NW, RP, SL, SN, ST, SH, TH — or `NATIONAL` for the nationwide holidays (Neujahrstag, Karfreitag, Ostermontag, Tag der Arbeit, Christi Himmelfahrt, Pfingstmontag, Tag der Deutschen Einheit, 1./2. Weihnachtstag). Use `feiertage_list_states` for the full list.
+- Holiday names are German; each dated holiday also carries its weekday in English and German.
+- A few entries have no date (`note_only: true`) — they are notes, e.g. school-free days, not statutory public holidays. Date-based tools skip them.
+- Years 1900–2100 are accepted; the API serves historical and future calendars.
+- `feiertage_holidays_between` fetches one request per year in the range (max ~2 years).
+
+Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)

feiertage_mcp-0.1.0/README-de.md

@@ -0,0 +1,55 @@
+# feiertage-mcp 📅
+
+mcp-name: io.github.mohammad-abbasi-sh/feiertage-mcp
+
+Inoffizieller **Nur-Lesen**-MCP-Server für **deutsche Feiertage** (gesetzliche Feiertage) über die [feiertage-api.de API](https://feiertage-api.de) (bundesAPI-Projekt): Feiertage pro Jahr und Bundesland, Ist-es-ein-Feiertag-Prüfung, der nächste Feiertag ab einem Datum und Feiertage in einem Zeitraum. Kein Schlüssel, keine Anmeldung nötig.
+
+> Gebaut von Mohammad Abbasi im Rahmen der „Germany MCP factory". Keine Verbindung zu feiertage-api.de / dem bundesAPI-Projekt.
+
+## Für KI-Agenten
+
+In die MCP-Client-Konfiguration eintragen (stdio):
+
+```json
+{
+  "mcpServers": {
+    "feiertage": {
+      "command": "uvx",
+      "args": ["feiertage-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+Oder lokal starten: `python -m feiertage_mcp.server` (benötigt `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Beschreibung |
+|------|--------------|
+| `feiertage_list_holidays` | Feiertage eines Jahres in einem Bundesland (optional nach Monat gefiltert) |
+| `feiertage_is_holiday` | Ist ein Datum (YYYY-MM-DD) ein Feiertag in einem Bundesland? |
+| `feiertage_next_holiday` | Der nächste Feiertag ab einem Datum (blickt auch ins nächste Jahr) |
+| `feiertage_holidays_between` | Feiertage in einem Zeitraum (max. ca. 2 Jahre) |
+| `feiertage_list_states` | Alle 16 Bundesländer + NATIONAL (bundesweite Feiertage) |
+| `feiertage_health` | Erreichbarkeitsprüfung (ok / blocked / error) — eine höfliche Anfrage |
+
+Beispielausgabe (`feiertage_is_holiday` / 2026-10-03, NATIONAL):
+
+```json
+{"date": "2026-10-03", "weekday": "Saturday", "weekday_de": "Samstag",
+ "state": "NATIONAL", "is_holiday": true,
+ "holidays": ["Tag der Deutschen Einheit"],
+ "details": [{"name": "Tag der Deutschen Einheit", "date": "2026-10-03",
+   "note": null, "note_only": false, "weekday": "Saturday",
+   "weekday_de": "Samstag"}]}
+```
+
+Hinweise:
+- Bundesland-Codes sind die 2-Buchstaben-Codes: BW, BY, BE, BB, HB, HH, HE, MV, NI, NW, RP, SL, SN, ST, SH, TH — oder `NATIONAL` für die bundesweiten Feiertage (Neujahrstag, Karfreitag, Ostermontag, Tag der Arbeit, Christi Himmelfahrt, Pfingstmontag, Tag der Deutschen Einheit, 1./2. Weihnachtstag). `feiertage_list_states` liefert die vollständige Liste.
+- Feiertagsnamen sind deutsch; jeder datierte Feiertag trägt zusätzlich seinen Wochentag auf Englisch und Deutsch.
+- Einige Einträge haben kein Datum (`note_only: true`) — das sind Hinweise, z. B. schulfreie Tage, keine gesetzlichen Feiertage. Datumsbasierte Tools überspringen sie.
+- Jahre 1900–2100 werden akzeptiert; die API liefert historische und zukünftige Kalender.
+- `feiertage_holidays_between` stellt eine Anfrage pro Jahr im Zeitraum (max. ca. 2 Jahre).
+
+Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)

feiertage_mcp-0.1.0/README-fa.md

@@ -0,0 +1,55 @@
+# feiertage-mcp 📅
+
+mcp-name: io.github.mohammad-abbasi-sh/feiertage-mcp
+
+سرور MCP غیررسمی و **فقط‌خواندنی** برای **تعطیلات رسمی آلمان** (gesetzliche Feiertage) از طریق [API سایت feiertage-api.de](https://feiertage-api.de) (پروژهٔ bundesAPI): تعطیلات هر سال در هر ایالت فدرال، بررسی اینکه یک تاریخ تعطیل است یا نه، نزدیک‌ترین تعطیل از یک تاریخ، و تعطیلات در یک بازهٔ زمانی. بدون کلید و بدون ورود.
+
+> ساختهٔ محمد عباسی در چارچوب «کارخانهٔ MCP آلمان». وابسته به feiertage-api.de / پروژهٔ bundesAPI نیست.
+
+## برای ایجنت‌های هوش مصنوعی
+
+به پیکربندی MCP Client اضافه کنید (stdio):
+
+```json
+{
+  "mcpServers": {
+    "feiertage": {
+      "command": "uvx",
+      "args": ["feiertage-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+یا به‌صورت محلی اجرا کنید: `python -m feiertage_mcp.server` (نیازمند `mcp<2` و `httpx`).
+
+## ابزارها
+
+| ابزار | توضیح |
+|------|-------|
+| `feiertage_list_holidays` | تعطیلات رسمی یک سال در یک ایالت فدرال (با فیلتر اختیاری ماه) |
+| `feiertage_is_holiday` | آیا یک تاریخ (YYYY-MM-DD) در یک ایالت تعطیل رسمی است؟ |
+| `feiertage_next_holiday` | نزدیک‌ترین تعطیل رسمی از یک تاریخ به بعد (به سال بعد هم نگاه می‌کند) |
+| `feiertage_holidays_between` | تعطیلات رسمی در یک بازهٔ زمانی (حداکثر حدود ۲ سال) |
+| `feiertage_list_states` | هر ۱۶ ایالت فدرال + NATIONAL (تعطیلات سراسری) |
+| `feiertage_health` | بررسی دسترسی به API (ok / blocked / error) — یک درخواست مؤدبانه |
+
+نمونهٔ خروجی (`feiertage_is_holiday` / ۲۰۲۶-۱۰-۰۳، NATIONAL):
+
+```json
+{"date": "2026-10-03", "weekday": "Saturday", "weekday_de": "Samstag",
+ "state": "NATIONAL", "is_holiday": true,
+ "holidays": ["Tag der Deutschen Einheit"],
+ "details": [{"name": "Tag der Deutschen Einheit", "date": "2026-10-03",
+   "note": null, "note_only": false, "weekday": "Saturday",
+   "weekday_de": "Samstag"}]}
+```
+
+نکته‌ها:
+- کد ایالت‌ها دو حرفی است: BW، BY، BE، BB، HB، HH، HE، MV، NI، NW، RP، SL، SN، ST، SH، TH — یا `NATIONAL` برای تعطیلات سراسری (Neujahrstag، Karfreitag، Ostermontag، Tag der Arbeit، Christi Himmelfahrt، Pfingstmontag، Tag der Deutschen Einheit، ۱ و ۲ Weihnachtstag). فهرست کامل را از `feiertage_list_states` بگیرید.
+- نام تعطیلات آلمانی است؛ هر تعطیلِ تاریخ‌دار روز هفته را هم به انگلیسی و هم به آلمانی دارد.
+- چند ورودی تاریخ ندارند (`note_only: true`) — این‌ها فقط یادداشت‌اند، مثلاً روزهای تعطیل مدارس، نه تعطیل رسمی قانونی. ابزارهای مبتنی بر تاریخ آن‌ها را رد می‌کنند.
+- سال‌های ۱۹۰۰ تا ۲۱۰۰ پذیرفته می‌شوند؛ API تقویم‌های گذشته و آینده را می‌دهد.
+- `feiertage_holidays_between` برای هر سال در بازه یک درخواست می‌فرستد (حداکثر حدود ۲ سال).
+
+Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)

feiertage_mcp-0.1.0/README.md

@@ -0,0 +1,55 @@
+# feiertage-mcp 📅
+
+mcp-name: io.github.mohammad-abbasi-sh/feiertage-mcp
+
+Unofficial **read-only** MCP server for **German public holidays** (gesetzliche Feiertage) via the [feiertage-api.de API](https://feiertage-api.de) (bundesAPI project): holidays per year and federal state, is-it-a-holiday checks, the next holiday from a date, and holidays in a date range. No key, no login.
+
+> Built by Mohammad Abbasi as part of the "Germany MCP factory". Not affiliated with feiertage-api.de / the bundesAPI project.
+
+## For AI agents
+
+Add to your MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "feiertage": {
+      "command": "uvx",
+      "args": ["feiertage-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+Or run locally: `python -m feiertage_mcp.server` (needs `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `feiertage_list_holidays` | Public holidays of one year in one federal state (optional month filter) |
+| `feiertage_is_holiday` | Is a date (YYYY-MM-DD) a public holiday in one state? |
+| `feiertage_next_holiday` | The next public holiday on or after a date (looks into the next year) |
+| `feiertage_holidays_between` | Public holidays in a date range (max ~2 years) |
+| `feiertage_list_states` | All 16 federal states + NATIONAL (nationwide holidays) |
+| `feiertage_health` | Reachability check (ok / blocked / error) — one polite request |
+
+Example output (`feiertage_is_holiday` / 2026-10-03, NATIONAL):
+
+```json
+{"date": "2026-10-03", "weekday": "Saturday", "weekday_de": "Samstag",
+ "state": "NATIONAL", "is_holiday": true,
+ "holidays": ["Tag der Deutschen Einheit"],
+ "details": [{"name": "Tag der Deutschen Einheit", "date": "2026-10-03",
+   "note": null, "note_only": false, "weekday": "Saturday",
+   "weekday_de": "Samstag"}]}
+```
+
+Notes:
+- State codes are the 2-letter codes: BW, BY, BE, BB, HB, HH, HE, MV, NI, NW, RP, SL, SN, ST, SH, TH — or `NATIONAL` for the nationwide holidays (Neujahrstag, Karfreitag, Ostermontag, Tag der Arbeit, Christi Himmelfahrt, Pfingstmontag, Tag der Deutschen Einheit, 1./2. Weihnachtstag). Use `feiertage_list_states` for the full list.
+- Holiday names are German; each dated holiday also carries its weekday in English and German.
+- A few entries have no date (`note_only: true`) — they are notes, e.g. school-free days, not statutory public holidays. Date-based tools skip them.
+- Years 1900–2100 are accepted; the API serves historical and future calendars.
+- `feiertage_holidays_between` fetches one request per year in the range (max ~2 years).
+
+Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)

feiertage_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "feiertage-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for German public holidays (feiertage-api.de) — holidays by year & state, is-it-a-holiday, next holiday & date ranges"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "mcp<2",
+    "httpx>=0.27",
+]
+authors = [{ name = "Mohammad Abbasi" }]
+
+[project.scripts]
+feiertage-mcp = "feiertage_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/feiertage_mcp"]

feiertage_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 public holidays (feiertage-api.de) — by year & state, is-it-a-holiday, next holiday.","name":"io.github.mohammad-abbasi-sh/feiertage-mcp","packages":[{"identifier":"feiertage-mcp","registryBaseUrl":"https://pypi.org","registryType":"pypi","transport":{"type":"stdio"},"version":"0.1.0"}],"repository":{"source":"github","url":"https://github.com/mohammad-abbasi-sh/feiertage-mcp"},"title":"Feiertage — German public holidays by year & federal state","version":"0.1.0","websiteUrl":"https://github.com/mohammad-abbasi-sh/feiertage-mcp"}

feiertage_mcp-0.1.0/src/feiertage_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""feiertage_mcp package — unofficial read-only MCP access to German public
+holidays (feiertage-api.de)."""

feiertage_mcp-0.1.0/src/feiertage_mcp/domain.py

@@ -0,0 +1,241 @@
+"""Domain logic: shape feiertage-api.de responses into compact dicts
+(stdlib only).
+
+Data source: the free feiertage-api.de API — German public holidays
+(gesetzliche Feiertage) per year and federal state, no key, no login.
+The API is a thin wrapper over the German holiday calendar (Wikipedia /
+feiertage-api.de, by the bundesAPI project).
+
+- GET /api/?jahr=YYYY — all 16 federal states + NATIONAL, each a dict
+  holiday name -> {"datum": "YYYY-MM-DD" or null, "hinweis": "..."}.
+- GET /api/?jahr=YYYY&nur_land=XX — one state only (2-letter code, or
+  NATIONAL for the nationwide holidays). Case-insensitive; an unknown
+  code returns JSON `null` with HTTP 200.
+- "datum" can be null: the entry is then a note only (e.g. Gründonnerstag
+  in Baden-Württemberg 1990 — pupils have the day off, but it is not a
+  statutory public holiday). Such entries are kept with date None and
+  flagged note_only; date-based tools skip them.
+- "hinweis" is a free-text note (often empty); kept as "note".
+
+Holiday names are German (Neujahrstag, Karfreitag, ...); this server
+does not translate them — the weekday is given in English and German.
+"""
+from __future__ import annotations
+
+import json
+import re
+from datetime import date, timedelta
+from urllib.parse import quote_plus
+
+BASE = "https://feiertage-api.de"
+
+# The 16 federal states (Bundesländer) + NATIONAL (bundesweite Feiertage).
+# Codes are the ones the API accepts in nur_land.
+STATES = {
+    "BW": "Baden-Württemberg",
+    "BY": "Bayern",
+    "BE": "Berlin",
+    "BB": "Brandenburg",
+    "HB": "Bremen",
+    "HH": "Hamburg",
+    "HE": "Hessen",
+    "MV": "Mecklenburg-Vorpommern",
+    "NI": "Niedersachsen",
+    "NW": "Nordrhein-Westfalen",
+    "RP": "Rheinland-Pfalz",
+    "SL": "Saarland",
+    "SN": "Sachsen",
+    "ST": "Sachsen-Anhalt",
+    "SH": "Schleswig-Holstein",
+    "TH": "Thüringen",
+    "NATIONAL": "Bundesweit (nationwide)",
+}
+
+STATE_CODES = sorted(STATES)
+DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+YEAR_MIN, YEAR_MAX = 1900, 2100
+MAX_RANGE_DAYS = 731  # holidays_between: at most ~2 years
+
+WEEKDAYS_EN = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday",
+               "Saturday", "Sunday"]
+WEEKDAYS_DE = ["Montag", "Dienstag", "Mittwoch", "Donnerstag", "Freitag",
+               "Samstag", "Sonntag"]
+
+
+def validate_year(year, default: int | None = None) -> int:
+    """A year the API serves (1900..2100); default = current year."""
+    if year is None:
+        if default is None:
+            default = date.today().year
+        year = default
+    try:
+        y = int(year)
+    except (TypeError, ValueError):
+        raise ValueError(f"year must be a number, got {year!r}") from None
+    if not YEAR_MIN <= y <= YEAR_MAX:
+        raise ValueError(
+            f"year out of range: {year} (expected {YEAR_MIN}..{YEAR_MAX})"
+        )
+    return y
+
+
+def validate_state(state: str | None, default: str = "NATIONAL") -> str:
+    """A 2-letter state code (case-insensitive) or NATIONAL."""
+    if state is None:
+        return default
+    code = state.strip().upper()
+    if code not in STATES:
+        raise ValueError(
+            f"unknown state {state!r} (expected one of: "
+            + ", ".join(STATE_CODES) + ")"
+        )
+    return code
+
+
+def validate_date(value: str) -> date:
+    """A YYYY-MM-DD date."""
+    text = (value or "").strip()
+    if not DATE_RE.fullmatch(text):
+        raise ValueError(
+            f"bad date {value!r} (expected YYYY-MM-DD, e.g. 2026-12-25)"
+        )
+    try:
+        return date.fromisoformat(text)
+    except ValueError:
+        raise ValueError(f"bad date {value!r} (not a real calendar date)") from None
+
+
+def validate_month(month) -> int | None:
+    """A month 1..12, or None (no month filter)."""
+    if month is None:
+        return None
+    try:
+        m = int(month)
+    except (TypeError, ValueError):
+        raise ValueError(f"month must be a number, got {month!r}") from None
+    if not 1 <= m <= 12:
+        raise ValueError(f"month out of range: {month} (expected 1..12)")
+    return m
+
+
+def holidays_url(year: int, state: str | None = None) -> str:
+    """API URL for one year; state=None fetches all states at once."""
+    y = validate_year(year)
+    url = f"{BASE}/api/?jahr={y}"
+    if state is not None:
+        url += f"&nur_land={quote_plus(validate_state(state))}"
+    return url
+
+
+def _holiday_row(name: str, entry: dict) -> dict:
+    datum = entry.get("datum")
+    note = (entry.get("hinweis") or "").strip()
+    row = {"name": name, "date": datum, "note": note or None,
+           "note_only": datum is None}
+    if datum:
+        d = date.fromisoformat(datum)
+        row["weekday"] = WEEKDAYS_EN[d.weekday()]
+        row["weekday_de"] = WEEKDAYS_DE[d.weekday()]
+    return row
+
+
+def parse_holidays(text: str) -> list:
+    """One state's holiday dict -> sorted list of holiday rows.
+
+    Raises ValueError on JSON null (unknown state code) or bad shapes.
+    Note-only entries (datum null) are kept, flagged note_only, and
+    sort after dated entries.
+    """
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"invalid holidays response: {e}") from e
+    if payload is None:
+        raise ValueError(
+            "unknown state code (the API returned null) — use one of: "
+            + ", ".join(STATE_CODES)
+        )
+    if not isinstance(payload, dict):
+        raise ValueError("unexpected holidays shape: not a JSON object")
+    rows = []
+    for name, entry in payload.items():
+        if not isinstance(entry, dict) or "datum" not in entry:
+            raise ValueError(f"unexpected holiday entry for {name!r}")
+        rows.append(_holiday_row(name, entry))
+    rows.sort(key=lambda r: (r["date"] is None, r["date"] or "", r["name"]))
+    return rows
+
+
+def parse_all_states(text: str) -> dict:
+    """Full-year response -> {state_code: [holiday rows]}."""
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"invalid holidays response: {e}") from e
+    if not isinstance(payload, dict):
+        raise ValueError("unexpected holidays shape: not a JSON object")
+    out = {}
+    for code, holidays in payload.items():
+        if not isinstance(holidays, dict):
+            raise ValueError(f"unexpected holidays shape for state {code!r}")
+        out[code] = [
+            _holiday_row(name, entry)
+            for name, entry in holidays.items()
+        ]
+        out[code].sort(key=lambda r: (r["date"] is None, r["date"] or "",
+                                      r["name"]))
+    return out
+
+
+def list_states() -> list:
+    """All state codes with their German names (static data)."""
+    return [{"code": code, "name": STATES[code]} for code in STATE_CODES]
+
+
+def holidays_in_month(rows: list, month: int | None) -> list:
+    """Filter dated holiday rows to one month (None = no filter)."""
+    if month is None:
+        return rows
+    return [r for r in rows
+            if r["date"] is not None and int(r["date"][5:7]) == month]
+
+
+def is_holiday(rows: list, day: date) -> list:
+    """Holiday rows falling on one date (dated entries only)."""
+    target = day.isoformat()
+    return [r for r in rows if r["date"] == target]
+
+
+def next_holiday(rows: list, start: date) -> dict | None:
+    """First dated holiday on or after `start`, or None."""
+    target = start.isoformat()
+    dated = [r for r in rows if r["date"] is not None]
+    dated.sort(key=lambda r: r["date"])
+    for row in dated:
+        if row["date"] >= target:
+            return row
+    return None
+
+
+def holidays_between(rows_by_year: dict[int, list], start: date,
+                     end: date) -> list:
+    """Merge per-year holiday rows into one dated, sorted list in range."""
+    if end < start:
+        raise ValueError(
+            f"end date {end} is before start date {start}"
+        )
+    if (end - start).days > MAX_RANGE_DAYS:
+        raise ValueError(
+            f"date range too wide: {(end - start).days} days "
+            f"(max {MAX_RANGE_DAYS})"
+        )
+    out = []
+    for year, rows in rows_by_year.items():
+        for row in rows:
+            if row["date"] is None:
+                continue
+            d = date.fromisoformat(row["date"])
+            if start <= d <= end:
+                out.append(row)
+    out.sort(key=lambda r: r["date"])
+    return out