@leadbay/mcp 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog — @leadbay/mcp
 
+## 0.4.0 — 2026-05-04
+
+### `leadbay_import_leads` 0.2.0 — custom field mapping
+
+The MCP tool now drives the same CRM-import wizard the web UI exposes — pass arbitrary CSV-shaped records and tell Leadbay which column maps to which `StandardCrmFieldType`.
+
+**Two modes** (pass exactly one of `domains` / `records`):
+
+- **Mode A (existing, unchanged):** `domains: [{domain, name?}]` — synthesizes a 2-column CSV (LEAD_NAME, LEAD_WEBSITE) and uses the default mapping. Output shape is identical to 0.1.x: `{ leads: [{domain, leadId, name}], not_imported: [{domain, reason}], ... }`.
+- **Mode B (new):** `records: [{Col1, Col2, ...}]` plus `mappings: { fields: { Col1: "LEAD_NAME", Col2: "LEAD_WEBSITE", Col3: "LEAD_SECTOR", ... } }`. The tool synthesizes a CSV from the union of record keys (sorted, deterministic) and POSTs the caller-supplied mapping to `/imports/{id}/update_mappings`. Output shape: `{ leads: [{rowId, domain?, leadId, name}], not_imported: [{rowId, domain?, reason}], ... }`. `rowId` round-trips your input row order; `domain` populated only when `LEAD_WEBSITE` was mapped and the value parsed.
+
+Mappings.fields must include `LEAD_NAME` or `LEAD_WEBSITE` — the wizard's resolver needs at least one of those to find a lead. Other CRM fields (`LEAD_SECTOR`, `LEAD_LOCATION`, `LEAD_SIZE`, `EMAIL`, `CRM_ID`, `LEADBAY_ID`, `DEAL_CRM_ID`, `CONTACT_TITLE`, `LEAD_STATUS`, `LEAD_STATUS_DATE`) are passed through verbatim.
+
+**Validation (records mode):** new typed error codes — `IMPORT_INPUT_CONFLICT` (both modes supplied), `IMPORT_MAPPING_REQUIRED` (no mappings.fields), `IMPORT_MAPPING_NO_RESOLVER` (no LEAD_NAME or LEAD_WEBSITE in mapping), `IMPORT_MAPPING_KEY_UNKNOWN` (mapping key absent from records), `IMPORT_RESERVED_COLUMN` (record or mapping key matches `MCP_ROW_ID` case-insensitively), `IMPORT_INVALID_COLUMN_NAME` (column name >128 chars or contains control chars), `IMPORT_INVALID_CELL_TYPE` (cell value is array/object — coerce to string before passing). null/undefined cells coerce to "", numbers/booleans coerce via `String(v)`.
+
+**Security:** user-supplied column names now flow through the same `escapeCsvCell` (RFC 4180 quoting + formula-injection prefix) that data values use. Header injection vectors (`=`, `+`, `-`, `@`, `,`, `"`, newline) are neutered.
+
+**Backward compat:** Mode A output shape unchanged — the new `rowId` field is records-mode only. Existing `domains: [...]` callers see no diff.
+
 ## 0.3.0 — 2026-04-29
 
 Behavior-changing release: closes [product#3504](https://github.com/leadbay/product/issues/3504) end-to-end. Default-installed MCP server now matches its own system prompt out of the box, the `login` command never lands a bearer token in scrollback by default, and `claude mcp add` registers Leadbay at user scope so it's visible from any project.

package/dist/bin.js

@@ -8,7 +8,7 @@ import {
   granularReadTools,
   granularWriteTools,
   resolveRegion
-} from "./chunk-NED7ATJI.js";
+} from "./chunk-O2UOXRZO.js";
 
 // src/bin.ts
 import { realpathSync } from "fs";
