govdata-mcp 0.1.0__py3-none-any.whl

govdata_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""govdata_mcp — unofficial read-only MCP server for govdata.de.
+
+Germany's national open-data portal govdata.de via its official CKAN API: search 163,000+ datasets, dataset details, publishers, recent datasets and resource details. No key, no login.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"

govdata_mcp/domain.py

@@ -0,0 +1,117 @@
+"""Domain logic: shape govdata.de CKAN API responses into compact
+dicts (stdlib only).
+
+Data source: the official CKAN API of Germany's national open-data
+portal (https://www.govdata.de/ckan/api/3/action/...) — free, no key,
+no login. Actions used: package_search, package_show,
+organization_list, resource_show.
+"""
+from __future__ import annotations
+
+import json
+import urllib.parse
+
+BASE = "https://www.govdata.de/ckan/api/3/action"
+
+
+def validate_limit(limit: int) -> int:
+    if not 1 <= limit <= 50:
+        raise ValueError(f"limit out of range: {limit} (expected 1..50)")
+    return limit
+
+
+def search_url(query: str, rows: int, sort: str) -> str:
+    params = {"q": query, "rows": str(rows)}
+    if sort == "recent":
+        params["sort"] = "metadata_modified desc"
+    return BASE + "/package_search?" + urllib.parse.urlencode(params)
+
+
+def recent_url(rows: int) -> str:
+    params = {"rows": str(rows), "sort": "metadata_modified desc"}
+    return BASE + "/package_search?" + urllib.parse.urlencode(params)
+
+
+def dataset_url(dataset_id: str) -> str:
+    return BASE + "/package_show?" + urllib.parse.urlencode({"id": dataset_id})
+
+
+def publishers_url(limit: int) -> str:
+    params = {"all_fields": "true", "limit": str(limit)}
+    return BASE + "/organization_list?" + urllib.parse.urlencode(params)
+
+
+def resource_url(resource_id: str) -> str:
+    return BASE + "/resource_show?" + urllib.parse.urlencode({"id": resource_id})
+
+
+def _load(text: str, what: str) -> dict:
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"invalid {what}: {e}") from e
+    if not data.get("success"):
+        err = data.get("error") or {}
+        raise ValueError(f"govdata.de error: {err.get('message') or err}")
+    return data["result"]
+
+
+def _compact_dataset(pkg: dict) -> dict:
+    org = pkg.get("organization") or {}
+    return {
+        "id": pkg.get("id") or "",
+        "name": pkg.get("name") or "",
+        "title": pkg.get("title") or "",
+        "notes": (pkg.get("notes") or "")[:400],
+        "organization": org.get("title") or org.get("name") or "",
+        "license": pkg.get("license_title") or "",
+        "num_resources": pkg.get("num_resources") or 0,
+        "tags": [t.get("name") for t in (pkg.get("tags") or [])[:5]],
+        "metadata_modified": pkg.get("metadata_modified") or "",
+        "resources": [
+            {"id": r.get("id") or "", "name": r.get("name") or "",
+             "format": r.get("format") or "", "url": r.get("url") or ""}
+            for r in (pkg.get("resources") or [])[:10]
+        ],
+    }
+
+
+def parse_search(text: str) -> dict:
+    result = _load(text, "package_search response")
+    return {
+        "total_results": result.get("count") or 0,
+        "items": [_compact_dataset(p) for p in result.get("results") or []],
+    }
+
+
+def parse_dataset(text: str) -> dict:
+    return _compact_dataset(_load(text, "package_show response"))
+
+
+def parse_publishers(text: str) -> list[dict]:
+    result = _load(text, "organization_list response")
+    orgs = [{
+        "id": o.get("id") or "",
+        "name": o.get("name") or "",
+        "title": o.get("title") or "",
+        "package_count": o.get("package_count") or 0,
+        "description": (o.get("description") or "")[:200],
+    } for o in result]
+    orgs.sort(key=lambda o: o["package_count"], reverse=True)
+    return orgs
+
+
+def parse_resource(text: str) -> dict:
+    r = _load(text, "resource_show response")
+    return {
+        "id": r.get("id") or "",
+        "name": r.get("name") or "",
+        "format": r.get("format") or "",
+        "url": r.get("url") or r.get("download_url") or "",
+        "description": (r.get("description") or "")[:400],
+        "size": r.get("size"),
+        "mimetype": r.get("mimetype") or "",
+        "created": r.get("created") or "",
+        "last_modified": r.get("last_modified") or "",
+        "package_id": r.get("package_id") or "",
+    }

