regon-mcp 0.2.0__py3-none-any.whl

regon_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""regon-mcp — an MCP server for the Polish GUS REGON business register (BIR1)."""
+
+__version__ = "0.2.0"

regon_mcp/__main__.py

@@ -0,0 +1,4 @@
+from .server import main
+
+if __name__ == "__main__":
+    main()

regon_mcp/client.py

@@ -0,0 +1,320 @@
+"""A small, dependency-light client for the GUS BIR1 REGON SOAP service.
+
+Rather than a full WSDL/SOAP stack, this builds the (very stable) SOAP 1.2
+envelopes by hand over ``httpx``. That avoids WCF/WS-Addressing/MTOM pain in
+generic SOAP libraries and keeps the runtime tiny.
+
+Session handling:
+  * ``Zaloguj(api_key)`` returns a session id (``sid``).
+  * The ``sid`` is sent as an HTTP header on every authorized call.
+  * Sessions expire after ~60 minutes of inactivity, so the client refreshes
+    proactively on a TTL well under that. If the service still rejects a session
+    mid-call (a session fault), it re-logs in once and retries — but *only* for a
+    positively-identified session fault, never for arbitrary transport errors.
+"""
+
+from __future__ import annotations
+
+import html
+import re
+import threading
+import time
+from dataclasses import dataclass
+from typing import Optional, Sequence
+from xml.sax.saxutils import escape
+
+import httpx
+
+from . import parse as _parse
+from .envelopes import NS_ACTION, build_envelope
+from .errors import (
+    RegonAuthError,
+    RegonError,
+    RegonProtocolError,
+    RegonSessionError,
+    RegonTransportError,
+)
+
+__all__ = [
+    "RegonClient",
+    "RegonConfig",
+    "RegonError",
+    "RegonAuthError",
+    "RegonSessionError",
+    "RegonTransportError",
+    "RegonProtocolError",
+    "TEST_KEY",
+    "MAX_BATCH",
+]
+
+TEST_KEY = "abcde12345abcde12345"
+
+ENDPOINTS = {
+    "test": "https://wyszukiwarkaregontest.stat.gov.pl/wsBIR/UslugaBIRzewnPubl.svc",
+    "prod": "https://wyszukiwarkaregon.stat.gov.pl/wsBIR/UslugaBIRzewnPubl.svc",
+}
+
+# Refresh well before the service's ~60-minute inactivity expiry.
+_SESSION_TTL = 30 * 60
+
+# GUS accepts at most 20 identifiers in one batch search.
+MAX_BATCH = 20
+
+# Reject absurdly large HTTP bodies before we try to parse them.
+_MAX_RESPONSE_BYTES = 16 * 1024 * 1024
+
+_ENVELOPE_RE = re.compile(r"<(?:\w+:)?Envelope\b.*</(?:\w+:)?Envelope>", re.S)
+# Fault text that indicates the session (sid) was rejected/expired.
+_SESSION_FAULT_RE = re.compile(
+    r"sesj|session|zaloguj|identyfikator|uwierzytelni|authentic", re.I
+)
+
+
+def _extract_envelope(raw: str) -> str:
+    match = _ENVELOPE_RE.search(raw)
+    if not match:
+        raise RegonProtocolError("no SOAP envelope found in the response")
+    return match.group(0)
+
+
+def _result_text(raw: str, tag: str) -> str:
+    """Return the (unescaped) text of ``<tag>`` from a SOAP response body.
+
+    Raises ``RegonSessionError`` for a session-related SOAP fault (recoverable by
+    re-login) and ``RegonProtocolError`` for any other fault or missing element.
+    """
+    envelope = _extract_envelope(raw)
+    if re.search(rf"<{tag}\s*/>", envelope):
+        return ""
+    match = re.search(rf"<{tag}(?:\s[^>]*)?>(.*?)</{tag}>", envelope, re.S)
+    if match:
+        return html.unescape(match.group(1))
+    fault = re.search(r"<(?:\w+:)?Text[^>]*>(.*?)</(?:\w+:)?Text>", envelope, re.S)
+    if fault:
+        message = fault.group(1).strip()
+        if _SESSION_FAULT_RE.search(message):
+            raise RegonSessionError(f"session rejected by service: {message}")
+        raise RegonProtocolError(f"SOAP fault: {message}")
+    raise RegonProtocolError(f"response did not contain <{tag}>")
+
+
+@dataclass
+class RegonConfig:
+    api_key: str = TEST_KEY
+    environment: str = "test"
+    timeout: float = 30.0
+
+    def __post_init__(self) -> None:
+        if self.environment not in ENDPOINTS:
+            raise ValueError(
+                f"environment must be one of {sorted(ENDPOINTS)}; got {self.environment!r}"
+            )
+        if not str(self.api_key).strip():
+            raise ValueError("api_key must not be empty")
+        if not (self.timeout > 0):
+            raise ValueError(f"timeout must be positive; got {self.timeout!r}")
+
+    @property
+    def endpoint(self) -> str:
+        return ENDPOINTS[self.environment]
+
+    @property
+    def is_test_key(self) -> bool:
+        return self.api_key == TEST_KEY
+
+
+class RegonClient:
+    """Thread-safe client managing the BIR1 login session lifecycle."""
+
+    def __init__(self, config: Optional[RegonConfig] = None):
+        self.config = config or RegonConfig()
+        self._sid: Optional[str] = None
+        self._sid_at: float = 0.0
+        self._lock = threading.RLock()
+        self._http = httpx.Client(timeout=self.config.timeout)
+
+    # ---- transport ---------------------------------------------------------
+    def _post(self, action: str, body: str, sid: Optional[str]) -> str:
+        headers = {
+            "Content-Type": (
+                f'application/soap+xml;charset=UTF-8;action="{NS_ACTION}/{action}"'
+            )
+        }
+        if sid:
+            headers["sid"] = sid
+        envelope = build_envelope(self.config.endpoint, action, body)
+        try:
+            response = self._http.post(
+                self.config.endpoint, content=envelope.encode("utf-8"), headers=headers
+            )
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise RegonTransportError(
+                f"{action} failed: HTTP {exc.response.status_code} from {self.config.endpoint}"
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise RegonTransportError(f"{action} request failed: {exc}") from exc
+        if len(response.content) > _MAX_RESPONSE_BYTES:
+            raise RegonProtocolError(f"{action} response exceeds the maximum allowed size")
+        return response.text
+
+    # ---- session -----------------------------------------------------------
+    def _wyloguj(self, sid: str) -> bool:
+        body = (
+            "<ns:Wyloguj><ns:pIdentyfikatorSesji>"
+            f"{escape(sid)}"
+            "</ns:pIdentyfikatorSesji></ns:Wyloguj>"
+        )
+        raw = self._post("Wyloguj", body, sid=sid)
+        return _result_text(raw, "WylogujResult").strip().lower() == "true"
+
+    def _logout_quiet(self, sid: str) -> None:
+        """Best-effort logout so replaced sessions don't leak server-side."""
+        try:
+            self._wyloguj(sid)
+        except RegonError:
+            pass
+
+    def _login(self) -> str:
+        body = (
+            "<ns:Zaloguj><ns:pKluczUzytkownika>"
+            f"{escape(self.config.api_key)}"
+            "</ns:pKluczUzytkownika></ns:Zaloguj>"
+        )
+        raw = self._post("Zaloguj", body, sid=None)
+        sid = _result_text(raw, "ZalogujResult").strip()
+        if not sid:
+            raise RegonAuthError("login failed: empty session id (check REGON_API_KEY).")
+        return sid
+
+    def _session(self, force: bool = False) -> str:
+        with self._lock:
+            fresh = self._sid and (time.monotonic() - self._sid_at) < _SESSION_TTL
+            if force or not fresh:
+                old = self._sid
+                self._sid = None
+                self._sid_at = 0.0
+                if old:
+                    self._logout_quiet(old)
+                self._sid = self._login()
+                self._sid_at = time.monotonic()
+            return self._sid
+
+    def _authorized(self, action: str, body: str, result_tag: str) -> str:
+        with self._lock:
+            raw = self._post(action, body, sid=self._session())
+            try:
+                return _result_text(raw, result_tag)
+            except RegonSessionError:
+                # Positively-identified session rejection: re-login once, retry once.
+                raw = self._post(action, body, sid=self._session(force=True))
+                return _result_text(raw, result_tag)
+
+    def login(self) -> str:
+        """Force a fresh login and return the session id."""
+        return self._session(force=True)
+
+    def logout(self) -> bool:
+        with self._lock:
+            if not self._sid:
+                return True
+            sid = self._sid
+            try:
+                return self._wyloguj(sid)
+            finally:
+                self._sid = None
+                self._sid_at = 0.0
+
+    # ---- operations --------------------------------------------------------
+    def search(
+        self,
+        *,
+        nip: Optional[str] = None,
+        regon: Optional[str] = None,
+        krs: Optional[str] = None,
+        nips: Optional[Sequence[str]] = None,
+        krss: Optional[Sequence[str]] = None,
+        regons9: Optional[Sequence[str]] = None,
+        regons14: Optional[Sequence[str]] = None,
+    ) -> list[dict]:
+        """Search the register by one identifier or a batch of the same type."""
+        for name, seq in (
+            ("nips", nips), ("krss", krss), ("regons9", regons9), ("regons14", regons14),
+        ):
+            if seq is None:
+                continue
+            if len(seq) == 0:
+                raise ValueError(f"{name} must be a non-empty list")
+            if len(seq) > MAX_BATCH:
+                raise ValueError(f"at most {MAX_BATCH} identifiers per batch search ({name})")
+            if any(not str(v).strip() for v in seq):
+                raise ValueError(f"{name} contains an empty identifier")
+        params = _build_search_params(
+            nip=nip, regon=regon, krs=krs,
+            nips=nips, krss=krss, regons9=regons9, regons14=regons14,
+        )
+        body = (
+            "<ns:DaneSzukajPodmioty><ns:pParametryWyszukiwania>"
+            f"{params}"
+            "</ns:pParametryWyszukiwania></ns:DaneSzukajPodmioty>"
+        )
+        inner = self._authorized(
+            "DaneSzukajPodmioty", body, "DaneSzukajPodmiotyResult"
+        )
+        return _parse.parse_search_results(inner)
+
+    def full_report(self, regon: str, report_name: str) -> list[dict]:
+        """Fetch a detailed report for one entity by REGON."""
+        body = (
+            "<ns:DanePobierzPelnyRaport>"
+            f"<ns:pRegon>{escape(regon)}</ns:pRegon>"
+            f"<ns:pNazwaRaportu>{escape(report_name)}</ns:pNazwaRaportu>"
+            "</ns:DanePobierzPelnyRaport>"
+        )
+        inner = self._authorized(
+            "DanePobierzPelnyRaport", body, "DanePobierzPelnyRaportResult"
+        )
+        return _parse.parse_report(inner)
+
+    # ---- lifecycle ---------------------------------------------------------
+    def close(self) -> None:
+        try:
+            self.logout()
+        except RegonError:
+            pass
+        self._http.close()
+
+    def __enter__(self) -> "RegonClient":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+
+_SINGLE_TAGS = {"nip": "Nip", "regon": "Regon", "krs": "Krs"}
+_BATCH_TAGS = {
+    "nips": "Nipy",
+    "krss": "Krsy",
+    "regons9": "Regony9zn",
+    "regons14": "Regony14zn",
+}
+
+
+def _build_search_params(**kwargs) -> str:
+    parts = []
+    for key, tag in _SINGLE_TAGS.items():
+        value = kwargs.get(key)
+        if value:
+            parts.append(f"<dat:{tag}>{escape(str(value))}</dat:{tag}>")
+    for key, tag in _BATCH_TAGS.items():
+        values = kwargs.get(key)
+        if values:
+            joined = ",".join(escape(str(v)) for v in values)
+            parts.append(f"<dat:{tag}>{joined}</dat:{tag}>")
+    if not parts:
+        raise ValueError(
+            "search requires at least one of nip/regon/krs or a batch list"
+        )
+    if len(parts) > 1:
+        raise ValueError("provide only one identifier type per search")
+    return parts[0]

