@mackody/quickenrich-mcp 0.1.0

package/scripts/agent-surface-smoke.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const serverPath = join(__dirname, "quickenrich-mcp.mjs");
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function sendRpc(proc, id, method, params = {}) {
+  const message = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+  proc.stdin.write(`Content-Length: ${Buffer.byteLength(message)}\r\n\r\n${message}`);
+}
+
+function readResponses(proc, wantedIds, timeoutMs = 5000) {
+  let buffer = Buffer.alloc(0);
+  const responses = new Map();
+  proc.stdout.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (true) {
+      const headerEnd = buffer.indexOf("\r\n\r\n");
+      if (headerEnd === -1) return;
+      const header = buffer.slice(0, headerEnd).toString("utf8");
+      const match = header.match(/Content-Length:\s*(\d+)/i);
+      if (!match) throw new Error(`Invalid MCP header: ${header}`);
+      const length = Number(match[1]);
+      const bodyStart = headerEnd + 4;
+      const bodyEnd = bodyStart + length;
+      if (buffer.length < bodyEnd) return;
+      const body = buffer.slice(bodyStart, bodyEnd).toString("utf8");
+      buffer = buffer.slice(bodyEnd);
+      const response = JSON.parse(body);
+      responses.set(response.id, response);
+    }
+  });
+  proc.stderr.on("data", (chunk) => process.stderr.write(chunk));
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error(`Timed out waiting for ${wantedIds.join(", ")}`)), timeoutMs);
+    const interval = setInterval(() => {
+      if (wantedIds.every((id) => responses.has(id))) {
+        clearTimeout(timeout);
+        clearInterval(interval);
+        resolve(wantedIds.map((id) => responses.get(id)));
+      }
+    }, 25);
+  });
+}
+
+async function listTools(mode) {
+  const proc = spawn(process.execPath, [serverPath], {
+    cwd: join(__dirname, ".."),
+    env: {
+      ...process.env,
+      QUICKENRICH_API_KEY: "",
+      QUICKENRICH_TOKEN: "",
+      QUICKENRICH_MCP_TOOL_MODE: mode,
+      QUICKENRICH_MCP_CONFIG: join(__dirname, "..", "tmp", "missing-config.json"),
+    },
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  try {
+    sendRpc(proc, 1, "initialize", { protocolVersion: "2024-11-05" });
+    sendRpc(proc, 2, "tools/list");
+    const [, list] = await readResponses(proc, [1, 2]);
+    return list.result?.tools?.map((tool) => tool.name) || [];
+  } finally {
+    proc.kill();
+  }
+}
+
+const agentTools = await listTools("");
+assert(agentTools.length <= 9, `Default agent mode must expose <=9 tools, got ${agentTools.length}.`);
+for (const required of [
+  "quickenrich_auth_status",
+  "quickenrich_agent_graph",
+  "quickenrich_natural_language",
+  "quickenrich_batch_pull_leads",
+  "quickenrich_batch_reverse_email",
+  "quickenrich_batch_employee_search",
+  "quickenrich_pipeline",
+  "quickenrich_lookup_values",
+]) {
+  assert(agentTools.includes(required), `Agent surface missing ${required}.`);
+}
+for (const lowLevel of [
+  "quickenrich_phone_search",
+  "quickenrich_employee_search",
+  "quickenrich_contact_finder",
+  "quickenrich_company_finder",
+]) {
+  assert(!agentTools.includes(lowLevel), `Agent surface should hide low-level tool ${lowLevel}.`);
+}
+
+const fullTools = await listTools("full");
+assert(fullTools.length >= 11, `Full mode must expose full API surface, got ${fullTools.length}.`);
+assert(fullTools.includes("quickenrich_company_finder"), "Full mode missing company finder.");
+
+console.log(JSON.stringify({ ok: true, agentTools: agentTools.length, fullTools: fullTools.length }, null, 2));

package/scripts/benchmark-contract-smoke.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import {
+  makeDuplicateDomainBenchmark,
+  summarizeBenchmarkComparison,
+} from "./lib/benchmark.mjs";
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+const fixture = makeDuplicateDomainBenchmark({
+  uniqueCount: 3,
+  duplicateFactor: 2,
+  prefix: "qe-mcp-contract",
+  title: "Founder",
+});
+
+assert(fixture.companies.length === 6, `Expected 6 input companies, got ${fixture.companies.length}.`);
+assert(fixture.uniqueCompanies.length === 3, `Expected 3 unique companies, got ${fixture.uniqueCompanies.length}.`);
+assert(fixture.coalescedCount === 3, `Expected 3 coalesced duplicates, got ${fixture.coalescedCount}.`);
+assert(fixture.companies.every((entry) => entry.title === "Founder"), "Expected title to be propagated to all companies.");
+
+for (const company of fixture.uniqueCompanies) {
+  const occurrences = fixture.companies.filter((entry) => entry.company_url === company.company_url).length;
+  assert(occurrences === 2, `Expected ${company.company_url} twice, got ${occurrences}.`);
+}
+
+const comparison = summarizeBenchmarkComparison({
+  rows: [
+    { label: "raw_sequential", durationMs: 1200, requestCount: 6, creditsUsed: 0 },
+    { label: "raw_concurrent_deduped", durationMs: 240, requestCount: 3, creditsUsed: 0 },
+    { label: "mcp_batch_stdio", durationMs: 300, requestCount: 3, creditsUsed: 0 },
+  ],
+  baselineLabel: "raw_sequential",
+  candidateLabel: "mcp_batch_stdio",
+  optimizedLabel: "raw_concurrent_deduped",
+});
+
+assert(comparison.candidateFasterThanBaseline === true, "Expected MCP batch to be faster than raw sequential.");
+assert(comparison.speedupVsBaseline === 4, `Expected 4x speedup, got ${comparison.speedupVsBaseline}.`);
+assert(comparison.requestReductionVsBaseline === 2, `Expected 2x request reduction, got ${comparison.requestReductionVsBaseline}.`);
+assert(comparison.optimizedDeltaPct === 25, `Expected 25% optimized delta, got ${comparison.optimizedDeltaPct}.`);
+assert(comparison.totalCreditsUsed === 0, `Expected zero credits, got ${comparison.totalCreditsUsed}.`);
+
+console.log(JSON.stringify({ ok: true, fixture, comparison }, null, 2));

package/scripts/envelope-budget-smoke.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import { compactToolPayload } from "./lib/core.mjs";
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+const payload = {
+  ok: true,
+  mode: "domain_search",
+  leads: Array.from({ length: 100 }, (_, i) => ({
+    first_name: `First${i}`,
+    last_name: `Last${i}`,
+    title: "Founder and Chief Executive Officer with an intentionally verbose title tail",
+    email: `founder${i}@example.com`,
+    phone: "+14155550100",
+    employee_linkedin: `https://linkedin.com/in/founder-${i}`,
+    company_url: `example-${i}.com`,
+    company_name: `Example Company ${i}`,
+    notes: "x".repeat(1000),
+  })),
+};
+
+const compact = compactToolPayload(payload);
+const text = JSON.stringify(compact);
+const meta = compactToolPayload({ ...payload, requestCount: 6, creditsUsed: 0 }, { mode: "meta" });
+
+assert(Buffer.byteLength(text, "utf8") <= 12_000, `Default envelope is too large: ${Buffer.byteLength(text, "utf8")} bytes.`);
+assert(compact.leads.length <= 13, `Default envelope should include at most 12 leads plus omitted marker, got ${compact.leads.length}.`);
+assert(compact._meta.truncated === true, "Default envelope should report truncation.");
+assert(!text.includes("x".repeat(800)), "Long fields should be truncated by default.");
+assert(meta.scalars.ok === true, "Meta envelope should preserve scalar ok status.");
+assert(meta.scalars.requestCount === 6, "Meta envelope should preserve scalar requestCount.");
+assert(meta.collections.leads.length === 100, "Meta envelope should preserve collection lengths.");
+
+console.log(JSON.stringify({ ok: true, bytes: Buffer.byteLength(text, "utf8"), leads: compact.leads.length, metaScalars: Object.keys(meta.scalars).length }, null, 2));

package/scripts/killer-contract-smoke.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { createServer } from "node:http";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  TOOL_DEFINITIONS,
+  agentGraph,
+  callQuickEnrichTool,
+  createClient,
+  selectTools,
+} from "./lib/core.mjs";
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function readJsonl(path) {
+  return readFileSync(path, "utf8")
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+const tmp = mkdtempSync(join(tmpdir(), "qe-killer-"));
+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: {
+        first_name: email.startsWith("grace") ? "Grace" : "Ada",
+        last_name: "Tester",
+        email,
+        title: "Founder",
+        company_url: "example.com",
+        employee_linkedin: `https://linkedin.com/in/${email.split("@")[0]}`,
+      },
+      meta: { credits_used: 1, remaining_credits: 1000 },
+    }));
+    return;
+  }
+
+  if (url.pathname === "/api/employees/dataset-search") {
+    const companyUrl = url.searchParams.get("company_url");
+    res.end(JSON.stringify({
+      success: true,
+      data: [{
+        first_name: companyUrl.startsWith("acme") ? "Ari" : "Bea",
+        last_name: "Founder",
+        title: url.searchParams.get("title") || "Founder",
+        email: `founder@${companyUrl}`,
+        employee_linkedin: `https://linkedin.com/in/${companyUrl}-founder`,
+        company_url: companyUrl,
+        company_name: companyUrl.split(".")[0],
+        has_email: true,
+      }],
+      meta: { page: 1, per_page: 20, total: 1, last_page: 1, credits_used: 1, remaining_credits: 999 },
+    }));
+    return;
+  }
+
+  if (url.pathname === "/api/companies/company-finder") {
+    res.end(JSON.stringify({
+      success: true,
+      data: [
+        { company_name: "Acme", url: "acme.test", email_domain: "acme.test", services: ["DevOps"], country_code: "US" },
+        { company_name: "Beta", url: "beta.test", email_domain: "beta.test", services: ["DevOps"], country_code: "US" },
+      ],
+      meta: { page: body?.page || 1, per_page: body?.per_page || 2, total: 2, last_page: 1, credits_used: 2, remaining_credits: 998 },
+    }));
+    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 = "killer-contract-key";
+  process.env.QUICKENRICH_API_BASE_URL = `http://127.0.0.1:${port}`;
+  process.env.QUICKENRICH_MCP_CACHE_DIR = join(tmp, "cache");
+  process.env.QUICKENRICH_MCP_SHARED_THROTTLE_DIR = join(tmp, "throttle");
+  process.env.QUICKENRICH_MCP_LEDGER_PATH = join(tmp, "credits.jsonl");
+
+  const client = createClient();
+  const emailFile = join(tmp, "emails.csv");
+  const reverseOut = join(tmp, "reverse.jsonl");
+  const reverseResume = join(tmp, "reverse-resume.json");
+  writeFileSync(emailFile, "email\nada@example.com\ngrace@example.com\nada@example.com\n");
+  writeFileSync(reverseResume, `${JSON.stringify({ completed: ["ada@example.com"] })}\n`);
+
+  const reverse = await callQuickEnrichTool("quickenrich_batch_reverse_email", {
+    input_file: emailFile,
+    output_file: reverseOut,
+    resume_file: reverseResume,
+    cache_mode: "readwrite",
+    credit_ledger: true,
+    projection: "emails",
+    response: { mode: "full" },
+  }, client);
+  assert(reverse.requestCount === 1, `Resume file should skip completed/collapsed emails; got ${reverse.requestCount}.`);
+  assert(reverse.foundCount === 1, `Expected one new reverse-email result, got ${reverse.foundCount}.`);
+  assert(reverse.output?.path === reverseOut, "Reverse batch should return output_file metadata.");
+  assert(reverse.resume?.path === reverseResume, "Reverse batch should return resume_file metadata.");
+  assert(readJson(reverseResume).completed.includes("grace@example.com"), "Resume file should be updated durably.");
+  assert(readJsonl(reverseOut).length === 1, "JSONL output file should contain exactly the newly processed result.");
+  assert(!("title" in reverse.results[0]), "emails projection should strip non-email fields from inline results.");
+  assert(reverse.results[0].quality?.match_status === "matched", "Projected result should retain compact quality metadata.");
+
+  const reverseRequestCount = requests.filter((entry) => entry.path === "/api/employees/email-search").length;
+  const cachedReverse = await callQuickEnrichTool("quickenrich_batch_reverse_email", {
+    input_file: emailFile,
+    resume_state: { completed: [] },
+    cache_mode: "readwrite",
+    credit_ledger: true,
+    projection: "emails",
+    response: { mode: "full" },
+  }, client);
+  const reverseRequestCountAfterCache = requests.filter((entry) => entry.path === "/api/employees/email-search").length;
+  assert(reverseRequestCountAfterCache === reverseRequestCount + 1, "Cache should avoid re-requesting grace@example.com while requesting uncached ada@example.com once.");
+  assert(cachedReverse.cache?.hits >= 1, "Batch should expose cache hit count.");
+  assert(existsSync(process.env.QUICKENRICH_MCP_LEDGER_PATH), "Credit ledger should be written when enabled.");
+
+  const sharedThrottlePlan = await callQuickEnrichTool("quickenrich_batch_pull_leads", {
+    mode: "domain_search",
+    companies: [{ company_url: "shared-throttle.test" }],
+    dry_run: true,
+    throttle_scope: "shared",
+    response: { mode: "full" },
+  }, client);
+  assert(sharedThrottlePlan.throttle?.scope === "shared", "Shared throttle dry-run should expose shared scope.");
+
+  const pipelineOut = join(tmp, "pipeline.jsonl");
+  const pipeline = await callQuickEnrichTool("quickenrich_pipeline", {
+    mode: "company_finder_to_domain_search",
+    filters: { services: ["DevOps"], country_code: ["US"] },
+    max_companies: 2,
+    title: "Founder",
+    output_file: pipelineOut,
+    projection: "people",
+    response: { mode: "full" },
+  }, client);
+  assert(pipeline.ok === true, "Native pipeline should succeed.");
+  assert(pipeline.steps.map((step) => step.tool).join(">") === "quickenrich_batch_pull_leads>quickenrich_batch_pull_leads", "Pipeline should expose compact step graph.");
+  assert(pipeline.companyCount === 2, `Expected 2 companies from pipeline, got ${pipeline.companyCount}.`);
+  assert(pipeline.leadCount === 2, `Expected 2 domain-search leads from pipeline, got ${pipeline.leadCount}.`);
+  assert(readJsonl(pipelineOut).length === 2, "Pipeline should stream JSONL results to output_file.");
+  assert(pipeline.leads.every((lead) => lead.quality?.source_endpoint), "Pipeline leads should carry quality metadata.");
+
+  const graph = agentGraph();
+  const agentToolNames = selectTools(TOOL_DEFINITIONS).map((tool) => tool.name);
+  assert(agentToolNames.includes("quickenrich_pipeline"), "Default agent surface should expose the native pipeline tool.");
+  assert(graph.bulkIO?.input_file && graph.bulkIO?.output_file && graph.bulkIO?.resume_file, "Agent graph should document file-handle bulk IO.");
+  assert(graph.cacheLedger?.toolArgs?.includes("cache_mode"), "Agent graph should document cache/ledger controls.");
+  assert(graph.projections?.modes?.includes("emails"), "Agent graph should document projection modes.");
+  assert(graph.evalBudgets?.toolsListBytes <= 8_000, "Agent graph should publish tools/list byte budget.");
+
+  const doctor = spawnSync(process.execPath, ["scripts/quickenrich-token.mjs", "doctor", "--json", "--config", join(tmp, "config.json")], {
+    cwd: join(new URL(".", import.meta.url).pathname, ".."),
+    env: { ...process.env, QUICKENRICH_API_KEY: "", QUICKENRICH_TOKEN: "" },
+    encoding: "utf8",
+  });
+  assert(doctor.status === 0, `doctor should exit 0: ${doctor.stderr || doctor.stdout}`);
+  const doctorPayload = JSON.parse(doctor.stdout);
+  assert(doctorPayload.ok === true, "doctor --json should report ok=true for local diagnostics.");
+  assert(doctorPayload.tools.defaultCount <= 9, "doctor should include compact tool-surface diagnostics.");
+
+  const installConfig = spawnSync(process.execPath, ["scripts/quickenrich-token.mjs", "install-config", "--json"], {
+    cwd: join(new URL(".", import.meta.url).pathname, ".."),
+    env: process.env,
+    encoding: "utf8",
+  });
+  assert(installConfig.status === 0, `install-config should exit 0: ${installConfig.stderr || installConfig.stdout}`);
+  assert(JSON.parse(installConfig.stdout).mcpServers?.["quick-enrich"], "install-config should print an MCP config snippet.");
+
+  console.log(JSON.stringify({
+    ok: true,
+    reverseRequests: reverse.requestCount,
+    cachedHits: cachedReverse.cache?.hits || 0,
+    pipelineLeads: pipeline.leadCount,
+    tools: agentToolNames.length,
+  }, null, 2));
+} finally {
+  server.close();
+  rmSync(tmp, { recursive: true, force: true });
+}

