getregdata-mcp 1.1.0 → 1.2.1

package/README.md

@@ -13,11 +13,27 @@ every beneficial owner, returned as a single verdict. The per-registry tools are
 depth behind that answer, and the way to run the same jobs elsewhere.
 
 Each registry is exposed as its own tool (e.g. `regdata_crbr_beneficial_owners`,
-`regdata_germany_handelsregister`, `regdata_adverse_media`), plus two helpers:
+`regdata_germany_handelsregister`, `regdata_adverse_media`), plus three helpers:
 
 - `regdata_catalog` - list every registry tool and what it returns.
 - `regdata_describe` - fetch a specific actor's live input schema so the agent
   builds a correct call.
+- `regdata_run_result` - collect a check that was still running when its tool call
+  returned.
+
+## Long checks return a handle, not a failure
+
+Most calls return dataset items directly. If a run is still going after ~45 seconds,
+the tool returns `{status, runId, datasetId, note}` instead. That run is still going
+and is **already billed**, so call `regdata_run_result` with the `runId` to collect it -
+re-running the check to "retry" charges the user twice.
+
+This matters most for the Poland KYB composite: 20-30 seconds typically, up to ~2.5
+minutes for a company with many beneficial owners. Set `"timeout": 600000` on the
+server in your MCP config so the common case still returns inline.
+
+Treat a `runId` as a secret: Apify resolves run and dataset IDs without checking
+ownership, so anyone holding the ID can read that check's result.
 
 ## Setup
 
@@ -34,7 +50,8 @@ Add to your MCP config (`claude_desktop_config.json`, or `.mcp.json` for Claude
     "getregdata": {
       "command": "npx",
       "args": ["-y", "getregdata-mcp"],
-      "env": { "APIFY_TOKEN": "apify_api_xxxxx" }
+      "env": { "APIFY_TOKEN": "apify_api_xxxxx" },
+      "timeout": 600000
     }
   }
 }

package/actors.js

@@ -1,12 +1,12 @@
 // Auto-generated from the live Apify fleet (deployed builds). 35 regdata actors.
 // Regenerate with: APIFY_TOKEN=... node scripts/gen-manifest.mjs
