prospectapis-mcp 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ All notable changes to `prospectapis-mcp` are documented here. The format follow
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-25
+
+### Added
+
+- `email_verify_stats` and `email_outcomes_report`: your verification mix, and bounced or delivered reports (a charged valid you report bounced within 30 days is credited back).
+- `email_verify_job_create`, `email_verify_job_get`, `email_verify_job_results`, `email_verify_job_stop`: bulk verification jobs of up to 50,000 addresses with free retries for slow servers, list sampling (`sample`) and list monitoring (`monitor_days`).
+- `email_find`: a person's work address from name and domain, $0.02 only when found.
+- `email_domain_check`: what DNS and our recent checks know about a domain, free.
+- `email_verify_calibration`: measured bounce rate per score band, free.
+- `email_clean_list`: sort up to 1,000 addresses into keep, review and remove with quick checks.
+- `email_verify` takes `depth: "quick"` ($0.001 per address, no mail server contacted). Twenty-five tools.
+
 ## [0.3.0] - 2026-10-25
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # prospectapis-mcp
 
-prospectapis-mcp is the MCP server for ProspectAPIs (https://prospectapis.com), for sales and prospecting teams and the AI agents they run in Claude Code, Claude Desktop, Cursor and other MCP clients. It gives your agent fifteen tools over the ProspectAPIs API: search funding rounds by date, round, amount, company, investor and country, get new matching rounds pushed to your webhook, verify email addresses, and order a cited research brief on any company or person. Funding records carry the public announcement URL when there is one. Every account starts with a free $1 balance and no card: records cost $0.02, an email check $0.004 and a completed brief $0.15, with no seats and no subscription. It needs Node.js 22 or later.
+prospectapis-mcp is the MCP server for ProspectAPIs (https://prospectapis.com), for sales and prospecting teams and the AI agents they run in Claude Code, Claude Desktop, Cursor and other MCP clients. It gives your agent twenty-five tools over the ProspectAPIs API: search funding rounds by date, round, amount, company, investor and country, get new matching rounds pushed to your webhook, verify, find and bulk-check email addresses, report what bounced, and order a cited research brief on any company or person. Funding records carry the public announcement URL when there is one. Every account starts with a free $1 balance and no card: records cost $0.02, an email check $0.004 and a completed brief $0.15, with no seats and no subscription. It needs Node.js 22 or later.
 
 Install (Claude Code): `claude mcp add prospectapis -e PROSPECTAPIS_API_KEY=pa_live_... -- npx -y prospectapis-mcp`
 
@@ -15,6 +15,11 @@ Website: https://prospectapis.com/mcp
 | `research_submit` | `POST /v1/research` | one research at `research_price_usd` (see `account_balance`), charged only when the brief completes; refunded on failure |
 | `research_get` | `GET /v1/research/:id` | free; poll until `status` is `completed` or `failed` |
 | `email_verify` | `POST /v1/email/verify` | $0.004 per `valid` or `invalid` result; `catch-all` and `unknown` are free; 1 to 25 addresses a call |
+| `email_verify_stats` | `GET /v1/email/verify/stats` | free |
+| `email_outcomes_report` | `POST /v1/email/outcomes` | free; 1 to 100 outcomes a call |
+| `email_verify_job_create` | `POST /v1/email/verify/jobs` | free to start; $0.004 per `valid` or `invalid` result as it is checked; up to 50,000 addresses |
+| `email_verify_job_get` | `GET /v1/email/verify/jobs/:id` | free |
+| `email_verify_job_results` | `GET /v1/email/verify/jobs/:id/results` | free; 1,000 a page |
 | `watchlist_create`, `watchlist_list`, `watchlist_get`, `watchlist_deliveries`, `watchlist_test`, `watchlist_delete` | `/v1/watchlists` | free to manage; a delivered event costs one record, only when your webhook answers 2xx |
 | `account_balance` | `GET /v1/account` | free |
 | `feedback_send` | `POST /v1/feedback` | free; reports a bug, wrong field or missing capability to the team (10 an hour per key) |
@@ -31,7 +36,7 @@ Website: https://prospectapis.com/mcp
 `outreach`). It returns a `research_id` at once; a brief takes 20 to 90 seconds.
 
 `email_verify` takes `emails`, a list of 1 to 25 addresses. Each result has `status` (`valid`, `invalid`,
-`catch-all` or `unknown`), `reason`, `charged`, `flags`, `smtp_code` and `catch_all_tier`. If the balance covers only
+`catch-all` or `unknown`), `reason`, `reason_text`, `score` (0 to 100), `recommendation` (`send`, `send_with_caution`, `retry_later` or `do_not_send`), `charged`, `flags`, `smtp_code` and `catch_all_tier`. If the balance covers only
 some addresses, the rest come back `unknown` with reason `not_checked_insufficient_credits` and are not charged.
 
 ## Configure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prospectapis-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "mcpName": "io.github.ProspectAPIs/prospectapis-mcp",
   "description": "MCP server for ProspectAPIs: search funding rounds, verify email addresses, run paid prospect research briefs, manage funding watchlists, read your balance and the live price list.",
   "type": "module",

