mediathek-mcp 0.1.0__tar.gz

mediathek_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

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

@@ -0,0 +1,61 @@
+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: 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)
+        run: |
+          mcp-publisher login github-oidc
+          mcp-publisher publish server.json
+        # A registry outage must never break the release; re-run from Actions if needed.
+        continue-on-error: true

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

mediathek_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: mediathek-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for the German public broadcasters' Mediathek — search ARD, ZDF, 3sat, ARTE, Phoenix and more via MediathekViewWeb
+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
+
+# mediathek-mcp 📺
+
+mcp-name: io.github.mohammad-abbasi-sh/mediathek-mcp
+
+Unofficial **read-only** MCP server for the **German Mediathek** via the free [MediathekViewWeb](https://mediathekviewweb.de) API — search the programmes of ARD, ZDF, 3sat, ARTE, Phoenix, tagesschau24, KiKA and the regional channels. No key, no login.
+
+> Built by Mohammad Abbasi as part of the "Germany MCP factory" (Sepehr-style pipeline). Not affiliated with MediathekView, ARD or ZDF.
+
+## For AI agents
+
+Add to your MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "mediathek": {
+      "command": "uvx",
+      "args": ["mediathek-mcp"]
+    }
+  }
+}
+```
+
+Or run locally: `python -m mediathek_mcp.server` (needs `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `mediathek_search_programmes` | Search programmes by title, topic or description — `query` (e.g. "Tagesschau"), optional `channel` (e.g. "ZDF"), `limit` 1..50 |
+| `mediathek_latest_broadcasts` | Newest programmes across all channels, newest first — `limit` 1..50 |
+| `mediathek_by_channel` | Newest programmes of one channel — `channel` (e.g. "ZDF", "ARD", "3sat", "ARTE.DE", "PHOENIX"), `limit` 1..50 |
+| `mediathek_by_topic` | All episodes of one show/series — `topic` (e.g. "heute journal"), `limit` 1..50 |
+| `mediathek_programme_detail` | Full detail of one programme: all video URLs (low/standard/HD), subtitle URL, website link — `title` (exact), optional `channel` |
+| `mediathek_list_channels` | Channels in the film list (curated list — the API has no channel-list endpoint) |
+
+Example output (`mediathek_search_programmes` / "Tagesschau"):
+
+```json
+{"query": "Tagesschau", "channel": null, "total_results": 8823, "count": 3,
+ "film_list_updated": "2026-11-09T10:19:00+00:00", "programmes": [
+  {"id": "+sU90jI0m7KCrRqsj5aYEh9Owg7tr+3K9IRl39v+A8o=",
+   "channel": "tagesschau24", "topic": "tagesschau in 100 Sekunden",
+   "title": "tagesschau in 100 Sekunden",
+   "description": "tagesschau in 100 Sekunden",
+   "broadcast": "2026-11-09T04:43:00+00:00", "duration_seconds": 170,
+   "duration": "2:50",
+   "video_url": "https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0445-5500.webxl.h264.mp4",
+   "video_url_hd": "https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0445-5500.webxxl.h264.mp4",
+   "video_url_low": "https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0257-3000.webm.h264.mp4",
+   "subtitle_url": "", "website_url": "https://www.ardmediathek.de/video/...",
+   "size_bytes": 40894464},
+  ...]}
+```
+
+Notes:
+- The film list holds ~700,000 programmes and is updated several times a day; results are newest first.
+- "Latest broadcasts" searches the most common letter across title/topic/description — the API returns nothing for an empty query and has no wildcard, so this is effectively the newest programmes.
+- Channel filtering in `mediathek_search_programmes` is applied client-side over the newest 50 text matches (the API has no AND query); `mediathek_by_channel` queries the channel directly.
+- `total_results` is capped at 10,000 by the API for very broad queries.
+- Video URLs are direct MP4 links (low / standard / HD); `subtitle_url` is empty when no subtitles exist.
+- Data: MediathekViewWeb public API — no key, no login, read-only.
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/python -m pytest tests/ -q
+```
+
+- `tests/test_domain.py` — offline, parses real captured API fixtures (19 tests)
+- `tests/test_live.py` — cautious live requests against mediathekviewweb.de (6 tests)
+
+Tests: 25/25 green (19 offline + 6 live, 2026-11-09).
+
+## License
+
+MIT

mediathek_mcp-0.1.0/README-de.md

@@ -0,0 +1,57 @@
+# mediathek-mcp 📺
+
+**Die deutsche Mediathek** über die kostenlose [MediathekViewWeb](https://mediathekviewweb.de)-API — inoffizieller, **nur lesender** MCP-Server: Sendungen von ARD, ZDF, 3sat, ARTE, Phoenix, tagesschau24, KiKA und den Regionalsendern durchsuchen. Kein Schlüssel, keine Anmeldung.
+
+> Gebaut von Mohammad Abbasi im Rahmen der „Germany MCP factory“ (Sepehr-Stil). Keine Verbindung zu MediathekView, ARD oder ZDF.
+
+## Für KI-Agenten
+
+In die MCP-Konfiguration eintragen (stdio):
+
+```json
+{
+  "mcpServers": {
+    "mediathek": {
+      "command": "uvx",
+      "args": ["mediathek-mcp"]
+    }
+  }
+}
+```
+
+Oder lokal starten: `python -m mediathek_mcp.server` (benötigt `mcp<2`, `httpx`).
+
+## Werkzeuge
+
+| Werkzeug | Beschreibung |
+|------|-------------|
+| `mediathek_search_programmes` | Sendungen nach Titel, Thema oder Beschreibung suchen — `query` (z. B. „Tagesschau“), optional `channel` (z. B. „ZDF“), `limit` 1..50 |
+| `mediathek_latest_broadcasts` | Neueste Sendungen aller Sender, neueste zuerst — `limit` 1..50 |
+| `mediathek_by_channel` | Neueste Sendungen eines Senders — `channel` (z. B. „ZDF“, „ARD“, „3sat“, „ARTE.DE“, „PHOENIX“), `limit` 1..50 |
+| `mediathek_by_topic` | Alle Folgen einer Sendung/Serie — `topic` (z. B. „heute journal“), `limit` 1..50 |
+| `mediathek_programme_detail` | Details einer Sendung: alle Video-URLs (niedrig/Standard/HD), Untertitel-URL, Webseiten-Link — `title` (exakt), optional `channel` |
+| `mediathek_list_channels` | Sender der Filmliste (kuratierte Liste — die API hat keinen Senderlisten-Endpunkt) |
+
+Hinweise:
+- Die Filmliste enthält ca. 700.000 Sendungen und wird mehrmals täglich aktualisiert; die Ergebnisse sind neueste zuerst sortiert.
+- „Neueste Sendungen“ sucht nach dem häufigsten Buchstaben in Titel/Thema/Beschreibung — die API liefert bei leerer Anfrage nichts und kennt keinen Platzhalter; das Ergebnis sind praktisch die neuesten Sendungen.
+- Die Senderfilterung in `mediathek_search_programmes` erfolgt clientseitig über die neuesten 50 Texttreffer (die API kennt keine UND-Anfrage); `mediathek_by_channel` fragt den Sender direkt ab.
+- `total_results` ist bei sehr breiten Anfragen von der API auf 10.000 begrenzt.
+- Video-URLs sind direkte MP4-Links (niedrig / Standard / HD); `subtitle_url` ist leer, wenn keine Untertitel existieren.
+- Daten: öffentliche MediathekViewWeb-API — kein Schlüssel, keine Anmeldung, nur lesend.
+
+## Entwicklung
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/python -m pytest tests/ -q
+```
+
+- `tests/test_domain.py` — offline, mit echten aufgezeichneten API-Antworten (19 Tests)
+- `tests/test_live.py` — wenige vorsichtige Live-Anfragen an mediathekviewweb.de (6 Tests)
+
+Tests: 25/25 grün (19 offline + 6 live, 09.11.2026).
+
+## Lizenz
+
+MIT

