@opennous/mcp 0.20.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opennous/mcp",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Nous MCP Server — Customer graph for GTM agents.",
   "license": "AGPL-3.0-only",
   "repository": {

package/src/server.js

@@ -29,13 +29,15 @@
  *   set_trigger          — create an outbound event trigger (webhook); list_triggers reads them
  *   list_triggers        — list the workspace's event triggers + available events
  *   lead_list_operations — the operations trail of a lead list (imports/enrich/push/replies), filterable
+ *   check_leads          — pre-spend coverage check: which candidates you already own / should re-enrich
+ *   lead_coverage        — attribute coverage estimate ("how many agency founders do we have, by freshness")
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { get, post } from "./client.js";
 
-export const SERVER_VERSION = "0.20.0";
+export const SERVER_VERSION = "0.22.0";
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -812,5 +814,100 @@ export function createServer() {
     }
   );
 
+  // ===========================================================================
+  // TOOL: check_leads  —  POST /v2/dedup
+  // The pre-spend coverage check. Run this BEFORE building/buying a lead list in
+  // Apollo, Sales Navigator, DeepSearch, Clay, etc. Paste the candidate emails /
+  // LinkedIn URLs / company domains (all visible for free in the tool's preview)
+  // and find out what you already own — so you never re-buy a record you have,
+  // and you re-enrich stale ones instead of paying to acquire them again.
+  // ===========================================================================
+  server.tool(
+    "check_leads",
+    "Pre-spend coverage check — call this BEFORE building or buying a lead list elsewhere (Apollo, " +
+    "Sales Navigator, DeepSearch, Clay). Paste the candidate emails, LinkedIn URLs, or company " +
+    "domains (free in any tool's preview) and learn what you already have, so you don't pay twice. " +
+    "Returns counts: net_new (acquire + enrich these), needs_enrichment (you already OWN these but " +
+    "they're stale / not enriched in 90 days — re-enrich instead of re-buying), reusable (you have a " +
+    "fresh verified email — reuse, spend nothing), plus engaged/recent/bounced/unsubscribed/known to " +
+    "skip. Each result carries entity_id, email_status, enriched_at, and stale so you can act per-lead.",
+    {
+      emails: z.array(z.string()).optional().describe("Candidate email addresses (up to 50,000)."),
+      linkedin_urls: z.array(z.string()).optional().describe("Candidate LinkedIn profile URLs (up to 50,000)."),
+      domains: z.array(z.string()).optional().describe("Company domains — 'do I already have anyone here?' (up to 50,000)."),
+    },
+    async ({ emails, linkedin_urls, domains }) => {
+      const body = {};
+      if (emails?.length) body.emails = emails;
+      if (linkedin_urls?.length) body.linkedin_urls = linkedin_urls;
+      if (domains?.length) body.domains = domains;
+      if (!Object.keys(body).length) {
+        return { content: [{ type: "text", text: "Pass at least one of: emails, linkedin_urls, domains." }] };
+      }
+      const r = await post("/v2/dedup", body);
+      const s = r.summary || {};
+      const lines = [
+        `COVERAGE (${s.total ?? 0} checked)`,
+        `  net_new          ${s.net_new ?? 0}   → acquire + enrich`,
+        `  needs_enrichment ${s.needs_enrichment ?? 0}   → you OWN these but stale (>90d) → re-enrich, don't re-buy`,
+        `  reusable         ${s.reusable ?? 0}   → fresh verified email on file → reuse, spend nothing`,
+        `  engaged          ${s.engaged ?? 0}   → in an active conversation, don't cold-send`,
+        `  recent           ${s.recent ?? 0}   → contacted <30d, defer`,
+        `  known            ${s.known ?? 0}   → company already in the workspace`,
+        `  bounced/unsub    ${(s.bounced ?? 0) + (s.unsubscribed ?? 0) + (s.suppressed ?? 0)}   → skip`,
+      ];
+      // Surface a few stale entities the caller should re-enrich (with their last date).
+      const stale = (r.results || []).filter(x => x.entity_id && x.stale).slice(0, 15);
+      if (stale.length) {
+        lines.push("", "RE-ENRICH (sample):");
+        for (const x of stale) {
+          lines.push(`  ${x.value}  [${x.enriched_at ? `last enriched ${relAge(x.enriched_at)}` : "never enriched"}]  ${x.entity_id}`);
+        }
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+
+  // ===========================================================================
+  // TOOL: lead_coverage  —  GET /v2/people/coverage
+  // The attribute-based planning check: "how many <agency founders> do we already
+  // have, and how fresh?" — answered WITHOUT pasting identifiers. Use it before
+  // building a list elsewhere to see how much you already cover.
+  // ===========================================================================
+  server.tool(
+    "lead_coverage",
+    "Estimate how many people you ALREADY have matching a role/keyword, bucketed by enrichment " +
+    "freshness — the planning question before building a list (no identifiers to paste). E.g. " +
+    "title='founder', keyword='agency' → how many agency founders are already in your workspace, " +
+    "how many were never enriched or are stale (>90d, so re-enrich), and how many have a fresh " +
+    "verified email. Rough by design (title is precise; keyword matches title/company/department). " +
+    "For an exact net-new check against specific candidates, use check_leads with their identifiers.",
+    {
+      title: z.string().optional().describe("Role match, e.g. 'founder', 'VP Sales' (matches job_title)."),
+      keyword: z.string().optional().describe("Extra match across title/company/department, e.g. 'agency'."),
+      stale_days: z.number().optional().describe("Days after which enrichment counts as stale (default 90)."),
+    },
+    async ({ title, keyword, stale_days }) => {
+      if (!title && !keyword) {
+        return { content: [{ type: "text", text: "Pass a title and/or keyword, e.g. title='founder', keyword='agency'." }] };
+      }
+      const r = await get("/v2/people/coverage", { title, keyword, stale_days });
+      const lines = [
+        `COVERAGE — ${[title && `title~"${title}"`, keyword && `keyword~"${keyword}"`].filter(Boolean).join(" + ")}`,
+        `  ${r.total ?? 0} already in your workspace`,
+        `    ${r.needs_enrichment ?? 0} need (re-)enrichment  (${r.never_enriched ?? 0} never enriched · ${r.stale ?? 0} stale >90d)`,
+        `    ${r.fresh_verified ?? 0} have a fresh verified email`,
+      ];
+      const sample = r.sample || [];
+      if (sample.length) {
+        lines.push("", "SAMPLE (oldest first):");
+        for (const s of sample.slice(0, 12)) {
+          lines.push(`  ${[s.job_title, s.company].filter(Boolean).join(" @ ") || s.entity_id}  [${s.enriched_at ? `enriched ${relAge(s.enriched_at)}` : "never enriched"}]`);
+        }
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+
   return server;
 }