mxprobe 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andriy Chemerynskiy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# mxprobe
+
+Email verification for AI agents. One call returns `send`, `hold` or `kill`
+with the reason. The DNS tier is free and runs on your machine; the hosted
+SMTP probe is 9 USD per 10,000 checks, 100 free at signup.
+
+```bash
+npx mxprobe check hello@example.com ops@example.org   # free, local, no key
+npx mxprobe signup you@company.com                    # a key by API, 100 free checks, saved to ~/.config/mxprobe
+npx mxprobe check --hosted hello@example.com          # DNS kills stay local; survivors go to the mailbox probe
+npx mxprobe balance
+npx mxprobe buy                                       # a Stripe link: 9 USD per 10,000, credits never expire
+npx mxprobe mcp                                       # the MCP server on stdio
+```
+
+## MCP
+
+```bash
+claude mcp add mxprobe -- npx -y mxprobe mcp
+```
+
+Any client: `{"mcpServers":{"mxprobe":{"command":"npx","args":["-y","mxprobe","mcp"]}}}`
+
+Tools: `verify_email`, `verify_batch`, `signup`, `balance`, `buy_credits`.
+With a key configured, `verify_*` probe the mailbox on the hosted tier; without
+one they run the free DNS tier. Set `MXPROBE_API_KEY` to use a key from the
+environment.
+
+## Verdict
+
+```json
+{
+  "email": "hello@example.com",
+  "action": "send",
+  "verdict": "OK",
+  "reason": "mailbox accepted by aspmx.l.google.com",
+  "checks": { "syntax": true, "mx": "aspmx.l.google.com", "smtp": "accepted", "catch_all": false }
+}
+```
+
+- `send`: the mail server accepted the mailbox.
+- `hold`: send only with a fallback in hand. A catch-all, a forwarder, a
+  greylist, or a server that refused the probe rather than the mailbox.
+- `kill`: never send. No mail server, or the mailbox does not exist.
+
+## From Node
+
+```js
+import { createClient, checkEmails } from "mxprobe";
+const client = createClient({ apiKey: process.env.MXPROBE_API_KEY });
+const { results, summary } = await checkEmails(["a@b.com"], { hosted: true, client });
+```
+
+Docs: https://mxprobe.dev. Source: https://github.com/andrewchmr/mxprobe. MIT.