package/scripts/lib/benchmark.mjs

@@ -0,0 +1,92 @@
+export const DEFAULT_BENCHMARK_TITLE = "Founder";
+
+export function makeDuplicateDomainBenchmark(options = {}) {
+  const uniqueCount = clampInteger(options.uniqueCount, 1, 100, 6);
+  const duplicateFactor = clampInteger(options.duplicateFactor, 1, 20, 2);
+  const prefix = safeDomainPrefix(options.prefix || `qe-mcp-bench-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+  const title = String(options.title || DEFAULT_BENCHMARK_TITLE).trim() || DEFAULT_BENCHMARK_TITLE;
+  const uniqueCompanies = Array.from({ length: uniqueCount }, (_, index) => ({
+    company_url: `${prefix}-${index + 1}.com`,
+    title,
+  }));
+  const companies = uniqueCompanies.flatMap((company) => (
+    Array.from({ length: duplicateFactor }, () => ({ ...company }))
+  ));
+  return {
+    title,
+    uniqueCount,
+    duplicateFactor,
+    inputCount: companies.length,
+    coalescedCount: companies.length - uniqueCompanies.length,
+    companies,
+    uniqueCompanies,
+  };
+}
+
+export function summarizeBenchmarkComparison({
+  rows,
+  baselineLabel = "raw_sequential",
+  candidateLabel = "mcp_batch_stdio",
+  optimizedLabel = "raw_concurrent_deduped",
+} = {}) {
+  const list = Array.isArray(rows) ? rows : [];
+  const baseline = requireRow(list, baselineLabel);
+  const candidate = requireRow(list, candidateLabel);
+  const optimized = optimizedLabel ? list.find((row) => row.label === optimizedLabel) : undefined;
+  return {
+    baselineLabel,
+    candidateLabel,
+    optimizedLabel: optimized?.label,
+    baselineDurationMs: roundNumber(baseline.durationMs),
+    candidateDurationMs: roundNumber(candidate.durationMs),
+    baselineRequestCount: roundNumber(baseline.requestCount),
+    candidateRequestCount: roundNumber(candidate.requestCount),
+    candidateFasterThanBaseline: Number(candidate.durationMs) < Number(baseline.durationMs),
+    speedupVsBaseline: ratio(baseline.durationMs, candidate.durationMs),
+    requestReductionVsBaseline: ratio(baseline.requestCount, candidate.requestCount),
+    optimizedDeltaPct: optimized ? percentDelta(candidate.durationMs, optimized.durationMs) : undefined,
+    totalCreditsUsed: roundNumber(list.reduce((sum, row) => sum + Number(row.creditsUsed || 0), 0)),
+  };
+}
+
+function requireRow(rows, label) {
+  const row = rows.find((entry) => entry.label === label);
+  if (!row) throw new Error(`Missing benchmark row: ${label}`);
+  return row;
+}
+
+function safeDomainPrefix(value) {
+  const cleaned = String(value || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/--+/g, "-")
+    .slice(0, 44);
+  return cleaned || "qe-mcp-bench";
+}
+
+function clampInteger(value, min, max, fallback) {
+  const number = Number.parseInt(value, 10);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(max, Math.max(min, number));
+}
+
+function ratio(numerator, denominator) {
+  const top = Number(numerator);
+  const bottom = Number(denominator);
+  if (!Number.isFinite(top) || !Number.isFinite(bottom) || bottom <= 0) return undefined;
+  return roundNumber(top / bottom);
+}
+
+function percentDelta(value, baseline) {
+  const current = Number(value);
+  const base = Number(baseline);
+  if (!Number.isFinite(current) || !Number.isFinite(base) || base <= 0) return undefined;
+  return roundNumber(((current - base) / base) * 100);
+}
+
+function roundNumber(value) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return undefined;
+  return Math.round(number * 100) / 100;
+}