mediathek_mcp-0.1.0/README-fa.md

@@ -0,0 +1,57 @@
+# mediathek-mcp 📺
+
+سرور MCP **غیررسمی و فقط‌خواندنی** برای **مدیاتک آلمان** از طریق API رایگان [MediathekViewWeb](https://mediathekviewweb.de) — جست‌وجوی برنامه‌های ARD ،ZDF ،3sat ،ARTE ،Phoenix ،tagesschau24 ،KiKA و شبکه‌های منطقه‌ای. بدون کلید، بدون لاگین.
+
+> ساختهٔ محمد عباسی در چارچوب «کارخانهٔ MCP آلمان» (به سبک سپهر). وابسته به MediathekView یا ARD یا ZDF نیست.
+
+## برای ایجنت‌های هوش مصنوعی
+
+به تنظیمات MCP اضافه کنید (stdio):
+
+```json
+{
+  "mcpServers": {
+    "mediathek": {
+      "command": "uvx",
+      "args": ["mediathek-mcp"]
+    }
+  }
+}
+```
+
+یا اجرای محلی: `python -m mediathek_mcp.server` (نیازمند `mcp<2` و `httpx`).
+
+## ابزارها
+
+| ابزار | توضیح |
+|------|------|
+| `mediathek_search_programmes` | جست‌وجوی برنامه‌ها با عنوان، موضوع یا توضیح — `query` (مثل «Tagesschau»)، `channel` اختیاری (مثل «ZDF»)، `limit` از ۱ تا ۵۰ |
+| `mediathek_latest_broadcasts` | جدیدترین برنامه‌های همهٔ شبکه‌ها، از جدید به قدیم — `limit` از ۱ تا ۵۰ |
+| `mediathek_by_channel` | جدیدترین برنامه‌های یک شبکه — `channel` (مثل «ZDF»، «ARD»، «3sat»، «ARTE.DE»، «PHOENIX»)، `limit` از ۱ تا ۵۰ |
+| `mediathek_by_topic` | همهٔ قسمت‌های یک برنامه/سریال — `topic` (مثل «heute journal»)، `limit` از ۱ تا ۵۰ |
+| `mediathek_programme_detail` | جزئیات کامل یک برنامه: همهٔ لینک‌های ویدیو (کم‌کیفیت/معمولی/HD)، لینک زیرنویس و لینک وب‌سایت — `title` (دقیق)، `channel` اختیاری |
+| `mediathek_list_channels` | شبکه‌های فهرست فیلم (فهرست انتخاب‌شده — API اندپوینت فهرست شبکه ندارد) |
+
+نکته‌ها:
+- فهرست فیلم حدود ۷۰۰٬۰۰۰ برنامه دارد و چند بار در روز به‌روز می‌شود؛ نتایج از جدید به قدیم مرتب‌اند.
+- «جدیدترین برنامه‌ها» با جست‌وجوی پرتکرارترین حرف در عنوان/موضوع/توضیح کار می‌کند — API برای پرس‌وجوی خالی چیزی برنمی‌گرداند و کاراکتر جایگزین ندارد؛ نتیجه عملاً جدیدترین برنامه‌هاست.
+- فیلتر شبکه در `mediathek_search_programmes` سمت کلاینت روی جدیدترین ۵۰ نتیجهٔ متنی اعمال می‌شود (API پرس‌وجوی AND ندارد)؛ `mediathek_by_channel` مستقیم شبکه را می‌پرسد.
+- مقدار `total_results` برای پرس‌وجوهای خیلی گسترده از طرف API به ۱۰٬۰۰۰ محدود است.
+- لینک‌های ویدیو مستقیم MP4 هستند (کم‌کیفیت / معمولی / HD)؛ اگر زیرنویس نباشد `subtitle_url` خالی است.
+- داده: API عمومی MediathekViewWeb — بدون کلید، بدون لاگین، فقط‌خواندنی.
+
+## توسعه
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/python -m pytest tests/ -q
+```
+
+- `tests/test_domain.py` — آفلاین، با پاسخ‌های واقعی ضبط‌شده از API (۱۹ تست)
+- `tests/test_live.py` — چند درخواست زندهٔ محتاطانه به mediathekviewweb.de (۶ تست)
+
+تست‌ها: ۲۵ از ۲۵ سبز (۱۹ آفلاین + ۶ زنده، ۲۰۲۶-۱۱-۰۹).
+
+## مجوز
+
+MIT

mediathek_mcp-0.1.0/README.md

@@ -0,0 +1,78 @@
+# mediathek-mcp 📺
+
+mcp-name: io.github.mohammad-abbasi-sh/mediathek-mcp
+
+Unofficial **read-only** MCP server for the **German Mediathek** via the free [MediathekViewWeb](https://mediathekviewweb.de) API — search the programmes of ARD, ZDF, 3sat, ARTE, Phoenix, tagesschau24, KiKA and the regional channels. No key, no login.
+
+> Built by Mohammad Abbasi as part of the "Germany MCP factory" (Sepehr-style pipeline). Not affiliated with MediathekView, ARD or ZDF.
+
+## For AI agents
+
+Add to your MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "mediathek": {
+      "command": "uvx",
+      "args": ["mediathek-mcp"]
+    }
+  }
+}
+```
+
+Or run locally: `python -m mediathek_mcp.server` (needs `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `mediathek_search_programmes` | Search programmes by title, topic or description — `query` (e.g. "Tagesschau"), optional `channel` (e.g. "ZDF"), `limit` 1..50 |
+| `mediathek_latest_broadcasts` | Newest programmes across all channels, newest first — `limit` 1..50 |
+| `mediathek_by_channel` | Newest programmes of one channel — `channel` (e.g. "ZDF", "ARD", "3sat", "ARTE.DE", "PHOENIX"), `limit` 1..50 |
+| `mediathek_by_topic` | All episodes of one show/series — `topic` (e.g. "heute journal"), `limit` 1..50 |
+| `mediathek_programme_detail` | Full detail of one programme: all video URLs (low/standard/HD), subtitle URL, website link — `title` (exact), optional `channel` |
+| `mediathek_list_channels` | Channels in the film list (curated list — the API has no channel-list endpoint) |
+
+Example output (`mediathek_search_programmes` / "Tagesschau"):
+
+```json
+{"query": "Tagesschau", "channel": null, "total_results": 8823, "count": 3,
+ "film_list_updated": "2026-11-09T10:19:00+00:00", "programmes": [
+  {"id": "+sU90jI0m7KCrRqsj5aYEh9Owg7tr+3K9IRl39v+A8o=",
+   "channel": "tagesschau24", "topic": "tagesschau in 100 Sekunden",
+   "title": "tagesschau in 100 Sekunden",
+   "description": "tagesschau in 100 Sekunden",
+   "broadcast": "2026-11-09T04:43:00+00:00", "duration_seconds": 170,
+   "duration": "2:50",
+   "video_url": "https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0445-5500.webxl.h264.mp4",
+   "video_url_hd": "https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0445-5500.webxxl.h264.mp4",
+   "video_url_low": "https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0257-3000.webm.h264.mp4",
+   "subtitle_url": "", "website_url": "https://www.ardmediathek.de/video/...",
+   "size_bytes": 40894464},
+  ...]}
+```
+
+Notes:
+- The film list holds ~700,000 programmes and is updated several times a day; results are newest first.
+- "Latest broadcasts" searches the most common letter across title/topic/description — the API returns nothing for an empty query and has no wildcard, so this is effectively the newest programmes.
+- Channel filtering in `mediathek_search_programmes` is applied client-side over the newest 50 text matches (the API has no AND query); `mediathek_by_channel` queries the channel directly.
+- `total_results` is capped at 10,000 by the API for very broad queries.
+- Video URLs are direct MP4 links (low / standard / HD); `subtitle_url` is empty when no subtitles exist.
+- Data: MediathekViewWeb public API — no key, no login, read-only.
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/python -m pytest tests/ -q
+```
+
+- `tests/test_domain.py` — offline, parses real captured API fixtures (19 tests)
+- `tests/test_live.py` — cautious live requests against mediathekviewweb.de (6 tests)
+
+Tests: 25/25 green (19 offline + 6 live, 2026-11-09).
+
+## License
+
+MIT

mediathek_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mediathek-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for the German public broadcasters' Mediathek — search ARD, ZDF, 3sat, ARTE, Phoenix and more via MediathekViewWeb"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "mcp<2",
+    "httpx>=0.27",
+]
+authors = [{ name = "Mohammad Abbasi" }]
+
+[project.scripts]
+mediathek-mcp = "mediathek_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mediathek_mcp"]
+
+[tool.pytest.ini_options]
+markers = ["live: tests that hit the real MediathekViewWeb API"]
+

