@mackody/quickenrich-mcp 0.1.0

package/scripts/local-floor-benchmark.mjs

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath } from "node:url";
+import { callQuickEnrichTool, createClient } from "./lib/core.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, "..");
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function round(value) {
+  return Math.round(Number(value) * 100) / 100;
+}
+
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.floor(sorted.length / 2)];
+}
+
+const stats = new Map();
+const mockLatencyMs = envInteger("QUICKENRICH_FLOOR_MOCK_LATENCY_MS", 0, 1_000, 0);
+
+function recordStart(path) {
+  const entry = stats.get(path) || { requests: 0, active: 0, maxActive: 0 };
+  entry.requests += 1;
+  entry.active += 1;
+  entry.maxActive = Math.max(entry.maxActive, entry.active);
+  stats.set(path, entry);
+}
+
+function recordEnd(path) {
+  const entry = stats.get(path);
+  if (entry) entry.active -= 1;
+}
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url, "http://127.0.0.1");
+  const path = url.pathname;
+  recordStart(path);
+  try {
+    const chunks = [];
+    for await (const chunk of req) chunks.push(chunk);
+    const bodyText = Buffer.concat(chunks).toString("utf8");
+    const body = bodyText ? JSON.parse(bodyText) : {};
+    res.setHeader("content-type", "application/json");
+    if (mockLatencyMs > 0) await sleep(mockLatencyMs);
+
+    if (path === "/api/employees/email-search") {
+      const email = url.searchParams.get("email");
+      res.end(JSON.stringify({
+        success: true,
+        data: {
+          first_name: "Bulk",
+          last_name: "Email",
+          email,
+          title: "Founder",
+          company_url: "floor.dev",
+        },
+        meta: { credits_used: 1, remaining_credits: 9999 },
+      }));
+      return;
+    }
+
+    if (path === "/api/employees/search") {
+      const first = url.searchParams.get("first_name") || "Exact";
+      const last = url.searchParams.get("last_name") || "Person";
+      res.end(JSON.stringify({
+        success: true,
+        data: {
+          first_name: first,
+          last_name: last,
+          title: "Founder",
+          email: `${first.toLowerCase()}.${last.toLowerCase()}@floor.dev`,
+          employee_linkedin: `https://linkedin.com/in/${first.toLowerCase()}-${last.toLowerCase()}`,
+          company_url: url.searchParams.get("company_url") || "floor.dev",
+        },
+        meta: { credits_used: 1, remaining_credits: 9999 },
+      }));
+      return;
+    }
+
+    if (path === "/api/employees/phone-search") {
+      res.end(JSON.stringify({
+        success: true,
+        data: {
+          employee_phone: "(415) 555-0100",
+          company_url: url.searchParams.get("company_url") || "floor.dev",
+        },
+        meta: { credits_used: 1, remaining_credits: 9999 },
+      }));
+      return;
+    }
+
+    if (path === "/api/employees/contact-finder") {
+      const page = Number(body.page || 1);
+      res.end(JSON.stringify({
+        success: true,
+        data: Array.from({ length: 5 }, (_, index) => ({
+          first_name: `Contact${page}_${index}`,
+          last_name: "Floor",
+          title: "Founder",
+          employee_linkedin: `https://linkedin.com/in/contact-${page}-${index}`,
+          company_url: "contact-floor.dev",
+          has_email: true,
+        })),
+        meta: { page, per_page: body.per_page || 5, total: 20, last_page: 4, credits_used: 0, remaining_credits: 9999 },
+      }));
+      return;
+    }
+
+    if (path === "/api/companies/company-finder") {
+      const page = Number(body.page || 1);
+      res.end(JSON.stringify({
+        success: true,
+        data: Array.from({ length: 5 }, (_, index) => ({
+          company_name: `Company ${page}-${index}`,
+          url: `company-${page}-${index}.dev`,
+          email_domain: `company-${page}-${index}.dev`,
+          linkedin_url: `https://linkedin.com/company/company-${page}-${index}`,
+          services: ["DevOps", "AWS"],
+          country_code: "US",
+        })),
+        meta: { page, per_page: body.per_page || 5, total: 20, last_page: 4, credits_used: 5, remaining_credits: 9999 },
+      }));
+      return;
+    }
+
+    res.statusCode = 404;
+    res.end(JSON.stringify({ error: "not found" }));
+  } finally {
+    recordEnd(path);
+  }
+});
+
+await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+const { port } = server.address();
+
+process.env.QUICKENRICH_API_KEY = "floor-benchmark-key";
+process.env.QUICKENRICH_API_BASE_URL = `http://127.0.0.1:${port}`;
+
+const client = createClient();
+const mcp = startMcpClient();
+const rows = [];
+
+try {
+  await initializeMcp(mcp);
+  await runScenario("reverse_csv_jsonl", {
+    tool: "quickenrich_batch_reverse_email",
+    args: {
+      input_csv: makeEmailCsv(64),
+      concurrency: 64,
+      requests_per_minute: 100_000,
+      burst_size: 128,
+      export_format: "jsonl",
+      response: { mode: "full", maxOutputChars: 1_000_000 },
+    },
+  });
+  await runScenario("exact_csv_phone_csv_export", {
+    tool: "quickenrich_batch_employee_search",
+    args: {
+      input_csv: makePersonCsv(32),
+      include_phone: true,
+      concurrency: 32,
+      requests_per_minute: 100_000,
+      phone_requests_per_minute: 100_000,
+      burst_size: 128,
+      export_format: "csv",
+      response: { mode: "full", maxOutputChars: 1_000_000 },
+    },
+  });
+  await runScenario("contact_finder_paging_jsonl", {
+    tool: "quickenrich_batch_pull_leads",
+    args: {
+      mode: "contact_finder",
+      filters: { company_name: ["Floor"] },
+      pages_per_company: 4,
+      per_page: 5,
+      max_results: 20,
+      concurrency: 4,
+      requests_per_minute: 100_000,
+      burst_size: 4,
+      export_format: "jsonl",
+      response: { mode: "full", maxOutputChars: 1_000_000 },
+    },
+  });
+  await runScenario("company_finder_paging_csv", {
+    tool: "quickenrich_batch_pull_leads",
+    args: {
+      mode: "company_finder",
+      filters: { services: ["DevOps"], country_code: ["US"] },
+      pages_per_company: 4,
+      per_page: 5,
+      max_results: 20,
+      concurrency: 4,
+      requests_per_minute: 100_000,
+      burst_size: 4,
+      export_format: "csv",
+      response: { mode: "full", maxOutputChars: 1_000_000 },
+    },
+  });
+
+  const slowRows = rows.filter((row) => !row.directOk || !row.mcpOk || row.mcpOverDirectRatio > 2.5);
+  if (slowRows.length) {
+    throw new Error(`Local MCP floor regression: ${JSON.stringify(slowRows)}`);
+  }
+
+  console.log(JSON.stringify({
+    ok: true,
+    apiBaseUrl: process.env.QUICKENRICH_API_BASE_URL,
+    mockLatencyMs,
+    rows,
+    endpointStats: Object.fromEntries([...stats.entries()].map(([path, entry]) => [
+      path,
+      { requests: entry.requests, maxActive: entry.maxActive },
+    ])),
+  }, null, 2));
+} finally {
+  await mcp.close();
+  server.close();
+}
+
+async function runScenario(label, { tool, args }) {
+  const directDurations = [];
+  const mcpDurations = [];
+  let directResult;
+  let mcpResult;
+  for (let iteration = 0; iteration < 3; iteration += 1) {
+    const directStart = performance.now();
+    directResult = await callQuickEnrichTool(tool, args, client);
+    directDurations.push(performance.now() - directStart);
+
+    const mcpStart = performance.now();
+    const response = await mcp.request("tools/call", { name: tool, arguments: args }, 20_000);
+    if (response.error) throw new Error(`${label} MCP failed: ${JSON.stringify(response.error)}`);
+    mcpResult = JSON.parse(response.result?.content?.[0]?.text || "{}");
+    mcpDurations.push(performance.now() - mcpStart);
+  }
+  const directMs = round(median(directDurations));
+  const mcpMs = round(median(mcpDurations));
+  rows.push({
+    label,
+    directCoreMs: directMs,
+    mcpStdioMs: mcpMs,
+    mcpOverDirectRatio: round(mcpMs / directMs),
+    requestCount: mcpResult.requestCount,
+    itemCount: mcpResult.foundCount ?? mcpResult.leadCount ?? mcpResult.companyCount,
+    exportBytes: Buffer.byteLength(mcpResult.export?.text || ""),
+    directOk: directResult.ok,
+    mcpOk: mcpResult.ok,
+  });
+}
+
+function makeEmailCsv(count) {
+  return [
+    "email",
+    ...Array.from({ length: count }, (_, index) => `person-${index}@floor.dev`),
+  ].join("\n");
+}
+
+function makePersonCsv(count) {
+  return [
+    "company_url,first_name,last_name",
+    ...Array.from({ length: count }, (_, index) => `floor.dev,First${index},Last${index}`),
+  ].join("\n");
+}
+
+function envInteger(name, min, max, fallback) {
+  const value = Number.parseInt(process.env[name] || "", 10);
+  if (!Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, value));
+}
+
+async function initializeMcp(mcp) {
+  const init = await mcp.request("initialize", { protocolVersion: "2024-11-05" });
+  if (init.error) throw new Error(`MCP initialize failed: ${JSON.stringify(init.error)}`);
+  const list = await mcp.request("tools/list");
+  if (list.error) throw new Error(`MCP tools/list failed: ${JSON.stringify(list.error)}`);
+}
+
+function startMcpClient() {
+  const mcpConfig = JSON.parse(readFileSync(join(repoRoot, ".mcp.json"), "utf8"));
+  const serverConfig = mcpConfig.mcpServers?.["quick-enrich"];
+  if (!serverConfig?.command) throw new Error("Missing quick-enrich MCP server command.");
+
+  const proc = spawn(serverConfig.command, serverConfig.args || [], {
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      ...(serverConfig.env || {}),
+      CLAUDE_PLUGIN_ROOT: repoRoot,
+    },
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  let buffer = Buffer.alloc(0);
+  let nextId = 1;
+  let stderr = "";
+  const pending = new Map();
+
+  proc.stdout.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    parseMcpFrames();
+  });
+  proc.stderr.on("data", (chunk) => {
+    stderr += chunk.toString("utf8");
+    stderr = stderr.slice(-8000);
+  });
+  proc.on("exit", (code, signal) => {
+    const error = new Error(`MCP process exited: code=${code} signal=${signal} stderr=${stderr.trim()}`);
+    for (const waiter of pending.values()) {
+      clearTimeout(waiter.timeout);
+      waiter.reject(error);
+    }
+    pending.clear();
+  });
+
+  function request(method, params = {}, timeoutMs = 10_000) {
+    const id = nextId;
+    nextId += 1;
+    const message = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`Timed out waiting for MCP response id=${id} method=${method}`));
+      }, timeoutMs);
+      pending.set(id, { resolve, reject, timeout });
+      proc.stdin.write(`Content-Length: ${Buffer.byteLength(message)}\r\n\r\n${message}`);
+    });
+  }
+
+  function parseMcpFrames() {
+    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);
+      const waiter = pending.get(response.id);
+      if (!waiter) continue;
+      pending.delete(response.id);
+      clearTimeout(waiter.timeout);
+      waiter.resolve(response);
+    }
+  }
+
+  async function close() {
+    if (proc.exitCode !== null || proc.killed) return;
+    proc.kill();
+    await new Promise((resolve) => proc.once("exit", resolve));
+  }
+
+  return { request, close };
+}

