@mackody/quickenrich-mcp 0.1.0

package/scripts/mock-api-smoke.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+import { createServer } from "node:http";
+import {
+  callQuickEnrichTool,
+  createClient,
+} from "./lib/core.mjs";
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+const requests = [];
+
+const server = createServer(async (req, res) => {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const bodyText = Buffer.concat(chunks).toString("utf8");
+  const url = new URL(req.url, "http://127.0.0.1");
+  requests.push({
+    method: req.method,
+    path: url.pathname,
+    query: Object.fromEntries(url.searchParams.entries()),
+    auth: req.headers.authorization,
+    body: bodyText ? JSON.parse(bodyText) : null,
+  });
+
+  res.setHeader("content-type", "application/json");
+  res.setHeader("x-ratelimit-limit", "300");
+  res.setHeader("x-ratelimit-remaining", "299");
+
+  if (url.pathname === "/api/employees/dataset-search") {
+    res.end(JSON.stringify({
+      success: true,
+      data: [
+        {
+          first_name: "Ada",
+          last_name: "Lovelace",
+          title: "Founder",
+          employee_linkedin: "https://linkedin.com/in/ada",
+          has_email: true,
+          has_phone: false,
+          company_url: url.searchParams.get("company_url"),
+          company_name: "Example",
+          country_code: "US",
+        },
+      ],
+      meta: { page: Number(url.searchParams.get("page") || 1), per_page: 20, total: 1, last_page: 1 },
+    }));
+    return;
+  }
+
+  if (url.pathname === "/api/employees/search") {
+    res.end(JSON.stringify({
+      success: true,
+      data: {
+        first_name: "Ada",
+        last_name: "Lovelace",
+        title: "Founder",
+        email: "ada@example.com",
+        employee_phone: "(415) 555-0100",
+        employee_linkedin: "https://linkedin.com/in/ada",
+        company_url: url.searchParams.get("company_url"),
+      },
+    }));
+    return;
+  }
+
+  if (url.pathname === "/api/lookups/country-codes") {
+    res.end(JSON.stringify(["US", "GB"]));
+    return;
+  }
+
+  res.statusCode = 404;
+  res.end(JSON.stringify({ error: "not found" }));
+});
+
+await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+const { port } = server.address();
+
+try {
+  process.env.QUICKENRICH_API_KEY = "test-secret-key";
+  process.env.QUICKENRICH_API_BASE_URL = `http://127.0.0.1:${port}`;
+  const client = createClient();
+
+  const batch = await callQuickEnrichTool("quickenrich_batch_pull_leads", {
+    companies: [{ company_url: "example.com", title: "Founder" }],
+    has_email: true,
+    enrich_contacts: true,
+    max_enrichments: 1,
+    response: { mode: "full" },
+  }, client);
+
+  assert(batch.ok === true, "Batch should succeed.");
+  assert(batch.leadCount === 1, "Batch should return one lead.");
+  assert(batch.leads[0].email === "ada@example.com", "Batch enrichment should merge email.");
+  assert(batch.leads[0].phone === "+14155550100", "Batch enrichment should normalize phone from employee search.");
+
+  const lookup = await callQuickEnrichTool("quickenrich_lookup_values", { lookup: "country_codes" }, client);
+  assert(Array.isArray(lookup.data), "Lookup should return public lookup data.");
+
+  assert(requests.some((entry) => entry.path === "/api/employees/dataset-search"), "Domain search was not called.");
+  assert(requests.find((entry) => entry.path === "/api/employees/dataset-search").query.has_email === "true", "Domain search should forward has_email=true.");
+  assert(requests.some((entry) => entry.path === "/api/employees/search"), "Employee search was not called.");
+  assert(requests.filter((entry) => entry.path !== "/api/lookups/country-codes").every((entry) => entry.auth === "Bearer test-secret-key"), "Authenticated calls must use bearer auth.");
+  assert(requests.find((entry) => entry.path === "/api/lookups/country-codes").auth === undefined, "Lookup calls should not require auth.");
+  assert(!JSON.stringify(batch).includes("test-secret-key"), "Tool output leaked API key.");
+
+  console.log(JSON.stringify({ ok: true }, null, 2));
+} finally {
+  server.close();
+}

