dnb-mcp 0.1.0__py3-none-any.whl

dnb_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""dnb_mcp — unofficial read-only MCP server for services.dnb.de.
+
+Deutsche Nationalbibliothek catalogue via its official SRU API: keyword, title and author search, ISBN and DNB-ID lookup. No key, no login.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"

dnb_mcp/domain.py

@@ -0,0 +1,119 @@
+"""Domain logic: shape DNB SRU (MARC21-xml) responses into compact
+dicts (stdlib only).
+
+Data source: the Deutsche Nationalbibliothek SRU API
+(https://services.dnb.de/sru/dnb) — free, no key, no login.
+CQL indexes used (from the API's own explain response, verified
+2026-11-10): woe (all terms), tit (title), per (person/author),
+num (number — incl. ISBN), idn (DNB identifier).
+
+NOT offered: a newspapers-only search — the `mat` (material type)
+index returns 0 for every German value tried (Bücher, Zeitschriften,
+Zeitung, Zeitungen, Online-Ressource), so no reliable newspaper
+filter exists; newspapers are still found by the keyword/title
+searches. Dublin Core recordSchema is unsupported ("Unknown schema
+for retrieval") — MARC21-xml only.
+"""
+from __future__ import annotations
+
+import re
+import urllib.parse
+import xml.etree.ElementTree as ET
+
+BASE = "https://services.dnb.de/sru/dnb"
+
+SRW = "{http://www.loc.gov/zing/srw/}"
+M = "{http://www.loc.gov/MARC21/slim}"
+
+_ISBN_RE = re.compile(r"^[\d-]{10,17}[0-9Xx]$")
+
+
+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 validate_isbn(isbn: str) -> str:
+    key = (isbn or "").strip().replace(" ", "")
+    if not _ISBN_RE.match(key) or not 10 <= len(key.replace("-", "")) <= 13:
+        raise ValueError(f"invalid ISBN: {isbn!r} "
+                         "(expected 10 or 13 digits, dashes allowed)")
+    return key
+
+
+def validate_dnb_id(dnb_id: str) -> str:
+    key = (dnb_id or "").strip()
+    if not key.isdigit():
+        raise ValueError(f"invalid DNB identifier: {dnb_id!r} "
+                         "(expected digits, e.g. \"1306459214\")")
+    return key
+
+
+def search_url(query: str, maximum_records: int = 10) -> str:
+    params = {
+        "operation": "searchRetrieve",
+        "version": "1.1",
+        "query": query,
+        "recordSchema": "MARC21-xml",
+        "maximumRecords": str(maximum_records),
+    }
+    return BASE + "?" + urllib.parse.urlencode(params)
+
+
+def _subs(record, tag, code):
+    return [s.text.strip() for df in record.findall(f"{M}datafield[@tag='{tag}']")
+            for s in df.findall(f"{M}subfield[@code='{code}']")
+            if (s.text or "").strip()]
+
+
+def _first(record, tag, code):
+    vals = _subs(record, tag, code)
+    return vals[0] if vals else ""
+
+
+def _compact(record) -> dict:
+    title = _first(record, "245", "a")
+    subtitle = _first(record, "245", "b")
+    if subtitle:
+        title = f"{title} : {subtitle}"
+    author = _first(record, "100", "a") or _first(record, "110", "a")
+    return {
+        "dnb_id": (record.findtext(f"{M}controlfield[@tag='001']") or "").strip(),
+        "title": title,
+        "author": author,
+        "contributors": _subs(record, "700", "a")[:3],
+        "year": _first(record, "264", "c"),
+        "publisher": _first(record, "264", "b"),
+        "place": _first(record, "264", "a"),
+        "edition": _first(record, "250", "a"),
+        "isbn": _first(record, "020", "a"),
+        "language": _first(record, "041", "a"),
+        "pages": _first(record, "300", "a"),
+        "subjects": _subs(record, "653", "a")[:5],
+        "url": _first(record, "856", "u"),
+    }
+
+
+def parse_search(text: str) -> dict:
+    """Parse an SRU searchRetrieve response -> {total_results, items}."""
+    try:
+        root = ET.fromstring(text)
+    except ET.ParseError as e:
+        raise ValueError(f"invalid SRU response: {e}") from e
+    diag = root.find(f"{SRW}diagnostics")
+    if diag is not None:
+        details = diag.findtext(".//{http://www.loc.gov/zing/srw/diagnostic/}details") or ""
+        msg = diag.findtext(".//{http://www.loc.gov/zing/srw/diagnostic/}message") or ""
+        raise ValueError(f"DNB SRU error: {details} ({msg})".strip())
+    total = root.findtext(f"{SRW}numberOfRecords")
+    try:
+        total_n = int(total or "0")
+    except ValueError:
+        total_n = 0
+    items = []
+    for rec in root.findall(f"{SRW}records/{SRW}record"):
+        data = rec.find(f"{SRW}recordData/{M}record")
+        if data is not None:
+            items.append(_compact(data))
+    return {"total_results": total_n, "items": items}