govdata_mcp/http.py

@@ -0,0 +1,99 @@
+"""HTTP layer for govdata_mcp — plain httpx GETs against govdata.de.
+
+No key, no login. One retry on 429/5xx; error taxonomy (403/429/other).
+"""
+from __future__ import annotations
+
+import os
+import ssl
+import time
+
+import httpx
+
+UA = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
+)
+TIMEOUT = 25.0
+PROBE_URL = "https://www.govdata.de/ckan/api/3/action/package_search?q=berlin&rows=1"
+SOURCE = "govdata.de"
+
+
+class GovdataMcpError(RuntimeError):
+    pass
+
+
+def _verify():
+    """TLS trust store: the OS bundle when present, else httpx/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.
+    proxy = os.environ.get("https_proxy") or os.environ.get("HTTPS_PROXY")
+    return httpx.Client(
+        headers={"User-Agent": UA, "Accept": "application/json, application/xml, text/html, */*"},
+        timeout=TIMEOUT,
+        proxy=proxy or None,
+        trust_env=False,
+        verify=_verify(),
+    )
+
+
+def fetch_text(url: str) -> str:
+    """GET one URL and return its text. One retry on 429/5xx."""
+    last_exc: Exception | None = None
+    r: httpx.Response | None = None
+    for attempt in range(2):
+        try:
+            with _client() as c:
+                r = c.get(url)
+        except httpx.HTTPError as e:
+            last_exc = e
+            if attempt == 0:
+                time.sleep(1.0)
+                continue
+            raise GovdataMcpError(f"network error fetching {url}: {e}") from e
+        if r.status_code in (429, 500, 502, 503):
+            if attempt == 0:
+                time.sleep(1.0)
+                continue
+        break
+    assert r is not None  # loop always assigns r or raises
+    if r.status_code == 403:
+        raise GovdataMcpError(
+            f"{SOURCE} returned HTTP 403 for {url} (bot wall) — try again later"
+        )
+    if r.status_code == 429:
+        raise GovdataMcpError(
+            f"{SOURCE} rate-limited the request (HTTP 429) — try again later"
+        )
+    if r.status_code != 200:
+        raise GovdataMcpError(f"{SOURCE} returned HTTP {r.status_code} for {url}")
+    return r.text
+
+
+def health_check() -> dict:
+    """One polite probe of the source site.
+
+    Returns {"status": "ok"|"blocked"|"error", "http_status": int|None,
+    "url": ..., "detail": ...}. Used by the `<prefix>_health` tool
+    and the daily smoke CI.
+    """
+    url = PROBE_URL
+    try:
+        fetch_text(url)
+    except GovdataMcpError as e:
+        msg = str(e)
+        if "403" in msg:
+            return {"status": "blocked", "http_status": 403, "url": url, "detail": msg}
+        if "429" in msg:
+            return {"status": "blocked", "http_status": 429, "url": url, "detail": msg}
+        return {"status": "error", "http_status": None, "url": url, "detail": msg}
+    return {"status": "ok", "http_status": 200, "url": url}

govdata_mcp/server.py

@@ -0,0 +1,140 @@
+"""MCP server: unofficial read-only access to Germany's national
+open-data portal govdata.de via its official CKAN API. No key, no
+login."""
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+
+from mcp.server.fastmcp import FastMCP
+
+from . import domain as _dom
+from . import http as _http
+
+INSTRUCTIONS = """\
+Unofficial read-only MCP server for Germany's national open-data \
+portal govdata.de via its official CKAN API (no key, no login): \
+search 163,000+ datasets, full dataset details, publishing \
+organisations, most recently updated datasets and resource details. \
+Built by Mohammad Abbasi (mohammad-abbasi-sh) — \
+https://almanibama.ir · https://mabbasi.ir — Germany MCP factory.\
+"""
+
+_SOURCE = "govdata.de"
+_DISCLAIMER = "Unofficial read-only data from the govdata.de CKAN API; verify on the site before acting on it."
+
+
+def _envelope() -> dict:
+    return {
+        "fetched_at": datetime.now(timezone.utc).isoformat(),
+        "source": _SOURCE,
+        "disclaimer": _DISCLAIMER,
+    }
+
+
+def _ok(payload: dict) -> str:
+    return json.dumps({**_envelope(), **payload}, ensure_ascii=False)
+
+
+def _err(e: Exception) -> str:
+    return _ok({"error": str(e)})
+
+
+mcp = FastMCP("govdata-mcp", instructions=INSTRUCTIONS)
+
+
+@mcp.tool()
+def govdata_search_datasets(query: str, limit: int = 10,
+                            sort: str = "relevance") -> str:
+    """Search govdata.de datasets. query: keyword or phrase, e.g.
+    "berlin". limit: 1..50 (default 10). sort: "relevance" or "recent"."""
+    try:
+        q = (query or "").strip()
+        if not q:
+            raise ValueError("query must not be empty")
+        lim = _dom.validate_limit(limit)
+        s = (sort or "relevance").strip().lower()
+        if s not in ("relevance", "recent"):
+            raise ValueError(f"unsupported sort: {sort!r} (relevance/recent)")
+        parsed = _dom.parse_search(
+            _http.fetch_text(_dom.search_url(q, lim, s)))
+    except (_http.GovdataMcpError, ValueError) as e:
+        return _err(e)
+    return _ok({"query": q, "sort": s,
+                "total_results": parsed["total_results"],
+                "count": len(parsed["items"]), "items": parsed["items"]})
+
+
+@mcp.tool()
+def govdata_get_dataset(dataset_id: str) -> str:
+    """Full details of one dataset. dataset_id: the dataset id (UUID)
+    or name, e.g. "wohnatlas-berlin"."""
+    try:
+        did = (dataset_id or "").strip()
+        if not did:
+            raise ValueError("dataset_id must not be empty")
+        out = _dom.parse_dataset(_http.fetch_text(_dom.dataset_url(did)))
+    except (_http.GovdataMcpError, ValueError) as e:
+        return _err(e)
+    return _ok(out)
+
+
+@mcp.tool()
+def govdata_list_publishers(limit: int = 10) -> str:
+    """Publishing organisations on govdata.de, most datasets first.
+    limit: 1..50 (default 10)."""
+    try:
+        lim = _dom.validate_limit(limit)
+        orgs = _dom.parse_publishers(
+            _http.fetch_text(_dom.publishers_url(50)))
+    except (_http.GovdataMcpError, ValueError) as e:
+        return _err(e)
+    return _ok({"total_results": len(orgs),
+                "count": min(lim, len(orgs)), "items": orgs[:lim]})
+
+
+@mcp.tool()
+def govdata_recent_datasets(limit: int = 10) -> str:
+    """Most recently updated datasets on govdata.de.
+    limit: 1..50 (default 10)."""
+    try:
+        lim = _dom.validate_limit(limit)
+        parsed = _dom.parse_search(
+            _http.fetch_text(_dom.recent_url(lim)))
+    except (_http.GovdataMcpError, ValueError) as e:
+        return _err(e)
+    return _ok({"total_results": parsed["total_results"],
+                "count": len(parsed["items"]), "items": parsed["items"]})
+
+
+@mcp.tool()
+def govdata_get_resource(resource_id: str) -> str:
+    """Details of one dataset resource (file/API download link).
+    resource_id: the resource UUID, shown on dataset resources."""
+    try:
+        rid = (resource_id or "").strip()
+        if not rid:
+            raise ValueError("resource_id must not be empty")
+        out = _dom.parse_resource(_http.fetch_text(_dom.resource_url(rid)))
+    except (_http.GovdataMcpError, ValueError) as e:
+        return _err(e)
+    return _ok(out)
+
+
+@mcp.tool()
+def govdata_health() -> str:
+    """Check whether govdata.de is reachable right now.
+
+    Returns status ok (HTTP 200), blocked (HTTP 403/429 — bot wall or
+    rate limit) or error, plus the HTTP status and the probed URL.
+    One polite request; it does not fetch any listings."""
+    return _ok(_http.health_check())
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