regon_mcp/envelopes.py

@@ -0,0 +1,35 @@
+"""SOAP 1.2 + WS-Addressing envelope construction for the GUS BIR1 service.
+
+The BIR1 endpoint is a WCF service that requires:
+  * SOAP 1.2 with the action carried in the Content-Type header, and
+  * WS-Addressing ``To`` / ``Action`` headers in the SOAP header.
+
+The session id returned by ``Zaloguj`` is *not* part of the SOAP body — it is
+sent as a plain HTTP header named ``sid`` on subsequent calls (see client.py).
+"""
+
+from __future__ import annotations
+
+# WS-Addressing action prefix (interface name), shared by every operation.
+NS_ACTION = "http://CIS/BIR/PUBL/2014/07/IUslugaBIRzewnPubl"
+
+_TEMPLATE = (
+    '<soap:Envelope '
+    'xmlns:soap="http://www.w3.org/2003/05/soap-envelope" '
+    'xmlns:ns="http://CIS/BIR/PUBL/2014/07" '
+    'xmlns:dat="http://CIS/BIR/PUBL/2014/07/DataContract" '
+    'xmlns:wsa="http://www.w3.org/2005/08/addressing">'
+    "<soap:Header>"
+    "<wsa:To>{endpoint}</wsa:To>"
+    "<wsa:Action>{action_ns}/{action}</wsa:Action>"
+    "</soap:Header>"
+    "<soap:Body>{body}</soap:Body>"
+    "</soap:Envelope>"
+)
+
+
+def build_envelope(endpoint: str, action: str, body: str) -> str:
+    """Wrap a SOAP body fragment in a full addressed SOAP 1.2 envelope."""
+    return _TEMPLATE.format(
+        endpoint=endpoint, action_ns=NS_ACTION, action=action, body=body
+    )