package/src/tools.js

@@ -134,17 +134,168 @@ export const TOOLS = [
     body: true,
     description:
       "Check whether 1 to 25 email addresses can receive mail. Each result has `status` (valid, invalid, catch-all or unknown), " +
-      "`reason`, `charged`, `flags`, `smtp_code` and `catch_all_tier`. Costs $0.004 per valid or invalid result, drawn from your " +
+      "`reason`, `reason_text`, `score` (0 to 100), `recommendation` (send, send_with_caution, retry_later or do_not_send), `charged`, `flags`, `smtp_code`, `catch_all_tier`, `did_you_mean` (a likely domain typo), `mail_provider` and `checked_at`. Costs $0.004 per valid or invalid result, drawn from your " +
       "balance; catch-all and unknown results are free (pricing_get lists which statuses are charged). When the balance covers only " +
-      "some addresses, the rest come back `unknown` with reason `not_checked_insufficient_credits`, free.",
+      "some addresses, the rest come back `unknown` with reason `not_checked_insufficient_credits`, free. " +
+      "`depth: \"quick\"` never contacts the mail server: syntax, disposable and free lists, DNS, parked and new-domain flags " +
+      "and a recently measured catch-all verdict, at $0.001 per address whatever the status; an address that needs a mailbox " +
+      "check comes back `unknown` with reason `not_probed`.",
     shape: {
+      depth: z.enum(["full", "quick"]).optional().describe("full (default) checks the mailbox; quick is DNS and lists only, $0.001 per address."),
       emails: z
-        .array(z.string().min(3).max(254))
+        .array(z.union([
+          z.string().min(3).max(254),
+          z.object({ email: z.string().min(3).max(254), first_name: z.string().max(80).optional(), last_name: z.string().max(80).optional() }),
+        ]))
         .min(1)
         .max(25)
-        .describe("The addresses to check, 1 to 25 per call."),
+        .describe("The addresses to check, 1 to 25 per call. An item may be {email, first_name, last_name} to also check the address against the person's name."),
     },
   },