package/scripts/native-capabilities-smoke.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+
+import { createServer } from "node:http";
+import { TOOL_DEFINITIONS, callQuickEnrichTool, createClient, selectTools } from "./lib/core.mjs";
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+const requests = [];
+
+const server = createServer(async (req, res) => {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const bodyText = Buffer.concat(chunks).toString("utf8");
+  const body = bodyText ? JSON.parse(bodyText) : null;
+  const url = new URL(req.url, "http://127.0.0.1");
+  requests.push({ method: req.method, path: url.pathname, query: Object.fromEntries(url.searchParams.entries()), body });
+  res.setHeader("content-type", "application/json");
+
+  if (url.pathname === "/api/employees/email-search") {
+    const email = url.searchParams.get("email");
+    res.end(JSON.stringify({
+      success: true,
+      data: email?.startsWith("missing") ? [] : {
+        first_name: "Ada",
+        last_name: "Lovelace",
+        email,
+        title: "Founder",
+        company_url: "example.com",
+      },
+      meta: { credits_used: email?.startsWith("missing") ? 0 : 1, remaining_credits: 900 },
+    }));
+    return;
+  }
+
+  if (url.pathname === "/api/employees/search") {
+    res.end(JSON.stringify({
+      success: true,
+      data: {
+        first_name: url.searchParams.get("first_name") || "Ada",
+        last_name: url.searchParams.get("last_name") || "Lovelace",
+        title: "Founder",
+        email: `${String(url.searchParams.get("first_name") || "ada").toLowerCase()}@example.com`,
+        employee_linkedin: url.searchParams.get("linkedin_url") || "https://linkedin.com/in/ada",
+        company_url: url.searchParams.get("company_url") || "example.com",
+      },
+      meta: { credits_used: 1, remaining_credits: 899 },
+    }));
+    return;
+  }
+
+  if (url.pathname === "/api/employees/phone-search") {
+    res.end(JSON.stringify({
+      success: true,
+      data: {
+        first_name: "Ada",
+        last_name: "Lovelace",
+        employee_phone: "(415) 555-0100",
+        company_url: url.searchParams.get("company_url") || "example.com",
+      },
+      meta: { credits_used: 1, remaining_credits: 898 },
+    }));
+    return;
+  }
+
+  if (url.pathname === "/api/employees/dataset-search") {
+    const companyUrl = url.searchParams.get("company_url");
+    res.end(JSON.stringify({
+      success: true,
+      data: [{
+        first_name: "Csv",
+        last_name: "Lead",
+        title: url.searchParams.get("title") || "Founder",
+        email: `founder@${companyUrl}`,
+        employee_linkedin: `https://linkedin.com/in/${companyUrl}-founder`,
+        company_url: companyUrl,
+        company_name: companyUrl,
+        has_email: true,
+      }],
+      meta: { page: 1, per_page: 20, total: 1, last_page: 1, credits_used: 1, remaining_credits: 897 },
+    }));
+    return;
+  }
+
+  if (url.pathname === "/api/employees/contact-finder") {
+    const page = Number(body?.page || 1);
+    res.end(JSON.stringify({
+      success: true,
+      data: page === 1 ? [
+        {
+          first_name: "Jane",
+          last_name: "Doe",
+          title: "CEO",
+          employee_linkedin: "https://linkedin.com/in/jane",
+          has_email: true,
+          has_phone: true,
+          company_url: "acme.com",
+          company_name: "Acme",
+          country_code: "US",
+        },
+      ] : [
+        {
+          first_name: "John",
+          last_name: "Smith",
+          title: "CFO",
+          employee_linkedin: "https://linkedin.com/in/john",
+          has_email: true,
+          has_phone: false,
+          company_url: "acme.com",
+          company_name: "Acme",
+          country_code: "US",
+        },
+      ],
+      meta: { page, per_page: body?.per_page || 1, total: 2, last_page: 2, credits_used: 0, remaining_credits: 898 },
+    }));
+    return;
+  }
+
+  if (url.pathname === "/api/companies/company-finder") {
+    const page = Number(body?.page || 1);
+    res.end(JSON.stringify({
+      success: true,
+      data: [
+        {
+          company_name: page === 1 ? "Acme Cloud" : "Beta Cloud",
+          url: page === 1 ? "acme.com" : "beta.com",
+          email_domain: page === 1 ? "acme.com" : "beta.com",
+          final_email_domain: page === 1 ? "acme.com" : "beta.com",
+          phone: "+1-555-0100",
+          linkedin_url: page === 1 ? "https://linkedin.com/company/acme" : "https://linkedin.com/company/beta",
+          city: "Austin",
+          region_code: "TX",
+          country_code: "US",
+          industry: "Computer Software",
+          employee_count: "51-200",
+          revenue: "10M-50M",
+          services: ["DevOps", "AWS"],
+          service_count: 2,
+          home_page_text_snippet: "Cloud migration help",
+          bio_li_snippet: "Cloud solutions provider",
+        },
+      ],
+      meta: { page, per_page: body?.per_page || 1, total: 2, last_page: 2, credits_used: 1, remaining_credits: 897 },
+    }));
+    return;
+  }
+
+  res.statusCode = 404;
+  res.end(JSON.stringify({ error: "not found" }));
+});
+
+await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+const { port } = server.address();
+
+try {
+  process.env.QUICKENRICH_API_KEY = "native-test-key";
+  process.env.QUICKENRICH_API_BASE_URL = `http://127.0.0.1:${port}`;
+  const client = createClient();
+  const toolNames = TOOL_DEFINITIONS.map((tool) => tool.name);
+  const agentToolNames = selectTools(TOOL_DEFINITIONS, "agent").map((tool) => tool.name);
+  assert(toolNames.includes("quickenrich_batch_reverse_email"), "Missing native batch reverse-email tool.");
+  assert(toolNames.includes("quickenrich_batch_employee_search"), "Missing native batch employee-search tool.");
+  assert(agentToolNames.includes("quickenrich_batch_reverse_email"), "Agent surface should expose batch reverse-email.");
+  assert(agentToolNames.includes("quickenrich_lookup_values"), "Agent surface should expose lookup discovery.");
+
+  const reverse = await callQuickEnrichTool("quickenrich_batch_reverse_email", {
+    input_csv: "email\nada@example.com\nmissing@example.com\nada@example.com\n",
+    max_credits: 1,
+    concurrency: 4,
+    export_format: "jsonl",
+    response: { mode: "full" },
+  }, client);
+  assert(reverse.requestCount === 1, `Credit guard should stop duplicate/remainder after 1 paid reverse lookup, got ${reverse.requestCount}.`);
+  assert(reverse.creditsUsed === 1, `Expected 1 reverse-email credit, got ${reverse.creditsUsed}.`);
+  assert(reverse.creditBudget.stopped === true, "Reverse-email credit budget should report stopped=true.");
+  assert(reverse.export?.format === "jsonl", "Reverse-email batch should return JSONL export.");
+  assert(reverse.export.text.split("\n").filter(Boolean).length === 1, "Reverse-email JSONL export should contain one found row.");
+
+  const exact = await callQuickEnrichTool("quickenrich_batch_employee_search", {
+    input_jsonl: '{"company_url":"example.com","first_name":"Ada","last_name":"Lovelace"}\n{"company_url":"example.com","first_name":"Grace","last_name":"Hopper"}\n',
+    include_phone: true,
+    max_credits: 4,
+    requests_per_minute: 1000,
+    burst_size: 2,
+    export_format: "csv",
+    response: { mode: "full" },
+  }, client);
+  assert(exact.requestCount === 4, `Expected 2 email + 2 phone requests, got ${exact.requestCount}.`);
+  assert(exact.creditsUsed === 4, `Expected 4 exact batch credits, got ${exact.creditsUsed}.`);
+  assert(exact.export?.format === "csv", "Exact batch should return CSV export.");
+  assert(exact.export.text.includes("email"), "Exact CSV export should include email header.");
+
+  const domainCsv = await callQuickEnrichTool("quickenrich_batch_pull_leads", {
+    mode: "domain_search",
+    input_csv: "company_url,title\ncsv-one.example,Founder\ncsv-one.example,Founder\ncsv-two.example,CEO\n",
+    concurrency: 4,
+    export_format: "jsonl",
+    response: { mode: "full" },
+  }, client);
+  const csvDomainRequests = requests.filter((entry) => entry.path === "/api/employees/dataset-search");
+  assert(domainCsv.requestCount === 2, `CSV domain batch should coalesce duplicate companies to 2 requests, got ${domainCsv.requestCount}.`);
+  assert(domainCsv.inputCompanyCount === 3, `CSV domain batch should report 3 input rows, got ${domainCsv.inputCompanyCount}.`);
+  assert(domainCsv.companyCount === 2, `CSV domain batch should report 2 unique companies, got ${domainCsv.companyCount}.`);
+  assert(domainCsv.coalescedCompanyCount === 1, `CSV domain batch should coalesce 1 duplicate, got ${domainCsv.coalescedCompanyCount}.`);
+  assert(csvDomainRequests.some((entry) => entry.query.company_url === "csv-two.example" && entry.query.title === "CEO"), "CSV domain batch should preserve per-row titles.");
+  assert(domainCsv.export?.format === "jsonl", "CSV domain batch should return JSONL export.");
+
+  const contacts = await callQuickEnrichTool("quickenrich_batch_pull_leads", {
+    mode: "contact_finder",
+    filters: {
+      company_name: { include: ["Acme"] },
+      country_code: ["US"],
+      title: { include: ["CEO"], exclude: ["Intern"] },
+    },
+    has_email: true,
+    has_phone: true,
+    max_results: 2,
+    per_page: 1,
+    pages_per_company: 3,
+    requests_per_minute: 120,
+    burst_size: 1,
+    export_format: "jsonl",
+    response: { mode: "full" },
+  }, client);
+  assert(contacts.requestCount === 2, `Contact finder should auto-page to 2 requests, got ${contacts.requestCount}.`);
+  assert(contacts.leadCount === 2, `Contact finder should return 2 leads, got ${contacts.leadCount}.`);
+  assert(contacts.creditsUsed === 0, "Contact finder should remain free in mock.");
+  assert(contacts.export?.format === "jsonl", "Contact finder should return JSONL export.");
+
+  const contactBody = requests.find((entry) => entry.path === "/api/employees/contact-finder")?.body;
+  assert(contactBody.company_name.include[0] === "Acme", "Typed contact builder should include company_name.");
+  assert(contactBody.country_code.include[0] === "US", "Typed contact builder should normalize array filters.");
+  assert(contactBody.has_email === true && contactBody.has_phone === true, "Typed contact builder should forward data flags.");
+
+  const companies = await callQuickEnrichTool("quickenrich_batch_pull_leads", {
+    mode: "company_finder",
+    filters: {
+      home_page_text: ["cloud migration"],
+      services: { include: ["DevOps"] },
+      industry: ["Computer Software"],
+      country_code: ["US"],
+    },
+    max_results: 2,
+    max_credits: 1,
+    per_page: 5,
+    pages_per_company: 3,
+    export_format: "csv",
+    response: { mode: "full" },
+  }, client);
+  assert(companies.requestCount === 1, `Company credit guard should stop after 1 page, got ${companies.requestCount}.`);
+  assert(companies.companyCount === 1, `Expected 1 company due credit guard, got ${companies.companyCount}.`);
+  assert(companies.companies[0].domain === "acme.com", "Company normalization should expose domain.");
+  assert(Array.isArray(companies.companies[0].services), "Company normalization should preserve services.");
+  assert(companies.export?.format === "csv", "Company finder should return CSV export.");
+  assert(companies.creditBudget.stopped === true, "Company finder credit budget should stop after max_credits.");
+
+  const companyBody = requests.find((entry) => entry.path === "/api/companies/company-finder")?.body;
+  assert(companyBody.per_page === 1, `Credit-limited company finder should shrink per_page to remaining budget, got ${companyBody.per_page}.`);
+  assert(companyBody.home_page_text.include[0] === "cloud migration", "Typed company builder should include home_page_text.");
+  assert(companyBody.services.include[0] === "DevOps", "Typed company builder should include services.");
+
+  console.log(JSON.stringify({
+    ok: true,
+    reverseRequests: reverse.requestCount,
+    exactRequests: exact.requestCount,
+    domainRequests: domainCsv.requestCount,
+    contactRequests: contacts.requestCount,
+    companyRequests: companies.requestCount,
+  }, null, 2));
+} finally {
+  server.close();
+}