mediathek_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 the German Mediathek — search ARD, ZDF, 3sat, ARTE & more.","name":"io.github.mohammad-abbasi-sh/mediathek-mcp","packages":[{"identifier":"mediathek-mcp","registryBaseUrl":"https://pypi.org","registryType":"pypi","transport":{"type":"stdio"},"version":"0.1.0"}],"repository":{"source":"github","url":"https://github.com/mohammad-abbasi-sh/mediathek-mcp"},"title":"Mediathek — German public broadcasters' programmes","version":"0.1.0","websiteUrl":"https://github.com/mohammad-abbasi-sh/mediathek-mcp"}

mediathek_mcp-0.1.0/src/mediathek_mcp/__init__.py

@@ -0,0 +1,9 @@
+"""mediathek_mcp — unofficial read-only MCP server for the German Mediathek.
+
+Searches the programmes of the German public broadcasters (ARD, ZDF, 3sat,
+ARTE, Phoenix, tagesschau24, KiKA and the regional channels) through the
+free MediathekViewWeb API (mediathekviewweb.de) — no key, no login.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"

mediathek_mcp-0.1.0/src/mediathek_mcp/domain.py

@@ -0,0 +1,118 @@
+"""Domain logic: shape MediathekViewWeb responses into compact dicts (stdlib only)."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+# Channels in the MediathekView film list, as seen in live probes and the
+# project's public channel list. The API itself has no channel-list
+# endpoint, so this is a curated list — search_by_channel passes any
+# other channel name through to the API unchanged.
+CHANNELS = [
+    {"channel": "ARD", "name": "Das Erste"},
+    {"channel": "ZDF", "name": "Zweites Deutsches Fernsehen"},
+    {"channel": "3sat", "name": "3sat"},
+    {"channel": "ARTE.DE", "name": "ARTE (deutsch)"},
+    {"channel": "ARTE.FR", "name": "ARTE (französisch)"},
+    {"channel": "PHOENIX", "name": "Phoenix"},
+    {"channel": "tagesschau24", "name": "tagesschau24"},
+    {"channel": "KiKA", "name": "Kinderkanal"},
+    {"channel": "ONE", "name": "ONE"},
+    {"channel": "WDR", "name": "Westdeutscher Rundfunk"},
+    {"channel": "NDR", "name": "Norddeutscher Rundfunk"},
+    {"channel": "BR", "name": "Bayerischer Rundfunk"},
+    {"channel": "SWR", "name": "Südwestrundfunk"},
+    {"channel": "MDR", "name": "Mitteldeutscher Rundfunk"},
+    {"channel": "HR", "name": "Hessischer Rundfunk"},
+    {"channel": "RBB", "name": "Rundfunk Berlin-Brandenburg"},
+    {"channel": "SR", "name": "Saarländischer Rundfunk"},
+]
+
+_KNOWN = {c["channel"].lower(): c["channel"] for c in CHANNELS}
+
+# Broad single-letter query used for "latest broadcasts": the API returns
+# nothing for an empty query and no wildcard exists, so we search the
+# most common letter across title/topic/description, newest first. The
+# result is effectively the newest programmes in the film list.
+LATEST_QUERY = "e"
+LATEST_FIELDS = ["title", "topic", "description"]
+
+
+def validate_limit(limit: int) -> int:
+    """Clamp/validate the page size (API-side max is 50)."""
+    if not 1 <= limit <= 50:
+        raise ValueError(f"limit out of range: {limit} (expected 1..50)")
+    return limit
+
+
+def normalise_channel(channel: str) -> str:
+    """Canonical capitalisation for known channels; unknown names pass through."""
+    key = (channel or "").strip()
+    if not key:
+        raise ValueError("channel must not be empty")
+    return _KNOWN.get(key.lower(), key)
+
+
+def _iso(ts) -> str | None:
+    if not ts:
+        return None
+    try:
+        return datetime.fromtimestamp(int(ts), tz=timezone.utc).isoformat()
+    except (TypeError, ValueError):
+        return None
+
+
+def _duration_hms(seconds) -> str | None:
+    if seconds is None:
+        return None
+    try:
+        s = int(seconds)
+    except (TypeError, ValueError):
+        return None
+    h, rem = divmod(s, 3600)
+    m, sec = divmod(rem, 60)
+    return f"{h}:{m:02d}:{sec:02d}" if h else f"{m}:{sec:02d}"
+
+
+def compact_programme(p: dict) -> dict:
+    """One programme, compact: no internal ids beyond the API's own id."""
+    return {
+        "id": p.get("id") or "",
+        "channel": p.get("channel") or "",
+        "topic": p.get("topic") or "",
+        "title": p.get("title") or "",
+        "description": p.get("description") or "",
+        "broadcast": _iso(p.get("timestamp")),
+        "duration_seconds": p.get("duration"),
+        "duration": _duration_hms(p.get("duration")),
+        "video_url": p.get("url_video") or "",
+        "video_url_hd": p.get("url_video_hd") or "",
+        "video_url_low": p.get("url_video_low") or "",
+        "subtitle_url": p.get("url_subtitle") or "",
+        "website_url": p.get("url_website") or "",
+        "size_bytes": p.get("size"),
+    }
+
+
+def compact_results(result: dict) -> dict:
+    """The API's result object, compacted for tool output."""
+    info = result.get("queryInfo") or {}
+    return {
+        "total_results": info.get("totalResults"),
+        "film_list_updated": _iso(info.get("filmlisteTimestamp")),
+        "count": len(result.get("results") or []),
+        "programmes": [compact_programme(p) for p in result.get("results") or []],
+    }
+
+
+def find_exact_title(results: list, title: str, channel: str | None) -> dict | None:
+    """First result whose title matches exactly (case-insensitive), optionally
+    restricted to one channel. Returns the raw API entry or None."""
+    want = (title or "").strip().lower()
+    chan = (channel or "").strip().lower()
+    for p in results or []:
+        if (p.get("title") or "").strip().lower() != want:
+            continue
+        if chan and (p.get("channel") or "").strip().lower() != chan:
+            continue
+        return p
+    return None

