@mackody/quickenrich-mcp 0.1.0

package/scripts/ops-contract-smoke.mjs

@@ -0,0 +1,270 @@
+#!/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 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/lookups/country-codes") {
+    res.end(JSON.stringify(["US", "GB"]));
+    return;
+  }
+  if (url.pathname === "/api/lookups/industries") {
+    res.end(JSON.stringify(["Computer Software"]));
+    return;
+  }
+  if (url.pathname === "/api/lookups/employee-ranges") {
+    res.end(JSON.stringify(["51-200"]));
+    return;
+  }
+  if (url.pathname === "/api/lookups/revenue-ranges") {
+    res.end(JSON.stringify(["10M-50M"]));
+    return;
+  }
+  if (url.pathname === "/api/lookups/company-services") {
+    res.end(JSON.stringify([{ service: "DevOps", count: 10 }, { service: "AWS", count: 7 }]));
+    return;
+  }
+
+  if (url.pathname === "/api/employees/email-search") {
+    const email = url.searchParams.get("email");
+    res.end(JSON.stringify({
+      success: true,
+      data: {
+        first_name: email?.startsWith("b") ? "Bee" : "Ada",
+        last_name: "Tester",
+        email,
+        company_url: "example.com",
+      },
+      meta: { credits_used: 1, remaining_credits: 800 },
+    }));
+    return;
+  }
+
+  if (url.pathname === "/api/employees/dataset-search") {
+    const companyUrl = url.searchParams.get("company_url");
+    res.end(JSON.stringify({
+      success: true,
+      data: [{
+        first_name: "Dana",
+        last_name: "Domain",
+        title: url.searchParams.get("title") || "Founder",
+        email: `founder@${companyUrl}`,
+        company_url: companyUrl,
+      }],
+      meta: { page: 1, per_page: 1, total: 1, last_page: 1, credits_used: 1, remaining_credits: 799 },
+    }));
+    return;
+  }
+
+  if (url.pathname === "/api/employees/contact-finder") {
+    const page = Number(body?.page || 1);
+    res.end(JSON.stringify({
+      success: true,
+      data: [{
+        first_name: page === 1 ? "Page" : "Second",
+        last_name: "Contact",
+        title: page === 1 ? "CEO" : "CFO",
+        employee_linkedin: `https://linkedin.com/in/contact-${page}`,
+        company_url: "resume-contact.com",
+        has_email: true,
+        has_phone: false,
+      }],
+      meta: { page, per_page: body?.per_page || 10, total: 2, last_page: 2, credits_used: 0, remaining_credits: 800 },
+    }));
+    return;
+  }
+
+  if (url.pathname === "/api/companies/company-finder") {
+    res.end(JSON.stringify({
+      success: true,
+      data: [],
+      meta: { page: body?.page || 1, per_page: body?.per_page || 10, total: 0, last_page: 1, credits_used: 0, remaining_credits: 800 },
+    }));
+    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 = "ops-test-key";
+  process.env.QUICKENRICH_API_BASE_URL = `http://127.0.0.1:${port}`;
+  const client = createClient();
+
+  const reverse = await callQuickEnrichTool("quickenrich_batch_reverse_email", {
+    emails: ["a@example.com", "b@example.com", "c@example.com"],
+    resume_state: { completed: ["a@example.com"] },
+    max_credits: 1,
+    response: { mode: "full" },
+  }, client);
+
+  const reverseRequests = requests.filter((entry) => entry.path === "/api/employees/email-search");
+  assert(reverse.requestCount === 1, `Expected one new reverse-email request, got ${reverse.requestCount}.`);
+  assert(reverseRequests[0].query.email === "b@example.com", `Expected resume to skip a@example.com, got ${reverseRequests[0].query.email}.`);
+  assert(reverse.resumeState.completed.includes("a@example.com"), "Resume state should retain prior completed email.");
+  assert(reverse.resumeState.completed.includes("b@example.com"), "Resume state should include newly completed email.");
+  assert(reverse.resumeState.pending.includes("c@example.com"), "Resume state should report pending email after credit stop.");
+
+  const reverseRequestsBeforeInvalid = requests.filter((entry) => entry.path === "/api/employees/email-search").length;
+  const invalidReverse = await callQuickEnrichTool("quickenrich_batch_reverse_email", {
+    emails: ["bad@example.invalid", "prior-failed@example.com"],
+    resume_state: { failed: ["prior-failed@example.com"] },
+    response: { mode: "full" },
+  }, client);
+  const reverseRequestsAfterInvalid = requests.filter((entry) => entry.path === "/api/employees/email-search").length;
+  assert(invalidReverse.ok === false, "Invalid reverse-email inputs should fail closed.");
+  assert(invalidReverse.requestCount === 0, `Invalid/prior-failed reverse-email batch should make 0 requests, got ${invalidReverse.requestCount}.`);
+  assert(reverseRequestsAfterInvalid === reverseRequestsBeforeInvalid, "Invalid/prior-failed reverse-email batch should not call vendor API.");
+  assert(invalidReverse.errors.some((entry) => entry.code === "invalid_email"), "Invalid reverse-email batch should report invalid_email.");
+  assert(invalidReverse.resumeState.failed.includes("bad@example.invalid"), "Invalid email should be marked failed in resume state.");
+  assert(invalidReverse.resumeState.failed.includes("prior-failed@example.com"), "Prior failed email should remain failed in resume state.");
+  assert(!invalidReverse.resumeState.pending.includes("prior-failed@example.com"), "Prior failed email should not remain pending.");
+
+  const domainResume = await callQuickEnrichTool("quickenrich_batch_pull_leads", {
+    mode: "domain_search",
+    companies: [
+      { company_url: "resume-skip.com", title: "Founder" },
+      { company_url: "resume-go.com", title: "Founder" },
+      { company_url: "resume-pending.com", title: "Founder" },
+    ],
+    resume_state: { completed: ["resume-skip.com|founder"] },
+    max_credits: 1,
+    per_page: 1,
+    pages_per_company: 1,
+    response: { mode: "full" },
+  }, client);
+  const domainRequests = requests.filter((entry) => entry.path === "/api/employees/dataset-search");
+  assert(domainResume.requestCount === 1, `Expected one domain request before credit stop, got ${domainResume.requestCount}.`);
+  assert(domainRequests[0].query.company_url === "resume-go.com", `Expected resume to skip resume-skip.com, got ${domainRequests[0].query.company_url}.`);
+  assert(domainResume.resumeState.completed.includes("resume-skip.com|founder"), "Domain resume should retain prior completed key.");
+  assert(domainResume.resumeState.completed.includes("resume-go.com|founder"), "Domain resume should include newly completed key.");
+  assert(domainResume.resumeState.pending.includes("resume-pending.com|founder"), "Domain resume should leave credit-stopped company pending.");
+
+  const directContactRequestsBefore = requests.filter((entry) => entry.path === "/api/employees/contact-finder").length;
+  const invalidDirectContacts = await callQuickEnrichTool("quickenrich_contact_finder", {
+    filters: { country_code: ["ZZ"] },
+    validate_filters: true,
+    response: { mode: "full" },
+  }, client);
+  const directContactRequestsAfter = requests.filter((entry) => entry.path === "/api/employees/contact-finder").length;
+  assert(invalidDirectContacts.ok === false, "Standalone contact finder should fail invalid filters.");
+  assert(directContactRequestsAfter === directContactRequestsBefore, "Invalid standalone contact finder should not call vendor API.");
+  assert(invalidDirectContacts.validation?.errors?.some((entry) => entry.field === "country_code"), "Standalone contact finder should report invalid country_code.");
+
+  const contactResumeFirst = await callQuickEnrichTool("quickenrich_batch_pull_leads", {
+    mode: "contact_finder",
+    filters: { country_code: ["US"] },
+    pages_per_company: 2,
+    per_page: 1,
+    max_results: 1,
+    response: { mode: "full" },
+  }, client);
+  assert(contactResumeFirst.requestCount === 1, `Expected first contact resume run to request one page, got ${contactResumeFirst.requestCount}.`);
+  assert(contactResumeFirst.resumeState.pendingCount === 1, "First contact resume run should leave page 2 pending.");
+  assert(contactResumeFirst.resumeState.nextPage === 2, `Expected contact resume nextPage=2, got ${contactResumeFirst.resumeState.nextPage}.`);
+
+  const contactRequestsBeforeResume = requests.filter((entry) => entry.path === "/api/employees/contact-finder").length;
+  const contactResumeSecond = await callQuickEnrichTool("quickenrich_batch_pull_leads", {
+    mode: "contact_finder",
+    filters: { country_code: ["US"] },
+    pages_per_company: 2,
+    per_page: 1,
+    max_results: 2,
+    resume_state: contactResumeFirst.resumeState,
+    response: { mode: "full" },
+  }, client);
+  const resumedContactRequests = requests.filter((entry) => entry.path === "/api/employees/contact-finder").slice(contactRequestsBeforeResume);
+  assert(contactResumeSecond.requestCount === 1, `Expected resumed contact finder to request one page, got ${contactResumeSecond.requestCount}.`);
+  assert(resumedContactRequests[0].body.page === 2, `Expected resumed contact finder to start at page 2, got ${resumedContactRequests[0].body.page}.`);
+  assert(contactResumeSecond.resumeState.pendingCount === 0, "Resumed contact finder should have no pending pages.");
+
+  const contactRequestsBeforeStaleResume = requests.filter((entry) => entry.path === "/api/employees/contact-finder").length;
+  const contactStaleResume = await callQuickEnrichTool("quickenrich_batch_pull_leads", {
+    mode: "contact_finder",
+    filters: { country_code: ["US"], city: ["Austin"] },
+    pages_per_company: 2,
+    per_page: 1,
+    max_results: 1,
+    resume_state: contactResumeFirst.resumeState,
+    response: { mode: "full" },
+  }, client);
+  const staleResumeRequests = requests.filter((entry) => entry.path === "/api/employees/contact-finder").slice(contactRequestsBeforeStaleResume);
+  assert(contactStaleResume.requestCount === 1, `Expected stale resume run to request one page, got ${contactStaleResume.requestCount}.`);
+  assert(staleResumeRequests[0].body.page === 1, `Fingerprint-mismatched resume should restart at page 1, got ${staleResumeRequests[0].body.page}.`);
+  assert(contactStaleResume.resumeState.fingerprint !== contactResumeFirst.resumeState.fingerprint, "Changed filters should produce a new finder fingerprint.");
+
+  const validContacts = await callQuickEnrichTool("quickenrich_batch_pull_leads", {
+    mode: "contact_finder",
+    filters: {
+      country_code: ["US"],
+      industry_linkedin: ["Computer Software"],
+      number_of_employees: ["51-200"],
+      revenue: ["10M-50M"],
+    },
+    validate_filters: true,
+    response: { mode: "full" },
+  }, client);
+  assert(validContacts.ok === true, "Valid contact finder filters should pass validation.");
+  assert(validContacts.validation?.ok === true, "Validation metadata should report ok=true.");
+
+  const directCompanyRequestsBefore = requests.filter((entry) => entry.path === "/api/companies/company-finder").length;
+  const invalidDirectCompanies = await callQuickEnrichTool("quickenrich_company_finder", {
+    filters: {
+      services: ["MadeUpService"],
+      country_code: ["ZZ"],
+    },
+    validate_filters: true,
+    response: { mode: "full" },
+  }, client);
+  const directCompanyRequestsAfter = requests.filter((entry) => entry.path === "/api/companies/company-finder").length;
+  assert(invalidDirectCompanies.ok === false, "Standalone company finder should fail invalid filters.");
+  assert(directCompanyRequestsAfter === directCompanyRequestsBefore, "Invalid standalone company finder should not call vendor API.");
+  assert(invalidDirectCompanies.validation?.errors?.some((entry) => entry.field === "services"), "Standalone company finder should report invalid services.");
+
+  const invalidCompanies = await callQuickEnrichTool("quickenrich_batch_pull_leads", {
+    mode: "company_finder",
+    filters: {
+      services: ["MadeUpService"],
+      country_code: ["ZZ"],
+    },
+    validate_filters: true,
+    response: { mode: "full" },
+  }, client);
+  assert(invalidCompanies.ok === false, "Invalid company finder filters should fail closed before API call.");
+  assert(invalidCompanies.validation?.ok === false, "Validation metadata should report ok=false.");
+  assert(invalidCompanies.validation.errors.some((entry) => entry.field === "services"), "Validation should flag invalid services.");
+  assert(invalidCompanies.validation.errors.some((entry) => entry.field === "country_code"), "Validation should flag invalid country_code.");
+
+  const companyRequests = requests.filter((entry) => entry.path === "/api/companies/company-finder");
+  assert(companyRequests.length === 0, "Invalid validated company finder should not call vendor API.");
+
+  console.log(JSON.stringify({
+    ok: true,
+    reverseRequests: reverse.requestCount,
+    invalidRequests: invalidReverse.requestCount,
+    domainRequests: domainResume.requestCount,
+    contactResumeNextPage: contactResumeFirst.resumeState.nextPage,
+    pending: reverse.resumeState.pending,
+    validationErrors: invalidCompanies.validation.errors.length,
+  }, null, 2));
+} finally {
+  server.close();
+}