regon_mcp/errors.py

@@ -0,0 +1,27 @@
+"""Typed exceptions shared across the package.
+
+Kept in a dedicated module so both ``client`` and ``parse`` can raise them
+without a circular import.
+"""
+
+from __future__ import annotations
+
+
+class RegonError(Exception):
+    """Base error for all REGON/BIR client failures."""
+
+
+class RegonAuthError(RegonError):
+    """Login failed — e.g. an invalid or missing USER_KEY."""
+
+
+class RegonSessionError(RegonError):
+    """The BIR session was rejected or has expired; a re-login may recover."""
+
+
+class RegonTransportError(RegonError):
+    """A network/HTTP-level failure talking to the BIR endpoint."""
+
+
+class RegonProtocolError(RegonError):
+    """The service returned a malformed, oversized, or unexpected response."""

regon_mcp/parse.py

@@ -0,0 +1,108 @@
+"""Parse the XML payloads returned inside BIR1 responses into plain dicts.
+
+Search and report results arrive as an XML *string* embedded (HTML-escaped)
+inside the SOAP result element. Once unescaped, that inner document looks like::
+
+    <root>
+      <dane> ... fields ... </dane>
+      <dane> ... </dane>
+    </root>
+
+Each ``<dane>`` is one matched entity.
+
+The inner XML comes from an external service, so it is parsed with
+``defusedxml`` (DTDs and entity declarations rejected) under a size cap to keep
+the long-running MCP process safe from entity-expansion / resource-exhaustion.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+from xml.etree.ElementTree import Element, ParseError
+
+from defusedxml.ElementTree import fromstring as _safe_fromstring
+
+from .errors import RegonProtocolError
+
+# Generous ceiling for a single REGON payload (real ones are a few KB).
+_MAX_INNER_BYTES = 8 * 1024 * 1024
+
+# Friendly snake_case names for the fields returned by DaneSzukajPodmioty.
+_SEARCH_FIELDS = {
+    "Regon": "regon",
+    "Nip": "nip",
+    "StatusNip": "nip_status",
+    "Nazwa": "name",
+    "Wojewodztwo": "voivodeship",
+    "Powiat": "county",
+    "Gmina": "commune",
+    "Miejscowosc": "city",
+    "KodPocztowy": "postal_code",
+    "Ulica": "street",
+    "NrNieruchomosci": "building_number",
+    "NrLokalu": "unit_number",
+    "Typ": "type",
+    "SilosID": "silo_id",
+    "DataZakonczeniaDzialalnosci": "activity_end_date",
+    "MiejscowoscPoczty": "post_office_city",
+}
+
+# BIR entity type codes.
+TYPE_LABELS = {
+    "P": "legal person",
+    "F": "natural person",
+    "LP": "local unit of a legal person",
+    "LF": "local unit of a natural person",
+}
+
+_CAMEL_BOUNDARY = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+def _snake(name: str) -> str:
+    return _CAMEL_BOUNDARY.sub("_", name).lower()
+
+
+def _text(element: Element) -> Optional[str]:
+    value = (element.text or "").strip()
+    return value or None
+
+
+def _rows(inner_xml: str) -> list[Element]:
+    """Return the ``<dane>`` elements from a result payload.
+
+    An empty payload is a legitimate zero-result response; a non-empty but
+    unparseable payload is a protocol error, not "no results".
+    """
+    inner = (inner_xml or "").strip()
+    if not inner:
+        return []
+    if len(inner.encode("utf-8", "ignore")) > _MAX_INNER_BYTES:
+        raise RegonProtocolError("REGON payload exceeds the maximum allowed size")
+    try:
+        root = _safe_fromstring(inner)
+    except (ParseError, ValueError) as exc:
+        raise RegonProtocolError(f"could not parse REGON XML payload: {exc}") from exc
+    return list(root.findall("dane"))
+
+
+def parse_search_results(inner_xml: str) -> list[dict]:
+    """Parse a DaneSzukajPodmioty payload into a list of entity summaries."""
+    results = []
+    for dane in _rows(inner_xml):
+        row = {
+            _SEARCH_FIELDS.get(child.tag, _snake(child.tag)): _text(child)
+            for child in dane
+        }
+        if row.get("type"):
+            row["type_label"] = TYPE_LABELS.get(row["type"], row["type"])
+        results.append(row)
+    return results
+
+
+def parse_report(inner_xml: str) -> list[dict]:
+    """Parse a DanePobierzPelnyRaport payload generically (tag -> snake_case)."""
+    return [
+        {_snake(child.tag): _text(child) for child in dane}
+        for dane in _rows(inner_xml)
+    ]

regon_mcp/server.py

@@ -0,0 +1,207 @@
+"""MCP server exposing the GUS REGON register as clean, typed tools."""
+
+from __future__ import annotations
+
+import math
+import os
+from datetime import datetime, timezone
+from typing import Optional
+
+from mcp.server import MCPServer
+
+from .client import MAX_BATCH, RegonClient, RegonConfig, TEST_KEY
+from .validate import normalize_krs, normalize_nip, normalize_regon
+
+mcp = MCPServer("regon")
+
+_config: Optional[RegonConfig] = None
+_client: Optional[RegonClient] = None
+
+# Report names accepted by get_full_report(). These are the BIR1.1 reports; the
+# newer BIR1.2 / PKD-2025 report family belongs to a different API version and
+# is intentionally out of scope for this client.
+REPORT_TYPES = {
+    "BIR11OsPrawna": "Legal person — full record (type P).",
+    "BIR11OsPrawnaPkd": "Legal person — PKD activity codes.",
+    "BIR11OsPrawnaListaJednLokalnych": "Legal person — list of local units.",
+    "BIR11JednLokalnaOsPrawnej": "Local unit of a legal person — full record.",
+    "BIR11JednLokalnaOsPrawnejPkd": "Local unit of a legal person — PKD codes.",
+    "BIR11OsFizycznaDaneOgolne": "Natural person — general data (type F).",
+    "BIR11OsFizycznaDzialalnoscCeidg": "Natural person — CEIDG business activity (silo 1).",
+    "BIR11OsFizycznaDzialalnoscRolnicza": "Natural person — agricultural activity (silo 2).",
+    "BIR11OsFizycznaDzialalnoscPozostala": "Natural person — other activity (silo 3).",
+    "BIR11OsFizycznaDzialalnoscSkreslonaDo20141108": "Natural person — activity removed before 2014-11-08 (silo 4).",
+    "BIR11OsFizycznaPkd": "Natural person — PKD activity codes.",
+    "BIR11OsFizycznaListaJednLokalnych": "Natural person — list of local units.",
+    "BIR11JednLokalnaOsFizycznej": "Local unit of a natural person — full record.",
+    "BIR11JednLokalnaOsFizycznejPkd": "Local unit of a natural person — PKD codes.",
+}
+
+
+def _load_config() -> RegonConfig:
+    """Read and eagerly validate configuration from the environment."""
+    global _config
+    if _config is None:
+        raw_timeout = os.getenv("REGON_TIMEOUT", "30")
+        try:
+            timeout = float(raw_timeout)
+        except ValueError as exc:
+            raise ValueError(f"REGON_TIMEOUT must be a number; got {raw_timeout!r}") from exc
+        if not (timeout > 0 and math.isfinite(timeout)):
+            raise ValueError(f"REGON_TIMEOUT must be a positive finite number; got {timeout!r}")
+        # RegonConfig validates api_key non-empty and environment membership.
+        _config = RegonConfig(
+            api_key=os.getenv("REGON_API_KEY", TEST_KEY),
+            environment=os.getenv("REGON_ENV", "test"),
+            timeout=timeout,
+        )
+    return _config
+
+
+def _get_client() -> RegonClient:
+    global _client
+    if _client is None:
+        _client = RegonClient(_load_config())
+    return _client
+
+
+def _source() -> dict:
+    config = _load_config()
+    source = {
+        "register": "REGON — Krajowy Rejestr Urzędowy Podmiotów Gospodarki Narodowej",
+        "provided_by": "Główny Urząd Statystyczny (Statistics Poland / GUS)",
+        "api": "BIR1.1",
+        "environment": config.environment,
+        "using_test_key": config.is_test_key,
+        "retrieved_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "attribution": (
+            "When presenting REGON data, cite the source as 'REGON, GUS' "
+            "together with the retrieval date."
+        ),
+    }
+    if config.is_test_key:
+        source["note"] = (
+            "Public test key in use — the GUS test database is anonymized and "
+            "returns limited or no data. Set REGON_API_KEY to a production "
+            "USER_KEY (and REGON_ENV=prod) for live results."
+        )
+    return source
+
+
+def _envelope(results: list[dict]) -> dict:
+    return {"count": len(results), "results": results, "source": _source()}
+
+
+@mcp.tool()
+def search_by_nip(nip: str) -> dict:
+    """Look up a Polish business entity by NIP (10-digit tax id).
+
+    Returns basic registry data (name, REGON, address, entity type). Use the
+    returned REGON with get_full_report() for the detailed record.
+    """
+    return _envelope(_get_client().search(nip=normalize_nip(nip)))
+
+
+@mcp.tool()
+def search_by_regon(regon: str) -> dict:
+    """Look up a Polish business entity by REGON (9- or 14-digit statistical id)."""
+    return _envelope(_get_client().search(regon=normalize_regon(regon)))
+
+
+@mcp.tool()
+def search_by_krs(krs: str) -> dict:
+    """Look up a Polish business entity by KRS (10-digit court-register number)."""
+    return _envelope(_get_client().search(krs=normalize_krs(krs)))
+
+
+@mcp.tool()
+def search_bulk(identifiers: list[str], id_type: str) -> dict:
+    """Look up up to 20 entities of the same identifier type in one call.
+
+    id_type must be one of: "nip", "krs", "regon9", "regon14".
+
+    The response adds `requested` (normalized inputs) and `unmatched` (requested
+    ids with no returned row) so partial results are explicit. For KRS the
+    service does not echo the KRS in search rows, so `unmatched` is null there.
+    """
+    if not identifiers:
+        raise ValueError("identifiers must be a non-empty list")
+    if len(identifiers) > MAX_BATCH:
+        raise ValueError(f"GUS BIR accepts at most {MAX_BATCH} identifiers per bulk search")
+
+    kind = id_type.lower()
+    client = _get_client()
+    if kind == "nip":
+        requested = [normalize_nip(x) for x in identifiers]
+        rows = client.search(nips=requested)
+        match_field = "nip"
+    elif kind == "krs":
+        requested = [normalize_krs(x) for x in identifiers]
+        rows = client.search(krss=requested)
+        match_field = None  # search rows do not include KRS
+    elif kind == "regon9":
+        requested = [normalize_regon(x) for x in identifiers]
+        if any(len(v) != 9 for v in requested):
+            raise ValueError("regon9 expects 9-digit REGONs")
+        rows = client.search(regons9=requested)
+        match_field = "regon"
+    elif kind == "regon14":
+        requested = [normalize_regon(x) for x in identifiers]
+        if any(len(v) != 14 for v in requested):
+            raise ValueError("regon14 expects 14-digit REGONs")
+        rows = client.search(regons14=requested)
+        match_field = "regon"
+    else:
+        raise ValueError("id_type must be one of: nip, krs, regon9, regon14")
+
+    envelope = _envelope(rows)
+    envelope["requested"] = requested
+    if match_field:
+        found = {r.get(match_field) for r in rows}
+        envelope["unmatched"] = [x for x in requested if x not in found]
+    else:
+        envelope["unmatched"] = None
+    return envelope
+
+
+@mcp.tool()
+def get_full_report(regon: str, report_type: str) -> dict:
+    """Fetch a detailed REGON report for one entity by REGON.
+
+    Choose report_type from list_report_types(), based on the entity's `type`
+    and `silo_id` returned by a search.
+    """
+    if report_type not in REPORT_TYPES:
+        raise ValueError(
+            f"Unknown report_type {report_type!r}. Call list_report_types() for valid names."
+        )
+    return _envelope(_get_client().full_report(normalize_regon(regon), report_type))
+
+
+@mcp.tool()
+def list_report_types() -> dict:
+    """List valid report_type values for get_full_report(), with guidance.
+
+    These are the BIR1.1 report names. Picking the right report:
+      - type "P" (legal person)   -> BIR11OsPrawna
+      - type "F" (natural person) -> by silo_id:
+          1 -> BIR11OsFizycznaDzialalnoscCeidg
+          2 -> BIR11OsFizycznaDzialalnoscRolnicza
+          3 -> BIR11OsFizycznaDzialalnoscPozostala
+          4 -> BIR11OsFizycznaDzialalnoscSkreslonaDo20141108
+      - local units (LP / LF) -> BIR11JednLokalnaOsPrawnej / ...OsFizycznej
+    """
+    return {
+        "report_types": REPORT_TYPES,
+        "count": len(REPORT_TYPES),
+        "source": _source(),
+    }
+
+
+def main() -> None:
+    """Console-script entry point: run the MCP server over stdio."""
+    try:
+        mcp.run()
+    finally:
+        if _client is not None:
+            _client.close()

regon_mcp/validate.py

@@ -0,0 +1,84 @@
+"""Validation and normalization for Polish business identifiers.
+
+Checksums are verified locally so obviously-wrong identifiers fail fast without
+a network round-trip. Only whitespace and common grouping separators (``-`` and
+``.``) are tolerated in the input; any other character is rejected rather than
+silently stripped, so ``"abc5261040828"`` is an error, not a valid NIP.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Characters allowed purely as visual separators in a typed identifier.
+_SEPARATORS = re.compile(r"[\s.\-]")
+_ALL_DIGITS = re.compile(r"\A\d+\Z")
+
+
+def _clean(value: str) -> str:
+    """Strip only whitespace/grouping separators; reject anything non-numeric."""
+    if value is None:
+        raise ValueError("identifier must not be None")
+    stripped = _SEPARATORS.sub("", value)
+    if not _ALL_DIGITS.match(stripped):
+        raise ValueError(
+            f"identifier may contain only digits and separators; got {value!r}"
+        )
+    return stripped
+
+
+def _reject_all_zeros(digits: str, label: str) -> None:
+    if set(digits) == {"0"}:
+        raise ValueError(f"{label} {digits} is not a real identifier (all zeros)")
+
+
+def normalize_nip(nip: str) -> str:
+    """Return a clean 10-digit NIP, raising ValueError if it is invalid."""
+    d = _clean(nip)
+    if len(d) != 10:
+        raise ValueError(f"NIP must contain 10 digits; got {len(d)} in {nip!r}")
+    _reject_all_zeros(d, "NIP")
+    weights = (6, 5, 7, 2, 3, 4, 5, 6, 7)
+    check = sum(int(a) * w for a, w in zip(d[:9], weights)) % 11
+    if check == 10 or check != int(d[9]):
+        raise ValueError(f"NIP {d} has an invalid checksum")
+    return d
+
+
+def _regon9_checksum_ok(d9: str) -> bool:
+    weights = (8, 9, 2, 3, 4, 5, 6, 7)
+    return sum(int(a) * w for a, w in zip(d9[:8], weights)) % 11 % 10 == int(d9[8])
+
+
+def normalize_regon(regon: str) -> str:
+    """Return a clean 9- or 14-digit REGON, validating every checksum.
+
+    A 14-digit REGON embeds a 9-digit parent REGON in its first nine digits, so
+    both the parent (9-digit) and the full (14-digit) checksums are verified.
+    """
+    d = _clean(regon)
+    if len(d) not in (9, 14):
+        raise ValueError(f"REGON must contain 9 or 14 digits; got {len(d)} in {regon!r}")
+    _reject_all_zeros(d, "REGON")
+    if not _regon9_checksum_ok(d[:9]):
+        raise ValueError(f"REGON {d} has an invalid 9-digit (parent) checksum")
+    if len(d) == 14:
+        weights = (2, 4, 8, 5, 0, 9, 7, 3, 6, 1, 2, 4, 8)
+        if sum(int(a) * w for a, w in zip(d[:13], weights)) % 11 % 10 != int(d[13]):
+            raise ValueError(f"REGON-14 {d} has an invalid 14-digit checksum")
+    return d
+
+
+def normalize_krs(krs: str) -> str:
+    """Return a zero-padded 10-digit KRS (no checksum exists).
+
+    Leading zeros are routinely omitted when a KRS is typed (``543759`` for
+    ``0000543759``), so a shorter numeric value is left-padded to 10 digits.
+    All-zero and over-long values are rejected.
+    """
+    d = _clean(krs)
+    if not d or len(d) > 10:
+        raise ValueError(f"KRS must contain 1 to 10 digits; got {krs!r}")
+    padded = d.zfill(10)
+    _reject_all_zeros(padded, "KRS")
+    return padded