package/scripts/native-live-smoke.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+import { authStatus, callQuickEnrichTool, createClient } from "./lib/core.mjs";
+
+const status = authStatus();
+if (!status.configured) {
+  console.log(JSON.stringify({
+    ok: true,
+    skipped: true,
+    reason: "Quick Enrich API key is not configured. Set QUICKENRICH_API_KEY or run node scripts/quickenrich-token.mjs set.",
+  }, null, 2));
+  process.exit(0);
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+const client = createClient();
+const suffix = `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+const result = await callQuickEnrichTool("quickenrich_batch_reverse_email", {
+  emails: [
+    `qe-native-${suffix}@gmail.com`,
+    `qe-native-${suffix}@gmail.com`,
+    `missing-native-${suffix}@gmail.com`,
+  ],
+  response: { mode: "full" },
+}, client);
+
+assert(result.ok === true, "Native batch reverse-email live smoke should return ok=true.");
+assert(result.requestCount <= 2, `Expected deduped live batch to make <=2 requests, got ${result.requestCount}.`);
+assert(Number(result.creditsUsed || 0) === 0, `Native live batch should use 0 credits, got ${result.creditsUsed}.`);
+assert(result.resumeState?.pendingCount === 0, "Native live batch should have no pending items after no-credit misses.");
+
+console.log(JSON.stringify({
+  ok: true,
+  skipped: false,
+  tool: "quickenrich_batch_reverse_email",
+  requestCount: result.requestCount,
+  creditsUsed: result.creditsUsed,
+  resumeState: result.resumeState,
+  throttle: result.throttle,
+}, null, 2));

package/scripts/offline-contract-smoke.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+import {
+  TOOL_DEFINITIONS,
+  agentGraph,
+  authStatus,
+  compactToolPayload,
+  planNaturalLanguage,
+  redact,
+} from "./lib/core.mjs";
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+const names = TOOL_DEFINITIONS.map((tool) => tool.name);
+assert(new Set(names).size === names.length, "Tool names must be unique.");
+for (const required of [
+  "quickenrich_auth_status",
+  "quickenrich_agent_graph",
+  "quickenrich_natural_language",
+  "quickenrich_pipeline",
+  "quickenrich_batch_pull_leads",
+  "quickenrich_employee_search",
+  "quickenrich_phone_search",
+  "quickenrich_reverse_email",
+  "quickenrich_batch_reverse_email",
+  "quickenrich_batch_employee_search",
+  "quickenrich_domain_search",
+  "quickenrich_contact_finder",
+  "quickenrich_company_finder",
+  "quickenrich_lookup_values",
+]) {
+  assert(names.includes(required), `Missing tool: ${required}`);
+}
+
+const graph = agentGraph();
+assert(graph.rateLimitsPerMinute.domain_search === 300, "Domain search rate limit should be documented.");
+assert(graph.creditNotes.contact_finder.includes("discovery"), "Contact finder credit note should explain discovery-only behavior.");
+assert(graph.endpointCoverage.length === 7, `Expected all Quick Enrich API surfaces in endpointCoverage, got ${graph.endpointCoverage.length}.`);
+assert(graph.agentRouting.some((entry) => entry.tool === "quickenrich_batch_pull_leads"), "Agent graph should prefer native batch lead pulls.");
+assert(graph.lookupHints.tool === "quickenrich_lookup_values", "Agent graph should route lookup discovery to lookup_values.");
+assert(graph.budgetMath.exact_email_phone.includes("phone"), "Agent graph should document email+phone budget math.");
+
+const status = authStatus();
+assert(!JSON.stringify(status).match(/sk-|test-token-123/), "Auth status must not include token-looking values.");
+
+const plan = planNaturalLanguage("Batch pull founder leads for example.com and sample.io");
+assert(plan.tool === "quickenrich_batch_pull_leads", "Natural language planner should choose batch lead pull.");
+assert(plan.arguments.companies.length === 2, "Planner should extract two domains.");
+
+const emailBatchPlan = planNaturalLanguage("Reverse lookup these emails: ada@example.com grace@example.com");
+assert(emailBatchPlan.tool === "quickenrich_batch_reverse_email", "Planner should batch multiple reverse-email lookups.");
+assert(emailBatchPlan.arguments.emails.length === 2, "Planner should extract both email addresses.");
+
+const companyFinderPlan = planNaturalLanguage("Use company finder for cloud companies");
+assert(companyFinderPlan.tool === "quickenrich_batch_pull_leads", "Planner should route company finder intent through batch_pull_leads.");
+assert(companyFinderPlan.arguments.mode === "company_finder", "Planner should set company_finder mode.");
+
+const contactFinderPlan = planNaturalLanguage("Use contact finder for CEOs at software companies");
+assert(contactFinderPlan.tool === "quickenrich_batch_pull_leads", "Planner should route contact finder intent through batch_pull_leads.");
+assert(contactFinderPlan.arguments.mode === "contact_finder", "Planner should set contact_finder mode.");
+
+const exactJsonlPlan = planNaturalLanguage('Batch exact employee search from JSONL: {"company_url":"example.com","first_name":"Ada","last_name":"Lovelace"}');
+assert(exactJsonlPlan.tool === "quickenrich_batch_employee_search", "Planner should route exact-person JSONL to batch employee search.");
+assert(exactJsonlPlan.requires.includes("input_jsonl"), "Exact-person JSONL route should require input_jsonl payload.");
+
+const reverseCsvPlan = planNaturalLanguage("Reverse lookup a CSV of emails");
+assert(reverseCsvPlan.tool === "quickenrich_batch_reverse_email", "Planner should route reverse-email CSV to batch reverse-email.");
+assert(reverseCsvPlan.requires.includes("input_csv"), "Reverse-email CSV route should require input_csv payload.");
+
+const redacted = JSON.stringify(redact({ Authorization: "Bearer secret-token", nested: { api_key: "abc" } }));
+assert(!redacted.includes("secret-token"), "Bearer token was not redacted.");
+assert(!redacted.includes("abc"), "api_key was not redacted.");
+
+const compacted = compactToolPayload({ ok: true, rows: Array.from({ length: 50 }, (_, i) => ({ i })) }, { maxItems: 3 });
+assert(compacted.rows.length === 4, "Compact payload should limit arrays and append omitted count.");
+assert(compacted._meta.truncated === true, "Compact payload should report truncation.");
+
+console.log(JSON.stringify({ ok: true }, null, 2));