mediathek_mcp-0.1.0/src/mediathek_mcp/http.py

@@ -0,0 +1,114 @@
+"""HTTP layer for mediathek_mcp — plain httpx POSTs against the free
+MediathekViewWeb API (mediathekviewweb.de/api/query).
+
+No key, no login. The API is a community service over the public film
+list of the German public broadcasters (ARD, ZDF, 3sat, ARTE, Phoenix
+and the regional channels). One POST per query; the body selects the
+fields to search, sort order and page size.
+"""
+from __future__ import annotations
+
+import os
+import ssl
+
+import httpx
+
+BASE = "https://mediathekviewweb.de/api/query"
+UA = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/120.0 Safari/537.36"
+)
+TIMEOUT = 25.0
+MAX_SIZE = 50
+
+
+class MediathekError(RuntimeError):
+    pass
+
+
+def _verify():
+    """TLS trust store: the OS bundle when present, else httpx/certifi.
+
+    The OS bundle matters behind MITM egress proxies (their CA is in the
+    system store, not in certifi) and is the right default on Linux
+    anyway; on systems without it we fall back to certifi.
+    """
+    for path in (
+        "/etc/ssl/certs/ca-certificates.crt",
+        ssl.get_default_verify_paths().openssl_cafile,
+    ):
+        if path and os.path.exists(path):
+            return ssl.create_default_context(cafile=path)
+    return True
+
+
+def _client() -> httpx.Client:
+    # NOTE: we read the proxy URL from the environment but never log it.
+    # trust_env=False because httpx fails to parse bracketed IPv6 entries
+    # (e.g. [::1]) that some environments put in no_proxy.
+    proxy = os.environ.get("https_proxy") or os.environ.get("HTTPS_PROXY")
+    return httpx.Client(
+        headers={"User-Agent": UA, "Content-Type": "application/json"},
+        timeout=TIMEOUT,
+        proxy=proxy or None,
+        trust_env=False,
+        verify=_verify(),
+    )
+
+
+def query(
+    queries: list[dict],
+    sort_by: str = "timestamp",
+    sort_order: str = "desc",
+    size: int = 10,
+    offset: int = 0,
+) -> dict:
+    """Run one MediathekViewWeb query and return the ``result`` object.
+
+    ``queries`` is a list of {"fields": [...], "query": "..."} objects
+    (OR-combined by the API). ``sort_by`` is "timestamp" (newest first
+    with desc) or "title". Raises MediathekError on any failure.
+    """
+    if not 1 <= size <= MAX_SIZE:
+        raise MediathekError(f"size out of range: {size} (expected 1..{MAX_SIZE})")
+    body = {
+        "queries": queries,
+        "sortBy": sort_by,
+        "sortOrder": sort_order,
+        "future": False,
+        "offset": max(0, offset),
+        "size": size,
+    }
+    try:
+        with _client() as c:
+            r = c.post(BASE, json=body)
+    except httpx.HTTPError as e:
+        raise MediathekError(f"network error querying MediathekViewWeb: {e}") from e
+    if r.status_code != 200:
+        raise MediathekError(
+            f"MediathekViewWeb returned HTTP {r.status_code} for {BASE}"
+        )
+    try:
+        data = r.json()
+    except ValueError as e:
+        raise MediathekError("MediathekViewWeb returned invalid JSON") from e
+    if data.get("err"):
+        raise MediathekError(f"MediathekViewWeb error: {data['err']}")
+    result = data.get("result")
+    if not isinstance(result, dict) or not isinstance(result.get("results"), list):
+        raise MediathekError("unexpected MediathekViewWeb response shape")
+    return result
+
+
+def search(
+    fields: list[str],
+    text: str,
+    size: int = 10,
+    sort_by: str = "timestamp",
+) -> dict:
+    """Single-field-set text search; returns the ``result`` object."""
+    return query(
+        [{"fields": fields, "query": text}],
+        sort_by=sort_by,
+        size=size,
+    )

mediathek_mcp-0.1.0/src/mediathek_mcp/server.py

