@mackody/quickenrich-mcp 0.1.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,39 @@
+{
+  "name": "quickenrich-mcp",
+  "version": "0.1.0",
+  "description": "Standalone MCP server and CLI for Quick Enrich lead enrichment APIs.",
+  "author": {
+    "name": "Cody Robertson"
+  },
+  "homepage": "https://app.quickenrich.io/docs",
+  "repository": "https://github.com/codyrobertson/quickenrich-mcp",
+  "license": "UNLICENSED",
+  "keywords": [
+    "quickenrich",
+    "quick-enrich",
+    "mcp",
+    "lead-enrichment",
+    "prospecting"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Quick Enrich MCP",
+    "shortDescription": "Use Quick Enrich APIs through a compact, batch-ready MCP server.",
+    "longDescription": "Quick Enrich MCP connects Codex and other MCP clients to Quick Enrich's documented APIs with secure local token storage, bearer-token auth, compact agent envelopes, exact person enrichment, reverse-email lookup, phone lookup, domain lead pulls, contact/company finder calls, and credit-aware batch lead pulling. It is a standalone repo and does not depend on PLM/Hermes runtime code.",
+    "developerName": "Cody Robertson",
+    "category": "Productivity",
+    "capabilities": [
+      "Read",
+      "Automation"
+    ],
+    "websiteURL": "https://app.quickenrich.io/docs",
+    "defaultPrompt": [
+      "Check Quick Enrich MCP auth status.",
+      "Pull founder leads for these company domains.",
+      "Find a verified email from a LinkedIn profile."
+    ],
+    "brandColor": "#2563EB",
+    "screenshots": []
+  },
+  "mcpServers": "./.mcp.json"
+}

package/.env.example

@@ -0,0 +1,17 @@
+QUICKENRICH_API_KEY=your-quickenrich-key
+QUICKENRICH_MCP_SERVER_NAME=quick-enrich
+QUICKENRICH_MCP_TOOL_MODE=agent
+QUICKENRICH_MCP_RESPONSE_MODE=compact
+QUICKENRICH_API_BASE_URL=https://app.quickenrich.io
+QUICKENRICH_API_TIMEOUT_MS=30000
+QUICKENRICH_API_RETRY_COUNT=2
+QUICKENRICH_API_RETRY_BASE_MS=250
+QUICKENRICH_API_USE_FETCH=0
+QUICKENRICH_MCP_MAX_OUTPUT_CHARS=12000
+QUICKENRICH_DOMAIN_SEARCH_REQUESTS_PER_MINUTE=300
+QUICKENRICH_DOMAIN_SEARCH_BURST_SIZE=8
+QUICKENRICH_EMPLOYEE_SEARCH_BURST_SIZE=16
+QUICKENRICH_PHONE_SEARCH_BURST_SIZE=16
+QUICKENRICH_REVERSE_EMAIL_BURST_SIZE=16
+QUICKENRICH_CONTACT_FINDER_BURST_SIZE=4
+QUICKENRICH_COMPANY_FINDER_BURST_SIZE=4

package/.mcp.json

@@ -0,0 +1,17 @@
+{
+  "mcpServers": {
+    "quick-enrich": {
+      "command": "sh",
+      "args": [
+        "-lc",
+        "exec node \"${CLAUDE_PLUGIN_ROOT:-.}/scripts/quickenrich-mcp.mjs\""
+      ],
+      "cwd": ".",
+      "env": {
+        "QUICKENRICH_MCP_SERVER_NAME": "quick-enrich",
+        "QUICKENRICH_MCP_TOOL_MODE": "agent",
+        "QUICKENRICH_MCP_RESPONSE_MODE": "compact"
+      }
+    }
+  }
+}

package/README.md

