regon-mcp 0.2.0__tar.gz

regon_mcp-0.2.0/.env.example

@@ -0,0 +1,12 @@
+# Copy to .env and adjust. The server reads these at startup.
+
+# Your GUS BIR USER_KEY. Request one (free) from regon_bir@stat.gov.pl.
+# Leave unset to use the public TEST key against the anonymized test database.
+REGON_API_KEY=abcde12345abcde12345
+
+# Which GUS environment to hit: "test" (anonymized data) or "prod" (live data).
+# Use "test" with the public test key; switch to "prod" only with a real USER_KEY.
+REGON_ENV=test
+
+# HTTP timeout in seconds.
+REGON_TIMEOUT=30

regon_mcp-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,64 @@
+name: publish
+
+# Publish to PyPI via Trusted Publishing (OIDC) — no API token is stored.
+# Triggers on pushing a semver tag (v1.2.3), or manually for the first release.
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Ensure the git tag matches the package version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(grep -m1 -E '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')"
+          echo "git tag: $tag / pyproject: $pkg"
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::Git tag v$tag does not match pyproject version $pkg"
+            exit 1
+          fi
+
+      - name: Validate distribution metadata
+        run: uvx twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/regon-mcp/
+    permissions:
+      id-token: write  # required for OIDC / Trusted Publishing
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

regon_mcp-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual envs / uv
+.venv/
+
+# Secrets / local config
+.env
+.env.*
+!.env.example
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

regon_mcp-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

regon_mcp-0.2.0/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.

regon_mcp-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,120 @@
+# 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/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "regon-mcp"
+version = "0.2.0"
+description = "Model Context Protocol server for the Polish GUS REGON business register (BIR1 API)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Smart Mobile House" }]
+keywords = [
+  "mcp",
+  "model-context-protocol",
+  "regon",
+  "gus",
+  "bir",
+  "poland",
+  "company-data",
+  "kyc",
+]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business",
+]
+dependencies = [
+  # Cap the MCP SDK below the next major: the 1.x -> 2.x jump was breaking,
+  # so a future 3.x could be too. httpx is intentionally left unbounded.
+  "mcp>=2.0.0,<3",
+  "httpx>=0.27",
+  "defusedxml>=0.7",
+]
+
+[project.urls]
+Homepage = "https://smartmobilehouse.com"
+Repository = "https://github.com/SmartMobileHouse/regon-mcp"
+Issues = "https://github.com/SmartMobileHouse/regon-mcp/issues"
+
+[project.scripts]
+regon-mcp = "regon_mcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/regon_mcp"]
+
+[tool.pytest.ini_options]
+markers = [
+  "network: integration tests that hit the live GUS BIR test endpoint",
+]

regon_mcp-0.2.0/src/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-0.2.0/src/regon_mcp/__main__.py

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