@@ -0,0 +1,183 @@
+"""MCP server: unofficial read-only access to the German Mediathek via
+MediathekViewWeb (mediathekviewweb.de) — no key, no login."""
+from __future__ import annotations
+
+import json
+import sys
+
+from mcp.server.fastmcp import FastMCP
+
+from . import domain as _dom
+from . import http as _http
+
+INSTRUCTIONS = """\
+Unofficial read-only MCP server for the German Mediathek via the free \
+MediathekViewWeb API (mediathekviewweb.de) — no key, no login. It \
+searches the programmes of the German public broadcasters (ARD, ZDF, \
+3sat, ARTE, Phoenix, tagesschau24, KiKA and the regional channels) in \
+the MediathekView film list (~700,000 entries, updated several times a \
+day). Searches match title, topic and description; results are newest \
+first. "Latest broadcasts" searches the most common letter across \
+title/topic/description because the API returns nothing for an empty \
+query and has no wildcard — the result is effectively the newest \
+programmes. Video URLs are direct MP4 links (low / standard / HD); \
+subtitle_url is empty when no subtitles exist. Built by Mohammad Abbasi \
+(mohammad-abbasi-sh) — Germany MCP factory.\
+"""
+
+mcp = FastMCP("mediathek-mcp", instructions=INSTRUCTIONS)
+
+
+def _err(e: Exception) -> str:
+    return json.dumps({"error": str(e)}, ensure_ascii=False)
+
+
+@mcp.tool()
+def mediathek_search_programmes(
+    query: str, channel: str | None = None, limit: int = 10
+) -> str:
+    """Search Mediathek programmes by title, topic or description. \
+query: free text, e.g. "Tagesschau" or "Tatort". channel: optional, \
+e.g. "ZDF" (see mediathek_list_channels). limit: 1..50 (default 10)."""
+    try:
+        if not (query or "").strip():
+            return json.dumps(
+                {"error": "query must not be empty"},
+                ensure_ascii=False,
+            )
+        lim = _dom.validate_limit(limit)
+        if channel:
+            # The API OR-combines query objects (no AND), so fetch the
+            # newest text matches and filter to the channel client-side.
+            chan = _dom.normalise_channel(channel)
+            result = _http.search(
+                ["title", "topic", "description"], query.strip(), size=50
+            )
+            filtered = [
+                p for p in result.get("results") or []
+                if (p.get("channel") or "").lower() == chan.lower()
+            ]
+            result = {**result, "results": filtered[:lim]}
+            out = _dom.compact_results(result)
+            out["total_results"] = len(filtered)
+            out["note"] = (
+                "channel filter applied client-side over the newest 50 "
+                "text matches (the API has no AND query)"
+            )
+            return json.dumps(
+                {"query": query.strip(), "channel": chan, **out},
+                ensure_ascii=False,
+            )
+        result = _http.search(
+            ["title", "topic", "description"], query.strip(), size=lim
+        )
+    except (_http.MediathekError, ValueError) as e:
+        return _err(e)
+    return json.dumps(
+        {"query": query.strip(), "channel": channel, **_dom.compact_results(result)},
+        ensure_ascii=False,
+    )
+
+
+@mcp.tool()
+def mediathek_latest_broadcasts(limit: int = 10) -> str:
+    """Newest programmes across all channels, newest first. \
+limit: 1..50 (default 10)."""
+    try:
+        lim = _dom.validate_limit(limit)
+        result = _http.search(_dom.LATEST_FIELDS, _dom.LATEST_QUERY, size=lim)
+    except (_http.MediathekError, ValueError) as e:
+        return _err(e)
+    return json.dumps(_dom.compact_results(result), ensure_ascii=False)
+
+
+@mcp.tool()
+def mediathek_by_channel(channel: str, limit: int = 10) -> str:
+    """Newest programmes of one channel, newest first. channel: e.g. \
+"ZDF", "ARD", "3sat", "ARTE.DE", "PHOENIX" (see mediathek_list_channels). \
+limit: 1..50 (default 10)."""
+    try:
+        lim = _dom.validate_limit(limit)
+        chan = _dom.normalise_channel(channel)
+        result = _http.search(["channel"], chan, size=lim)
+    except (_http.MediathekError, ValueError) as e:
+        return _err(e)
+    return json.dumps(
+        {"channel": chan, **_dom.compact_results(result)}, ensure_ascii=False
+    )
+
+
+@mcp.tool()
+def mediathek_by_topic(topic: str, limit: int = 10) -> str:
+    """All episodes of one show/series (topic), newest first. topic: \
+e.g. "heute journal" or "Tagesschau". limit: 1..50 (default 10)."""
+    try:
+        if not (topic or "").strip():
+            return json.dumps(
+                {"error": "topic must not be empty"},
+                ensure_ascii=False,
+            )
+        lim = _dom.validate_limit(limit)
+        result = _http.search(["topic"], topic.strip(), size=lim)
+    except (_http.MediathekError, ValueError) as e:
+        return _err(e)
+    return json.dumps(
+        {"topic": topic.strip(), **_dom.compact_results(result)},
+        ensure_ascii=False,
+    )
+
+
+@mcp.tool()
+def mediathek_programme_detail(title: str, channel: str | None = None) -> str:
+    """Full detail of one programme: all video URLs (low/standard/HD), \
+subtitle URL and website link. title: exact programme title, e.g. \
+"heute journal vom 8. November 2026 (S2026/E333)". channel: optional, \
+e.g. "ZDF", to disambiguate same-named titles."""
+    try:
+        if not (title or "").strip():
+            return json.dumps(
+                {"error": "title must not be empty"},
+                ensure_ascii=False,
+            )
+        result = _http.search(["title"], title.strip(), size=50)
+        found = _dom.find_exact_title(
+            result.get("results") or [],
+            title.strip(),
+            _dom.normalise_channel(channel) if channel else None,
+        )
+    except (_http.MediathekError, ValueError) as e:
+        return _err(e)
+    if not found:
+        return json.dumps(
+            {
+                "error": f"no programme with exact title {title.strip()!r}"
+                + (f" on channel {channel!r}" if channel else ""),
+                "hint": "use mediathek_search_programmes first to get an exact title",
+            },
+            ensure_ascii=False,
+        )
+    return json.dumps(_dom.compact_programme(found), ensure_ascii=False)
+
+
+@mcp.tool()
+def mediathek_list_channels() -> str:
+    """Channels in the MediathekView film list (curated list — the API \
+has no channel-list endpoint)."""
+    return json.dumps(
+        {
+            "count": len(_dom.CHANNELS),
+            "channels": _dom.CHANNELS,
+            "note": "curated list of the channels in the film list; "
+            "mediathek_by_channel also accepts any other channel name "
+            "and passes it to the API unchanged.",
+        },
+        ensure_ascii=False,
+    )
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mediathek_mcp-0.1.0/tests/fixtures/by-channel-zdf.json

@@ -0,0 +1 @@
+{"result":{"results":[{"channel":"ZDF","topic":"Wirtschaft","title":"KI: Kollege oder Konkurrent für Junge?","description":"Berufseinsteiger haben es durch KI besonders schwer -  aber nicht in allen Jobs. So das Ergebnis einer ifo-Analyse, die  Berufe, Altersgruppen und Abhängigkeiten von KI vergleicht.","timestamp":1794214380,"duration":116,"size":39845888,"url_website":"https://www.zdfheute.de/wirtschaft/ki-arbeitsmarkt-ifo-analyse-berufseinsteiger-100.html","url_subtitle":"","url_video":"https://nrodlzdf-a.akamaihd.net/none/zdf/26/10/261019_1400_clip_3_hid/1/261019_1400_clip_3_hid_3360k_p36v17.mp4","url_video_low":"https://rodlzdf-a.akamaihd.net/none/zdf/26/10/261019_1400_clip_3_hid/1/261019_1400_clip_3_hid_808k_p11v17.mp4","url_video_hd":"https://nrodlzdf-a.akamaihd.net/none/zdf/26/10/261019_1400_clip_3_hid/1/261019_1400_clip_3_hid_6660k_p37v17.mp4","filmlisteTimestamp":1794216000,"id":"3F7w+vkNC+SXA3w1mvEj405dbUcbzEo5KbbNEgQJygU="},{"channel":"ZDF","topic":"Politik","title":"Dröge zu Merz’ COP-Absage: \"Ein wirklich schlechtes Signal\"","description":"Grünen-Fraktionschefin Katharina Dröge kritisiert Bundeskanzler Merz für sein Fernbleiben bei der Weltklimakonferenz. Sie fordert mehr Einsatz beim Ausstieg aus fossiler Energie.","timestamp":1794211260,"duration":308,"size":112197632,"url_website":"https://www.zdfheute.de/politik/deutschland/cop-31-klima-konferenz-merz-fossile-energie-droege-100.html","url_subtitle":"","url_video":"https://nrodlzdf-a.akamaihd.net/none/zdf/26/11/261109_clip_17_mom/1/261109_clip_17_mom_3360k_p36v17.mp4","url_video_low":"https://rodlzdf-a.akamaihd.net/none/zdf/26/11/261109_clip_17_mom/1/261109_clip_17_mom_808k_p11v17.mp4","url_video_hd":"https://nrodlzdf-a.akamaihd.net/none/zdf/26/11/261109_clip_17_mom/1/261109_clip_17_mom_6660k_p37v17.mp4","filmlisteTimestamp":1794216000,"id":"6Oq3sTj/QOpcoS0KBkpgolEUgvyJYqTmTk2zeyEgHG0="}],"queryInfo":{"filmlisteTimestamp":1794216000,"searchEngineTime":"4.38","resultCount":2,"totalResults":10000,"totalRelation":"gte","totalEntries":711540}},"err":null}