package/scripts/paged-finder-floor-smoke.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+import { createServer } from "node:http";
+import { performance } from "node:perf_hooks";
+import { callQuickEnrichTool, createClient } from "./lib/core.mjs";
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+let active = 0;
+let maxActive = 0;
+const requests = [];
+
+const server = createServer(async (req, res) => {
+  active += 1;
+  maxActive = Math.max(maxActive, active);
+  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) : {};
+    const url = new URL(req.url, "http://127.0.0.1");
+    requests.push({ path: url.pathname, body });
+    await sleep(60);
+    res.setHeader("content-type", "application/json");
+    if (url.pathname === "/api/employees/contact-finder") {
+      const page = Number(body.page || 1);
+      res.end(JSON.stringify({
+        success: true,
+        data: [{
+          first_name: `Page${page}`,
+          last_name: "Contact",
+          title: page === 1 ? "CEO" : "Founder",
+          employee_linkedin: `https://linkedin.com/in/page-${page}`,
+          company_url: "floor.example",
+          company_name: "Floor Inc",
+          has_email: true,
+        }],
+        meta: { page, per_page: 1, total: 4, last_page: 4, credits_used: 0, remaining_credits: 9999 },
+      }));
+      return;
+    }
+    res.statusCode = 404;
+    res.end(JSON.stringify({ error: "not found" }));
+  } finally {
+    active -= 1;
+  }
+});
+
+await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+const { port } = server.address();
+
+try {
+  process.env.QUICKENRICH_API_KEY = "paged-floor-key";
+  process.env.QUICKENRICH_API_BASE_URL = `http://127.0.0.1:${port}`;
+  const client = createClient();
+
+  const startedAt = performance.now();
+  const result = await callQuickEnrichTool("quickenrich_batch_pull_leads", {
+    mode: "contact_finder",
+    filters: { company_name: ["Floor Inc"] },
+    pages_per_company: 4,
+    per_page: 1,
+    max_results: 4,
+    concurrency: 4,
+    requests_per_minute: 120,
+    burst_size: 4,
+    response: { mode: "full" },
+  }, client);
+  const durationMs = performance.now() - startedAt;
+
+  const contactRequests = requests.filter((entry) => entry.path === "/api/employees/contact-finder");
+  assert(result.ok === true, "Paged finder floor batch should succeed.");
+  assert(result.requestCount === 4, `Expected 4 finder requests, got ${result.requestCount}.`);
+  assert(result.leadCount === 4, `Expected 4 finder records, got ${result.leadCount}.`);
+  assert(contactRequests.map((entry) => entry.body.page).join(",") === "1,2,3,4", "Finder should request pages 1 through 4.");
+  assert(maxActive >= 2, `Finder auto-pagination should fan out after page 1, maxActive=${maxActive}.`);
+  assert(durationMs < 220, `Finder auto-pagination should stay near the 2-hop floor, got ${durationMs.toFixed(1)}ms.`);
+
+  console.log(JSON.stringify({
+    ok: true,
+    durationMs: Math.round(durationMs),
+    requestCount: result.requestCount,
+    maxActive,
+  }, null, 2));
+} finally {
+  server.close();
+}