@@ -0,0 +1,283 @@
+# Quick Enrich MCP
+
+Standalone MCP server for Quick Enrich's documented APIs. It is built for internal prospecting workflows: secure local API-key storage, exact person enrichment, reverse-email/phone lookup, domain lead pulls, contact/company finder calls, and compact batch envelopes for agent use.
+
+Docs source: [Quick Enrich API Documentation](https://app.quickenrich.io/docs).
+
+## Install
+
+```bash
+npm install
+npm run test
+```
+
+Package/agent setup after install:
+
+```bash
+quickenrich-token set
+quickenrich-token doctor
+quickenrich-agent-docs install --cwd /path/to/agent-project
+```
+
+`quickenrich-agent-docs install` appends exactly two managed Quick Enrich how-to-use lines to `CLAUDE.md` and `AGENTS.md` in the target project. It is idempotent. Remove those managed lines with:
+
+```bash
+quickenrich-agent-docs uninstall --cwd /path/to/agent-project
+```
+
+Set an API key with either an environment variable:
+
+```bash
+export QUICKENRICH_API_KEY=...
+```
+
+or the local secure config:
+
+```bash
+node scripts/quickenrich-token.mjs set
+node scripts/quickenrich-token.mjs status
+```
+
+The token CLI stores the key at `~/.config/quickenrich-mcp/config.json` with `0600` permissions. Env vars override the config file.
+
+## MCP
+
+Use the bundled `.mcp.json` or run directly:
+
+```bash
+node scripts/quickenrich-mcp.mjs
+```
+
+MCP server alias: `quick-enrich`
+
+Default agent tools:
+
+- `quickenrich_auth_status`
+- `quickenrich_agent_graph`
+- `quickenrich_natural_language`
+- `quickenrich_pipeline`
+- `quickenrich_batch_pull_leads`
+- `quickenrich_batch_reverse_email`
+- `quickenrich_batch_employee_search`
+- `quickenrich_reverse_email`
+- `quickenrich_lookup_values`
+
+Full-mode tools (`QUICKENRICH_MCP_TOOL_MODE=full`) also expose:
+
+- `quickenrich_pipeline`
+- `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_batch_pull_leads`
+- `quickenrich_lookup_values`
+
+Use `QUICKENRICH_MCP_TOOL_MODE=minimal` for only auth, graph, natural-language planning, and batch pull. Use `QUICKENRICH_MCP_TOOL_MODE=full` when you want every low-level endpoint and verbose schema descriptions.
+
+Default agent mode intentionally emits slim schemas and short tool descriptions so cold agents do not spend context on prose they can recover from `quickenrich_agent_graph`. The default `tools/list` surface is budgeted under 8 KB and includes lookup discovery because finder filters need valid country, industry, employee-range, revenue-range, and service values.
+
+Responses default to compact mode with a 12 KB output budget, 12 array items, 48 object keys, depth 4, and 240-character strings. Pass `response: { "mode": "full", "maxOutputChars": 64000 }` for rawer output, or `response: { "mode": "meta" }` for shape-only output.
+
+MCP tool text is emitted as single-line JSON by default to reduce stdio bytes and token overhead. Set `QUICKENRICH_MCP_PRETTY_JSON=1` only when debugging by hand.
+
+The API client uses a native keep-alive HTTP transport by default for lower batch overhead. Set `QUICKENRICH_API_USE_FETCH=1` to force the global `fetch` transport while debugging.
+
+## Batch Pull
+
+Example MCP arguments:
+
+```json
+{
+  "companies": [
+    { "company_url": "example.com", "title": "Founder" },
+    { "company_url": "shop.example", "title": "CEO" }
+  ],
+  "per_company_limit": 20,
+  "pages_per_company": 1,
+  "has_email": true,
+  "concurrency": 8,
+  "requests_per_minute": 300,
+  "burst_size": 1,
+  "max_credits": 100,
+  "export_format": "jsonl",
+  "enrich_contacts": false
+}
+```
+
+Native batch surfaces:
+
+- `quickenrich_pipeline`: native company-finder to domain-search workflow with durable output and projected rows.
+- `quickenrich_batch_pull_leads`: domain lead pulls plus Contact Finder and Company Finder batch modes.
+- `quickenrich_batch_reverse_email`: deduped reverse-email lookup from `emails`, `input_csv`, or `input_jsonl`.
+- `quickenrich_batch_employee_search`: exact-person lookup from `persons`, `input_csv`, or `input_jsonl`, with optional phone enrichment.
+
+Batch-native controls:
+
+- `max_credits`: stops starting new paid calls after the budget is reached. Paid lanes reserve estimated credits before starting work, so they keep safe parallelism without overspending the caller's budget.
+- `resume_state`: skips previously completed or failed keys and returns `resumeState` with `completed`, `failed`, and `pending` keys for continuing large runs.
+- `input_file`: local CSV/JSONL path or `file://` URL for large jobs without pasting rows into prompts.
+- `output_file`: local JSONL/CSV artifact path for results.
+- `resume_file`: local JSON checkpoint merged with `resume_state` and updated as work completes.
+- `projection`: `people`, `companies`, `emails`, `phones`, `ids`, or `full` for token-efficient row shape.
+- `cache_mode`: `off`, `read`, `write`, `readwrite`, `refresh`, or `cache_only` for local duplicate-spend avoidance.
+- `credit_ledger`: appends a local JSONL credit/request ledger when enabled.
+- Finder-mode resumes include a filter `fingerprint` and `nextPage`; pass the returned `resumeState` back unchanged to continue a large Contact Finder or Company Finder run.
+- Reverse-email batches locally fail invalid/reserved email domains before calling Quick Enrich.
+- `validate_filters`: validates lookup-backed Contact Finder and Company Finder fields before calling vendor search endpoints.
+- `requests_per_minute` and `burst_size`: endpoint-specific pacing controls. Env defaults are also supported, e.g. `QUICKENRICH_EMPLOYEE_SEARCH_REQUESTS_PER_MINUTE`.
+- `export_format`: `jsonl` or `csv`; returned inline as `export.text`.
+- `input_csv` / `input_jsonl`: native text ingestion for domain-search, reverse-email, and exact-person batch tools.
+- `response:{mode:"meta"}` keeps scalar metrics and collection lengths while omitting records for low-token planning passes.
+- `max_results`: target result count for Contact Finder and Company Finder pagination.
+- Finder auto-pagination runs page 1 first to discover `last_page`, then fans out remaining safe pages up to `concurrency`. Credit-limited Company Finder fanout is capped by the remaining reserved budget.
+
+Typed finder builders:
+
+```json
+{
+  "mode": "contact_finder",
+  "filters": {
+    "company_name": { "include": ["Acme"], "exclude": [] },
+    "country_code": ["US"],
+    "title": { "include": ["CEO"], "exclude": ["Intern"] }
+  },
+  "has_email": true,
+  "has_phone": true,
+  "max_results": 100,
+  "per_page": 50
+}
+```
+
+Company Finder uses company-shaped output with `domain`, `linkedin_url`, `services`, snippets, firmographics, and contact fields preserved. Supported typed company filters include `home_page_text`, `bio_li`, `services`, `industry`, `number_of_employees`, `revenue`, `country_code`, `city`, `company_name`, and `company_url`.
+
+Lookup-backed validation covers Contact Finder `country_code`, `industry_linkedin`, `number_of_employees`, and `revenue`; Company Finder `services`, `industry`, `country_code`, `number_of_employees`, and `revenue`. Validation is opt-in because public lookup endpoints are external dependencies; successful lookup reads are cached in-process.
+
+Agent graph:
+
+- `quickenrich_agent_graph` returns `endpointCoverage`, `agentRouting`, `budgetMath`, `lookupHints`, `inputHints`, and `envelopePolicy` so cold agents can choose native batch tools without reading docs.
+- `quickenrich_natural_language` routes CSV/JSONL reverse-email, exact-person, domain-search, finder, and resume intents to the native batch tools. It returns `requires` for missing payloads and refuses `execute=true` when required fields are absent.
+
+Credit/rate notes from the current docs:
+
+- Search, phone, reverse-email: 1000 requests/minute.
+- Domain search: 300 requests/minute, up to 20 contacts/page.
+- Contact finder and company finder: 120 requests/minute.
+- Contact finder is discovery-only and does not return email/phone values; use `enrich_contacts: true` only when you intentionally want follow-up employee/phone lookups.
+- For domain search, use `has_email: true` when you only want contacts with an email signal. This is useful before paid enrichment and keeps agent envelopes cleaner.
+
+Domain batch pulls use a shared token-bucket limiter per MCP client plus a rolling 60-second cap. The default is Quick Enrich's published `requests_per_minute=300` with `burst_size=8`, so small deduped batches start immediately while sustained traffic still refills at one token every 200 ms without exceeding the rolling minute ceiling. Set `burst_size:1` for strict one-at-a-time pacing, or set a higher lane only with provider approval:
+
+```bash
+QUICKENRICH_DOMAIN_SEARCH_REQUESTS_PER_MINUTE=300 \
+QUICKENRICH_DOMAIN_SEARCH_BURST_SIZE=8 \
+node scripts/quickenrich-mcp.mjs
+```
+
+The batch result includes `throttle` metadata showing the active ceiling, burst, total acquired slots, and sleep time. Repeated calls through the same MCP process share buckets, so follow-up batches do not reset the burst. If a final 429 includes `Retry-After`, the limiter cools down before later starts.
+
+Use `throttle_scope:"shared"` to coordinate the rolling request ceiling across multiple local MCP processes through a small local file lock. This does not bypass published Quick Enrich limits; it keeps separate agents inside the same ceiling.
+
+Other batch lanes also use small compliant default bursts: employee search, phone search, and reverse email default to `burst_size=16`; Contact Finder and Company Finder default to `burst_size=4`.
+
+## Smoke Tests
+
+```bash
+npm run test
+```
+
+The default suite includes:
+
+- agent docs install/uninstall smoke
+- token CLI config and redaction smoke
+- offline contract smoke
+- mocked Quick Enrich API smoke
+- duplicate-request coalescing and concurrency smoke
+- native batch capabilities smoke
+- resumability and finder-validation ops smoke
+- request pacing/rate-limit contract smoke
+- shared token-bucket burst contract smoke
+- reverse-email high-concurrency floor smoke
+- paged finder floor smoke
+- serialization floor smoke
+- local direct-vs-MCP floor benchmark
+- benchmark fixture/comparison contract smoke
+- default agent-surface smoke
+- compact envelope budget smoke
+- cold-agent envelope/workflow smoke
+- MCP stdio config smoke
+- live Quick Enrich auth smoke when a key is configured
+- live native batch no-credit smoke when a key is configured
+- live MCP stdio auth smoke when a key is configured
+
+The live auth probes use random reverse-email no-match calls and fail if Quick Enrich reports `credits_used > 0`.
+
+Observed vendor diagnostic: `GET /api/lookups/country-codes` returned HTTP 500 during live testing on 2026-07-08. The live smoke records this as a non-blocking diagnostic because the authenticated no-match probe is the real auth gate.
+
+## Live Benchmark
+
+```bash
+npm run bench:live
+npm run bench:floor
+npm run bench:credit
+```
+
+The default benchmark uses random no-match company domains with a title filter and fails closed if Quick Enrich returns records or reports any credit usage. It compares:
+
+- `raw_sequential`: direct Quick Enrich API calls for every input row, including duplicates.
+- `raw_concurrent_deduped`: direct Quick Enrich API calls after caller-side dedupe and concurrency.
+- `direct_core_batch`: the local batch tool path without stdio transport.
+- `mcp_batch_stdio`: the real MCP stdio tool path.
+
+Default shape: 2 iterations, 12 input companies per iteration, 6 unique domains, duplicate factor 2, concurrency 8, `per_page=5`. Override with `QUICKENRICH_BENCH_ITERATIONS`, `QUICKENRICH_BENCH_UNIQUE`, `QUICKENRICH_BENCH_DUPLICATE_FACTOR`, `QUICKENRICH_BENCH_CONCURRENCY`, and `QUICKENRICH_BENCH_PER_PAGE`.
+
+Set `QUICKENRICH_BENCH_META_LANE=1` to add an extra `mcp_batch_stdio_meta` diagnostic lane. It is opt-in because shared token buckets make back-to-back lanes intentionally affect each other.
+
+`npm run bench:credit` sets `QUICKENRICH_BENCH_SPEND_CREDITS=1`, uses real domains, and requires at least one credit to be spent unless `QUICKENRICH_BENCH_REQUIRE_CREDITS=0` is set. Override paid-run domains with `QUICKENRICH_BENCH_DOMAINS="example.com,sample.com"`.
+
+The fair production claim is that MCP batch should beat naive raw sequential API usage by coalescing duplicate work and running the remaining requests concurrently. An already-optimized raw client that dedupes and parallelizes requests can be as fast or faster because it has no JSON-RPC stdio envelope.
+
+`npm run bench:floor` uses a local mock API and spends no credits. It measures implementation overhead without vendor latency by default; set `QUICKENRICH_FLOOR_MOCK_LATENCY_MS` to model response latency. Latest local floor run on 2026-07-09:
+
+- `reverse_csv_jsonl`: direct core 8.71 ms, MCP stdio 7.43 ms, 64 requests, 64 found, 11.1 KB JSONL export.
+- `exact_csv_phone_csv_export`: direct core 6.99 ms, MCP stdio 6.51 ms, 64 requests, 32 found, 4.6 KB CSV export.
+- `contact_finder_paging_jsonl`: direct core 2.30 ms, MCP stdio 1.43 ms, 4 paged requests, 20 leads, 4.5 KB JSONL export.
+- `company_finder_paging_csv`: direct core 1.20 ms, MCP stdio 1.33 ms, 4 paged requests, 20 companies, 2.7 KB CSV export.
+- Guardrail: local MCP stdio must stay within 2.5x of direct core for every floor lane.
+
+Latest default token-bucket no-credit local run on 2026-07-09 against `https://app.quickenrich.io`:
+
+- Shape: 2 iterations, 12 input companies, 6 unique no-match domains, duplicate factor 2, default `300/min` with burst `8`.
+- `raw_sequential`: 1602.61 ms average, 12 requests/iteration, 0 credits.
+- `raw_concurrent_deduped`: 194.37 ms average, 6 requests/iteration, 0 credits.
+- `direct_core_batch`: 213.22 ms average, 6 requests/iteration, 0 credits.
+- `mcp_batch_stdio`: 241.81 ms average, 6 requests/iteration, 0 credits.
+- Result: MCP stdio batch was 6.63x faster than naive raw sequential API usage and cut request volume 2x.
+
+Latest default token-bucket paid local run on 2026-07-09:
+
+- Shape: 1 iteration, `danosseasoning.com` and `sagegoddess.com`, duplicate factor 2, default `300/min` with burst `8`.
+- `raw_sequential`: 666.60 ms, 4 requests, 4 credits, 4 leads.
+- `raw_concurrent_deduped`: 237.11 ms, 2 requests, 2 credits, 2 leads.
+- `direct_core_batch`: 266.64 ms, 2 requests, 2 credits, 2 leads.
+- `mcp_batch_stdio`: 318.64 ms, 2 requests, 2 credits, 2 leads.
+- Result: MCP stdio batch was 2.09x faster than naive raw sequential API usage, cut request volume 2x, and saved 50% credits on duplicate inputs.
+
+## NPM Publish Prep
+
+Dry-run the package contents before publishing:
+
+```bash
+npm run check
+npm run smoke
+npm run pack:dry-run
+```
+
+Actual publish is intentionally manual:
+
+```bash
+npm publish --access public
+```

package/agents/AGENTS.md

@@ -0,0 +1,6 @@
+# Quick Enrich MCP Agent Notes
+
+- 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`.
+- Quick Enrich MCP auth: run `quickenrich-token set` once and `quickenrich-token doctor` before live runs; never paste API keys into prompts.
+
+For large CSV/JSONL work, do not paste rows into the prompt. Pass `input_file`, write records with `output_file`, checkpoint with `resume_file`, and keep live calls inside published Quick Enrich limits.

package/agents/CLAUDE.md

@@ -0,0 +1,6 @@
+# Quick Enrich MCP Agent Notes
+
+- 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`.
+- Quick Enrich MCP auth: run `quickenrich-token set` once and `quickenrich-token doctor` before live runs; never paste API keys into prompts.
+
+Use `response:{mode:"meta"}` for planning, `projection:"emails"` or `projection:"people"` for compact row handoff, and `throttle_scope:"shared"` when multiple local MCP processes may run at once.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@mackody/quickenrich-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Standalone MCP server and CLI for Quick Enrich lead enrichment APIs.",
+  "bin": {
+    "quickenrich-agent-docs": "scripts/quickenrich-agent-docs.mjs",
+    "quickenrich-mcp": "scripts/quickenrich-mcp.mjs",
+    "quickenrich-token": "scripts/quickenrich-token.mjs"
+  },
+  "files": [
+    ".codex-plugin/",
+    ".env.example",
+    ".mcp.json",
+    "agents/",
+    "scripts/",
+    "skills/",
+    "README.md"
+  ],
+  "scripts": {
+    "agent-docs:install": "node scripts/quickenrich-agent-docs.mjs install",
+    "agent-docs:uninstall": "node scripts/quickenrich-agent-docs.mjs uninstall",
+    "check": "node --check scripts/quickenrich-agent-docs.mjs && node --check scripts/quickenrich-mcp.mjs && node --check scripts/quickenrich-token.mjs && node --check scripts/lib/core.mjs && node --check scripts/lib/benchmark.mjs && node --check scripts/agent-docs-smoke.mjs && node --check scripts/token-cli-smoke.mjs && node --check scripts/offline-contract-smoke.mjs && node --check scripts/mock-api-smoke.mjs && node --check scripts/perf-contract-smoke.mjs && node --check scripts/rate-limit-contract-smoke.mjs && node --check scripts/token-bucket-contract-smoke.mjs && node --check scripts/reverse-concurrency-floor-smoke.mjs && node --check scripts/paged-finder-floor-smoke.mjs && node --check scripts/serialization-floor-smoke.mjs && node --check scripts/local-floor-benchmark.mjs && node --check scripts/native-capabilities-smoke.mjs && node --check scripts/ops-contract-smoke.mjs && node --check scripts/benchmark-contract-smoke.mjs && node --check scripts/agent-surface-smoke.mjs && node --check scripts/envelope-budget-smoke.mjs && node --check scripts/agent-envelope-workflow-smoke.mjs && node --check scripts/killer-contract-smoke.mjs && node --check scripts/live-smoke.mjs && node --check scripts/native-live-smoke.mjs && node --check scripts/mcp-live-smoke.mjs && node --check scripts/mcp-config-smoke.mjs && node --check scripts/live-benchmark.mjs",
+    "smoke": "node scripts/agent-docs-smoke.mjs && node scripts/token-cli-smoke.mjs && node scripts/offline-contract-smoke.mjs && node scripts/mock-api-smoke.mjs && node scripts/perf-contract-smoke.mjs && node scripts/rate-limit-contract-smoke.mjs && node scripts/token-bucket-contract-smoke.mjs && node scripts/reverse-concurrency-floor-smoke.mjs && node scripts/paged-finder-floor-smoke.mjs && node scripts/serialization-floor-smoke.mjs && node scripts/local-floor-benchmark.mjs && node scripts/native-capabilities-smoke.mjs && node scripts/ops-contract-smoke.mjs && node scripts/benchmark-contract-smoke.mjs && node scripts/agent-surface-smoke.mjs && node scripts/envelope-budget-smoke.mjs && node scripts/agent-envelope-workflow-smoke.mjs && node scripts/killer-contract-smoke.mjs && node scripts/mcp-config-smoke.mjs",
+    "smoke:live": "node scripts/live-smoke.mjs && node scripts/native-live-smoke.mjs && node scripts/mcp-live-smoke.mjs",
+    "bench:live": "node scripts/live-benchmark.mjs",
+    "bench:floor": "node scripts/local-floor-benchmark.mjs",
+    "bench:credit": "QUICKENRICH_BENCH_SPEND_CREDITS=1 node scripts/live-benchmark.mjs",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepublishOnly": "npm run check && npm run smoke",
+    "test": "npm run check && npm run smoke && npm run smoke:live"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED"
+}

package/scripts/agent-docs-smoke.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function run(args, cwd) {
+  const result = spawnSync(process.execPath, ["scripts/quickenrich-agent-docs.mjs", ...args], {
+    cwd,
+    encoding: "utf8",
+  });
+  if (result.status !== 0) throw new Error(`Command failed: ${args.join(" ")}\n${result.stderr || result.stdout}`);
+  return JSON.parse(result.stdout);
+}
+
+function managedLines(text) {
+  return text.split(/\r?\n/).filter((line) => line.includes("<!-- quickenrich-mcp:line"));
+}
+
+const repoRoot = new URL("..", import.meta.url).pathname;
+const tempDir = mkdtempSync(join(tmpdir(), "qe-agent-docs-"));
+
+try {
+  const claudePath = join(tempDir, "CLAUDE.md");
+  const agentsPath = join(tempDir, "AGENTS.md");
+  writeFileSync(claudePath, "# Existing Claude\n\nKeep this line.\n");
+  writeFileSync(agentsPath, "# Existing Agents\n\nKeep this line.\n");
+
+  const installed = run(["install", "--cwd", tempDir, "--json"], repoRoot);
+  assert(installed.ok === true, "install should report ok=true.");
+  assert(installed.action === "install", "install action should be reported.");
+  assert(installed.files.length === 2, "install should touch CLAUDE.md and AGENTS.md.");
+
+  const claudeInstalled = readFileSync(claudePath, "utf8");
+  const agentsInstalled = readFileSync(agentsPath, "utf8");
+  assert(claudeInstalled.includes("Keep this line."), "install should preserve existing CLAUDE.md content.");
+  assert(agentsInstalled.includes("Keep this line."), "install should preserve existing AGENTS.md content.");
+  assert(managedLines(claudeInstalled).length === 2, "install should append exactly two managed CLAUDE.md lines.");
+  assert(managedLines(agentsInstalled).length === 2, "install should append exactly two managed AGENTS.md lines.");
+  assert(claudeInstalled.includes("quickenrich_agent_graph"), "managed lines should explain agent graph usage.");
+  assert(agentsInstalled.includes("quickenrich-token doctor"), "managed lines should explain auth/doctor usage.");
+
+  run(["install", "--cwd", tempDir, "--json"], repoRoot);
+  assert(managedLines(readFileSync(claudePath, "utf8")).length === 2, "install should be idempotent for CLAUDE.md.");
+  assert(managedLines(readFileSync(agentsPath, "utf8")).length === 2, "install should be idempotent for AGENTS.md.");
+
+  const uninstalled = run(["uninstall", "--cwd", tempDir, "--json"], repoRoot);
+  assert(uninstalled.ok === true, "uninstall should report ok=true.");
+  assert(uninstalled.action === "uninstall", "uninstall action should be reported.");
+  assert(managedLines(readFileSync(claudePath, "utf8")).length === 0, "uninstall should remove managed CLAUDE.md lines.");
+  assert(managedLines(readFileSync(agentsPath, "utf8")).length === 0, "uninstall should remove managed AGENTS.md lines.");
+  assert(readFileSync(claudePath, "utf8").includes("Keep this line."), "uninstall should preserve existing CLAUDE.md content.");
+  assert(readFileSync(agentsPath, "utf8").includes("Keep this line."), "uninstall should preserve existing AGENTS.md content.");
+
+  run(["uninstall", "--cwd", tempDir, "--json"], repoRoot);
+  assert(managedLines(readFileSync(claudePath, "utf8")).length === 0, "uninstall should be idempotent for CLAUDE.md.");
+  assert(managedLines(readFileSync(agentsPath, "utf8")).length === 0, "uninstall should be idempotent for AGENTS.md.");
+
+  const claudeTemplate = readFileSync(join(repoRoot, "agents", "CLAUDE.md"), "utf8");
+  const agentsTemplate = readFileSync(join(repoRoot, "agents", "AGENTS.md"), "utf8");
+  assert(claudeTemplate.includes("quickenrich_pipeline"), "agent CLAUDE.md should document the pipeline tool.");
+  assert(agentsTemplate.includes("input_file"), "agent AGENTS.md should document file-based bulk inputs.");
+
+  console.log(JSON.stringify({ ok: true }, null, 2));
+} finally {
+  rmSync(tempDir, { recursive: true, force: true });
+}

package/scripts/agent-envelope-workflow-smoke.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+import {
+  TOOL_DEFINITIONS,
+  agentGraph,
+  callQuickEnrichTool,
+  compactToolPayload,
+  planNaturalLanguage,
+  selectTools,
+  toolPayloadText,
+} from "./lib/core.mjs";
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function bytes(value) {
+  return Buffer.byteLength(typeof value === "string" ? value : JSON.stringify(value), "utf8");
+}
+
+const agentTools = selectTools(TOOL_DEFINITIONS);
+const fullTools = selectTools(TOOL_DEFINITIONS, "full");
+const agentToolBytes = bytes({ tools: agentTools });
+const fullToolBytes = bytes({ tools: fullTools });
+
+assert(agentTools.length <= 9, `Default agent surface should stay <=9 tools, got ${agentTools.length}.`);
+assert(agentToolBytes <= 8_000, `Default tools/list surface is too large: ${agentToolBytes} bytes.`);
+assert(fullToolBytes > agentToolBytes, "Full tool surface should remain more verbose than agent surface.");
+assert(agentTools.some((tool) => tool.name === "quickenrich_lookup_values"), "Agent surface should expose lookup discovery.");
+assert(agentTools.every((tool) => !JSON.stringify(tool).includes("description\":\"CSV text")), "Agent surface should strip verbose nested schema descriptions.");
+
+const graph = agentGraph();
+const graphCompact = compactToolPayload(graph);
+const graphMeta = compactToolPayload(graph, { mode: "meta" });
+const graphFull = compactToolPayload(graph, { mode: "full", maxOutputChars: 100_000 });
+const graphCompactText = toolPayloadText(graphCompact);
+const graphMetaText = toolPayloadText(graphMeta);
+const graphFullText = toolPayloadText(graphFull);
+
+assert(bytes(graphCompactText) <= 8_000, `Agent graph compact envelope is too large: ${bytes(graphCompactText)} bytes.`);
+assert(bytes(graphMetaText) <= 1_600, `Agent graph meta envelope is too large: ${bytes(graphMetaText)} bytes.`);
+assert(graphCompact._meta.responseMode === "compact", "Agent graph compact response mode should be compact.");
+assert(graphMeta._meta.responseMode === "meta", "Agent graph meta response mode should be meta.");
+assert(graphFull._meta.responseMode === "full", "Agent graph full response mode should be full.");
+assert(graph.lookupHints?.tool === "quickenrich_lookup_values", "Agent graph should point filter discovery to lookup_values.");
+assert(graph.budgetMath?.exact_email_phone?.includes("phone"), "Agent graph should explain email+phone budget math.");
+
+const reverseCsv = planNaturalLanguage("Reverse lookup CSV emails: email\nada@example.com\ngrace@example.com");
+assert(reverseCsv.tool === "quickenrich_batch_reverse_email", `CSV email route chose ${reverseCsv.tool}.`);
+assert(reverseCsv.arguments.emails.length === 2, "CSV email route should extract embedded emails.");
+
+const reverseCsvPlaceholder = planNaturalLanguage("Reverse lookup a CSV of emails");
+assert(reverseCsvPlaceholder.tool === "quickenrich_batch_reverse_email", `CSV placeholder route chose ${reverseCsvPlaceholder.tool}.`);
+assert(reverseCsvPlaceholder.requires.includes("input_csv"), "CSV placeholder route should require input_csv.");
+
+const exactJsonl = planNaturalLanguage('Batch exact employee search from JSONL: {"company_url":"example.com","first_name":"Ada","last_name":"Lovelace"}');
+assert(exactJsonl.tool === "quickenrich_batch_employee_search", `Exact JSONL route chose ${exactJsonl.tool}.`);
+assert(exactJsonl.arguments.response?.mode === "meta", "Exact JSONL route should default to meta planning output.");
+assert(exactJsonl.requires.includes("input_jsonl"), "Exact JSONL route should require input_jsonl payload.");
+
+const domainCsv = planNaturalLanguage("Use CSV domain_search for company_url,title\nexample.com,Founder\nsample.io,CEO");
+assert(domainCsv.tool === "quickenrich_batch_pull_leads", `Domain CSV route chose ${domainCsv.tool}.`);
+assert(domainCsv.arguments.mode === "domain_search", `Domain CSV route mode=${domainCsv.arguments.mode}.`);
+assert(!domainCsv.arguments.companies, "Domain CSV route should avoid expanding file-shaped input into object arrays.");
+assert(domainCsv.requires.includes("input_csv"), "Domain CSV route should require input_csv payload.");
+
+const creditPlan = planNaturalLanguage("pull founder leads from 50 company domains with max 100 credits");
+assert(creditPlan.tool === "quickenrich_batch_pull_leads", `Credit lead route chose ${creditPlan.tool}.`);
+assert(creditPlan.arguments.max_credits === 100, `Expected max_credits=100, got ${creditPlan.arguments.max_credits}.`);
+assert(creditPlan.requires.includes("companies or input_csv/input_jsonl"), "Credit lead route should ask for company input when no domains are present.");
+
+const resumePlan = planNaturalLanguage("continue a paged company finder run");
+assert(resumePlan.tool === "quickenrich_batch_pull_leads", `Resume route chose ${resumePlan.tool}.`);
+assert(resumePlan.arguments.mode === "company_finder", `Resume route mode=${resumePlan.arguments.mode}.`);
+assert(resumePlan.requires.includes("resume_state"), "Resume route should require resume_state.");
+
+const blockedExecute = await callQuickEnrichTool("quickenrich_natural_language", {
+  request: "reverse lookup a CSV of emails",
+  execute: true,
+  response: { mode: "full" },
+});
+assert(blockedExecute.ok === false, "Natural-language execute should not run incomplete plans.");
+assert(blockedExecute.error.includes("input_csv"), "Blocked execute should name the missing input_csv requirement.");
+
+console.log(JSON.stringify({
+  ok: true,
+  agentTools: agentTools.length,
+  agentToolBytes,
+  graphCompactBytes: bytes(graphCompactText),
+  graphMetaBytes: bytes(graphMetaText),
+  graphFullBytes: bytes(graphFullText),
+}, null, 2));