mediathek_mcp-0.1.0/tests/fixtures/by-topic-heute-journal.json

@@ -0,0 +1 @@
+{"result":{"results":[{"channel":"ZDF","topic":"heute journal","title":"heute journal vom 8. November 2026 (S2026/E333)","description":"Mit den Themen: Nach Schüssen in Krakau - Ermittlungen wegen Terrorismus laufen; Aigner als Steinmeier-Nachfolgerin - CDU-Präsidium berät über Kandidatin; Vor der Cop 31 in Antalya - Alte Hürden für Weltklimakonferenz.","timestamp":1794170700,"duration":1786,"size":631242752,"url_website":"https://www.zdf.de/video/magazine/heute-journal-104/heute-journal-vom-8-november-2026-100","url_subtitle":"https://utstreaming.zdf.de/mtt/zdf/26/11/261108_2145_sendung_hjo/4/heute_journal_081126.xml","url_video":"https://nrodlzdf-a.akamaihd.net/none/zdf/26/11/261108_2145_sendung_hjo/1/261108_2145_sendung_hjo_3360k_p36v17.mp4","url_video_low":"https://rodlzdf-a.akamaihd.net/none/zdf/26/11/261108_2145_sendung_hjo/1/261108_2145_sendung_hjo_808k_p11v17.mp4","url_video_hd":"https://nrodlzdf-a.akamaihd.net/none/zdf/26/11/261108_2145_sendung_hjo/1/261108_2145_sendung_hjo_6660k_p37v17.mp4","filmlisteTimestamp":1794197940,"id":"zsBPTMwoMrTFnHXen7MQ68WdJQ9mzRMlTSTkSHNGYUE="},{"channel":"ZDF","topic":"heute journal","title":"Krakau nach dem Anschlag","description":"Nach der tödlichen Attacke im polnischen Krakau ermittelt die Staatsanwaltschaft wegen Terrorismus. Sechs Menschen und weitere Familienmitglieder des Schützen wurden erschossen.","timestamp":1794170700,"duration":127,"size":44040192,"url_website":"https://www.zdfheute.de/video/heute-journal/krakau-anschlag-ermittlungen-100.html","url_subtitle":"","url_video":"https://nrodlzdf-a.akamaihd.net/none/zdf/26/11/261108_2145_clip_3_hjo/1/261108_2145_clip_3_hjo_3360k_p36v17.mp4","url_video_low":"https://rodlzdf-a.akamaihd.net/none/zdf/26/11/261108_2145_clip_3_hjo/1/261108_2145_clip_3_hjo_808k_p11v17.mp4","url_video_hd":"https://nrodlzdf-a.akamaihd.net/none/zdf/26/11/261108_2145_clip_3_hjo/1/261108_2145_clip_3_hjo_6660k_p37v17.mp4","filmlisteTimestamp":1794176340,"id":"qVTXWFi/4GBxbH83HN60NAaUCccYHyzP41wlUwm0BeI="}],"queryInfo":{"filmlisteTimestamp":1794216000,"searchEngineTime":"3.86","resultCount":2,"totalResults":5399,"totalRelation":"eq","totalEntries":711540}},"err":null}

mediathek_mcp-0.1.0/tests/fixtures/latest.json

@@ -0,0 +1 @@
+{"result":{"results":[{"channel":"ARTE.DE","topic":"Entdeckung der Welt - Kulinarik","title":"Küchen der Welt - Nordfrankreich: Hering","description":"Typisches Fischgericht aus Dunkerque: Hering mit Kartoffeln / Kulinarische Mitbringsel / Ran an die Töpfe!","timestamp":1794221880,"duration":1806,"size":null,"url_website":"https://www.arte.tv/de/videos/126457-125-A/kuechen-der-welt/","url_subtitle":"","url_video":"https://manifest-arte.akamaized.net/api/manifest/v1/Generate/a1ebc08f-298c-4a3c-aa97-372d34e212a0/de/XQ+KS+CHEV1/126457-125-A.m3u8","url_video_low":"","url_video_hd":"","filmlisteTimestamp":1794197940,"id":"y0Mv6ZJx/cIH1vteFS+aBGEIHJY7m8ah9WFNDae/es4="},{"channel":"BR","topic":"aktiv und gesund","title":"Lipödem, Teebaumöl, Ernährungstrends im Wandel","description":"Lipödem Das Lipödem ist eine Krankheit, von der die meisten Betroffenen nichts wissen. Rund 3,8 Millionen Menschen sind in Deutschland betroffen, hauptsächlich Frauen. Durch eine Fettverteilungsstörung kommt es zu einer Fettvermehrung vor allem an Beinen, Hüfte, Gesäß und in einigen Fällen auch an den Armen. Die Folgen sind heftige Schmerzen und Spannungsgefühle....","timestamp":1794221400,"duration":1689,"size":636485632,"url_website":"https://www.ardmediathek.de/video/Y3JpZDovL2JyLmRlL2Jyb2FkY2FzdC9GMjAyNFdPMDE1MTE5QTA","url_subtitle":"https://api.ardmediathek.de/player-service/subtitle/ebutt/urn:ard:subtitle:f3e8a8b5d02a1294","url_video":"https://cdn-storage.br.de/b7/2025-04/30/3bdb8ba6-25c7-11f0-a101-02420a000526_X.mp4","url_video_low":"https://cdn-storage.br.de/b7/2025-04/30/3bdb8ba6-25c7-11f0-a101-02420a000526_E.mp4","url_video_hd":"https://cdn-storage.br.de/b7/2025-04/30/3bdb8ba6-25c7-11f0-a101-02420a000526_HD.mp4","filmlisteTimestamp":1790717100,"id":"CcQMhDp4LUoicNkAMpne4HrMHnexihB3WI6jaIDvUuU="}],"queryInfo":{"filmlisteTimestamp":1794216000,"searchEngineTime":"4.06","resultCount":2,"totalResults":10000,"totalRelation":"gte","totalEntries":711540}},"err":null}

mediathek_mcp-0.1.0/tests/fixtures/search-tagesschau.json

