getregdata-mcp 1.1.0 → 1.2.0

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

@@ -6,7 +6,7 @@ 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": {

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.
@@ -70,7 +138,7 @@ async function describeActor(slug) {
 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.0",
   "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",