dnb_mcp/http.py

@@ -0,0 +1,99 @@
+"""HTTP layer for dnb_mcp — plain httpx GETs against services.dnb.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://services.dnb.de/sru/dnb?operation=searchRetrieve&version=1.1&query=woe%3DKafka&recordSchema=MARC21-xml&maximumRecords=1"
+SOURCE = "services.dnb.de"
+
+
+class DnbMcpError(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 DnbMcpError(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 DnbMcpError(
+            f"{SOURCE} returned HTTP 403 for {url} (bot wall) — try again later"
+        )
+    if r.status_code == 429:
+        raise DnbMcpError(
+            f"{SOURCE} rate-limited the request (HTTP 429) — try again later"
+        )
+    if r.status_code != 200:
+        raise DnbMcpError(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 DnbMcpError 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}

dnb_mcp/server.py

@@ -0,0 +1,145 @@
+"""MCP server: unofficial read-only access to the Deutsche
+Nationalbibliothek catalogue via its official SRU API. No key, no
+login. NOTE: the `mat` (material type) index returns 0 for every
+German value tried, so no newspapers-only filter is offered."""
+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 the Deutsche \
+Nationalbibliothek catalogue via its official SRU API (no key, no \
+login): keyword, title and author search, ISBN lookup and full \
+records by DNB identifier. NOTE: the SRU `mat` (material type) \
+index returns 0 for every German value tried, so no newspapers-only \
+filter is offered — newspapers are still found by the keyword and \
+title searches. Built by Mohammad Abbasi (mohammad-abbasi-sh) — \
+https://almanibama.ir · https://mabbasi.ir — Germany MCP factory.\
+"""
+
+_SOURCE = "services.dnb.de"
+_DISCLAIMER = "Unofficial read-only data from the Deutsche Nationalbibliothek SRU API; verify on dnb.de 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("dnb-mcp", instructions=INSTRUCTIONS)
+
+
+def _search(cql: str, limit: int) -> dict:
+    lim = _dom.validate_limit(limit)
+    parsed = _dom.parse_search(
+        _http.fetch_text(_dom.search_url(cql, maximum_records=lim)))
+    return {"total_results": parsed["total_results"],
+            "count": len(parsed["items"]), "items": parsed["items"]}
+
+
+@mcp.tool()
+def dnb_search_books(query: str, limit: int = 10) -> str:
+    """Keyword search across the whole DNB catalogue (all fields).
+    query: keyword or phrase, e.g. "Kafka". limit: 1..50 (default 10)."""
+    try:
+        q = (query or "").strip()
+        if not q:
+            raise ValueError("query must not be empty")
+        out = _search(f"woe={q}", limit)
+    except (_http.DnbMcpError, ValueError) as e:
+        return _err(e)
+    return _ok({"query": q, **out})
+
+
+@mcp.tool()
+def dnb_search_by_title(title: str, limit: int = 10) -> str:
+    """Search the DNB catalogue by title. title: e.g. "Briefe 1921-1922".
+    limit: 1..50 (default 10)."""
+    try:
+        q = (title or "").strip()
+        if not q:
+            raise ValueError("title must not be empty")
+        out = _search(f"tit={q}", limit)
+    except (_http.DnbMcpError, ValueError) as e:
+        return _err(e)
+    return _ok({"title": q, **out})
+
+
+@mcp.tool()
+def dnb_search_by_author(author: str, limit: int = 10) -> str:
+    """Search the DNB catalogue by author. author: e.g. "Kafka, Franz".
+    limit: 1..50 (default 10)."""
+    try:
+        q = (author or "").strip()
+        if not q:
+            raise ValueError("author must not be empty")
+        out = _search(f"per={q}", limit)
+    except (_http.DnbMcpError, ValueError) as e:
+        return _err(e)
+    return _ok({"author": q, **out})
+
+
+@mcp.tool()
+def dnb_by_isbn(isbn: str) -> str:
+    """Look up one book by ISBN. isbn: 10 or 13 digits, dashes allowed,
+    e.g. "9783100381682"."""
+    try:
+        key = _dom.validate_isbn(isbn)
+        out = _search(f"num={key}", 1)
+        if not out["items"]:
+            return _ok({"isbn": key, "total_results": 0, "count": 0,
+                        "items": []})
+    except (_http.DnbMcpError, ValueError) as e:
+        return _err(e)
+    return _ok({"isbn": key, **out})
+
+
+@mcp.tool()
+def dnb_get_record(dnb_id: str) -> str:
+    """Full record by DNB identifier. dnb_id: digits, e.g. "1306459214"
+    (the ID shown on every record)."""
+    try:
+        key = _dom.validate_dnb_id(dnb_id)
+        out = _search(f"idn={key}", 1)
+        if not out["items"]:
+            return _ok({"dnb_id": key, "total_results": 0, "count": 0,
+                        "items": []})
+    except (_http.DnbMcpError, ValueError) as e:
+        return _err(e)
+    return _ok({"dnb_id": key, **out})
+
+
+@mcp.tool()
+def dnb_health() -> str:
+    """Check whether services.dnb.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())

dnb_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: dnb-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for the Deutsche Nationalbibliothek catalogue (DNB SRU) — books, authors, ISBN
+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
+
+# dnb-mcp 📚
+
+mcp-name: io.github.mohammad-abbasi-sh/dnb-mcp
+
+Unofficial **read-only** MCP server for **[services.dnb.de](https://www.dnb.de)** — Deutsche Nationalbibliothek catalogue via its official SRU API: keyword, title and author search, ISBN and DNB-ID lookup. No key, no login. No key, no login.
+
+> Built by Mohammad Abbasi as part of the "Germany MCP factory". Not affiliated with services.dnb.de.
+
+## For AI agents
+
+Add to your MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "dnb": {
+      "command": "uvx",
+      "args": ["dnb-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+Or run locally: `python -m dnb_mcp.server` (needs `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `dnb_search_books` | Keyword search across the DNB catalogue — `query`, `limit` 1..50 |
+| `dnb_search_by_title` | Title search — `title`, `limit` 1..50 |
+| `dnb_search_by_author` | Author search — `author` (e.g. "Kafka, Franz"), `limit` 1..50 |
+| `dnb_by_isbn` | Look up one book by ISBN — `isbn` (13 or 10 digits, with or without dashes) |
+| `dnb_get_record` | Full record by DNB identifier — `dnb_id` (e.g. "1306459214") |
+| `dnb_health` | Reachability probe (ok / blocked / error) — one polite request |
+
+## Notes
+
+- All data comes from the **Deutsche Nationalbibliothek SRU API** (free, no key, no login).
+- Indexes used (from the API's own explain response): `woe` (all terms), `tit` (title), `per` (person/author), `num` (number incl. ISBN), `idn` (DNB identifier).
+- There is **no newspapers-only filter**: the `mat` (material type) index returns 0 for every German value tried (Bücher, Zeitschriften, Zeitung, Zeitungen, Online-Ressource), so no newspapers-only tool is offered; newspapers are still found by the keyword and title searches.
+- Dublin Core recordSchema is unsupported by the API — MARC21-xml only.
+
+Tests: 20/20 green (14 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)

dnb_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+dnb_mcp/__init__.py,sha256=37fBPHxxbn7BDs9iesg8V7zWcU2YzZBiQJB7k49Kbj0,271
+dnb_mcp/domain.py,sha256=YcYh7JoXunRbaUhe98IjVKx227x2KsV7c0cfTy-Fvdg,4198
+dnb_mcp/http.py,sha256=VxdQmvGObbIxD6vVgxj-GZQVyefVMflSsQRyeEtlYjQ,3202
+dnb_mcp/server.py,sha256=JWQkWk5I17a4eM26TUBs9nLfSVaF4RuOQhuyvl6dzl8,4647
+dnb_mcp-0.1.0.dist-info/METADATA,sha256=yLpocgeEEM_YPTm2LGzoPqKSTQZBvX261WUngc6bQSE,2575
+dnb_mcp-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+dnb_mcp-0.1.0.dist-info/entry_points.txt,sha256=ZfS4P-hGyNtcTe__f_yURUxzTb-qnoDzfam2oItgqb8,48
+dnb_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=HsN4iUNpKeikxp-vzzw-M0KlwyflwVQKzIFR7COhaHs,1072
+dnb_mcp-0.1.0.dist-info/RECORD,,

dnb_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

dnb_mcp-0.1.0.dist-info/entry_points.txt

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

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