@@ -0,0 +1 @@
+{"result":{"results":[{"channel":"tagesschau24","topic":"tagesschau in 100 Sekunden","title":"tagesschau in 100 Sekunden","description":"tagesschau in 100 Sekunden","timestamp":1794195780,"duration":170,"size":40894464,"url_website":"https://www.ardmediathek.de/video/Y3JpZDovL3RhZ2Vzc2NoYXUuZGUvN2FjNWY5ZmItYTQxNi00OTcwLWJiNmMtYTJmMjJhZDA4M2Nl","url_subtitle":"","url_video":"https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0445-5500.webxl.h264.mp4","url_video_low":"https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0445-5500.webm.h264.mp4","url_video_hd":"https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0445-5500.webxxl.h264.mp4","filmlisteTimestamp":1794212340,"id":"+sU90jI0m7KCrRqsj5aYEh9Owg7tr+3K9IRl39v+A8o="},{"channel":"tagesschau24","topic":"tagesschau in 100 Sekunden","title":"tagesschau in 100 Sekunden","description":"tagesschau in 100 Sekunden","timestamp":1794189480,"duration":160,"size":41943040,"url_website":"https://www.ardmediathek.de/video/Y3JpZDovL3RhZ2Vzc2NoYXUuZGUvZTUzZDE4YjUtZmYxMC00ZWFkLTljYmMtYTQzOWY4NzQwOWU3","url_subtitle":"","url_video":"https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0257-3000.webxl.h264.mp4","url_video_low":"https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0257-3000.webm.h264.mp4","url_video_hd":"https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0257-3000.webxxl.h264.mp4","filmlisteTimestamp":1794212340,"id":"KeXQDG431jwNB7OwGCb2GnFKFfQpNH31Mstz1Xp2ccc="},{"channel":"tagesschau24","topic":"tagesschau in 100 Sekunden","title":"tagesschau in 100 Sekunden","description":"tagesschau in 100 Sekunden","timestamp":1794183780,"duration":150,"size":34603008,"url_website":"https://www.ardmediathek.de/video/Y3JpZDovL3RhZ2Vzc2NoYXUuZGUvODE3MzAyY2QtY2Y4Ni00NmNkLTllZWItYzNiZWI4MmI4YTEy","url_subtitle":"","url_video":"https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0127-3500.webxl.h264.mp4","url_video_low":"https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0127-3500.webm.h264.mp4","url_video_hd":"https://tagesschau-progressive.ard-mcdn.de/video/2026/1109/TV-20261109-0127-3500.webxxl.h264.mp4","filmlisteTimestamp":1794212340,"id":"8pFbcaTz6MbBjO/mlb4py3cZW+48RF5h0aYdkIA1YMs="}],"queryInfo":{"filmlisteTimestamp":1794216000,"searchEngineTime":"3.69","resultCount":3,"totalResults":8823,"totalRelation":"eq","totalEntries":711540}},"err":null}

mediathek_mcp-0.1.0/tests/test_domain.py

@@ -0,0 +1,200 @@
+"""Offline tests — parse real captured MediathekViewWeb responses, no network."""
+import json
+import pathlib
+import sys
+import unittest
+from unittest import mock
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "src"))
+
+from mediathek_mcp import domain as dom
+from mediathek_mcp import server as srv
+
+FIX = pathlib.Path(__file__).resolve().parent / "fixtures"
+
+
+def _load(name):
+    return json.loads((FIX / name).read_text(encoding="utf-8"))
+
+
+def _result(name):
+    return _load(name)["result"]
+
+
+class TestCompact(unittest.TestCase):
+    def test_search_fixture_shape(self):
+        out = dom.compact_results(_result("search-tagesschau.json"))
+        self.assertEqual(out["total_results"], 8823)
+        self.assertEqual(out["count"], 3)
+        self.assertEqual(len(out["programmes"]), 3)
+
+    def test_compact_programme_fields(self):
+        p = dom.compact_programme(_result("search-tagesschau.json")["results"][0])
+        self.assertEqual(p["channel"], "tagesschau24")
+        self.assertEqual(p["topic"], "tagesschau in 100 Sekunden")
+        self.assertEqual(p["title"], "tagesschau in 100 Sekunden")
+        self.assertEqual(p["duration_seconds"], 170)
+        self.assertEqual(p["duration"], "2:50")
+        self.assertTrue(p["broadcast"].startswith("2026-11-09T"))
+        self.assertTrue(p["video_url"].endswith(".mp4"))
+        self.assertTrue(p["video_url_hd"].endswith(".mp4"))
+        self.assertTrue(p["website_url"].startswith("https://www.ardmediathek.de/"))
+        self.assertEqual(p["size_bytes"], 40894464)
+
+    def test_topic_fixture_duration(self):
+        p = dom.compact_programme(_result("by-topic-heute-journal.json")["results"][0])
+        self.assertEqual(p["channel"], "ZDF")
+        self.assertEqual(p["topic"], "heute journal")
+        self.assertEqual(p["duration_seconds"], 1786)
+        self.assertEqual(p["duration"], "29:46")
+
+    def test_channel_fixture_all_zdf(self):
+        out = dom.compact_results(_result("by-channel-zdf.json"))
+        self.assertTrue(all(p["channel"] == "ZDF" for p in out["programmes"]))
+        self.assertEqual(out["total_results"], 10000)
+
+    def test_latest_fixture(self):
+        out = dom.compact_results(_result("latest.json"))
+        self.assertEqual(out["count"], 2)
+        self.assertTrue(all(p["broadcast"] for p in out["programmes"]))
+
+
+class TestHelpers(unittest.TestCase):
+    def test_duration_hms(self):
+        self.assertEqual(dom._duration_hms(170), "2:50")
+        self.assertEqual(dom._duration_hms(3661), "1:01:01")
+        self.assertEqual(dom._duration_hms(45), "0:45")
+        self.assertIsNone(dom._duration_hms(None))
+
+    def test_validate_limit(self):
+        self.assertEqual(dom.validate_limit(10), 10)
+        with self.assertRaises(ValueError):
+            dom.validate_limit(0)
+        with self.assertRaises(ValueError):
+            dom.validate_limit(51)
+
+    def test_normalise_channel(self):
+        self.assertEqual(dom.normalise_channel("zdf"), "ZDF")
+        self.assertEqual(dom.normalise_channel(" ARTE.de "), "ARTE.DE")
+        self.assertEqual(dom.normalise_channel("phoenix"), "PHOENIX")
+        # Unknown names pass through unchanged.
+        self.assertEqual(dom.normalise_channel("SomeChannel"), "SomeChannel")
+        with self.assertRaises(ValueError):
+            dom.normalise_channel("  ")
+
+    def test_find_exact_title(self):
+        results = _result("by-topic-heute-journal.json")["results"]
+        title = "heute journal vom 8. November 2026 (S2026/E333)"
+        found = dom.find_exact_title(results, title, None)
+        self.assertIsNotNone(found)
+        self.assertEqual(found["channel"], "ZDF")
+        # Case-insensitive match.
+        self.assertIsNotNone(dom.find_exact_title(results, title.upper(), None))
+        # Channel restriction.
+        self.assertIsNotNone(dom.find_exact_title(results, title, "zdf"))
+        self.assertIsNone(dom.find_exact_title(results, title, "ARD"))
+        # No match.
+        self.assertIsNone(dom.find_exact_title(results, "does not exist", None))
+
+
+class TestServerToolsOffline(unittest.TestCase):
+    """Server tools with the HTTP layer mocked to return fixture data."""
+
+    def test_search_programmes(self):
+        with mock.patch(
+            "mediathek_mcp.http.search",
+            return_value=_result("search-tagesschau.json"),
+        ):
+            out = json.loads(srv.mediathek_search_programmes("Tagesschau"))
+        self.assertNotIn("error", out)
+        self.assertEqual(out["query"], "Tagesschau")
+        self.assertEqual(out["count"], 3)
+        self.assertEqual(out["programmes"][0]["channel"], "tagesschau24")
+
+    def test_search_programmes_empty_query(self):
+        out = json.loads(srv.mediathek_search_programmes("  "))
+        self.assertIn("error", out)
+
+    def test_search_programmes_bad_limit(self):
+        out = json.loads(srv.mediathek_search_programmes("Tagesschau", limit=99))
+        self.assertIn("error", out)
+
+    def test_search_programmes_with_channel_filters(self):
+        # Fixture has 3 tagesschau24 results; filtering to ZDF yields none.
+        with mock.patch(
+            "mediathek_mcp.http.search",
+            return_value=_result("search-tagesschau.json"),
+        ):
+            out = json.loads(
+                srv.mediathek_search_programmes("Tagesschau", channel="ZDF")
+            )
+        self.assertNotIn("error", out)
+        self.assertEqual(out["channel"], "ZDF")
+        self.assertEqual(out["count"], 0)
+        self.assertEqual(out["total_results"], 0)
+
+    def test_latest_broadcasts(self):
+        with mock.patch(
+            "mediathek_mcp.http.search",
+            return_value=_result("latest.json"),
+        ):
+            out = json.loads(srv.mediathek_latest_broadcasts(limit=2))
+        self.assertNotIn("error", out)
+        self.assertEqual(out["count"], 2)
+
+    def test_by_channel(self):
+        with mock.patch(
+            "mediathek_mcp.http.search",
+            return_value=_result("by-channel-zdf.json"),
+        ) as m:
+            out = json.loads(srv.mediathek_by_channel("zdf", limit=2))
+        self.assertNotIn("error", out)
+        self.assertEqual(out["channel"], "ZDF")
+        # Normalised channel is what reaches the API.
+        self.assertEqual(m.call_args.args[1], "ZDF")
+
+    def test_by_topic(self):
+        with mock.patch(
+            "mediathek_mcp.http.search",
+            return_value=_result("by-topic-heute-journal.json"),
+        ):
+            out = json.loads(srv.mediathek_by_topic("heute journal"))
+        self.assertNotIn("error", out)
+        self.assertEqual(out["topic"], "heute journal")
+        self.assertEqual(out["count"], 2)
+
+    def test_programme_detail_found(self):
+        with mock.patch(
+            "mediathek_mcp.http.search",
+            return_value=_result("by-topic-heute-journal.json"),
+        ):
+            out = json.loads(
+                srv.mediathek_programme_detail(
+                    "heute journal vom 8. November 2026 (S2026/E333)"
+                )
+            )
+        self.assertNotIn("error", out)
+        self.assertEqual(out["channel"], "ZDF")
+        self.assertTrue(out["video_url"].endswith(".mp4"))
+
+    def test_programme_detail_missing(self):
+        with mock.patch(
+            "mediathek_mcp.http.search",
+            return_value=_result("by-topic-heute-journal.json"),
+        ):
+            out = json.loads(
+                srv.mediathek_programme_detail("no such programme title")
+            )
+        self.assertIn("error", out)
+        self.assertIn("hint", out)
+
+    def test_list_channels(self):
+        out = json.loads(srv.mediathek_list_channels())
+        self.assertGreaterEqual(out["count"], 10)
+        channels = [c["channel"] for c in out["channels"]]
+        for want in ("ARD", "ZDF", "3sat", "ARTE.DE", "PHOENIX", "tagesschau24"):
+            self.assertIn(want, channels)
+
+
+if __name__ == "__main__":
+    unittest.main()

