polish-mcp-servers 0.1.0 → 0.1.2

package/README.md

@@ -2,10 +2,12 @@
 
 [![Glama](https://glama.ai/mcp/servers/kamilkaczmareksolutions/polish-mcp-servers/badge)](https://glama.ai/mcp/servers/kamilkaczmareksolutions/polish-mcp-servers)
 
-Local [Model Context Protocol](https://modelcontextprotocol.io) server for Polish public data. It speaks stdio and exposes 12 tools, one for each public Apify Actor by [enterprising_hamster](https://apify.com/enterprising_hamster).
+Local [Model Context Protocol](https://modelcontextprotocol.io) server for Polish public data. It speaks stdio and exposes 13 tools, one for each public Apify Actor by [enterprising_hamster](https://apify.com/enterprising_hamster).
 
 `tools/list` answers with no `APIFY_TOKEN` and no network. `tools/call` runs that Actor on your Apify account. Create a token at [console.apify.com/settings/integrations](https://console.apify.com/settings/integrations) and set `APIFY_TOKEN`. A call without a token returns an MCP tool error that points at that page.
 
+AI agents without an Apify account can buy a prepaid Apify API token at [agi.apify.com](https://agi.apify.com) (x402, MPP or Skyfire; minimum $1, expires after 14 days, unused balance is not refunded) and set it as `APIFY_TOKEN`. See [Agentic payments with x402](https://docs.apify.com/integrations/x402).
+
 Each call returns at most 100 dataset items and at most 256 KiB of JSON. Pass `maxItems` to ask for fewer. When the Actor schema already defaults `maxItems` to 100 or less, that default stands. The law tool defaults to 20, because that Actor's schema has no `maxItems`.
 
 ## Tools
@@ -24,20 +26,31 @@ Each call returns at most 100 dataset items and at most 256 KiB of JSON. Pass `m
 | `polish-healthcare-facilities-rpwdl` | RPWDL facilities with address, contact, specialties, and beds. | [Store](https://apify.com/enterprising_hamster/polish-healthcare-facilities-rpwdl) |
 | `polish-developer-apartment-prices` | Developer apartment and house offers, with price per m², from dane.gov.pl. | [Store](https://apify.com/enterprising_hamster/polish-developer-apartment-prices) |
 | `polish-electricity-market-pse` | PSE electricity prices and grid rows (RCE, day-ahead, imbalance, load, generation). | [Store](https://apify.com/enterprising_hamster/polish-electricity-market-pse) |
+| `polish-new-companies-krs` | New and changed companies from the KRS bulletin with NIP, REGON, PKD, and share capital. No personal data. | [Store](https://apify.com/enterprising_hamster/polish-new-companies-krs) |
+
+The full tool and parameter descriptions that clients see live in [`catalog/tool-descriptions.json`](catalog/tool-descriptions.json). Every tool is annotated `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: true`: it only reads the public source, but each `tools/call` starts a paid Apify Actor run, billed pay-per-event to the Apify account behind `APIFY_TOKEN`, and waits up to 300 s for it.
 
-`polish-mcp-servers` and `polish-mcp` list all 12. `polish-law-mcp` lists only `polish-law-mcp-server`. `polish-public-registers` lists the other 11, including `cee-public-tenders`.
+`polish-mcp-servers` and `polish-mcp` list all 13. `polish-law-mcp` lists only `polish-law-mcp-server`. `polish-public-registers` lists the other 12, including `cee-public-tenders`.
 
 ## Install
 
-From GitHub, without an npm publish:
+From npm ([`polish-mcp-servers`](https://www.npmjs.com/package/polish-mcp-servers)):
 
 ```bash
-npx -y github:kamilkaczmareksolutions/polish-mcp-servers
+npx -y polish-mcp-servers
 ```
 
 Law only, or registers only:
 
 ```bash
+npx -y --package polish-mcp-servers polish-law-mcp
+npx -y --package polish-mcp-servers polish-public-registers
+```
+
+Alternative, straight from GitHub (latest `main`, no npm registry):
+
+```bash
+npx -y github:kamilkaczmareksolutions/polish-mcp-servers
 npx -y --package github:kamilkaczmareksolutions/polish-mcp-servers polish-law-mcp
 npx -y --package github:kamilkaczmareksolutions/polish-mcp-servers polish-public-registers
 ```
@@ -75,21 +88,21 @@ Claude Desktop reads `claude_desktop_config.json`. Cursor reads `~/.cursor/mcp.j
   "mcpServers": {
     "polish-mcp": {
       "command": "npx",
-      "args": ["-y", "github:kamilkaczmareksolutions/polish-mcp-servers"],
+      "args": ["-y", "polish-mcp-servers"],
       "env": {
         "APIFY_TOKEN": "<YOUR_APIFY_TOKEN>"
       }
     },
     "polish-law": {
       "command": "npx",
-      "args": ["-y", "--package", "github:kamilkaczmareksolutions/polish-mcp-servers", "polish-law-mcp"],
+      "args": ["-y", "--package", "polish-mcp-servers", "polish-law-mcp"],
       "env": {
         "APIFY_TOKEN": "<YOUR_APIFY_TOKEN>"
       }
     },
     "polish-public-registers": {
       "command": "npx",
-      "args": ["-y", "--package", "github:kamilkaczmareksolutions/polish-mcp-servers", "polish-public-registers"],
+      "args": ["-y", "--package", "polish-mcp-servers", "polish-public-registers"],
       "env": {
         "APIFY_TOKEN": "<YOUR_APIFY_TOKEN>"
       }
@@ -105,7 +118,7 @@ Omit `APIFY_TOKEN` if you only want `tools/list`.
 The same data is also available as hosted MCP servers on [Apify](https://apify.com/enterprising_hamster). Point your client at a URL and authenticate with your Apify account. Those servers still run as Apify Actors.
 
 - **Polish Law MCP**: Polish statutes from the Sejm ELI API (Dziennik Ustaw, Monitor Polski) and court judgments from SAOS.
-- **Polish Public Registers**: 10 official Polish registers (EU-funded tenders, EV charging stations, vehicle registrations, building permits, land parcels and zoning, healthcare facilities, developer apartment prices, electricity market, legal acts, court judgments).
+- **Polish Public Registers**: 11 official Polish registers (EU-funded tenders, EV charging stations, vehicle registrations, building permits, land parcels and zoning, healthcare facilities, developer apartment prices, electricity market, new companies from KRS, legal acts, court judgments).
 
 | Server | MCP Registry name | MCP URL (Streamable HTTP) |
 |---|---|---|
@@ -116,7 +129,7 @@ The same data is also available as hosted MCP servers on [Apify](https://apify.c
 ### Polish Public Registers URL
 
 ```
-https://mcp.apify.com/?tools=enterprising_hamster/polish-eu-funds-tenders-baza-konkurencyjnosci,enterprising_hamster/polish-ev-charging-stations-eipa,enterprising_hamster/polish-vehicle-registrations-cepik,enterprising_hamster/polish-building-permits-gunb,enterprising_hamster/polish-land-parcels-uldk-zoning,enterprising_hamster/polish-healthcare-facilities-rpwdl,enterprising_hamster/polish-developer-apartment-prices,enterprising_hamster/polish-electricity-market-pse,enterprising_hamster/polish-legal-acts-eli,enterprising_hamster/polish-court-judgments-saos
+https://mcp.apify.com/?tools=enterprising_hamster/polish-eu-funds-tenders-baza-konkurencyjnosci,enterprising_hamster/polish-ev-charging-stations-eipa,enterprising_hamster/polish-vehicle-registrations-cepik,enterprising_hamster/polish-building-permits-gunb,enterprising_hamster/polish-land-parcels-uldk-zoning,enterprising_hamster/polish-healthcare-facilities-rpwdl,enterprising_hamster/polish-developer-apartment-prices,enterprising_hamster/polish-electricity-market-pse,enterprising_hamster/polish-new-companies-krs,enterprising_hamster/polish-legal-acts-eli,enterprising_hamster/polish-court-judgments-saos
 ```
 
 You can drop Actors from the `tools=` list to expose only the registers you need.
@@ -147,7 +160,7 @@ Pricing (pay per event, FREE/BRONZE Apify plan tier):
 
 ### Polish Public Registers tools
 
-Each Actor is exposed as one MCP tool that runs the Actor. The Apify MCP server also adds four helper tools: `get-actor-run`, `get-dataset-items`, `get-key-value-store-record`, `abort-actor-run` (14 tools in total).
+Each Actor is exposed as one MCP tool that runs the Actor. The Apify MCP server also adds four helper tools: `get-actor-run`, `get-dataset-items`, `get-key-value-store-record`, `abort-actor-run` (15 tools in total).
 
 Prices are per delivered result, FREE/BRONZE Apify plan tier. Higher plan tiers pay less; see each Actor page.
 
@@ -161,6 +174,7 @@ Prices are per delivered result, FREE/BRONZE Apify plan tier. Higher plan tiers
 | Healthcare facilities (RPWDL) | [polish-healthcare-facilities-rpwdl](https://apify.com/enterprising_hamster/polish-healthcare-facilities-rpwdl) | $0.004 facility |
 | Developer apartment prices (dane.gov.pl) | [polish-developer-apartment-prices](https://apify.com/enterprising_hamster/polish-developer-apartment-prices) | $0.002 offer; $0.004 price change |
 | Electricity market (PSE API) | [polish-electricity-market-pse](https://apify.com/enterprising_hamster/polish-electricity-market-pse) | $0.0003 market data row |
+| New and changed companies (KRS API, Ministry of Justice) | [polish-new-companies-krs](https://apify.com/enterprising_hamster/polish-new-companies-krs) | $0.004 company |
 | Legal acts (Sejm ELI) | [polish-legal-acts-eli](https://apify.com/enterprising_hamster/polish-legal-acts-eli) | $0.002 act metadata; $0.008 act with text |
 | Court judgments (SAOS) | [polish-court-judgments-saos](https://apify.com/enterprising_hamster/polish-court-judgments-saos) | $0.003 judgment metadata; $0.01 judgment with full text |
 
@@ -193,7 +207,7 @@ Cursor, `~/.cursor/mcp.json` or `.cursor/mcp.json` in a project:
       }
     },
     "polish-public-registers": {
-      "url": "https://mcp.apify.com/?tools=enterprising_hamster/polish-eu-funds-tenders-baza-konkurencyjnosci,enterprising_hamster/polish-ev-charging-stations-eipa,enterprising_hamster/polish-vehicle-registrations-cepik,enterprising_hamster/polish-building-permits-gunb,enterprising_hamster/polish-land-parcels-uldk-zoning,enterprising_hamster/polish-healthcare-facilities-rpwdl,enterprising_hamster/polish-developer-apartment-prices,enterprising_hamster/polish-electricity-market-pse,enterprising_hamster/polish-legal-acts-eli,enterprising_hamster/polish-court-judgments-saos",
+      "url": "https://mcp.apify.com/?tools=enterprising_hamster/polish-eu-funds-tenders-baza-konkurencyjnosci,enterprising_hamster/polish-ev-charging-stations-eipa,enterprising_hamster/polish-vehicle-registrations-cepik,enterprising_hamster/polish-building-permits-gunb,enterprising_hamster/polish-land-parcels-uldk-zoning,enterprising_hamster/polish-healthcare-facilities-rpwdl,enterprising_hamster/polish-developer-apartment-prices,enterprising_hamster/polish-electricity-market-pse,enterprising_hamster/polish-new-companies-krs,enterprising_hamster/polish-legal-acts-eli,enterprising_hamster/polish-court-judgments-saos",
       "headers": {
         "Authorization": "Bearer <YOUR_APIFY_TOKEN>"
       }
@@ -237,7 +251,7 @@ Look them up at `https://registry.modelcontextprotocol.io/v0.1/servers?search=ka
 
 ## Data sources
 
-All data comes from official Polish public registers and open-data APIs: Sejm ELI, SAOS, Baza Konkurencyjności, EIPA (UDT), CEPiK, GUNB, GUGiK ULDK, RPWDL, dane.gov.pl, PSE. Personal data is limited. Building-permit investors who are private persons are anonymised, private EV station operators are anonymised, CEPiK data is aggregated (no VINs or owners), and ULDK parcels come without owners.
+All data comes from official Polish public registers and open-data APIs: Sejm ELI, SAOS, Baza Konkurencyjności, EIPA (UDT), CEPiK, GUNB, GUGiK ULDK, RPWDL, dane.gov.pl, PSE, KRS. Personal data is limited. Building-permit investors who are private persons are anonymised, private EV station operators are anonymised, CEPiK data is aggregated (no VINs or owners), ULDK parcels come without owners, and KRS rows carry company-level fields only (no board members or shareholders).
 
 ## License
 

package/catalog/actors.json

@@ -2375,5 +2375,132 @@
         }
       }
     }
+  },
+  {
+    "actorId": "enterprising_hamster/polish-new-companies-krs",
+    "name": "polish-new-companies-krs",
+    "title": "Poland New Companies API – KRS Registrations Feed",
+    "description": "New and changed Polish companies every day from the official KRS register (nowe spółki KRS): name, NIP, REGON, address, PKD, share capital, registration date. No personal data. For leads, KYC, CRM and AI agents (MCP). CSV, JSON, Excel.",
+    "isPublic": true,
+    "buildId": "3yawBGDegPz9hilZA",
+    "buildNumber": "0.1.2",
+    "inputSchema": {
+      "title": "Poland new & changed companies (KRS)",
+      "type": "object",
+      "schemaVersion": 1,
+      "properties": {
+        "dateFrom": {
+          "title": "From date",
+          "type": "string",
+          "editor": "textfield",
+          "description": "First bulletin day (YYYY-MM-DD, Europe/Warsaw). Empty with dateTo empty means yesterday. One day when only dateFrom is set.",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+        },
+        "dateTo": {
+          "title": "To date",
+          "type": "string",
+          "editor": "textfield",
+          "description": "Last bulletin day (inclusive). Must be used together with dateFrom. At most 31 days in the range.",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+        },
+        "events": {
+          "title": "Events",
+          "type": "array",
+          "editor": "select",
+          "description": "New = registration date in the window. Changed = appeared on the bulletin but registered earlier. Last-entry date does not reclassify.",
+          "items": {
+            "type": "string",
+            "enum": [
+              "new",
+              "changed"
+            ],
+            "enumTitles": [
+              "New registrations",
+              "Changed companies"
+            ]
+          },
+          "default": [
+            "new",
+            "changed"
+          ]
+        },
+        "pkd": {
+          "title": "PKD codes",
+          "type": "array",
+          "editor": "stringList",
+          "description": "Match full PKD codes or prefixes (e.g. 93 matches 93.29.B). Empty = any activity.",
+          "default": []
+        },
+        "voivodeships": {
+          "title": "Voivodeships",
+          "type": "array",
+          "editor": "select",
+          "description": "Registered seat must be in one of these voivodeships. Empty = whole country.",
+          "items": {
+            "type": "string",
+            "enum": [
+              "dolnośląskie",
+              "kujawsko-pomorskie",
+              "lubelskie",
+              "lubuskie",
+              "łódzkie",
+              "małopolskie",
+              "mazowieckie",
+              "opolskie",
+              "podkarpackie",
+              "podlaskie",
+              "pomorskie",
+              "śląskie",
+              "świętokrzyskie",
+              "warmińsko-mazurskie",
+              "wielkopolskie",
+              "zachodniopomorskie"
+            ],
+            "enumTitles": [
+              "dolnośląskie",
+              "kujawsko-pomorskie",
+              "lubelskie",
+              "lubuskie",
+              "łódzkie",
+              "małopolskie",
+              "mazowieckie",
+              "opolskie",
+              "podkarpackie",
+              "podlaskie",
+              "pomorskie",
+              "śląskie",
+              "świętokrzyskie",
+              "warmińsko-mazurskie",
+              "wielkopolskie",
+              "zachodniopomorskie"
+            ]
+          },
+          "default": []
+        },
+        "legalForms": {
+          "title": "Legal forms",
+          "type": "array",
+          "editor": "stringList",
+          "description": "Exact forma prawna strings after trimming. Empty = any form.",
+          "default": []
+        },
+        "minShareCapital": {
+          "title": "Minimum share capital",
+          "type": "number",
+          "editor": "number",
+          "description": "Companies without share capital fail this filter when set.",
+          "minimum": 0
+        },
+        "maxItems": {
+          "title": "Max companies",
+          "type": "integer",
+          "editor": "number",
+          "description": "Stop after this many companies are saved (default keeps Start runs cheap).",
+          "default": 20,
+          "minimum": 1,
+          "maximum": 20000
+        }
+      }
+    }
   }
 ]

package/catalog/tool-descriptions.json

@@ -0,0 +1,45 @@
+{
+  "polish-law-mcp-server": {
+    "description": "Makes one call to the Polish Law MCP Actor, which reads the official Sejm ELI API (Dziennik Ustaw, Monitor Polski) and the SAOS court judgments API live: set tool to search_legal_acts, get_legal_act, get_legal_act_text (current consolidated wording, optionally one article), list_changed_legal_acts, search_court_judgments or get_court_judgment, and pass that tool's arguments. Use it to find or read one specific act, article or judgment; for bulk filtered lists or onlyNew feeds use polish-legal-acts-eli or polish-court-judgments-saos. Read-only: it only queries the public sources and never writes to them. Each call needs the APIFY_TOKEN env var and starts one paid run of the Apify Actor enterprising_hamster/polish-law-mcp-server on your Apify account, billed pay-per-event per successful tool call (calls returning full text cost more; failed or empty calls are free) plus any Apify platform usage. The server waits up to 300 s; ELI answers in about a second, SAOS searches take 1-20 s and one full SAOS judgment 15-60 s.",
+    "parameters": {
+      "tool": "Which law tool to run once. search_legal_acts: find acts by title stem, publisher (DU or MP), year, type, keywords, in-force status or date range. get_legal_act: metadata, status and references of one act. get_legal_act_text: plain text of an act or one article (newest consolidated text), paged. list_changed_legal_acts: acts whose ELI record changed since a time. search_court_judgments: find SAOS judgments. get_court_judgment: full text and metadata of one judgment.",
+      "arguments": "Arguments object for the chosen tool, exactly as the hosted Polish Law MCP server takes them, e.g. {\"title\": \"ochron danych\", \"limit\": 5} for search_legal_acts, {\"eli\": \"DU/1964/93\", \"article\": \"415\"} for get_legal_act_text (an ELI id or a Dz.U. citation), or {\"query\": \"art. 415 k.c.\", \"court_type\": \"SUPREME\", \"limit\": 5} for search_court_judgments. Full argument lists: https://apify.com/enterprising_hamster/polish-law-mcp-server"
+    }
+  },
+  "polish-legal-acts-eli": {
+    "description": "Lists Polish legal acts from the official Sejm ELI API (Dziennik Ustaw or Monitor Polski), filtered by year or date range, title stem, ELI keywords, act type and in-force status; each item is act metadata, with includeDetails adding keywords, references, issuing bodies and inForce, and includeText adding extracted HTML/PDF text (no OCR, charged at a higher rate). Use it for bulk lists or monitoring of acts; to read one act or article interactively use polish-law-mcp-server. Read-only: it only queries the public source and never writes to the registry; onlyNew merely keeps a stateKey memory in your own Apify account. Each call needs the APIFY_TOKEN env var and starts one paid run of the Apify Actor enterprising_hamster/polish-legal-acts-eli on your Apify account, billed pay-per-event per delivered item plus any Apify platform usage; the server waits up to 300 s for the run and returns JSON {items, truncated} with at most maxItems (max 100) items and 256 KiB."
+  },
+  "polish-court-judgments-saos": {
+    "description": "Searches Polish court judgments in the official SAOS database (System Analizy Orzeczeń Sądowych) by court type, date range, SAOS query phrase, subject keywords and judgment type; each item has case numbers, judges and keywords, and includeFullText adds the published anonymised text (charged at a higher rate). Coverage is uneven: common courts are current, Supreme Court data ends in 2016-06, the Constitutional Tribunal in 2015-12 and KIO in 2018-09, and administrative courts return nothing. Use it for bulk lists or onlyNew feeds; to read one judgment interactively use polish-law-mcp-server. Read-only: it only queries the public source and never writes to the registry; onlyNew merely keeps a stateKey memory in your own Apify account. Each call needs the APIFY_TOKEN env var and starts one paid run of the Apify Actor enterprising_hamster/polish-court-judgments-saos on your Apify account, billed pay-per-event per delivered item plus any Apify platform usage; the server waits up to 300 s for the run and returns JSON {items, truncated} with at most maxItems (max 100) items and 256 KiB."
+  },
+  "polish-eu-funds-tenders-baza-konkurencyjnosci": {
+    "description": "Lists procurement notices (zapytania ofertowe) published by EU-grant beneficiaries on the official Baza Konkurencyjności portal (archive from 2014-01-01), filtered by publication date, status, search query, category, CPV, region, beneficiary name or NIP and submission deadline; includeDetails adds orders, conditions, evaluation criteria, estimated values and attachments (charged at a higher rate). Use it for Polish EU-funded procurement; for Czech, Slovak, Hungarian or Ukrainian tenders use cee-public-tenders. Read-only: it only queries the public source and never writes to the registry; onlyNew merely keeps a stateKey memory in your own Apify account. Each call needs the APIFY_TOKEN env var and starts one paid run of the Apify Actor enterprising_hamster/polish-eu-funds-tenders-baza-konkurencyjnosci on your Apify account, billed pay-per-event per delivered item plus any Apify platform usage; the server waits up to 300 s for the run and returns JSON {items, truncated} with at most maxItems (max 100) items and 256 KiB."
+  },
+  "cee-public-tenders": {
+    "description": "Lists public tenders from Czechia, Slovakia, Hungary and Ukraine in one normalised schema, collected from the official Prozorro, Slovak Vestník and TED sources: title, CPV codes, value, deadline and status, with includeDetails adding lots, places of performance, document links and an EU-funding flag (charged at a higher rate). Filter by country, lastDays, keywords, CPV prefixes and onlyOpen. It does not cover Poland; for Polish EU-funded procurement use polish-eu-funds-tenders-baza-konkurencyjnosci. Read-only: it only queries the public source and never writes to the registry; onlyNew merely keeps a stateKey memory in your own Apify account. Each call needs the APIFY_TOKEN env var and starts one paid run of the Apify Actor enterprising_hamster/cee-public-tenders on your Apify account, billed pay-per-event per delivered item plus any Apify platform usage; the server waits up to 300 s for the run and returns JSON {items, truncated} with at most maxItems (max 100) items and 256 KiB."
+  },
+  "polish-ev-charging-stations-eipa": {
+    "description": "Returns EV, CNG/LNG and hydrogen stations in Poland from the official EIPA register run by UDT: operator, address, GPS, power in kW and connectors, with includeLiveData adding live point status and ad-hoc prices; stations of possibly private operators are anonymised or skipped. Without eipaToken it uses a shared EIPA demo account limited to 10 static downloads an hour, so it may be refused when busy; pass your own free EIPA reader token for regular use. Use it for charging infrastructure; for vehicle fleet statistics use polish-vehicle-registrations-cepik. Read-only: it only queries the public source and never writes to the registry; onlyNew merely keeps a stateKey memory in your own Apify account. Each call needs the APIFY_TOKEN env var and starts one paid run of the Apify Actor enterprising_hamster/polish-ev-charging-stations-eipa on your Apify account, billed pay-per-event per delivered item plus any Apify platform usage; the server waits up to 300 s for the run and returns JSON {items, truncated} with at most maxItems (max 100) items and 256 KiB."
+  },
+  "polish-vehicle-registrations-cepik": {
+    "description": "Returns monthly vehicle registration counts from the official CEPiK open data API, grouped by brand, model, fuel, powertrain, origin, production year or county and filtered by vehicle type, fuel, origin, voivodeship and month range (at most 60 months per run); aggregates only, no VINs or owners. Defaults are electric passenger cars in Mazowieckie for the last complete month; all of Poland can take several minutes when CEPiK is busy. Use it for fleet and EV adoption statistics; for charging infrastructure use polish-ev-charging-stations-eipa. Read-only: it only queries the public source and never writes to the registry; onlyNew merely keeps a stateKey memory in your own Apify account. Each call needs the APIFY_TOKEN env var and starts one paid run of the Apify Actor enterprising_hamster/polish-vehicle-registrations-cepik on your Apify account, billed pay-per-event per delivered item plus any Apify platform usage; the server waits up to 300 s for the run and returns JSON {items, truncated} with at most maxItems (max 100) items and 256 KiB."
+  },
+  "polish-building-permits-gunb": {
+    "description": "Returns building permit decisions (pozwolenia na budowę) and construction notifications (zgłoszenia) from the official GUNB register (RWDZ), newest first: project name, Construction Law category, cubature, location and dates; investors are named only when they are organisations, never private persons. Defaults to permits in Mazowieckie; set voivodeships to ALL or pass TERYT codes for other areas. Use it for construction projects and leads; for parcel boundaries and zoning use polish-land-parcels-uldk-zoning. Read-only: it only queries the public source and never writes to the registry; onlyNew merely keeps a stateKey memory in your own Apify account. Each call needs the APIFY_TOKEN env var and starts one paid run of the Apify Actor enterprising_hamster/polish-building-permits-gunb on your Apify account, billed pay-per-event per delivered project (named organisation investors cost more) plus any Apify platform usage; the server waits up to 300 s for the run and returns JSON {items, truncated} with at most maxItems (max 100) items and 256 KiB."
+  },
+  "polish-land-parcels-uldk-zoning": {
+    "description": "Looks up Polish land parcels (działki) in the official GUGiK ULDK service by full parcel ID, precinct name plus number, or GPS point, returning location, area and an optional GeoJSON boundary; includeZoning adds local zoning plans (MPZP) and general plan zones (POG) with building limits from Rejestr Urbanistyczny (charged at a higher rate). No owner data; with no input it looks up three example parcels. Use it for one parcel's geometry and zoning; for building permits use polish-building-permits-gunb. Read-only: it only queries the public source and never writes to the registry; onlyNew merely keeps a stateKey memory in your own Apify account. Each call needs the APIFY_TOKEN env var and starts one paid run of the Apify Actor enterprising_hamster/polish-land-parcels-uldk-zoning on your Apify account, billed pay-per-event per delivered item plus any Apify platform usage; the server waits up to 300 s for the run and returns JSON {items, truncated} with at most maxItems (max 100) items and 256 KiB."
+  },
+  "polish-healthcare-facilities-rpwdl": {
+    "description": "Returns Polish healthcare facilities from the official RPWDL register (Rejestr Podmiotów Wykonujących Działalność Leczniczą): address, phone, organisation e-mail, website, NIP/REGON, specialties and beds. Filter by voivodeship, TERYT code, city, facility kind, ownership, specialty code or keyword, name, NIP, available contacts and minimum beds; the whole register is about 24,000 facilities. Use it for hospital and clinic lookups or lead lists; no sibling tool covers healthcare. Read-only: it only queries the public source and never writes to the registry; onlyNew merely keeps a stateKey memory in your own Apify account. Each call needs the APIFY_TOKEN env var and starts one paid run of the Apify Actor enterprising_hamster/polish-healthcare-facilities-rpwdl on your Apify account, billed pay-per-event per delivered item plus any Apify platform usage; the server waits up to 300 s for the run and returns JSON {items, truncated} with at most maxItems (max 100) items and 256 KiB."
+  },
+  "polish-developer-apartment-prices": {
+    "description": "Returns new-build apartment and house offers from the developer price lists published on dane.gov.pl under the price transparency rules (jawność cen): one record per unit with price, price per m² and location, or, in priceChanges mode, only the differences from the developer's previous list. Filter by publication window (lastDays, or a date range of at most 14 days), voivodeship, city, developer, property type and availability. Use it for primary-market housing prices from developers; no sibling tool covers real estate. Read-only: it only queries the public source and never writes to the registry; onlyNew merely keeps a stateKey memory in your own Apify account. Each call needs the APIFY_TOKEN env var and starts one paid run of the Apify Actor enterprising_hamster/polish-developer-apartment-prices on your Apify account, billed pay-per-event per delivered record (price changes cost more) plus any Apify platform usage; the server waits up to 300 s for the run and returns JSON {items, truncated} with at most maxItems (max 100) items and 256 KiB."
+  },
+  "polish-electricity-market-pse": {
+    "description": "Returns Polish electricity market and grid data from the official PSE API (Polskie Sieci Elektroenergetyczne): RCE market price, day-ahead and imbalance prices, Kompas Energetyczny, load and generation mix, as 15-minute, hourly or daily rows. Filter by business-date range (history from 2024-06-14) or lastDays; next-day data appears once PSE publishes it, about 14:00 Europe/Warsaw. Use it for energy prices and grid statistics; no sibling tool covers electricity. Read-only: it only queries the public source and never writes to the registry; onlyNew merely keeps a stateKey memory in your own Apify account. Each call needs the APIFY_TOKEN env var and starts one paid run of the Apify Actor enterprising_hamster/polish-electricity-market-pse on your Apify account, billed pay-per-event per delivered data row plus any Apify platform usage; the server waits up to 300 s for the run and returns JSON {items, truncated} with at most maxItems (max 100) items and 256 KiB."
+  },
+  "polish-new-companies-krs": {
+    "description": "Returns new and changed Polish companies from the official KRS register of entrepreneurs (Krajowy Rejestr Sądowy, rejestr przedsiębiorców) via the Ministry of Justice KRS API: for each KRS number on the daily bulletin in the date window (empty dates mean yesterday, at most 31 days) one item with name, KRS, NIP, REGON, legal form, seat address, main and other PKD codes, share capital, registration and last-entry dates and eventType new or changed. Filter by events, PKD code prefixes, voivodeships, legal forms and minimum share capital; company-level fields only, no personal data such as board members or shareholders. Use it for new-company lead lists, KYC and CRM monitoring; for healthcare providers use polish-healthcare-facilities-rpwdl. Read-only: it only queries the public source and never writes to the registry. Each call needs the APIFY_TOKEN env var and starts one paid run of the Apify Actor enterprising_hamster/polish-new-companies-krs on your Apify account, billed pay-per-event per delivered company plus any Apify platform usage; the server waits up to 300 s for the run and returns JSON {items, truncated} with at most maxItems (max 100) items and 256 KiB."
+  }
+}

package/dist/server.js

@@ -4,6 +4,8 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 const CATALOG_URL = new URL("../catalog/actors.json", import.meta.url);
+const DESCRIPTIONS_URL = new URL("../catalog/tool-descriptions.json", import.meta.url);
+const PACKAGE_URL = new URL("../package.json", import.meta.url);
 const TOKEN_URL = "https://console.apify.com/settings/integrations";
 const MISSING_TOKEN = `Missing APIFY_TOKEN. Create a token at ${TOKEN_URL} and set APIFY_TOKEN.`;
 const DEFAULT_MAX_ITEMS = 20;
@@ -11,19 +13,26 @@ const ITEM_CEILING = 100;
 const RESPONSE_BYTE_CAP = 256 * 1024;
 const SYNC_TIMEOUT_SECS = 300;
 const FETCH_ABORT_MS = 320_000;
-const SERVER_VERSION = "0.1.0";
 const LAW_INSTRUCTIONS = "One tool runs the law actor. Set tool to an enum value and pass arguments. maxItems caps returned dataset rows.";
 const REGISTERS_INSTRUCTIONS = "Each tool runs one actor with that actor's input. maxItems caps dataset rows.";
+// Every tool proxies a public read of an official register through an Apify Actor run.
+const TOOL_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
 export async function serve(profile) {
-    const tools = selectProfile(loadCatalog(CATALOG_URL), profile);
+    const tools = selectProfile(loadCatalog(CATALOG_URL, DESCRIPTIONS_URL), profile);
     const label = serverLabel(profile);
-    const server = new Server({ name: label.name, version: SERVER_VERSION }, { capabilities: { tools: {} }, instructions: label.instructions });
+    const server = new Server({ name: label.name, version: readVersion(PACKAGE_URL) }, { capabilities: { tools: {} }, instructions: label.instructions });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: tools.map((tool) => ({
             name: tool.name,
             title: tool.title,
             description: tool.description,
             inputSchema: tool.inputSchema,
+            annotations: { title: tool.title, ...TOOL_ANNOTATIONS },
         })),
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -46,7 +55,38 @@ function serverLabel(profile) {
         }
     }
 }
-function loadCatalog(url) {
+function readVersion(url) {
+    const parsed = JSON.parse(readFileSync(fileURLToPath(url), "utf8"));
+    if (!isObject(parsed)) {
+        throw new Error("package.json must be a JSON object.");
+    }
+    return requiredString(parsed.version, "version");
+}
+function loadToolTexts(url) {
+    const parsed = JSON.parse(readFileSync(fileURLToPath(url), "utf8"));
+    if (!isObject(parsed)) {
+        throw new Error("Tool descriptions must be a JSON object keyed by tool name.");
+    }
+    const texts = new Map();
+    for (const [name, entry] of Object.entries(parsed)) {
+        if (!isObject(entry)) {
+            throw new Error(`Tool description for ${name} must be an object.`);
+        }
+        const parameters = {};
+        if (entry.parameters !== undefined) {
+            if (!isObject(entry.parameters)) {
+                throw new Error(`Tool ${name} parameters must be an object.`);
+            }
+            for (const [key, text] of Object.entries(entry.parameters)) {
+                parameters[key] = requiredString(text, `${name}.parameters.${key}`);
+            }
+        }
+        texts.set(name, { description: requiredString(entry.description, `${name}.description`), parameters });
+    }
+    return texts;
+}
+function loadCatalog(url, descriptionsUrl) {
+    const texts = loadToolTexts(descriptionsUrl);
     const parsed = JSON.parse(readFileSync(fileURLToPath(url), "utf8"));
     if (!Array.isArray(parsed)) {
         throw new Error("Actor catalog must be a JSON array.");
@@ -57,7 +97,7 @@ function loadCatalog(url) {
         if (!isObject(row) || row.isPublic !== true) {
             continue;
         }
-        const tool = bindTool(row);
+        const tool = bindTool(row, texts);
         if (names.has(tool.name)) {
             throw new Error(`Duplicate actor name ${tool.name}.`);
         }
@@ -66,7 +106,7 @@ function loadCatalog(url) {
     }
     return tools;
 }
-function bindTool(row) {
+function bindTool(row, texts) {
     const name = requiredString(row.name, "name");
     const actorId = requiredString(row.actorId, "actorId");
     const slash = actorId.indexOf("/");
@@ -74,15 +114,34 @@ function bindTool(row) {
         throw new Error(`Actor id ${actorId} must look like owner/name.`);
     }
     const title = requiredString(row.title, "title");
-    const description = requiredString(row.description, "description");
+    const text = texts.get(name);
+    if (text === undefined) {
+        throw new Error(`Tool ${name} has no entry in catalog/tool-descriptions.json.`);
+    }
+    const description = text.description;
     const buildNumber = requiredString(row.buildNumber, "buildNumber");
     if (!isObject(row.inputSchema) || row.inputSchema.type !== "object") {
         throw new Error(`Actor ${name} inputSchema must be a JSON object schema.`);
     }
     const router = isLawRouter(row.inputSchema);
-    const { inputSchema, cap } = listSchema(row.inputSchema);
+    const { inputSchema, cap } = listSchema(describeParameters(name, row.inputSchema, text.parameters));
     return { name, title, description, inputSchema, actorId, buildNumber, router, cap };
 }
+function describeParameters(name, schema, texts) {
+    const properties = schema.properties;
+    if (!isObject(properties)) {
+        throw new Error(`Actor ${name} inputSchema.properties must be an object.`);
+    }
+    const described = { ...properties };
+    for (const [key, description] of Object.entries(texts)) {
+        const property = properties[key];
+        if (!isObject(property)) {
+            throw new Error(`Tool ${name} describes unknown parameter ${key}.`);
+        }
+        described[key] = { ...property, description };
+    }
+    return { ...schema, properties: described };
+}
 function isLawRouter(schema) {
     if (!isObject(schema.properties)) {
         return false;
@@ -118,7 +177,7 @@ function listSchema(schema) {
                 maxItems: {
                     type: "integer",
                     title: "Maximum items",
-                    description: "Maximum dataset items returned to the client.",
+                    description: "Maximum dataset items returned to the client (1-100), applied by this server to the run's dataset.",
                     default: cap.fallback,
                     minimum: cap.min,
                     maximum: cap.max,

package/dist/stdio.test.js

@@ -7,6 +7,8 @@ import { fileURLToPath } from "node:url";
 const TOKEN_URL = "https://console.apify.com/settings/integrations";
 const LAW_TOOL = "polish-law-mcp-server";
 const root = fileURLToPath(new URL("..", import.meta.url));
+const descriptions = JSON.parse(readFileSync(new URL("../catalog/tool-descriptions.json", import.meta.url), "utf8"));
+const packageVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const catalog = JSON.parse(readFileSync(new URL("../catalog/actors.json", import.meta.url), "utf8"))
     .filter((row) => row.isPublic);
 function childEnv(token) {
@@ -56,11 +58,22 @@ function schemaOf(tool) {
 test("tools/list works without a token", async () => {
     await withClient("dist/main.js", childEnv(), async (client) => {
         assert.equal(client.getServerVersion()?.name, "polish-mcp");
+        assert.equal(client.getServerVersion()?.version, packageVersion);
         const listed = await client.listTools();
         assert.deepEqual(listed.tools.map((tool) => tool.name), catalog.map((row) => row.name));
         for (const tool of listed.tools) {
             const row = catalog.find((entry) => entry.name === tool.name);
             assert.ok(row);
+            const text = descriptions[tool.name];
+            assert.ok(text, `${tool.name} has a description entry`);
+            assert.equal(tool.description, text.description);
+            for (const phrase of ["Read-only", "APIFY_TOKEN", "paid run", "300 s"]) {
+                assert.equal(tool.description?.includes(phrase), true, `${tool.name} description mentions ${phrase}`);
+            }
+            assert.equal(tool.annotations?.readOnlyHint, true);
+            assert.equal(tool.annotations?.destructiveHint, false);
+            assert.equal(tool.annotations?.idempotentHint, true);
+            assert.equal(tool.annotations?.openWorldHint, true);
             const listedProperties = schemaOf(tool).properties ?? {};
             const catalogProperties = row.inputSchema.properties ?? {};
             assert.equal(listedProperties.maxItems !== undefined, true);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "polish-mcp-servers",
-  "version": "0.1.0",
-  "description": "MCP stdio server for Polish public law and registers. Lists 12 Apify Actor tools without a token and runs them with APIFY_TOKEN.",
+  "version": "0.1.2",
+  "description": "MCP stdio server for Polish public law and registers. Lists 13 Apify Actor tools without a token and runs them with APIFY_TOKEN.",
   "license": "MIT",
   "author": "Kamil Kaczmarek",
   "homepage": "https://github.com/kamilkaczmareksolutions/polish-mcp-servers#readme",
@@ -21,17 +21,18 @@
     "open-data",
     "eli",
     "saos",
-    "cepik"
+    "cepik",
+    "krs"
   ],
   "type": "module",
   "engines": {
     "node": ">=20"
   },
   "bin": {
-    "polish-mcp-servers": "./dist/main.js",
-    "polish-mcp": "./dist/main.js",
-    "polish-law-mcp": "./dist/law.js",
-    "polish-public-registers": "./dist/registers.js"
+    "polish-mcp-servers": "dist/main.js",
+    "polish-mcp": "dist/main.js",
+    "polish-law-mcp": "dist/law.js",
+    "polish-public-registers": "dist/registers.js"
   },
   "files": [
     "dist",