package/scripts/mcp-config-smoke.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, "..");
+const mcpConfig = JSON.parse(readFileSync(join(repoRoot, ".mcp.json"), "utf8"));
+const server = mcpConfig.mcpServers?.["quick-enrich"];
+
+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);
+  });
+}
+
+assert(server?.command, "Missing quick-enrich MCP server command.");
+assert(Array.isArray(server.args), "Missing quick-enrich MCP args.");
+
+const proc = spawn(server.command, server.args, {
+  cwd: repoRoot,
+  env: {
+    ...process.env,
+    ...(server.env || {}),
+    QUICKENRICH_API_KEY: "",
+    QUICKENRICH_TOKEN: "",
+    QUICKENRICH_MCP_CONFIG: join(repoRoot, "tmp", "missing-config.json"),
+    CLAUDE_PLUGIN_ROOT: repoRoot,
+  },
+  stdio: ["pipe", "pipe", "pipe"],
+});
+
+try {
+  sendRpc(proc, 1, "initialize", { protocolVersion: "2024-11-05" });
+  sendRpc(proc, 2, "resources/list");
+  sendRpc(proc, 3, "prompts/list");
+  sendRpc(proc, 4, "tools/list");
+  sendRpc(proc, 5, "tools/call", { name: "quickenrich_auth_status", arguments: {} });
+  sendRpc(proc, 6, "tools/call", {
+    name: "quickenrich_natural_language",
+    arguments: { request: "Batch pull founder leads for example.com and sample.io", execute: false },
+  });
+  sendRpc(proc, 7, "tools/call", {
+    name: "quickenrich_batch_pull_leads",
+    arguments: { companies: [{ company_url: "example.com" }], dry_run: true },
+  });
+  const [, resources, prompts, list, status, nl, dryRun] = await readResponses(proc, [1, 2, 3, 4, 5, 6, 7]);
+  assert(resources.result?.resources?.length === 0, "Expected empty resources.");
+  assert(prompts.result?.prompts?.length === 0, "Expected empty prompts.");
+  const names = list.result?.tools?.map((tool) => tool.name) || [];
+  const toolBytes = Buffer.byteLength(JSON.stringify(list.result?.tools || []), "utf8");
+  assert(names.length <= 9, `Expected compact agent surface, got ${names.length} tools.`);
+  assert(toolBytes <= 8_000, `Expected compact tools/list <=8KB, got ${toolBytes} bytes.`);
+  assert(names.includes("quickenrich_batch_pull_leads"), "Missing batch tool.");
+  assert(names.includes("quickenrich_batch_reverse_email"), "Missing batch reverse-email tool.");
+  assert(names.includes("quickenrich_batch_employee_search"), "Missing batch employee-search tool.");
+  assert(names.includes("quickenrich_pipeline"), "Missing native pipeline tool.");
+  assert(names.includes("quickenrich_lookup_values"), "Missing lookup discovery tool.");
+  assert(!names.includes("quickenrich_employee_search"), "Default config should keep exact-person lookup in full mode.");
+  assert(!names.includes("quickenrich_company_finder"), "Default config should not expose full low-level surface.");
+  assert(!String(status.result?.content?.[0]?.text || "").includes("\n"), "Default MCP tool output should be compact single-line JSON.");
+  const statusPayload = JSON.parse(status.result?.content?.[0]?.text || "{}");
+  assert(statusPayload.configured === false, "Auth status should be unconfigured in smoke.");
+  const nlPayload = JSON.parse(nl.result?.content?.[0]?.text || "{}");
+  assert(nlPayload.plan?.tool === "quickenrich_batch_pull_leads", "NL planner should choose batch tool.");
+  const dryRunPayload = JSON.parse(dryRun.result?.content?.[0]?.text || "{}");
+  assert(dryRunPayload.dryRun === true, "Batch dry-run should not require auth.");
+  console.log(JSON.stringify({ ok: true, tools: names.length }, null, 2));
+} finally {
+  proc.kill();
+}