regon_mcp-0.2.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: regon-mcp
+Version: 0.2.0
+Summary: Model Context Protocol server for the Polish GUS REGON business register (BIR1 API).
+Project-URL: Homepage, https://smartmobilehouse.com
+Project-URL: Repository, https://github.com/SmartMobileHouse/regon-mcp
+Project-URL: Issues, https://github.com/SmartMobileHouse/regon-mcp/issues
+Author: Smart Mobile House
+License: MIT
+License-File: LICENSE
+Keywords: bir,company-data,gus,kyc,mcp,model-context-protocol,poland,regon
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.10
+Requires-Dist: defusedxml>=0.7
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.0.0
+Description-Content-Type: text/markdown
+
+# regon-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI
+assistants clean, typed access to the **Polish REGON business register** (GUS
+BIR1). Look up any Polish company by **NIP**, **REGON**, or **KRS** and get back
+structured data — name, address, legal form, activity codes — without touching
+the underlying SOAP API.
+
+The official [GUS BIR1 API](https://api.stat.gov.pl/Home/RegonApi) is a WCF SOAP
+service with WS-Addressing, MTOM multipart responses, an HTTP-header session
+token, and XML-nested-inside-XML result payloads. `regon-mcp` hides all of that
+behind a handful of simple tools.
+
+> Built and maintained by [Smart Mobile House](https://smartmobilehouse.com) —
+> secure AI implementation for enterprise.
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `search_by_nip(nip)` | Look up an entity by 10-digit NIP (tax id). |
+| `search_by_regon(regon)` | Look up an entity by 9- or 14-digit REGON. |
+| `search_by_krs(krs)` | Look up an entity by 10-digit KRS (court register). |
+| `search_bulk(identifiers, id_type)` | Look up up to 20 entities of one type at once. |
+| `get_full_report(regon, report_type)` | Fetch a detailed report for one entity. |
+| `list_report_types()` | List valid report names, with guidance on which to use. |
+
+Every response includes a `source` block that names the register (REGON / GUS),
+the environment, and a UTC `retrieved_at` timestamp — so downstream use can cite
+the data correctly, as GUS requires.
+
+## Quick start
+
+No install needed — run it straight from the repo with
+[uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx --from git+https://github.com/SmartMobileHouse/regon-mcp regon-mcp
+```
+
+By default it uses the **public test key** against the anonymized GUS test
+database, so it runs with zero setup. For live data, request a free `USER_KEY`
+from `regon_bir@stat.gov.pl` and set the environment variables below.
+
+### Use it in Claude Desktop / Claude Code
+
+Add to your MCP config (e.g. `claude_desktop_config.json` or a project
+`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "regon": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/SmartMobileHouse/regon-mcp", "regon-mcp"],
+      "env": {
+        "REGON_API_KEY": "your-user-key",
+        "REGON_ENV": "prod"
+      }
+    }
+  }
+}
+```
+
+During development, point it at a local checkout instead:
+
+```json
+{
+  "mcpServers": {
+    "regon": {
+      "command": "uvx",
+      "args": ["--from", "/absolute/path/to/regon-mcp", "regon-mcp"],
+      "env": { "REGON_API_KEY": "abcde12345abcde12345" }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `REGON_API_KEY` | public test key | Your GUS BIR `USER_KEY`. |
+| `REGON_ENV` | `test` | `test` (anonymized data) or `prod` (live data). |
+| `REGON_TIMEOUT` | `30` | HTTP timeout in seconds. |
+
+Use `REGON_ENV=prod` only with a real `USER_KEY`; the test key works only
+against the test environment.
+
+## Development
+
+```bash
+git clone https://github.com/SmartMobileHouse/regon-mcp
+cd regon-mcp
+uv sync                 # create the venv and install deps
+uv run pytest           # offline tests: validation, parsing, mocked client,
+                        # and an in-memory MCP tool-discovery smoke test.
+                        # (network tests are deselected by default)
+uv run regon-mcp        # run the server over stdio
+
+# Live tests against the GUS endpoint (deselected unless opted in):
+REGON_RUN_NETWORK=1 uv run pytest -m network            # session lifecycle (test env)
+REGON_PROD_KEY=<your-key> uv run pytest -m network      # positive-control on live data
+```
+
+The client is a small hand-rolled SOAP layer over `httpx` (see
+`src/regon_mcp/client.py`) — no heavyweight SOAP stack, no runtime WSDL fetch.
+
+## Notes & limitations
+
+- The **GUS test database is anonymized** and returns little or no entity data.
+  Meaningful results require a production `USER_KEY` with `REGON_ENV=prod`.
+- Respect the GUS terms of use and rate limits. This project is an independent
+  open-source client and is not affiliated with or endorsed by GUS.
+- Data belongs to GUS. When you present it, cite **REGON / GUS** with the
+  retrieval date (surfaced in every response's `source` block).
+
+## License
+
+[MIT](LICENSE) © Smart Mobile House

regon_mcp-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+regon_mcp/__init__.py,sha256=IxgMld53-eyT5692PLJ7LcMVrpLub6JCeeYTtoflcIU,108
+regon_mcp/__main__.py,sha256=9it1my_mM7xBpDh79QSi7FAvZD3Vki3GQFPJIDZw_zs,64
+regon_mcp/client.py,sha256=rabDjtrg5MP4AhOFUkR9OaPKra-e1gZVFJ5HFvZvTyU,11228
+regon_mcp/envelopes.py,sha256=-3WlpQXwrfx6AsWiU2F1LHzToFRNLvQqPGaasuo1FDs,1297
+regon_mcp/errors.py,sha256=kg46-M1eRV0-CO27rUx53R3RZ-1BdQEiLw2vTrRSlCo,723
+regon_mcp/parse.py,sha256=ipojnsCah740fgGvXlnQ4yBX-f983VLLbCN-4P2dXpc,3342
+regon_mcp/server.py,sha256=CRlL8utniCtw-ok3_lDikwiphN-3IdCec5XHxL5P6dc,8039
+regon_mcp/validate.py,sha256=soH1yddg7G5GocJudUHK7pVcdT-1bn2OX2g6Uj0-JrY,3159
+regon_mcp-0.2.0.dist-info/METADATA,sha256=uJUk0QJRnMyF5OnDcGtao_90OMwJQ22zflZFza0iCm4,5052
+regon_mcp-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+regon_mcp-0.2.0.dist-info/entry_points.txt,sha256=RgFuW-CRpGmTjtOCC83-8Z5ti8tULoU8P0klxyG_5fo,52
+regon_mcp-0.2.0.dist-info/licenses/LICENSE,sha256=2vLtjN350BRPGjAPtYoFZ3wJtuSt2VZHxBWGUsAsrl8,1075
+regon_mcp-0.2.0.dist-info/RECORD,,

regon_mcp-0.2.0.dist-info/WHEEL

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

regon_mcp-0.2.0.dist-info/entry_points.txt

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

regon_mcp-0.2.0.dist-info/licenses/LICENSE

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