package/bin/mxprobe.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.mjs";
+
+// No forced exit on success: the MCP server may still be answering a call
+// when stdin closes, and `check` has nothing left to wait for anyway.
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code ?? 0;
+  },
+  (err) => {
+    console.error(err?.message ?? err);
+    process.exit(1);
+  },
+);

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "mxprobe",
+  "version": "0.1.0",
+  "description": "Email verification for AI agents. One call returns send, hold or kill with the reason. Free DNS tier runs locally; the hosted SMTP probe is 9 USD per 10,000 checks. CLI + MCP server.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "mxprobe": "./bin/mxprobe.mjs"
+  },
+  "main": "./src/client.mjs",
+  "exports": {
+    ".": "./src/client.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/andrewchmr/mxprobe",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://mxprobe.dev",
+  "keywords": [
+    "email",
+    "verification",
+    "email-verifier",
+    "mx",
+    "smtp",
+    "bounce",
+    "ai-agent",
+    "mcp",
+    "mcp-server",
+    "outreach"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.5.4",
+    "mxprobe-core": "^0.1.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,121 @@
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { readConfig, writeConfig, configPath } from "./config.mjs";
+import { createClient, checkEmails, ApiError } from "./client.mjs";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+
+const HELP = `mxprobe ${version}: email verification for AI agents. Verdicts: send, hold, kill.
+
+Usage
+  mxprobe check <email>...            DNS tier, local, free, no key
+  mxprobe check --hosted <email>...   send the survivors to the hosted SMTP probe (1 credit each)
+  mxprobe check --file list.txt       one address per line
+  mxprobe check --json ...            print the verdict objects as JSON
+  mxprobe signup <email>              get an API key by mail, with 100 free checks
+  mxprobe balance                     credits left on the key
+  mxprobe buy [--packs N]             a Stripe Checkout link: 9 USD per 10,000 checks
+  mxprobe mcp                         start the MCP server on stdio
+
+Options
+  --smtp        run the SMTP probe locally too (needs outbound port 25; most laptops and clouds block it)
+  --api-url     hosted API base (default https://api.mxprobe.dev)
+
+Key: MXPROBE_API_KEY in the environment, else ${configPath()}
+Docs: https://mxprobe.dev`;
+
+export async function main(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env } = {}) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      hosted: { type: "boolean", default: false },
+      smtp: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      file: { type: "string" },
+      packs: { type: "string", default: "1" },
+      "api-url": { type: "string" },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "v", default: false },
+    },
+  });
+  if (values.version) return void stdout.write(`${version}\n`);
+  const [command, ...rest] = positionals;
+  if (values.help || !command || command === "help") return void stdout.write(HELP + "\n");
+
+  const cfg = readConfig(env);
+  if (values["api-url"]) cfg.apiUrl = values["api-url"].replace(/\/$/, "");
+  const client = createClient({ apiUrl: cfg.apiUrl, apiKey: cfg.apiKey });
+
+  try {
+    switch (command) {
+      case "check": {
+        const emails = [...rest];
+        if (values.file) {
+          emails.push(
+            ...readFileSync(values.file, "utf8")
+              .split("\n")
+              .map((l) => l.trim())
+              .filter((l) => l && !l.startsWith("#")),
+          );
+        }
+        if (emails.length === 0) {
+          stderr.write("usage: mxprobe check [--hosted] [--json] <email>... | --file <list>\n");
+          return 2;
+        }
+        const out = await checkEmails(emails, { hosted: values.hosted, client, smtp: values.smtp });
+        if (values.json) {
+          stdout.write(JSON.stringify(out, null, 2) + "\n");
+        } else {
+          const width = Math.max(...out.results.map((r) => r.email.length));
+          for (const r of out.results) stdout.write(`${r.action.padEnd(4)} ${r.verdict.padEnd(4)} ${r.email.padEnd(width)}  ${r.reason}\n`);
+          const s = out.summary;
+          stderr.write(`\n${s.total} checked: ${s.send} send, ${s.hold} hold, ${s.kill} kill`);
+          if (values.hosted) stderr.write(`; ${out.hosted} probed on the hosted tier, ${out.credits_left ?? "?"} credits left`);
+          else if (!values.smtp) stderr.write(`. DNS tier only: a send means the domain takes mail, not that the mailbox exists. Add --hosted to probe the mailbox.`);
+          stderr.write("\n");
+        }
+        return out.summary.kill > 0 && emails.length === 1 ? 1 : 0;
+      }
+      case "signup": {
+        const email = rest[0];
+        if (!email) {
+          stderr.write("usage: mxprobe signup <email>\n");
+          return 2;
+        }
+        const res = await client.signup(email);
+        const path = writeConfig({ api_key: res.api_key, api_url: cfg.apiUrl, email: res.email }, env);
+        stdout.write(`Key saved to ${path}. ${res.credits} free checks on it. The key was also mailed to ${res.email}.\n`);
+        return 0;
+      }
+      case "balance": {
+        const res = await client.balance();
+        stdout.write(values.json ? JSON.stringify(res) + "\n" : `${res.credits} credits left on the key for ${res.email} (${res.checks_total} checks so far)\n`);
+        return 0;
+      }
+      case "buy": {
+        const packs = Math.max(1, Number.parseInt(values.packs, 10) || 1);
+        const res = await client.checkout(packs);
+        stdout.write(values.json ? JSON.stringify(res) + "\n" : `Pay ${res.amount_usd} USD for ${res.credits} checks here:\n${res.url}\nCredits land on the key as soon as Stripe confirms the payment.\n`);
+        return 0;
+      }
+      case "mcp": {
+        const { startMcpServer } = await import("./mcp.mjs");
+        await startMcpServer({ client, config: cfg, env });
+        return 0;
+      }
+      default:
+        stderr.write(`unknown command "${command}"\n\n${HELP}\n`);
+        return 2;
+    }
+  } catch (err) {
+    if (err instanceof ApiError) {
+      stderr.write(`${err.status}: ${err.message}\n`);
+      if (err.status === 402 && err.body?.checkout_hint) stderr.write(`${err.body.checkout_hint}\n`);
+      return 1;
+    }
+    throw err;
+  }
+}

package/src/client.mjs