package/scripts/perf-contract-smoke.mjs

@@ -0,0 +1,111 @@
+#!/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);
+}
+
+let active = 0;
+let maxActive = 0;
+const requests = [];
+
+const server = createServer(async (req, res) => {
+  active += 1;
+  maxActive = Math.max(maxActive, active);
+  try {
+    await new Promise((resolve) => setTimeout(resolve, 25));
+    const url = new URL(req.url, "http://127.0.0.1");
+    requests.push({ path: url.pathname, query: Object.fromEntries(url.searchParams.entries()) });
+    res.setHeader("content-type", "application/json");
+    if (url.pathname === "/api/employees/dataset-search") {
+      res.end(JSON.stringify({
+        success: true,
+        data: [
+          {
+            first_name: "Ada",
+            last_name: "Lovelace",
+            title: "Founder",
+            email: "N/A",
+            employee_linkedin: `https://linkedin.com/in/${url.searchParams.get("company_url")}-ada`,
+            has_email: false,
+            has_phone: false,
+            company_url: url.searchParams.get("company_url"),
+            company_name: "Example",
+          },
+        ],
+        meta: { page: Number(url.searchParams.get("page") || 1), per_page: 20, total: 1, last_page: 1, credits_used: 1, remaining_credits: 9990 },
+      }));
+      return;
+    }
+    res.statusCode = 404;
+    res.end(JSON.stringify({ error: "not found" }));
+  } finally {
+    active -= 1;
+  }
+});
+
+await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+const { port } = server.address();
+
+try {
+  process.env.QUICKENRICH_API_KEY = "perf-test-key";
+  process.env.QUICKENRICH_API_BASE_URL = `http://127.0.0.1:${port}`;
+  const client = createClient();
+  const result = await callQuickEnrichTool("quickenrich_batch_pull_leads", {
+    companies: [
+      { company_url: "example.com", title: "Founder" },
+      { company_url: "example.com", title: "Founder" },
+      { company_url: "sample.io", title: "Founder" },
+      { company_url: "sample.io", title: "Founder" },
+    ],
+    pages_per_company: 1,
+    concurrency: 2,
+    response: { mode: "full" },
+  }, client);
+
+  const domainRequests = requests.filter((entry) => entry.path === "/api/employees/dataset-search");
+  assert(result.ok === true, "Batch should succeed.");
+  assert(domainRequests.length === 2, `Expected coalesced domain requests for 2 unique company/title/page keys, got ${domainRequests.length}.`);
+  assert(result.requestCount === 2, `Expected requestCount=2 after coalescing, got ${result.requestCount}.`);
+  assert(result.creditsUsed === 2, `Expected creditsUsed=2 after coalescing, got ${result.creditsUsed}.`);
+  assert(result.remainingCredits === 9990, `Expected remainingCredits=9990, got ${result.remainingCredits}.`);
+  assert(result.leadCount === 2, `Expected 2 deduped leads, got ${result.leadCount}.`);
+  assert(result.leads.every((lead) => lead.email !== "N/A"), "Placeholder email values must be normalized away.");
+  assert(maxActive <= 2, `Concurrency cap failed: maxActive=${maxActive}.`);
+
+  maxActive = 0;
+  const limitedStart = requests.length;
+  const limited = await callQuickEnrichTool("quickenrich_batch_pull_leads", {
+    companies: [
+      { company_url: "credit-one.example", title: "Founder" },
+      { company_url: "credit-two.example", title: "Founder" },
+      { company_url: "credit-three.example", title: "Founder" },
+      { company_url: "credit-four.example", title: "Founder" },
+    ],
+    pages_per_company: 1,
+    concurrency: 4,
+    max_credits: 2,
+    response: { mode: "full" },
+  }, client);
+  const limitedRequests = requests.slice(limitedStart).filter((entry) => entry.path === "/api/employees/dataset-search");
+  assert(limited.ok === true, "Credit-limited batch should succeed with pending work, not fail.");
+  assert(limited.requestCount === 2, `Expected max_credits=2 to start two paid requests, got ${limited.requestCount}.`);
+  assert(limitedRequests.length === 2, `Expected two vendor requests under max_credits=2, got ${limitedRequests.length}.`);
+  assert(limited.creditsUsed === 2, `Expected creditsUsed=2 under max_credits=2, got ${limited.creditsUsed}.`);
+  assert(limited.creditBudget?.reserved === 0, `Credit reservations should settle to zero, got ${limited.creditBudget?.reserved}.`);
+  assert(limited.creditBudget?.remaining === 0, `Expected no remaining credit budget, got ${limited.creditBudget?.remaining}.`);
+  assert(limited.resumeState?.pendingCount === 2, `Expected two pending companies after credit stop, got ${limited.resumeState?.pendingCount}.`);
+  assert(maxActive >= 2, `Credit-limited paid lane should retain safe parallelism, maxActive=${maxActive}.`);
+
+  console.log(JSON.stringify({
+    ok: true,
+    requests: domainRequests.length,
+    maxActive,
+    limitedRequests: limitedRequests.length,
+    limitedPending: limited.resumeState.pendingCount,
+  }, null, 2));
+} finally {
+  server.close();
+}