+  {
+    name: "email_domain_check",
+    method: "GET",
+    path: "/v1/email/domain/{domain}",
+    title: "Check Email Domain",
+    idempotent: true,
+    write: false,
+    description:
+      "What is known about one email domain without contacting its mail server: `exists`, `accepts_mail`, `null_mx`, `mx` hosts, " +
+      "`mail_provider`, `spf`, `dmarc`, `disposable`, `free_provider`, `parked`, `domain_age_days`, `new_domain`, `did_you_mean`, " +
+      "and `catch_all` (true or false only when our own check measured it recently, else null) with `catch_all_checked_at`. " +
+      "Free, up to 300 lookups an hour per account.",
+    shape: { domain: z.string().min(3).max(253).describe("A domain name such as example.com.") },
+  },
+  {
+    name: "email_find",
+    method: "POST",
+    path: "/v1/email/find",
+    title: "Find Email Address",
+    write: true,
+    body: true,
+    description:
+      "Find a person's work email from `first_name`, `last_name` and company `domain`. The common patterns are checked in order " +
+      "against the mail server, most common first. Returns `status` (found, catch_all, unknown, not_found), `email`, `pattern`, " +
+      "`score`, `recommendation` and the addresses `checked`. Costs $0.02 only when an address is found; on a catch-all domain " +
+      "it returns the most likely address as `best_guess`, free.",
+    shape: {
+      first_name: z.string().min(1).max(80).describe("The person's first name."),
+      last_name: z.string().max(80).optional().describe("The person's last name."),
+      domain: z.string().min(3).max(253).describe("The company's email domain, such as example.com."),
+    },
+  },
+  {
+    name: "email_verify_calibration",
+    method: "GET",
+    path: "/v1/email/verify/calibration",
+    title: "Email Score Calibration",
+    idempotent: true,
+    write: false,
+    description:
+      "What each verification score band has meant in practice: the measured bounce rate per band from delivery outcomes " +
+      "customers reported over the last 90 days. A band with fewer than 30 reports shows a null rate. Free.",
+    shape: {},
+  },
+  {
+    name: "email_clean_list",
+    method: "POST",
+    path: "/v1/email/clean",
+    title: "Clean Email List",
+    write: true,
+    body: true,
+    description:
+      "Clean a list of up to 1,000 addresses in one call with quick checks (no mail server is contacted): returns `keep`, " +
+      "`review` (role, free, parked, new or typo addresses, with a reason) and `remove` (cannot receive mail), plus `counts`. " +
+      "$0.001 per well-formed address. Run email_verify on the kept addresses you will actually send to.",
+    shape: {
+      emails: z.array(z.string().min(3).max(254)).min(1).max(1000).describe("The addresses to clean, 1 to 1,000."),
+    },
+  },
+  {
+    name: "email_verify_stats",
+    method: "GET",
+    path: "/v1/email/verify/stats",
+    title: "Email Verification Stats",
+    write: false,
+    description:
+      "Your own email verification mix over the last `days` (1 to 90, default 30): `total`, `by_status` (valid, invalid, " +
+      "catch-all, unknown), `charged`, `served_from_cache`, `catch_all_share` and `unknown_share`. Free.",
+    shape: {
+      days: z.number().int().min(1).max(90).optional().describe("Window in days, 1 to 90 (default 30)."),
+    },
+  },
+  {
+    name: "email_outcomes_report",
+    method: "POST",
+    path: "/v1/email/outcomes",
+    title: "Report Email Outcomes",
+    write: true,
+    body: true,
+    description:
+      "Report what happened when you sent: `bounced` or `delivered`, 1 to 100 addresses per call. A bounce you report makes " +
+      "your later email_verify checks of that address come back invalid (reason `reported_bounce`); a delivered report on a " +
+      "catch-all address raises its score. Returns `stored`. Free.",
+    shape: {
+      outcomes: z
+        .array(z.object({ email: z.string().min(3).max(254), outcome: z.enum(["bounced", "delivered"]) }))
+        .min(1)
+        .max(100)
+        .describe("Each address and what happened when you sent to it."),
+    },
+  },
+  {
+    name: "email_verify_job_create",
+    method: "POST",
+    path: "/v1/email/verify/jobs",
+    title: "Start Email Verification Job",
+    write: true,
+    body: true,
+    description:
+      "Check up to 50,000 addresses in the background. Returns 202 with a job `id`; poll email_verify_job_get. A slow or " +
+      "greylisting server is retried about 5, 15 and 30 minutes later, free. Each valid or invalid result costs $0.004 as " +
+      "it is checked; catch-all and unknown are free. An optional https `callback_url` gets one signed POST when the job " +
+      "completes (verify with the returned `secret`). At most 5 jobs run at once per account.",
+    shape: {
+      sample: z.number().int().min(10).max(50000).optional().describe("Check only a random sample of this many addresses; the job then reports estimated shares for the whole list."),
+      monitor_days: z.number().int().min(7).max(90).optional().describe("Check the whole list again this many days after each run, billing each definite result again; the callback reports what changed."),
+      emails: z.array(z.string().min(1).max(254)).min(1).max(50000).describe("The addresses, 1 to 50,000."),
+      callback_url: z.string().url().max(2048).optional().describe("An https URL to POST to when the job completes."),
+    },
+  },
+  {
+    name: "email_verify_job_get",
+    method: "GET",
+    path: "/v1/email/verify/jobs/:id",
+    title: "Get Email Verification Job",
+    write: false,
+    description: "A job's `status` (queued, running, completed), `total`, `done`, `charged_count` and `amount_usd`. Free.",
+    shape: { id: z.string().uuid().describe("The job `id` from email_verify_job_create.") },
+  },
+  {
+    name: "email_verify_job_results",
+    method: "GET",
+    path: "/v1/email/verify/jobs/:id/results",
+    title: "Get Email Verification Job Results",
+    write: false,
+    description:
+      "A job's results in input order, up to 1,000 a page (`limit`), from `cursor`; `next_cursor` is null on the last page. " +
+      "An address not yet checked shows status `pending`. Free.",
+    shape: {
+      id: z.string().uuid().describe("The job `id`."),
+      cursor: z.number().int().min(0).optional().describe("Start at this position (0-based)."),
+      limit: z.number().int().min(1).max(1000).optional().describe("Results per page, 1 to 1,000 (default 1,000)."),
+    },
+  },
+  {
+    name: "email_verify_job_stop",
+    method: "POST",
+    path: "/v1/email/verify/jobs/{id}/stop",
+    title: "Stop Verification Job",
+    body: true,
+    write: true,
+    description: "Turn off a job's monitoring (its regular re-checks); a job still running is cancelled, and what it already checked stays readable. Free.",
+    shape: { id: z.string().uuid().describe("The job id.") },
+  },
   {
     name: "watchlist_create",
     method: "POST",