@@ -0,0 +1,73 @@
+// The hosted API client. Also the package's main export, so a Node agent can
+// `import { createClient } from "mxprobe"` without the CLI.
+import { createVerifier, summarize } from "mxprobe-core";
+
+export class ApiError extends Error {
+  constructor(status, body) {
+    super(body?.message || body?.error || `HTTP ${status}`);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export function createClient({ apiUrl = "https://api.mxprobe.dev", apiKey = null, fetchImpl = fetch } = {}) {
+  const base = apiUrl.replace(/\/$/, "");
+
+  async function call(method, path, body, { auth = true } = {}) {
+    const headers = { "content-type": "application/json", "user-agent": "mxprobe-cli" };
+    if (auth) {
+      if (!apiKey) throw new ApiError(401, { error: "no_api_key", message: "No API key. Run `mxprobe signup you@company.com` or set MXPROBE_API_KEY." });
+      headers.authorization = `Bearer ${apiKey}`;
+    }
+    const res = await fetchImpl(`${base}${path}`, { method, headers, body: body ? JSON.stringify(body) : undefined });
+    const text = await res.text();
+    let json;
+    try {
+      json = text ? JSON.parse(text) : {};
+    } catch {
+      json = { error: "bad_response", message: text.slice(0, 200) };
+    }
+    if (!res.ok) throw new ApiError(res.status, json);
+    return json;
+  }
+
+  return {
+    signup: (email) => call("POST", "/v1/signup", { email }, { auth: false }),
+    verify: (emails) => call("POST", "/v1/verify", { emails }),
+    balance: () => call("GET", "/v1/balance"),
+    checkout: (packs = 1) => call("POST", "/v1/credits/checkout", { packs }),
+  };
+}
+
+/**
+ * The two-tier check the CLI and the MCP server share. The DNS tier runs
+ * locally and is free; with `hosted` on, the survivors (send and hold) go to
+ * the hosted SMTP probe, one credit each. A DNS kill never costs a credit.
+ */
+export async function checkEmails(emails, { hosted = false, client = null, smtp = false, verifierOptions = {} } = {}) {
+  const local = createVerifier({ ...verifierOptions, smtp });
+  const results = await local.verifyBatch(emails);
+  let hostedCount = 0;
+  let creditsLeft = null;
+  if (hosted) {
+    if (!client) throw new Error("hosted check needs an API client");
+    const survivors = results.filter((r) => r.action !== "kill").map((r) => r.email);
+    if (survivors.length) {
+      const byEmail = new Map();
+      for (let i = 0; i < survivors.length; i += 100) {
+        const chunk = survivors.slice(i, i + 100);
+        const res = await client.verify(chunk);
+        for (const r of res.results) byEmail.set(r.email, r);
+        creditsLeft = res.credits_left ?? creditsLeft;
+      }
+      for (let i = 0; i < results.length; i++) {
+        const h = byEmail.get(results[i].email);
+        if (h) {
+          results[i] = h;
+          hostedCount++;
+        }
+      }
+    }
+  }
+  return { results, summary: summarize(results), hosted: hostedCount, credits_left: creditsLeft };
+}

package/src/config.mjs

@@ -0,0 +1,40 @@
+// Where the API key lives: MXPROBE_API_KEY in the environment wins, then
+// ~/.config/mxprobe/config.json (written by `mxprobe signup`).
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const DEFAULT_API_URL = "https://api.mxprobe.dev";
+
+export function configPath(env = process.env) {
+  const base = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+  return join(base, "mxprobe", "config.json");
+}
+
+export function readConfig(env = process.env) {
+  let file = {};
+  try {
+    file = JSON.parse(readFileSync(configPath(env), "utf8"));
+  } catch {
+    /* no file yet */
+  }
+  return {
+    apiKey: env.MXPROBE_API_KEY || file.api_key || null,
+    apiUrl: (env.MXPROBE_API_URL || file.api_url || DEFAULT_API_URL).replace(/\/$/, ""),
+    email: file.email || null,
+  };
+}
+
+export function writeConfig(patch, env = process.env) {
+  const path = configPath(env);
+  let file = {};
+  try {
+    file = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    /* new file */
+  }
+  const next = { ...file, ...patch };
+  mkdirSync(join(path, ".."), { recursive: true });
+  writeFileSync(path, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+  return path;
+}

package/src/mcp.mjs

@@ -0,0 +1,130 @@
+// The MCP server: the same five things the API does, as tools an agent can
+// call. verify_email and verify_batch run the free DNS tier locally and, when
+// a key is configured, send the survivors to the hosted SMTP probe.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createRequire } from "node:module";
+import { readConfig, writeConfig } from "./config.mjs";
+import { createClient, checkEmails, ApiError } from "./client.mjs";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+
+const VERDICT_DOC =
+  "Each result is { email, action, verdict, reason, checks }. action is send | hold | kill: send means go ahead, hold means send only with a fallback in hand (catch-all, forwarder, greylisted or refused probe), kill means never send (no mail server, or the mailbox does not exist). checks.smtp is skipped on the free DNS tier; the hosted tier probes the mailbox.";
+
+function text(obj) {
+  return { content: [{ type: "text", text: JSON.stringify(obj, null, 2) }], structuredContent: obj };
+}
+
+function failure(err) {
+  const body = err instanceof ApiError ? { error: err.body?.error ?? "api_error", status: err.status, message: err.message, ...(err.body?.checkout_hint ? { checkout_hint: err.body.checkout_hint } : {}) } : { error: "failed", message: err.message };
+  return { ...text(body), isError: true };
+}
+
+export function buildMcpServer({ env = process.env } = {}) {
+  const server = new McpServer({ name: "mxprobe", version });
+
+  // Re-read the config on every call so a signup made through the server is
+  // picked up without a restart.
+  const state = () => {
+    const cfg = readConfig(env);
+    return { cfg, client: createClient({ apiUrl: cfg.apiUrl, apiKey: cfg.apiKey }) };
+  };
+
+  server.registerTool(
+    "verify_email",
+    {
+      title: "Verify one email address",
+      description: `Check whether an email address can receive mail before sending to it. ${VERDICT_DOC} Uses the hosted SMTP probe (1 credit) when an API key is configured and hosted is not false; otherwise the free local DNS tier.`,
+      inputSchema: { email: z.string().describe("The address to check"), hosted: z.boolean().optional().describe("Probe the mailbox on the hosted tier (default: yes when a key is configured)") },
+    },
+    async ({ email, hosted }) => {
+      try {
+        const { cfg, client } = state();
+        const useHosted = hosted ?? !!cfg.apiKey;
+        const out = await checkEmails([email], { hosted: useHosted, client });
+        return text({ ...out.results[0], hosted: useHosted, credits_left: out.credits_left });
+      } catch (err) {
+        return failure(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "verify_batch",
+    {
+      title: "Verify a list of email addresses",
+      description: `Check up to 500 addresses in one call. ${VERDICT_DOC} DNS kills cost nothing; with a key the survivors go to the hosted probe at 1 credit each.`,
+      inputSchema: { emails: z.array(z.string()).min(1).max(500).describe("The addresses to check"), hosted: z.boolean().optional().describe("Probe mailboxes on the hosted tier (default: yes when a key is configured)") },
+    },
+    async ({ emails, hosted }) => {
+      try {
+        const { cfg, client } = state();
+        const useHosted = hosted ?? !!cfg.apiKey;
+        const out = await checkEmails(emails, { hosted: useHosted, client });
+        return text({ results: out.results, summary: out.summary, hosted: useHosted, credits_left: out.credits_left });
+      } catch (err) {
+        return failure(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "signup",
+    {
+      title: "Create an MX Probe API key",
+      description: "Sign up with an email address. Returns an API key with 100 free checks and saves it locally for the other tools. The key is also mailed to the address. One key per address.",
+      inputSchema: { email: z.string().describe("The operator's email address, where the key is mailed") },
+    },
+    async ({ email }) => {
+      try {
+        const { cfg, client } = state();
+        const res = await client.signup(email);
+        const path = writeConfig({ api_key: res.api_key, api_url: cfg.apiUrl, email: res.email }, env);
+        return text({ ok: true, email: res.email, credits: res.credits, api_key: res.api_key, saved_to: path, message: res.message });
+      } catch (err) {
+        return failure(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "balance",
+    { title: "Credits left", description: "How many hosted checks are left on the configured API key.", inputSchema: {} },
+    async () => {
+      try {
+        return text(await state().client.balance());
+      } catch (err) {
+        return failure(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "buy_credits",
+    {
+      title: "Buy credits",
+      description: "Get a Stripe Checkout link for more hosted checks: 9 USD per 10,000, one payment, credits never expire. Open the link to pay; credits land on the key when Stripe confirms.",
+      inputSchema: { packs: z.number().int().min(1).max(100).optional().describe("How many packs of 10,000 (default 1)") },
+    },
+    async ({ packs }) => {
+      try {
+        return text(await state().client.checkout(packs ?? 1));
+      } catch (err) {
+        return failure(err);
+      }
+    },
+  );
+
+  return server;
+}
+
+export async function startMcpServer(opts = {}) {
+  const server = buildMcpServer(opts);
+  await server.connect(new StdioServerTransport());
+  // The transport keeps the process alive while stdin is open; when the
+  // client closes it, in-flight calls finish and the loop drains on its own.
+  return server;
+}