@@ -158,7 +158,7 @@ function buildServer(client, opts = {}) {
 
 // src/bin.ts
 import { createRequire } from "module";
-var VERSION = "0.3.0";
+var VERSION = "0.4.0";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -447,7 +447,7 @@ async function runLogin(args) {
   let result;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-YMZYFHZK.js");
+      const { REGIONS } = await import("./dist-RONMQBYU.js");
       const baseUrl = REGIONS[pinnedRegion];
       const c = createClient({ region: pinnedRegion });
       const token = await loginAt(baseUrl, email, password);
@@ -939,7 +939,7 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
   let region;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-YMZYFHZK.js");
+      const { REGIONS } = await import("./dist-RONMQBYU.js");
       const baseUrl = REGIONS[pinnedRegion];
       token = await loginAt(baseUrl, email, password);
       region = pinnedRegion;

package/dist/{chunk-NED7ATJI.js → chunk-O2UOXRZO.js}

@@ -2286,6 +2286,8 @@ var POLL_INTERVAL_MS = 2e3;
 var DEFAULT_PER_PHASE_BUDGET_MS = 6e4;
 var DEFAULT_TOTAL_BUDGET_MS2 = 3e5;
 var STABILIZATION_POLLS = 2;
+var MAX_COLUMN_NAME_LEN = 128;
+var RESERVED_COLUMN_RE = /^mcp_row_id$/i;
 var PUBLIC_MAILBOX_DOMAINS = /* @__PURE__ */ new Set([
   "gmail.com",
   "googlemail.com",
@@ -2357,12 +2359,10 @@ function escapeCsvCell(raw) {
   }
   return s;
 }
-function synthesizeCsv(rows) {
-  const lines = ["MCP_ROW_ID,LEAD_NAME,LEAD_WEBSITE"];
-  for (const r of rows) {
-    lines.push([escapeCsvCell(r.rowId), escapeCsvCell(r.name), escapeCsvCell(r.website)].join(","));
-  }
-  return lines.join("\n") + "\n";
+function synthesizeCsv(header, rows) {
+  const headerLine = header.map(escapeCsvCell).join(",");
+  const dataLines = rows.map((r) => header.map((col) => escapeCsvCell(r[col] ?? "")).join(","));
+  return [headerLine, ...dataLines].join("\n") + "\n";
 }
 function chunkAt100(items) {
   if (items.length === 0)
@@ -2430,27 +2430,144 @@ function readCell(record, key) {
   }
   return null;
 }
-function buildInputLookup(inputs) {
+function validateColumnName(client, name, path) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw client.makeError("IMPORT_INVALID_COLUMN_NAME", `Column name at ${path} must be a non-empty string`, `Use a plain string column name (1-${MAX_COLUMN_NAME_LEN} chars).`, "POST /imports");
+  }
+  if (name.length > MAX_COLUMN_NAME_LEN) {
+    throw client.makeError("IMPORT_INVALID_COLUMN_NAME", `Column name at ${path} exceeds ${MAX_COLUMN_NAME_LEN} chars`, `Shorten the column name to ${MAX_COLUMN_NAME_LEN} chars or fewer.`, "POST /imports");
+  }
+  if (/[\x00-\x1F\x7F]/.test(name)) {
+    throw client.makeError("IMPORT_INVALID_COLUMN_NAME", `Column name at ${path} contains control characters`, `Strip control characters (e.g. \\n, \\t, \\x00) from column names.`, "POST /imports");
+  }
+}
+function coerceCell(client, v, path) {
+  if (v == null)
+    return "";
+  if (typeof v === "string")
+    return v;
+  if (typeof v === "number" || typeof v === "boolean")
+    return String(v);
+  throw client.makeError("IMPORT_INVALID_CELL_TYPE", `Cell at ${path} is ${Array.isArray(v) ? "an array" : typeof v}, expected string|number|boolean|null`, `Convert the value to a string before passing.`, "POST /imports");
+}
+function prepareDomainsMode(client, inputs) {
   const validInputs = [];
-  const malformed = [];
+  const malformedDomains = [];
   const byDomain = /* @__PURE__ */ new Map();
   const byRowId = /* @__PURE__ */ new Map();
-  inputs.forEach((inp, i) => {
-    void i;
-    const norm = normalizeDomain(inp.domain ?? "");
+  for (const inp of inputs) {
+    const norm = normalizeDomain(inp?.domain ?? "");
     if (!norm) {
-      malformed.push(inp.domain ?? "");
-      return;
+      malformedDomains.push(inp?.domain ?? "");
+      continue;
     }
     if (byDomain.has(norm))
-      return;
+      continue;
     const rowId = randomUUID();
     const idx = validInputs.length;
-    validInputs.push({ index: idx, rowId, domain: norm, name: inp.name?.trim() || norm });
+    const name = inp.name?.trim() || norm;
+    validInputs.push({
+      index: idx,
+      rowId,
+      row: { MCP_ROW_ID: rowId, LEAD_NAME: name, LEAD_WEBSITE: norm },
+      domain: norm,
+      outputDomain: norm
+    });
     byDomain.set(norm, idx);
     byRowId.set(rowId, idx);
+  }
+  return {
+    mode: "domains",
+    validInputs,
+    malformedDomains,
+    byDomain,
+    byRowId,
+    header: ["MCP_ROW_ID", "LEAD_NAME", "LEAD_WEBSITE"],
+    mappings: {
+      fields: { LEAD_NAME: "LEAD_NAME", LEAD_WEBSITE: "LEAD_WEBSITE" },
+      statuses: {},
+      default_status: null
+    }
+  };
+}
+function prepareRecordsMode(client, records, mappings) {
+  if (!mappings || !mappings.fields || typeof mappings.fields !== "object") {
+    throw client.makeError("IMPORT_MAPPING_REQUIRED", "records[] requires a mappings.fields object", "Pass `mappings: { fields: { CsvColumn: 'LEAD_NAME', ... } }`.", "POST /imports");
+  }
+  const fieldEntries = Object.entries(mappings.fields);
+  if (fieldEntries.length === 0) {
+    throw client.makeError("IMPORT_MAPPING_REQUIRED", "mappings.fields must contain at least one column \u2192 CRM field entry", "Map at least one CSV column to LEAD_NAME or LEAD_WEBSITE.", "POST /imports");
+  }
+  const targets = new Set(fieldEntries.map(([, v]) => v));
+  if (!targets.has("LEAD_NAME") && !targets.has("LEAD_WEBSITE")) {
+    throw client.makeError("IMPORT_MAPPING_NO_RESOLVER", "mappings.fields must include LEAD_NAME or LEAD_WEBSITE", "The wizard needs at least one of those fields to match a lead. Map a CSV column to one of them.", "POST /imports");
+  }
+  for (const [colName] of fieldEntries) {
+    validateColumnName(client, colName, `mappings.fields[${JSON.stringify(colName)}]`);
+    if (RESERVED_COLUMN_RE.test(colName)) {
+      throw client.makeError("IMPORT_RESERVED_COLUMN", `mappings.fields key '${colName}' collides with reserved synthetic column MCP_ROW_ID`, `Rename the column. MCP_ROW_ID (any case) is reserved for tool-internal reconciliation.`, "POST /imports");
+    }
+  }
+  const headerSet = /* @__PURE__ */ new Set();
+  const coercedRecords = [];
+  records.forEach((rec, i) => {
+    if (rec == null || typeof rec !== "object" || Array.isArray(rec)) {
+      throw client.makeError("IMPORT_INVALID_CELL_TYPE", `records[${i}] must be a plain object`, `Pass each record as { ColumnName: value, ... }.`, "POST /imports");
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(rec)) {
+      validateColumnName(client, k, `records[${i}] key`);
+      if (RESERVED_COLUMN_RE.test(k)) {
+        throw client.makeError("IMPORT_RESERVED_COLUMN", `records[${i}] key '${k}' collides with reserved synthetic column MCP_ROW_ID`, `Rename the column in your records (any case variant of MCP_ROW_ID is reserved).`, "POST /imports");
+      }
+      out[k] = coerceCell(client, v, `records[${i}].${k}`);
+      headerSet.add(k);
+    }
+    coercedRecords.push(out);
   });
-  return { validInputs, malformed, byDomain, byRowId };
+  for (const [colName] of fieldEntries) {
+    if (!headerSet.has(colName)) {
+      throw client.makeError("IMPORT_MAPPING_KEY_UNKNOWN", `mappings.fields key '${colName}' is not present in any record`, `Add a value for '${colName}' to at least one record, or remove it from mappings.`, "POST /imports");
+    }
+  }
+  const userKeys = [...headerSet].sort();
+  const header = ["MCP_ROW_ID", ...userKeys];
+  const websiteCol = fieldEntries.find(([, v]) => v === "LEAD_WEBSITE")?.[0];
+  const validInputs = [];
+  const byDomain = /* @__PURE__ */ new Map();
+  const byRowId = /* @__PURE__ */ new Map();
+  coercedRecords.forEach((row) => {
+    const rowId = randomUUID();
+    const idx = validInputs.length;
+    let normDomain = null;
+    if (websiteCol) {
+      normDomain = normalizeDomain(row[websiteCol] ?? "");
+    }
+    const fullRow = { MCP_ROW_ID: rowId, ...row };
+    validInputs.push({
+      index: idx,
+      rowId,
+      row: fullRow,
+      domain: normDomain,
+      outputDomain: normDomain ?? void 0
+    });
+    byRowId.set(rowId, idx);
+    if (normDomain && !byDomain.has(normDomain))
+      byDomain.set(normDomain, idx);
+  });
+  return {
+    mode: "records",
+    validInputs,
+    malformedDomains: [],
+    byDomain,
+    byRowId,
+    header,
+    mappings: {
+      fields: { ...mappings.fields },
+      statuses: mappings.statuses ?? {},
+      default_status: mappings.default_status ?? null
+    }
+  };
 }
 async function pollUntil(fn, done, budgetMs, signal, ctx, label) {
   const deadline = Date.now() + budgetMs;
@@ -2538,13 +2655,13 @@ async function pollRecordsToTerminal(client, importId, budgetMs, expectedRowCoun
     }
     if (Date.now() >= deadline) {
       ctx?.logger?.warn?.(`import-leads: records did not stabilize (transient=${transient}, total=${total}); returning best-effort`);
-      throw client.makeError("IMPORT_NOT_TERMINAL", `Backend hasn't fully settled records within ${budgetMs}ms`, `Retry leadbay_import_leads with the same domains in 30s, or split the batch. importId=${importId}.`, `GET /imports/${importId}/records`);
+      throw client.makeError("IMPORT_NOT_TERMINAL", `Backend hasn't fully settled records within ${budgetMs}ms`, `Retry leadbay_import_leads with the same input in 30s, or split the batch. importId=${importId}.`, `GET /imports/${importId}/records`);
     }
     await sleepWithAbort(POLL_INTERVAL_MS, signal);
   }
 }
-async function runOneChunk(client, chunk, chunkIdx, totalChunks, dryRun, perPhaseBudgetMs, totalDeadline, ctx, signal, onImportId) {
-  const csv = synthesizeCsv(chunk.map((c) => ({ rowId: c.rowId, name: c.name, website: c.domain })));
+async function runOneChunk(client, chunk, chunkIdx, totalChunks, header, mappings, dryRun, perPhaseBudgetMs, totalDeadline, ctx, signal, onImportId) {
+  const csv = synthesizeCsv(header, chunk.map((c) => c.row));
   const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
   const fileName = `mcp-import-${ts}-${chunkIdx}.csv`;
   ctx?.logger?.info?.(`import-leads: uploading chunk ${chunkIdx + 1}/${totalChunks} (${chunk.length} rows, ${csv.length}B)`);
@@ -2557,11 +2674,6 @@ async function runOneChunk(client, chunk, chunkIdx, totalChunks, dryRun, perPhas
   if (dryRun) {
     return { importId, records: [] };
   }
-  const mappings = {
-    fields: { LEAD_NAME: "LEAD_NAME", LEAD_WEBSITE: "LEAD_WEBSITE" },
-    statuses: {},
-    default_status: null
-  };
   await client.requestVoid("POST", `/imports/${importId}/update_mappings`, mappings);
   ctx?.logger?.info?.(`import-leads: mappings committed for importId=${importId}`);
   const phaseBudget2 = Math.min(perPhaseBudgetMs, Math.max(1, totalDeadline - Date.now()));
@@ -2572,7 +2684,7 @@ async function runOneChunk(client, chunk, chunkIdx, totalChunks, dryRun, perPhas
   ctx?.logger?.info?.(`import-leads: ${records.length} records terminal for importId=${importId}`);
   return { importId, records };
 }
-function reconcileOneChunk(chunk, byRowIdGlobal, byDomainGlobal, validInputsGlobal, matched, notImported) {
+function reconcileOneChunk(prep, chunk, matched, notImported) {
   const seenInputIndex = /* @__PURE__ */ new Set();
   const sortedRecords = [...chunk.records].sort((a, b) => {
     const aHasLead = a.lead?.id ? 0 : 1;
@@ -2582,61 +2694,61 @@ function reconcileOneChunk(chunk, byRowIdGlobal, byDomainGlobal, validInputsGlob
   for (const rec of sortedRecords) {
     let inputIdx;
     const rowIdCell = readCell(rec, "MCP_ROW_ID");
-    if (rowIdCell && byRowIdGlobal.has(rowIdCell)) {
-      inputIdx = byRowIdGlobal.get(rowIdCell);
+    if (rowIdCell && prep.byRowId.has(rowIdCell)) {
+      inputIdx = prep.byRowId.get(rowIdCell);
     }
     if (inputIdx === void 0) {
       const websiteCell = readCell(rec, "LEAD_WEBSITE");
       if (websiteCell) {
         const norm = normalizeDomain(websiteCell);
-        if (norm && byDomainGlobal.has(norm)) {
-          inputIdx = byDomainGlobal.get(norm);
+        if (norm && prep.byDomain.has(norm)) {
+          inputIdx = prep.byDomain.get(norm);
         }
       }
     }
     if (inputIdx === void 0 && rec.lead?.website) {
       const norm = normalizeDomain(rec.lead.website);
-      if (norm && byDomainGlobal.has(norm)) {
-        inputIdx = byDomainGlobal.get(norm);
+      if (norm && prep.byDomain.has(norm)) {
+        inputIdx = prep.byDomain.get(norm);
       }
     }
     if (inputIdx === void 0)
       continue;
     if (seenInputIndex.has(inputIdx)) {
       if (!matched.has(inputIdx) && !notImported.has(inputIdx)) {
-        const inp2 = validInputsGlobal[inputIdx];
-        notImported.set(inputIdx, { domain: inp2.domain, reason: "ambiguous" });
+        const inp2 = prep.validInputs[inputIdx];
+        notImported.set(inputIdx, { domain: inp2.outputDomain, reason: "ambiguous" });
       }
       continue;
     }
     seenInputIndex.add(inputIdx);
-    const inp = validInputsGlobal[inputIdx];
+    const inp = prep.validInputs[inputIdx];
     const matchType = (rec.match_type ?? rec.matchType ?? "").toString();
     if (rec.lead?.id) {
       matched.set(inputIdx, {
-        domain: inp.domain,
+        domain: inp.outputDomain,
         leadId: rec.lead.id,
         name: rec.lead.name ?? null
       });
     } else if (matchType === "NO_MATCH") {
-      const reason = PUBLIC_MAILBOX_DOMAINS.has(inp.domain) ? "no_match" : "uncrawled";
-      notImported.set(inputIdx, { domain: inp.domain, reason });
+      const reason = inp.domain && PUBLIC_MAILBOX_DOMAINS.has(inp.domain) ? "no_match" : "uncrawled";
+      notImported.set(inputIdx, { domain: inp.outputDomain, reason });
     } else {
-      notImported.set(inputIdx, { domain: inp.domain, reason: "internal_error" });
+      notImported.set(inputIdx, { domain: inp.outputDomain, reason: "internal_error" });
     }
   }
 }
 var importLeads = {
   name: "leadbay_import_leads",
-  description: "Import a list of company domains and get back stable Leadbay leadIds for downstream chaining into leadbay_bulk_qualify_leads / leadbay_research_lead.\n\n\u26A0\uFE0F MUTATES USER STATE. This tool wraps Leadbay's CRM-import wizard. Each call:\n  - creates a row in the user's CRM-imports list (visible in the web UI)\n  - touches onboarding state (startFileless, onboarding step \u2192 PROCESSING)\nSuitable for occasional automation. NOT suitable for high-cadence (>5 calls/day) \u2014 wait for the backend programmatic endpoint (issue: leadbay/backend prolonged-import-with-crawl).\n\nReturns: leads = leadIds for domains Leadbay already knows about (via crawler). not_imported = domains Leadbay doesn't know yet, with a reason. The tool does NOT create new leads for unknown domains; the caller decides what to do.\n\nWhen to use: you have a list of domains from another system (CRM, analytics, email correspondents) and need to map them to Leadbay leadIds.\nWhen NOT to use: for prospect discovery (use leadbay_pull_leads); for one specific company's profile (use leadbay_research_company); when you can't tolerate the side effects above.\n\nRequires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role on the Leadbay account; active billing.",
+  description: "Import leads into Leadbay's CRM via the file-import wizard. Returns stable Leadbay leadIds for downstream chaining into leadbay_bulk_qualify_leads / leadbay_research_lead.\n\nTWO MODES:\n  A) Domain-list shortcut \u2014 pass `domains: [{domain, name?}]`. The tool builds a 2-column CSV (LEAD_NAME, LEAD_WEBSITE) and imports with the default mapping. Output: { leads: [{domain, leadId, name}], not_imported: [{domain, reason}], importIds, _meta }.\n  B) Custom records + mapping \u2014 pass `records: [{Col1, Col2, ...}]` plus `mappings.fields: {Col1: 'LEAD_NAME', Col2: 'LEAD_WEBSITE', ...}`. The tool synthesizes a CSV from the union of record keys (deterministic order) and POSTs the caller-supplied mapping to the wizard. mappings.fields must include LEAD_NAME or LEAD_WEBSITE (the resolver needs at least one). Output: { leads: [{rowId, domain?, leadId, name}], not_imported: [{rowId, domain?, reason}], importIds, _meta }. `rowId` round-trips your input order.\n\nPass exactly one of `domains` / `records`. Reserved column MCP_ROW_ID (any case) cannot appear in records or mappings \u2014 the tool injects it for stable reconciliation.\n\n\u26A0\uFE0F MUTATES USER STATE. Each call:\n  - creates a row in the user's CRM-imports list (visible in the web UI)\n  - touches onboarding state (startFileless, onboarding step \u2192 PROCESSING)\nSuitable for occasional automation. NOT suitable for high-cadence (>5 calls/day) \u2014 wait for the backend programmatic endpoint (issue: leadbay/backend prolonged-import-with-crawl).\n\nWhen to use: you have a list of company domains from another system (CRM, analytics, email correspondents) and need stable Leadbay leadIds; or you have CRM-shaped rows with custom columns (sector, location, status, etc.) and want to drive the wizard with explicit field mappings.\nWhen NOT to use: for prospect discovery (use leadbay_pull_leads); for one specific company's profile (use leadbay_research_company); when you can't tolerate the side effects above.\n\nRequires: LEADBAY_MCP_WRITE=1 (MCP) or exposeWrite=true (OpenClaw); admin role on the Leadbay account; active billing.",
   write: true,
-  version: "0.1.0",
+  version: "0.2.0",
   inputSchema: {
     type: "object",
     properties: {
       domains: {
         type: "array",
-        description: "List of company domains to map to Leadbay leadIds.",
+        description: "Mode A: list of company domains to map to Leadbay leadIds. Mutually exclusive with `records`.",
         items: {
           type: "object",
           properties: {
@@ -2652,9 +2764,33 @@ var importLeads = {
           required: ["domain"]
         }
       },
+      records: {
+        type: "array",
+        description: "Mode B: arbitrary CSV-shaped rows. Each record is an object whose keys are column names and values are scalar (string/number/boolean/null). Mutually exclusive with `domains`. Must be accompanied by `mappings.fields`. The tool synthesizes a CSV from the union of all record keys.",
+        items: { type: "object" }
+      },
+      mappings: {
+        type: "object",
+        description: "Mode B: how each CSV column maps to Leadbay's CRM field schema. Required when `records` is supplied; ignored otherwise.",
+        properties: {
+          fields: {
+            type: "object",
+            description: "Object whose keys are CSV column names (matching keys in `records`) and whose values are Leadbay CRM field types (LEAD_NAME, LEAD_WEBSITE, LEAD_STATUS, LEAD_LOCATION, LEAD_SECTOR, LEAD_SIZE, CRM_ID, LEADBAY_ID, EMAIL, DEAL_CRM_ID, CONTACT_TITLE, LEAD_STATUS_DATE). At least one entry must target LEAD_NAME or LEAD_WEBSITE \u2014 the wizard needs that to find leads."
+          },
+          statuses: {
+            type: "object",
+            description: "Optional status string mapping (rarely needed). Defaults to {}."
+          },
+          default_status: {
+            type: ["string", "null"],
+            description: "Optional default status. Defaults to null."
+          }
+        },
+        required: ["fields"]
+      },
       dry_run: {
         type: "boolean",
-        description: "If true, run preprocess only \u2014 do NOT commit lead-CRM linking. Note: an import row still appears in the user's CRM-imports list as 'incomplete'. Use to verify domain format / wizard reachability without polluting the CRM."
+        description: "If true, run preprocess only \u2014 do NOT commit lead-CRM linking. Note: an import row still appears in the user's CRM-imports list as 'incomplete'. Use to verify input format / wizard reachability without polluting the CRM."
       },
       per_phase_budget_ms: {
         type: "number",
@@ -2664,8 +2800,9 @@ var importLeads = {
         type: "number",
         description: `Overall cap across all phases (default ${DEFAULT_TOTAL_BUDGET_MS2}ms).`
       }
-    },
-    required: ["domains"]
+    }
+    // Neither field is "required" at the schema level; xor + presence is
+    // enforced in execute() so we can produce specific error codes.
   },
   execute: async (client, params, ctx) => {
     const signal = ctx?.signal;
@@ -2673,16 +2810,21 @@ var importLeads = {
     const perPhaseBudget = params.per_phase_budget_ms ?? DEFAULT_PER_PHASE_BUDGET_MS;
     const totalBudget = params.total_budget_ms ?? DEFAULT_TOTAL_BUDGET_MS2;
     const totalDeadline = Date.now() + totalBudget;
-    if (!Array.isArray(params.domains) || params.domains.length === 0) {
-      throw client.makeError("IMPORT_EMPTY_INPUT", "domains[] must contain at least one entry", "Pass at least one domain in domains[].", "POST /imports");
+    const hasDomains = Array.isArray(params.domains) && params.domains.length > 0;
+    const hasRecords = Array.isArray(params.records) && params.records.length > 0;
+    if (hasDomains && hasRecords) {
+      throw client.makeError("IMPORT_INPUT_CONFLICT", "Pass exactly one of `domains` or `records`, not both", "Use `domains` for the simple shortcut, or `records`+`mappings` for arbitrary CSV input.", "POST /imports");
+    }
+    if (!hasDomains && !hasRecords) {
+      throw client.makeError("IMPORT_EMPTY_INPUT", "domains[] or records[] must contain at least one entry", "Pass at least one entry. See the tool description for the two input modes.", "POST /imports");
     }
     const me = await client.resolveMe();
     if (!me.admin) {
       throw client.makeError("IMPORT_ADMIN_REQUIRED", "This tool requires admin role on the Leadbay account", "Ask the account owner to grant import permission, or use a token from an admin user.", "POST /imports");
     }
-    const lookup = buildInputLookup(params.domains);
-    if (lookup.validInputs.length === 0) {
-      const not_imported2 = lookup.malformed.map((d) => ({
+    const prep = hasDomains ? prepareDomainsMode(client, params.domains) : prepareRecordsMode(client, params.records, params.mappings);
+    if (prep.validInputs.length === 0) {
+      const not_imported2 = prep.malformedDomains.map((d) => ({
         domain: d,
         reason: "malformed"
       }));
@@ -2700,8 +2842,8 @@ var importLeads = {
         }
       };
     }
-    const chunks = chunkAt100(lookup.validInputs);
-    ctx?.logger?.info?.(`import-leads: ${lookup.validInputs.length} domains \u2192 ${chunks.length} chunk(s); dry_run=${dryRun}, totalBudgetMs=${totalBudget}`);
+    const chunks = chunkAt100(prep.validInputs);
+    ctx?.logger?.info?.(`import-leads(${prep.mode}): ${prep.validInputs.length} rows \u2192 ${chunks.length} chunk(s); dry_run=${dryRun}, totalBudgetMs=${totalBudget}`);
     const importIds = [];
     const matched = /* @__PURE__ */ new Map();
     const notImported = /* @__PURE__ */ new Map();
@@ -2713,13 +2855,9 @@ var importLeads = {
     try {
       for (let i = 0; i < chunks.length; i++) {
         const chunk = chunks[i];
-        const out = await runOneChunk(client, chunk, i, chunks.length, dryRun, perPhaseBudget, totalDeadline, ctx, signal, recordImportId);
+        const out = await runOneChunk(client, chunk, i, chunks.length, prep.header, prep.mappings, dryRun, perPhaseBudget, totalDeadline, ctx, signal, recordImportId);
         if (!dryRun) {
-          reconcileOneChunk(out, lookup.byRowId, lookup.byDomain, lookup.validInputs, matched, notImported);
-        } else {
-          for (const c of chunk) {
-            notImported.set(c.index, { domain: c.domain, reason: "dry_run" });
-          }
+          reconcileOneChunk(prep, out, matched, notImported);
         }
       }
     } catch (err) {
@@ -2738,33 +2876,65 @@ var importLeads = {
         throw err;
       }
     }
-    for (const m of lookup.malformed) {
-      notImported.set(-1 - notImported.size, { domain: m, reason: "malformed" });
-    }
     const leads = [];
     const not_imported = [];
     if (dryRun) {
-      for (const inp of lookup.validInputs) {
-        not_imported.push({ domain: inp.domain, reason: "dry_run" });
+      for (const inp of prep.validInputs) {
+        if (prep.mode === "domains") {
+          not_imported.push({ domain: inp.outputDomain, reason: "dry_run" });
+        } else {
+          const entry = { rowId: inp.rowId, reason: "dry_run" };
+          if (inp.outputDomain)
+            entry.domain = inp.outputDomain;
+          not_imported.push(entry);
+        }
       }
     } else {
-      for (const inp of lookup.validInputs) {
+      for (const inp of prep.validInputs) {
         const m = matched.get(inp.index);
         if (m) {
-          leads.push(m);
+          if (prep.mode === "domains") {
+            leads.push({
+              domain: inp.outputDomain,
+              leadId: m.leadId,
+              name: m.name
+            });
+          } else {
+            const e = {
+              rowId: inp.rowId,
+              leadId: m.leadId,
+              name: m.name
+            };
+            if (m.domain ?? inp.outputDomain)
+              e.domain = m.domain ?? inp.outputDomain;
+            leads.push(e);
+          }
           continue;
         }
         const ni = notImported.get(inp.index);
         if (ni) {
-          not_imported.push(ni);
+          if (prep.mode === "domains") {
+            not_imported.push({ domain: inp.outputDomain, reason: ni.reason });
+          } else {
+            const e = { rowId: inp.rowId, reason: ni.reason };
+            if (ni.domain ?? inp.outputDomain)
+              e.domain = ni.domain ?? inp.outputDomain;
+            not_imported.push(e);
+          }
           continue;
         }
-        not_imported.push({ domain: inp.domain, reason: "internal_error" });
+        if (prep.mode === "domains") {
+          not_imported.push({ domain: inp.outputDomain, reason: "internal_error" });
+        } else {
+          const e = { rowId: inp.rowId, reason: "internal_error" };
+          if (inp.outputDomain)
+            e.domain = inp.outputDomain;
+          not_imported.push(e);
+        }
       }
     }
-    for (const [k, v] of notImported) {
-      if (k < 0)
-        not_imported.push(v);
+    for (const m of prep.malformedDomains) {
+      not_imported.push({ domain: m, reason: "malformed" });
     }
     return {
       leads,

package/dist/{dist-YMZYFHZK.js → dist-RONMQBYU.js}

@@ -71,7 +71,7 @@ import {
   tools,
   updateLens,
   updateLensFilter
-} from "./chunk-NED7ATJI.js";
+} from "./chunk-O2UOXRZO.js";
 export {
   InMemoryBulkStore,
   LeadbayClient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadbay/mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Model Context Protocol (MCP) server for Leadbay — AI lead discovery, qualification, and enrichment for Claude Desktop, Cursor, and Claude Code.",
   "type": "module",
   "bin": {