govdata_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: govdata-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for govdata.de (German open data, CKAN) — search datasets, publishers, resources
+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
+
+# govdata-mcp 🗃️
+
+mcp-name: io.github.mohammad-abbasi-sh/govdata-mcp
+
+Unofficial **read-only** MCP server for **[govdata.de](https://www.govdata.de)** — Germany's national open-data portal govdata.de via its official CKAN API: search 163,000+ datasets, dataset details, publishers, recent datasets and resource details. No key, no login. No key, no login.
+
+> Built by Mohammad Abbasi as part of the "Germany MCP factory". Not affiliated with govdata.de.
+
+## For AI agents
+
+Add to your MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "govdata": {
+      "command": "uvx",
+      "args": ["govdata-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+Or run locally: `python -m govdata_mcp.server` (needs `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `govdata_search_datasets` | Search govdata.de datasets — `query`, `limit` 1..50, `sort` (relevance/recent) |
+| `govdata_get_dataset` | Full details of one dataset — `dataset_id` (id or name, e.g. "wohnatlas-berlin") |
+| `govdata_list_publishers` | Publishing organisations on govdata.de, most datasets first — `limit` 1..50 |
+| `govdata_recent_datasets` | Most recently updated datasets — `limit` 1..50 |
+| `govdata_get_resource` | Details of one dataset resource (file/API link) — `resource_id` |
+| `govdata_health` | Reachability probe (ok / blocked / error) — one polite request |
+
+## Notes
+
+- All data comes from the **govdata.de CKAN API** (free, no key, no login) — 163,247 datasets at last check.
+- Competition note: pipeworx-io/mcp-govdata-de (★0, 2026-11-09) covers the same portal but only ships 2 tools (`list_organizations`, `list_groups`) behind a commercial gateway and has no dataset search; this server adds search, dataset/resource details, recency and tests.
+
+Tests: 19/19 green (13 offline + 6 live, 2026-11-10).
+
+## 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
+```
+
+## License
+
+MIT
+
+---
+
+Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)

govdata_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+govdata_mcp/__init__.py,sha256=QNPc42Q4dquZ5KHwkTLPCQkGeGPyY8ClrlS0vBv_Bus,315
+govdata_mcp/domain.py,sha256=uc9En0LWj2_rtttujOdnyvGfCUJ6TLndqnFNkdtsLqI,3939
+govdata_mcp/http.py,sha256=9ZvQcSDxAIPcLslRbvtYsq8XbOu4WCTHSgwTSLhbxU8,3164
+govdata_mcp/server.py,sha256=IR2ZtAZaG6-cBn0ynv-WN5f8nYBYMbwywsrL5m6bT44,4627
+govdata_mcp-0.1.0.dist-info/METADATA,sha256=o58gKduiUHYWnflaFI43Rb4obnrdOBTHYJZCLX2O__M,2500
+govdata_mcp-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+govdata_mcp-0.1.0.dist-info/entry_points.txt,sha256=6nt1UOz0rOLjY9X4wX6JSOZYWG4eCIhqtHlJiHFbYzc,56
+govdata_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=HsN4iUNpKeikxp-vzzw-M0KlwyflwVQKzIFR7COhaHs,1072
+govdata_mcp-0.1.0.dist-info/RECORD,,

govdata_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

govdata_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+govdata-mcp = govdata_mcp.server:main

govdata_mcp-0.1.0.dist-info/licenses/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.