package/scripts/quickenrich-agent-docs.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+const MANAGED_LINES = [
+  "- Quick Enrich MCP: call `quickenrich_agent_graph` first, then prefer `quickenrich_pipeline` or batch tools with `input_file`, `output_file`, `resume_file`, `projection`, and `max_credits`. <!-- quickenrich-mcp:line1 -->",
+  "- Quick Enrich MCP auth: run `quickenrich-token set` once and `quickenrich-token doctor` before live runs; never paste API keys into prompts. <!-- quickenrich-mcp:line2 -->",
+];
+
+function usage() {
+  return `Usage:
+  quickenrich-agent-docs install [--cwd <path>] [--json] [--dry-run]
+  quickenrich-agent-docs uninstall [--cwd <path>] [--json] [--dry-run]
+`;
+}
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--json") args.json = true;
+    else if (arg === "--dry-run") args.dryRun = true;
+    else if (arg === "--cwd") {
+      args.cwd = argv[index + 1];
+      index += 1;
+    } else args._.push(arg);
+  }
+  return args;
+}
+
+function targetFiles(cwd) {
+  return [
+    firstExisting(cwd, ["CLAUDE.md", "Claude.md", "claude.md"]) || "CLAUDE.md",
+    firstExisting(cwd, ["AGENTS.md", "agents.md", "Agents.md"]) || "AGENTS.md",
+  ].map((name) => join(cwd, name));
+}
+
+function firstExisting(cwd, names) {
+  return names.find((name) => existsSync(join(cwd, name)));
+}
+
+function stripManagedLines(text) {
+  return String(text || "")
+    .split(/\r?\n/)
+    .filter((line) => !line.includes("<!-- quickenrich-mcp:line"))
+    .join("\n")
+    .replace(/\n+$/, "");
+}
+
+function installFile(path, dryRun = false) {
+  const before = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const stripped = stripManagedLines(before);
+  const next = `${stripped}${stripped ? "\n\n" : ""}${MANAGED_LINES.join("\n")}\n`;
+  if (!dryRun && next !== before) writeFileSync(path, next, { mode: 0o644 });
+  return {
+    path,
+    existed: Boolean(before),
+    changed: next !== before,
+    managedLines: MANAGED_LINES.length,
+  };
+}
+
+function uninstallFile(path, dryRun = false) {
+  if (!existsSync(path)) {
+    return { path, existed: false, changed: false, managedLines: 0 };
+  }
+  const before = readFileSync(path, "utf8");
+  const stripped = stripManagedLines(before);
+  const next = stripped ? `${stripped}\n` : "";
+  if (!dryRun && next !== before) writeFileSync(path, next, { mode: 0o644 });
+  return {
+    path,
+    existed: true,
+    changed: next !== before,
+    managedLines: 0,
+  };
+}
+
+function print(payload, json = false) {
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(`${payload.action}: ${payload.files.length} files`);
+  for (const file of payload.files) {
+    console.log(`${file.changed ? "updated" : "unchanged"} ${file.path}`);
+  }
+}
+
+const args = parseArgs(process.argv.slice(2));
+const action = args._[0] || "install";
+const cwd = resolve(args.cwd || process.cwd());
+
+try {
+  if (action === "install") {
+    print({ ok: true, action, cwd, dryRun: Boolean(args.dryRun), files: targetFiles(cwd).map((path) => installFile(path, args.dryRun)) }, Boolean(args.json));
+  } else if (action === "uninstall" || action === "remove") {
+    print({ ok: true, action: "uninstall", cwd, dryRun: Boolean(args.dryRun), files: targetFiles(cwd).map((path) => uninstallFile(path, args.dryRun)) }, Boolean(args.json));
+  } else if (action === "help" || action === "--help" || action === "-h") {
+    process.stdout.write(usage());
+  } else {
+    process.stderr.write(usage());
+    process.exitCode = 2;
+  }
+} catch (error) {
+  console.error(error.message || String(error));
+  process.exitCode = 1;
+}