package/scripts/mcp-live-smoke.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { authStatus } from "./lib/core.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, "..");
+const status = authStatus();
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+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);
+}
+
+const mcpConfig = JSON.parse(readFileSync(join(repoRoot, ".mcp.json"), "utf8"));
+const server = mcpConfig.mcpServers?.["quick-enrich"];
+assert(server?.command, "Missing quick-enrich MCP server command.");
+
+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 = 10_000) {
+  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);
+  });
+}
+
+const proc = spawn(server.command, server.args, {
+  cwd: repoRoot,
+  env: {
+    ...process.env,
+    ...(server.env || {}),
+    CLAUDE_PLUGIN_ROOT: repoRoot,
+  },
+  stdio: ["pipe", "pipe", "pipe"],
+});
+
+try {
+  const email = `qe-mcp-live-${Date.now()}-${Math.random().toString(16).slice(2)}@gmail.com`;
+  sendRpc(proc, 1, "initialize", { protocolVersion: "2024-11-05" });
+  sendRpc(proc, 2, "tools/list");
+  sendRpc(proc, 3, "tools/call", {
+    name: "quickenrich_reverse_email",
+    arguments: {
+      email,
+      response: { mode: "compact", maxOutputChars: 4000 },
+    },
+  });
+  const [, listResponse, callResponse] = await readResponses(proc, [1, 2, 3]);
+  const tools = listResponse.result?.tools?.map((tool) => tool.name) || [];
+  assert(tools.length <= 9, `Expected compact default MCP surface, got ${tools.length}.`);
+  assert(tools.includes("quickenrich_reverse_email"), "Default MCP surface must include reverse-email probe tool.");
+  assert(tools.includes("quickenrich_batch_reverse_email"), "Default MCP surface must include batch reverse-email tool.");
+  assert(tools.includes("quickenrich_batch_employee_search"), "Default MCP surface must include batch employee-search tool.");
+  assert(tools.includes("quickenrich_lookup_values"), "Default MCP surface must include lookup discovery tool.");
+  assert(!callResponse.error, `MCP live tool call failed: ${JSON.stringify(callResponse.error)}`);
+  const payload = JSON.parse(callResponse.result?.content?.[0]?.text || "{}");
+  assert(payload.ok === true, "MCP live reverse-email probe did not return ok=true.");
+  assert(payload.found === false, "Random live smoke email should not be found.");
+  assert(Number(payload.meta?.credits_used || 0) === 0, "MCP live smoke should not use credits.");
+
+  console.log(JSON.stringify({
+    ok: true,
+    skipped: false,
+    tools: tools.length,
+    authProbe: {
+      found: payload.found,
+      meta: payload.meta,
+      rateLimit: payload.rateLimit,
+    },
+  }, null, 2));
+} finally {
+  proc.kill();
+}