-// Generated 2026-07-23. Do not edit inputSchema by hand.
+// Generated 2026-10-27. Do not edit inputSchema by hand.
 export const ACTORS = [
   {
     "slug": "poland-kyb-check",
     "tool": "regdata_poland_kyb_check",
     "title": "Poland KYB Risk Check - one call, one verdict",
-    "description": "Run a COMPLETE Polish KYB check from a single NIP or KRS - start here for Poland instead of chaining the individual registry tools. Resolves official company identity, pulls beneficial owners from the national UBO register, and screens the national debtor register for insolvency, restructuring and enforcement proceedings against the company AND every beneficial owner by exact identifier. Returns one normalized verdict - clear, findings, not_found or partial - plus machine-readable risk flags and the underlying registry entries (case signature, classification, court, dates, source). A \"partial\" verdict means a source could not be reached, not that the company is clean, and is not billed. Poland only; use the per-registry tools for other jurisdictions or for deeper single-source detail.",
+    "description": "Run a COMPLETE Polish KYB check from a single NIP or KRS - start here for Poland instead of chaining the individual registry tools. Resolves official company identity, pulls beneficial owners from the national UBO register, and screens the national debtor register for insolvency, restructuring and enforcement proceedings against the company AND every beneficial owner by exact identifier. Returns one normalized verdict - clear, findings, not_found or partial - plus machine-readable risk flags and the underlying registry entries (case signature, classification, court, dates, source). A \"partial\" verdict means a source could not be reached, not that the company is clean, and is not billed. Poland only; use the per-registry tools for other jurisdictions or for deeper single-source detail. TIMING: this check typically takes 20-30 seconds, but scales with the number of beneficial owners and has been measured up to ~2.5 minutes. If it has not finished in time, the tool returns {status, runId, note} instead of results - the check is running and already billed, so call regdata_run_result with that runId to collect it. Never re-run the check to 'retry': that bills twice.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -15,6 +15,12 @@ export const ACTORS = [
           "title": "Company identifiers (NIP or KRS)",
           "description": "The Polish companies to check, by NIP (10 digits) or KRS (10 digits, leading zeros). Each identifier returns one complete KYB check: identity, beneficial owners, and insolvency proceedings against the company and every beneficial owner."
         },
+        "includeManagement": {
+          "type": "boolean",
+          "title": "Include management board (KRS)",
+          "description": "Also read the current KRS extract and return the sitting management board (or representing partners), representation rule, prokurenci (proxies), supervisory board, shareholders/partners and share capital. Companies without a KRS number are reported as not applicable. The board is billed by the board-members actor it runs, on top of the check.",
+          "default": false
+        },
         "krzConcurrency": {
           "type": "integer",
           "title": "Beneficial-owner screening concurrency",
@@ -158,12 +164,12 @@ export const ACTORS = [
         "dateFrom": {
           "type": "string",
           "title": "Published Since (Date From)",
-          "description": "Only return publications from this date onward (YYYY-MM-DD). Default: 30 days ago. | Nur Veroffentlichungen ab diesem Datum (JJJJ-MM-TT)."
+          "description": "Only return edicts published on or after this date (YYYY-MM-DD). Setting it is strongly recommended: it is the only filter the register applies server-side, so it is what keeps a browse-style run short, and it removes the need for the GmbH fallback query - without it a run with no searchQuery returns ONLY debtors whose name contains 'GmbH'. | Nur Veroeffentlichungen ab diesem Datum."
         },
         "dateTo": {
           "type": "string",
           "title": "Published Until (Date To)",
-          "description": "Only return publications up to this date (YYYY-MM-DD). Default: today. | Nur Veroffentlichungen bis zu diesem Datum (JJJJ-MM-TT)."
+          "description": "Only return edicts published up to this date (YYYY-MM-DD). Applied per edict, not by the register, so a narrow window costs one page fetch per candidate. | Nur Veroeffentlichungen bis zu diesem Datum."
         },
         "entryType": {
           "type": "string",
@@ -179,7 +185,7 @@ export const ACTORS = [
         "maxResults": {
           "type": "integer",
           "title": "Max Results",
-          "description": "Maximum number of results to return. Default: 100. Set to 0 for unlimited. | Maximale Anzahl der Ergebnisse.",
+          "description": "Maximum number of matching records to return. Default: 100. Set to 0 for unlimited. This caps matches, not work: dateTo and proceedingType are checked per edict, so reaching the cap can require many more page fetches than the cap itself. | Maximale Anzahl der Ergebnisse.",
           "default": 100
         }
       },
@@ -350,6 +356,17 @@ export const ACTORS = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "mode": {
+          "type": "string",
+          "title": "What to do",
+          "description": "<b>Search</b> looks up the names or entity numbers you list below. <b>New filings</b> delivers every newly approved California entity since the last run - schedule it daily and each run picks up where the previous one stopped. <b>Add addresses</b> takes the results of an earlier run and completes each record with its principal address, mailing address and the registered agent's address.",
+          "enum": [
+            "search",
+            "newFilings",
+            "addresses"
+          ],
+          "default": "search"
+        },
         "searchQueries": {
           "type": "array",
           "title": "Search queries",
@@ -360,12 +377,60 @@ export const ACTORS = [
           "title": "Max results per query",
           "description": "Maximum number of entities to keep per query (default 50 to avoid surprise charges on broad searches). Set 0 for no limit (all matches, typically up to ~500 per search).",
           "default": 50
+        },
+        "startEntityNumber": {
+          "type": "string",
+          "title": "Start from entity number",
+          "description": "New filings only, first run only: the California entity number to start from, e.g. <code>B20260403469</code>. Later runs continue automatically from the saved position."
+        },
+        "maxNumbersPerRun": {
+          "type": "integer",
+          "title": "Entity numbers to check per run",
+          "description": "Upper bound on how many entity numbers one run checks. California issues roughly 1,500-2,000 per business day; a daily schedule at the default keeps up, and whatever is not reached is picked up next run.",
+          "default": 2500
+        },
+        "includeNameReservations": {
+          "type": "boolean",
+          "title": "Include name reservations",
+          "description": "Name reservations share the number sequence but are not formed businesses. Off by default: they are skipped and not billed.",
+          "default": false
+        },
+        "restartFromStartNumber": {
+          "type": "boolean",
+          "title": "Restart from the start number",
+          "description": "Discard the saved position and start again from \"Start from entity number\". Use it to re-run a range; every record in it is delivered (and billed) again.",
+          "default": false
+        },
+        "stateStoreName": {
+          "type": "string",
+          "title": "Progress store name",
+          "description": "Name of the key-value store in your Apify account that keeps the scan position between runs. Use a different name to run several independent feeds.",
+          "default": "california-new-filings"
+        },
+        "stopAfterConsecutiveMisses": {
+          "type": "integer",
+          "title": "Stop after consecutive unanswered numbers",
+          "description": "How many consecutive entity numbers with no approved filing yet mark the end of what the registry has processed so far. Leave at the default unless a run stops too early.",
+          "default": 300
+        },
+        "reserveForNewNumbers": {
+          "type": "integer",
+          "title": "Look-ups reserved for new entity numbers",
+          "description": "Every run re-checks numbers that had no record yet before it moves on to new ones. This reserves part of the run's budget for new numbers so the scan always moves forward, even when the re-check queue is long. Leave at the default unless a run reports a growing backlog.",
+          "default": 1800
+        },
+        "sourceDatasetId": {
+          "type": "string",
+          "title": "Results to complete (dataset ID)",
+          "description": "The dataset ID of an earlier run of this actor. Every record in it is looked up once and returned with <code>principalAddress</code>, <code>mailingAddress</code>, <code>agentType</code>, <code>agentName</code> and <code>agentAddress</code> added. Commercial registered agents have no address of their own on the entity's record, so <code>agentAddress</code> is empty for those."
+        },
+        "sourceRunId": {
+          "type": "string",
+          "title": "...or the run ID",
+          "description": "Alternative to the dataset ID: the ID of the earlier run whose results should be completed."
         }
       },
-      "additionalProperties": true,
-      "required": [
-        "searchQueries"
-      ]
+      "additionalProperties": true
     }
   },
   {
@@ -512,7 +577,7 @@ export const ACTORS = [
         "kwNumbers": {
           "type": "array",
           "title": "KW Numbers",
-          "description": "List of KW numbers to look up. Format: 'CODE/NUMBER/DIGIT' (e.g., 'WR1K/00094598/3'). The check digit (last part) is optional - it will be auto-calculated if omitted. You can also provide just 'CODE/NUMBER'. Note: users on the Apify Free plan get a preview allowance of 25 KW numbers per 30 days; upgrade to any paid Apify plan to run unlimited batches."
+          "description": "List of KW numbers to look up. Format: 'CODE/NUMBER/DIGIT' (e.g., 'WA4M/00160286/2'). The check digit (last part) is optional - it will be auto-calculated if omitted. You can also provide just 'CODE/NUMBER'. Note: users on the Apify Free plan get a preview allowance of 25 KW numbers per 30 days; upgrade to any paid Apify plan to run unlimited batches."
         },
         "viewType": {
           "type": "string",
@@ -546,8 +611,8 @@ export const ACTORS = [
         "maxConcurrency": {
           "type": "integer",
           "title": "Max parallel lookups",
-          "description": "How many KW numbers to process in parallel (1-5). Higher = faster batches. Default 5.",
-          "default": 5
+          "description": "How many KW numbers to process in parallel. Default 4; values above 4 are accepted but run at 4, so one access slot always stays free for other runs.",
+          "default": 4
         }
       },
       "additionalProperties": true,
@@ -567,7 +632,7 @@ export const ACTORS = [
         "searchQuery": {
           "type": "string",
           "title": "Company name / keyword",
-          "description": "Company name or keyword(s) to search for (Schlagwörter). E.g. \"Zalando SE\" or \"BioNTech\"."
+          "description": "Company name or keyword(s) to search for (Schlagwörter). E.g. \"Zalando SE\" or \"BioNTech\". The register accepts at most 5 keywords - send the company name only, not a website title or description. Legal forms (GmbH, AG, KG, e.V., ...), \"und\", \"mit\" and repeated words do not count; \"der\", \"für\", \"von\" do. Single letters and legal forms alone are ignored: \"K&F\" searches for nothing - add a word from the name (\"K & F Kältetechnik\") or write the letters together (\"KF\")."
         },
         "exactMatch": {
           "type": "boolean",
@@ -578,13 +643,24 @@ export const ACTORS = [
         "registerNumber": {
           "type": "string",
           "title": "Register number (optional)",
-          "description": "Optional commercial register number to narrow the search, e.g. \"215511\" (HRB). Must be combined with a company name/keyword - the portal does not allow number-only searches."
+          "description": "Optional register number to narrow the search. The number on its own (\"215511\") or with its register type (\"HRB 6684\", \"HRB 215511 B\") - both work, and the type is selected for you. Must be combined with a company name/keyword: the portal does not allow number-only searches."
         },
         "maxResults": {
           "type": "integer",
           "title": "Max results",
           "description": "Maximum number of matching companies to return structured data for (from the first results page). 1-30.",
           "default": 10
+        },
+        "onlyNew": {
+          "type": "boolean",
+          "title": "Monitor mode - only new or changed companies",
+          "description": "For scheduled checks of the same company or search. The first run returns every company found and remembers it; every later run of the SAME search returns only companies that are new to it, or whose status, name, seat, share capital or officers changed - each with changeType, changedFields and previousValues. When the register cannot serve a company's structured document on a run, its capital and officers are not compared that time (they are never reported as changed on missing data). A run with nothing new succeeds with an empty dataset and a status message, and is billed like any run. The memory is kept in your own Apify account (a key-value store named regdata-handelsregister-monitor); delete it to start again.",
+          "default": false
+        },
+        "monitorKey": {
+          "type": "string",
+          "title": "Monitor name (optional)",
+          "description": "Just a label for your watchlist history, not a password or API key - it is shown masked. Optional name for this monitor's memory, e.g. 'supplier-acme'. Leave empty and the search itself is the name."
         }
       },
       "additionalProperties": true
@@ -606,7 +682,7 @@ export const ACTORS = [
         "watchlist": {
           "type": "array",
           "title": "Watchlist (bulk / monitoring)",
-          "description": "A list of company names or surnames to check in one run. Ideal for scheduled monitoring - run this Actor daily against your counterparties and get any new insolvency publications. Overrides the single \"name\" field when set."
+          "description": "A list of company names or surnames to check in one run (up to 100). Ideal for scheduled monitoring - run this Actor daily against your counterparties and get any new insolvency publications. Overrides the single \"name\" field when set. For more than 100 names, split them across several runs or scheduled tasks."
         },
         "firstName": {
           "type": "string",
@@ -680,7 +756,7 @@ export const ACTORS = [
         "maxResults": {
           "type": "integer",
           "title": "Max results",
-          "description": "Maximum publications to export across all queries in this run.",
+          "description": "Maximum publications to export across all queries in this run. Each publication returned is billed, so this also caps the per-publication cost.",
           "default": 200
         }
       },
@@ -872,12 +948,28 @@ export const ACTORS = [
         "dateFrom": {
           "type": "string",
           "title": "Date From",
-          "description": "Start date for announcement search (YYYY-MM-DD). Only used in announcements mode."
+          "description": "Start date for announcement search (YYYY-MM-DD). Only used in announcements mode. A date range of up to 366 days is returned in full, even when it holds more than 1000 announcements; the run says so if a single day exceeds what the register will return."
         },
         "dateTo": {
           "type": "string",
           "title": "Date To",
-          "description": "End date for announcement search (YYYY-MM-DD). Only used in announcements mode."
+          "description": "End date for announcement search (YYYY-MM-DD), inclusive. Only used in announcements mode. A malformed date, or a dateFrom after dateTo, stops the run before any search and nothing is charged."
+        },
+        "proceedingType": {
+          "type": "array",
+          "title": "Proceeding type filter (announcements)",
+          "description": "Optional, announcements mode only. Keep only announcements of these proceeding types; leave empty for all. 'appeal' = second-instance rulings on a bankruptcy or restructuring case (e.g. on an arrangement or a repayment plan) - choosing 'restructuring' alone does NOT include appeal rulings on restructuring cases, so add 'appeal' too if you need them. Left-out rows are not exported and not charged.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "proceedingKinds": {
+          "type": "array",
+          "title": "Proceeding kind filter (entity search)",
+          "description": "Optional, entity mode only. A company search returns one row per proceeding the register holds for it. Keep only these kinds; leave empty for all. Left-out rows are not exported and not charged.",
+          "items": {
+            "type": "string"
+          }
         },
         "maxResults": {
           "type": "integer",
@@ -885,6 +977,17 @@ export const ACTORS = [
           "description": "Maximum number of results to return. Default: 100. Set to 0 for unlimited.",
           "default": 100
         },
+        "onlyNew": {
+          "type": "boolean",
+          "title": "Monitor mode - only new or changed",
+          "description": "For scheduled checks of the same company or search. The first run returns everything and remembers it; every later run of the SAME search returns only proceedings that are new to it. Case-signature searches, where the register returns status and type, also report a status or type change (changeType, changedFields, previousValues); company-name searches carry no status, so they report new proceedings only. A run with nothing new succeeds with an empty dataset and a status message, and is billed like any search - 'nothing new' is the answer. The memory is kept in your own Apify account (a key-value store named regdata-krz-monitor); delete it to start again. Not available for proceedingDetails. Dates are not part of the memory, so a rolling announcements window keeps one history.",
+          "default": false
+        },
+        "monitorKey": {
+          "type": "string",
+          "title": "Monitor name (optional)",
+          "description": "Just a label for your watchlist history, not a password or API key - it is shown masked. Optional name for this monitor's memory, e.g. 'client-acme'. Leave empty and the search itself is the name. Use it to keep two separate histories of the same search."
+        },
         "disableSessionCache": {
           "type": "boolean",
           "title": "Disable session cache (advanced)",
@@ -931,12 +1034,12 @@ export const ACTORS = [
         "textInBody": {
           "type": "string",
           "title": "Text in Body",
-          "description": "Full-text search in announcement content (max 1000 chars). Use for finding specific terms like 'upadłość', 'likwidacja', etc."
+          "description": "Full-text search inside the announcement body (max 1000 chars). MATCHES LITERALLY, SO POLISH DIACRITICS ARE REQUIRED: \"upadłości\" returns hundreds of notices a month, \"upadlosci\" returns none. Case does not matter and phrases work. Try: upadłości, likwidacji, wierzycieli, syndyk, restrukturyzacji."
         },
         "textInPosition": {
           "type": "string",
           "title": "Text in Position",
-          "description": "Search in announcement header/position text (max 1000 chars)"
+          "description": "Search the announcement header line - the \"Poz. NNNNN. NAME. KRS ... COURT ...\" summary (max 1000 chars). Same literal matching as Text in Body, so Polish diacritics are required. Try: LIKWIDACJI, REJONOWY, GOSPODARCZY."
         },
         "signatureOfCase": {
           "type": "string",
@@ -945,13 +1048,13 @@ export const ACTORS = [
         },
         "dateFrom": {
           "type": "string",
-          "title": "Date From",
-          "description": "Publication date range start (YYYY-MM-DD). Required."
+          "title": "Published from",
+          "description": "Start of the publication date range. Required by the gazette - a search without both dates is rejected. Pick a date, or type a relative one such as \"3 months\"."
         },
         "dateTo": {
           "type": "string",
-          "title": "Date To",
-          "description": "Publication date range end (YYYY-MM-DD). Required."
+          "title": "Published to",
+          "description": "End of the publication date range. Required by the gazette - a search without both dates is rejected. Pick a date, or type a relative one such as \"1 week\"."
         },
         "fetchDetails": {
           "type": "boolean",
@@ -962,8 +1065,19 @@ export const ACTORS = [
         "maxResults": {
           "type": "integer",
           "title": "Max Results",
-          "description": "Maximum number of results to return. Default: 100. Set to 0 for unlimited.",
-          "default": 100
+          "description": "Maximum number of announcements to return. Set to 0 for every match. Starts at 10 so a first run is cheap to try - raise it once the search looks right.",
+          "default": 10
+        },
+        "onlyNew": {
+          "type": "boolean",
+          "title": "Monitor mode - only new notices",
+          "description": "For scheduled checks of the same company or search. The first run returns every matching notice and remembers it; every later run of the SAME search returns only notices published since, each with changeType 'new'. Gazette notices never change once published, so nothing is reported as changed. A run with nothing new succeeds with an empty dataset and a status message. Use a rolling window such as Published from '1 month' and Published to '0 days' - the dates are not part of the memory. Set Max results to 0 so the first run records every match. The memory is kept in your own Apify account (a key-value store named regdata-msig-monitor); delete it to start again.",
+          "default": false
+        },
+        "monitorKey": {
+          "type": "string",
+          "title": "Monitor name (optional)",
+          "description": "Just a label for your watchlist history, not a password or API key - it is shown masked. Optional name for this monitor's memory, e.g. 'client-acme'. Leave empty and the search itself is the name."
         }
       },
       "additionalProperties": true,
@@ -1002,6 +1116,17 @@ export const ACTORS = [
           "title": "Include raw statement file",
           "description": "Include the raw XML/XHTML (iXBRL) statement in the output. Files over 5 MB are linked via the key-value store (rawXmlUrl) instead of inlined.",
           "default": true
+        },
+        "onlyNew": {
+          "type": "boolean",
+          "title": "Monitor mode - only new statements",
+          "description": "For scheduled checks of the same company. The first run returns the latest filed statement and remembers it; every later run returns a row only when a NEWER statement has been filed (changeType 'new'). When nothing new has been filed, nothing is downloaded, the dataset stays empty and the status message says which statement is still the latest - you pay only the run start. The memory is kept in your own Apify account (a key-value store named regdata-krs-financial-monitor); delete it to start again.",
+          "default": false
+        },
+        "monitorKey": {
+          "type": "string",
+          "title": "Monitor name (optional)",
+          "description": "Just a label for your watchlist history, not a password or API key - it is shown masked. Optional name for this monitor's memory. Leave empty and the KRS / NIP number is the name."
         }
       },
       "additionalProperties": true
@@ -1052,7 +1177,7 @@ export const ACTORS = [
         "seedIdentifiers": {
           "type": "array",
           "title": "Seed identifiers (NIP / REGON / KRS)",
-          "description": "List of company identifiers to expand. Auto-detected by shape: 9 or 14 digits = REGON, 10 digits = NIP (override with Seed identifier type). The BIR registry has no geographic search, so you seed the companies to examine here (or via Seed dataset)."
+          "description": "List of company identifiers to expand. Auto-detected by shape: 9 or 14 digits = REGON, 10 digits = NIP (override with Seed identifier type). This actor expands companies you already know into their local units (jednostki lokalne) - it does not discover companies by area, so seed them here (or via Seed dataset)."
         },
         "seedDatasetId": {
           "type": "string",
@@ -1248,7 +1373,7 @@ export const ACTORS = [
         "minIntervalMs": {
           "type": "integer",
           "title": "Min interval between requests (ms)",
-          "description": "Politeness delay between requests. The site allows ~3/s; keep >= 350ms to avoid the conditional CAPTCHA.",
+          "description": "Delay between requests in milliseconds. Keep the default for reliable runs.",
           "default": 350
         }
       },
@@ -1395,8 +1520,8 @@ export const ACTORS = [
         },
         "province": {
           "type": "string",
-          "title": "Province",
-          "description": "Filter results by Spanish province. Matching is case- and accent-insensitive and understands the registry's dual-language names (searching 'Alava' matches 'ARABA/ALAVA'). Companies outside the province are discarded before extraction, so you are never charged for them. Example: 'Madrid', 'Barcelona', 'Valencia', 'Sevilla'"
+          "title": "Province or region",
+          "description": "Limit results to one Spanish province or one autonomous community (region). A province: its name in Spanish or the local language, common older spellings, or the INE code (1-52) - 'Madrid', 'Navarra', 'Bizkaia' or 'Vizcaya', 'A Coruña' or 'La Coruña', 'Illes Balears' or 'Baleares', '31'. A region: its Spanish, local or English name - 'Catalonia' or 'Cataluña', 'Andalucía', 'Basque Country' or 'Euskadi', 'Comunitat Valenciana', 'Galicia'. A region runs one search per province in it, one after another, and returns companies from all of them (pricing is unchanged: as listed in Pricing). A one-province region such as 'Comunidad de Madrid' is the same as that province. For A Coruña and Araba/Álava, combine the filter with a specific company name or activity code - on a very broad search the filter cannot be applied to those two provinces."
         },
         "maxResults": {
           "type": "integer",
@@ -1456,7 +1581,7 @@ export const ACTORS = [
         "maxResults": {
           "type": "integer",
           "title": "Max results",
-          "description": "Maximum party records to export across all queries. The register serves results in pages, and the Actor pages through until it reaches this limit or runs out of matches. Set to 0 to export every match.",
+          "description": "Maximum party records to export across all queries. The register serves results in pages, and the Actor pages through until it reaches this limit or runs out of matches. Set to 0 to export every match. The register returns debtor entries first, so a search truncated by maxResults can contain no disqualified-person or insolvency-administrator rows even when the full result set does. Raise maxResults (or set 0) for broad name searches.",
           "default": 100
         }
       },
@@ -1643,7 +1768,7 @@ export const ACTORS = [
         "searchType": {
           "type": "string",
           "title": "Search type",
-          "description": "How the company name is matched. 'Starts with' is the register's default and the most reliable. 'Sounds like' uses the register's own phonetic index, which is narrow - it will not behave like a general fuzzy search.",
+          "description": "How the company name is matched. The register matches WHOLE WORDS, not the start of a name: 'INVESTMENT' finds every name containing that word, but 'INVEST' finds only names with the word 'INVEST'. 'All these words' (default) needs every word you type; 'Any of these words' needs one of them; 'Sounds like' uses the register's phonetic index. A very common word on its own (INVESTMENT, HOLDINGS, SHIPPING) is refused by the register as too many matches - add a second distinctive word.",
           "enum": [
             "startsWith",
             "endsWith",
@@ -1683,7 +1808,7 @@ export const ACTORS = [
         "companyNames": {
           "type": "array",
           "title": "Company names",
-          "description": "One or more company names to search, each looked up separately (min 2 characters). Partial names work. A broad name can hit the register's 50-result ceiling.",
+          "description": "One or more company names to search, each looked up separately (min 2 characters). Partial names work: every word must appear in the company name, in any order (legal-form words such as 'Ltd' or 'DAC' are optional). Exact and starts-with matches come first, live companies before dissolved ones.",
           "items": {
             "type": "string"
           }
@@ -1691,7 +1816,7 @@ export const ACTORS = [
         "companyNumbers": {
           "type": "array",
           "title": "Company numbers",
-          "description": "One or more Irish CRO registration numbers, each looked up separately. Digits only, e.g. '104547'.",
+          "description": "One or more Irish CRO registration numbers, each looked up separately. Each must contain digits, e.g. '104547' (a prefix such as 'IE' is ignored). Company numbers only - limited partnership (LP...), reserved name (RN...), society (...R) and trade union (...T) numbers are skipped and not charged.",
           "items": {
             "type": "string"
           }
@@ -1699,13 +1824,13 @@ export const ACTORS = [
         "maxResultsPerQuery": {
           "type": "integer",
           "title": "Max results per query",
-          "description": "Maximum company records to export per query. The register returns at most 50 matches per search, so 50 is the ceiling. Fetching the full record for each match happens in the same run.",
+          "description": "Maximum company records to export per query (up to 50). When a name matches more companies, the run says so - narrow the name or search by number.",
           "default": 50
         },
         "statusFilter": {
           "type": "array",
           "title": "Status filter",
-          "description": "Keep only companies whose status contains one of these words, e.g. 'Normal', 'Dissolved', 'Liquidation'. Leave empty to export every match - a Dissolved or Liquidation counterparty is usually the finding you most want to see.",
+          "description": "Keep only companies whose status contains one of these words, e.g. 'Normal', 'Dissolved', 'Strike Off Listed', 'Liquidation'. Leave empty to export every match - a Dissolved or Liquidation counterparty is usually the finding you most want to see.",
           "default": [],
           "items": {
             "type": "string"

package/index.js

@@ -36,21 +36,89 @@ function requireToken() {
   return t;
 }
 
-// Run an actor synchronously and return its dataset items.
+// How long we hold a tool call open before handing back a run handle. Must stay
+// under the MCP client's default request timeout (60s) with margin: if the CLIENT
+// gives up first, the caller sees an error for a run that is still billing.
+const WAIT_SECS = 45;
+const TERMINAL = new Set(["SUCCEEDED", "FAILED", "ABORTED", "TIMED-OUT"]);
+
+// Retrying a pending check runs - and bills - a second time. This wording is
+// deliberately blunt: it is the only thing between a slow check and a double charge.
+const PENDING_NOTE =
+  "This check is STILL RUNNING and is already being billed. Do NOT retry it and do NOT call this tool again - " +
+  "call regdata_run_result with the runId above to collect the result. Retrying charges the user twice for the same check.";
+
+async function apiJson(url, init) {
+  const res = await fetch(url, init);
+  const text = await res.text();
+  if (!res.ok) throw new Error(`Apify API ${res.status}: ${text.slice(0, 300)}`);
+  return JSON.parse(text).data;
+}
+
+async function datasetItems(datasetId, maxItems) {
+  const url = new URL(`${APIFY_BASE}/datasets/${datasetId}/items`);
+  url.searchParams.set("token", requireToken());
+  if (maxItems) url.searchParams.set("limit", String(maxItems));
+  const res = await fetch(url);
+  const text = await res.text();
+  if (!res.ok) throw new Error(`Could not read dataset ${datasetId} (${res.status})`);
+  return text; // JSON array of dataset items
+}
+
+// Either the items, or a redeemable handle. Never a lost run.
+async function settle(run, label, maxItems) {
+  if (run.status === "SUCCEEDED") return await datasetItems(run.defaultDatasetId, maxItems);
+  if (TERMINAL.has(run.status)) {
+    throw new Error(
+      `regdata/${label} run ${run.id} ended as ${run.status}` +
+        (run.statusMessage ? `: ${run.statusMessage}` : "")
+    );
+  }
+  return JSON.stringify(
+    { status: run.status, runId: run.id, datasetId: run.defaultDatasetId, note: PENDING_NOTE },
+    null,
+    2
+  );
+}
+
+// Start the actor and wait briefly.
+//
+// Started ASYNC on purpose. This previously used run-sync-get-dataset-items, which
+// holds one connection open until the run ends. Per Apify's docs, "if the connection
+// breaks, you will not receive any information about the run and its output" and
+// "this won't abort the run itself" - so a client timeout destroyed the only handle
+// to a run that then completed and BILLED. Measured durations for the Poland KYB
+// composite were 21-148s against a 60s client default, so this was routine, not rare.
+// Starting async means the runId exists from the first response and a disconnect is
+// always recoverable.
 async function runActor(slug, input, { maxItems } = {}) {
-  const url = new URL(`${APIFY_BASE}/acts/regdata~${slug}/run-sync-get-dataset-items`);
+  const url = new URL(`${APIFY_BASE}/acts/regdata~${slug}/runs`);
   url.searchParams.set("token", requireToken());
+  url.searchParams.set("waitForFinish", String(WAIT_SECS)); // Apify caps this at 60
   if (maxItems) url.searchParams.set("maxItems", String(maxItems));
-  const res = await fetch(url, {
+  const run = await apiJson(url, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(input ?? {}),
   });
-  const text = await res.text();
-  if (!res.ok) {
-    throw new Error(`Apify run failed (${res.status}) for regdata/${slug}: ${text.slice(0, 400)}`);
-  }
-  return text; // JSON array of dataset items
+  return await settle(run, slug, maxItems);
+}
+
+// Collect a run that was still going when its tool call returned.
+//
+// NOTE on access: we send the caller's token, but Apify does NOT scope runs or
+// datasets to it - verified 2026-07-23, `GET /actor-runs/{id}` and
+// `/datasets/{id}/items` both return 200 with a foreign token AND with no token
+// at all, on a dataset whose isPublic is unset. The storage ID is itself the
+// capability. So this tool grants nothing a runId holder could not already fetch
+// straight from the public API; it is convenience, not an access boundary.
+// Treat a runId as a secret and do not log or forward it.
+async function collectRun(runId, { waitSecs, maxItems } = {}) {
+  const url = new URL(`${APIFY_BASE}/actor-runs/${runId}`);
+  url.searchParams.set("token", requireToken());
+  url.searchParams.set("waitForFinish", String(Math.max(0, Math.min(waitSecs ?? WAIT_SECS, 60))));
+  const run = await apiJson(url);
+  return await settle(run, run.actId ?? "run", maxItems);
 }
 
 // Fetch an actor's live input schema so the model can construct correct input.
@@ -63,14 +131,14 @@ async function describeActor(slug) {
   const schema =
     data?.defaultRunOptions?.inputSchema ||
     data?.exampleRunInput ||
-    "See https://apify.com/regdata/" + slug + " for the input schema.";
+    "See https://apify.com/regdata/" + slug + "?fpr=getregdata for the input schema.";
   return { slug, title: data?.title, description: data?.description, schema };
 }
 
 const bySlug = Object.fromEntries(ACTORS.map((a) => [a.slug, a]));
 const byTool = Object.fromEntries(ACTORS.map((a) => [a.tool, a]));
 
-// One tool per actor + two helpers (catalog, describe).
+// One tool per actor + three helpers (catalog, run_result, describe).
 const MAX_ITEMS_PROP = {
   type: "integer",
   description: "Optional cap on billed dataset items returned.",
@@ -110,6 +178,30 @@ function buildToolList() {
         `Use this catalog to find the right single-registry tool for other jurisdictions, or when you need one specific source in depth.`,
       inputSchema: { type: "object", properties: {}, additionalProperties: false },
     },
+    {
+      name: "regdata_run_result",
+      description:
+        "Collect the result of a regdata check that was still running when its tool call returned. " +
+        "When any regdata tool returns {status, runId, note} instead of results, the check is running and already billed - " +
+        "call THIS tool with that runId rather than re-running the check, which would charge the user twice. " +
+        "Returns the dataset items once the run finishes; if it is still going, returns the same handle so you can call again.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          runId: {
+            type: "string",
+            description: "The runId returned by the pending tool call, e.g. NAMNqpPch7RFSY1oQ",
+          },
+          waitSecs: {
+            type: "integer",
+            description: "Seconds to wait for the run to finish before returning (0-60, default 45).",
+          },
+          maxItems: MAX_ITEMS_PROP,
+        },
+        required: ["runId"],
+        additionalProperties: false,
+      },
+    },
     {
       name: "regdata_describe",
       description:
@@ -143,6 +235,11 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       const list = ACTORS.map((a) => ({ tool: a.tool, slug: a.slug, title: a.title }));
       return { content: [{ type: "text", text: JSON.stringify(list, null, 2) }] };
     }
+    if (name === "regdata_run_result") {
+      if (!args.runId) throw new Error("runId is required - it is returned by the pending tool call.");
+      const out = await collectRun(args.runId, { waitSecs: args.waitSecs, maxItems: args.maxItems });
+      return { content: [{ type: "text", text: out }] };
+    }
     if (name === "regdata_describe") {
       const slug = args.slug || byTool[args.tool]?.slug;
       if (!slug || !bySlug[slug]) throw new Error(`Unknown actor: ${args.slug || args.tool}`);
@@ -164,4 +261,4 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error(`getregdata MCP server ready - ${ACTORS.length} registry tools + catalog/describe.`);
+console.error(`getregdata MCP server ready - ${ACTORS.length} registry tools + catalog/run_result/describe.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getregdata-mcp",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "mcpName": "io.github.Nolpak14/getregdata",
   "description": "MCP server for official business-registry data - KYC/AML, beneficial owners, credit-risk, adverse media. One-call Poland KYB verdict, plus per-registry tools for Germany, Italy, Spain, Austria, France, Belgium, Czechia, Slovakia, Cyprus, Ireland, Portugal, Nigeria, Colombia, the US (California) and the UAE.",
   "type": "module",