mediathek_mcp-0.1.0/tests/test_live.py

@@ -0,0 +1,70 @@
+"""Live tests — hit the real mediathekviewweb.de API. Cautious: few requests.
+
+Run:  pytest tests/test_live.py -v
+Skip: pytest -m "not live"  (or set MEDIATHEK_SKIP_LIVE=1)
+"""
+import json
+import os
+import pathlib
+import sys
+import unittest
+
+import pytest
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "src"))
+
+from mediathek_mcp import server as srv
+
+pytestmark = pytest.mark.live
+SKIP = os.environ.get("MEDIATHEK_SKIP_LIVE") == "1"
+
+
+@pytest.mark.skipif(SKIP, reason="MEDIATHEK_SKIP_LIVE=1")
+class TestLive(unittest.TestCase):
+    def test_search_live(self):
+        out = json.loads(srv.mediathek_search_programmes("Tagesschau", limit=3))
+        self.assertNotIn("error", out)
+        self.assertGreaterEqual(out["count"], 1)
+        self.assertTrue(all(p["title"] and p["channel"] for p in out["programmes"]))
+        self.assertTrue(all(p["video_url"] for p in out["programmes"]))
+        print(f"\nLIVE search 'Tagesschau': {out['count']} results, "
+              f"total {out['total_results']}")
+
+    def test_latest_live(self):
+        out = json.loads(srv.mediathek_latest_broadcasts(limit=3))
+        self.assertNotIn("error", out)
+        self.assertGreaterEqual(out["count"], 1)
+        self.assertTrue(all(p["broadcast"] for p in out["programmes"]))
+        print(f"\nLIVE latest: {out['programmes'][0]['channel']} — "
+              f"{out['programmes'][0]['title']}")
+
+    def test_by_channel_live(self):
+        out = json.loads(srv.mediathek_by_channel("ZDF", limit=3))
+        self.assertNotIn("error", out)
+        self.assertGreaterEqual(out["count"], 1)
+        self.assertTrue(all(p["channel"] == "ZDF" for p in out["programmes"]))
+        print(f"\nLIVE ZDF newest: {out['programmes'][0]['title']}")
+
+    def test_by_topic_live(self):
+        out = json.loads(srv.mediathek_by_topic("heute journal", limit=3))
+        self.assertNotIn("error", out)
+        self.assertGreaterEqual(out["count"], 1)
+        self.assertTrue(
+            all(p["topic"] == "heute journal" for p in out["programmes"])
+        )
+
+    def test_programme_detail_live(self):
+        found = json.loads(srv.mediathek_search_programmes("Tagesschau", limit=1))
+        title = found["programmes"][0]["title"]
+        out = json.loads(srv.mediathek_programme_detail(title))
+        self.assertNotIn("error", out)
+        self.assertEqual(out["title"], title)
+        self.assertTrue(out["video_url"])
+        self.assertTrue(out["video_url_hd"])
+        print(f"\nLIVE detail: {title} — {out['duration']} "
+              f"({out['channel']})")
+
+    def test_list_channels_live(self):
+        out = json.loads(srv.mediathek_list_channels())
+        self.assertNotIn("error", out)
+        self.assertGreaterEqual(out["count"], 10)