@datapad-nl/vouch-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Datapad
+
+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,85 @@
+# @datapad-nl/vouch-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for **[Vouch](https://vouch.fast)** email
+verification. It gives your AI assistant (Claude, Cursor, Cline, …) a `verify_email` tool that checks
+whether an email address is really deliverable — syntax, MX records, a live SMTP probe, and catch-all
+detection — and returns a verdict, a 0–100 confidence score, and quality flags.
+
+## Prerequisites
+
+- A Vouch API key (`vch_live_…`) — get one from the [dashboard](https://vouch.fast/dashboard).
+- Node.js ≥ 18 (provides `npx`).
+
+## Install
+
+Add the server to your MCP client's config. There is nothing to install ahead of time — `npx` fetches
+the package on first run.
+
+**Claude Desktop, Claude Code, Cline, Windsurf, and most clients** (`.mcp.json` /
+`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "vouch": {
+      "command": "npx",
+      "args": ["-y", "@datapad-nl/vouch-mcp"],
+      "env": { "VOUCH_API_KEY": "vch_live_your_key_here" }
+    }
+  }
+}
+```
+
+**Claude Code (CLI):**
+
+```bash
+claude mcp add vouch --env VOUCH_API_KEY=vch_live_your_key_here -- npx -y @datapad-nl/vouch-mcp
+```
+
+**Cursor:** Settings → MCP → *Add new server*, then use the same `command`, `args`, and `env` as above.
+
+## The tool
+
+**`verify_email`** — input `{ "email": "jane@example.com" }`. Returns a one-line summary plus the full
+JSON verdict:
+
+```json
+{
+  "email": "jane@example.com",
+  "user": "jane",
+  "domain": "example.com",
+  "status": "deliverable",
+  "reason": "mailbox_exists",
+  "score": 95,
+  "checks": { "syntax": true, "domainHasMx": true, "smtpConnected": true, "mailboxExists": true, "catchAll": false },
+  "flags": { "disposable": false, "roleAccount": false, "freeProvider": false },
+  "didYouMean": null,
+  "mxHost": "aspmx.l.google.com",
+  "meta": { "durationMs": 412, "checkedAt": "2026-06-11T13:28:23.957Z" }
+}
+```
+
+- **status** — `deliverable` · `undeliverable` · `risky` · `unknown`
+- **score** — 0–100 confidence
+- **flags** — `disposable`, `roleAccount`, `freeProvider`
+- **didYouMean** — a corrected address when a likely typo is detected (e.g. `jane@gmial.com` →
+  `jane@gmail.com`)
+
+Ask your assistant something like *"Is jane@exmaple.com a real address?"* and it will call `verify_email`
+and report back the verdict and any typo suggestion.
+
+## Configuration
+
+| Env var          | Required | Default                     | Description                          |
+| ---------------- | -------- | --------------------------- | ------------------------------------ |
+| `VOUCH_API_KEY`  | yes      | —                           | Your `vch_live_…` key.               |
+| `VOUCH_API_URL`  | no       | `https://vouch.fast`  | Override the API base URL.           |
+
+## Privacy
+
+The server runs locally on your machine. Your API key and the address you verify are sent only to the
+Vouch API over HTTPS — nothing is transmitted or stored by this package itself.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * Vouch MCP server (stdio transport).
+ *
+ * Exposes one tool — `verify_email` — that calls the hosted Vouch API
+ * (GET /v1/verify) with the customer's API key and returns the deliverability
+ * verdict. The key stays on the customer's machine; it is sent only as a Bearer
+ * token to the Vouch API over HTTPS.
+ *
+ * Environment:
+ *   VOUCH_API_KEY  (required)  your vch_live_… key — https://vouch.fast/dashboard
+ *   VOUCH_API_URL  (optional)  API base URL, default https://vouch.fast
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const VERSION = "0.1.0";
+const DEFAULT_API_URL = "https://vouch.fast";
+// SMTP probes can take several seconds; allow margin over the API's ~8s budget.
+const REQUEST_TIMEOUT_MS = 20_000;
+function apiBase() {
+    const raw = process.env.VOUCH_API_URL?.trim() || DEFAULT_API_URL;
+    return raw.replace(/\/+$/, "");
+}
+function errorResult(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+function formatSummary(r) {
+    const flags = (r.flags ?? {});
+    const tags = Object.keys(flags).filter((k) => flags[k]);
+    const flagStr = tags.length ? ` [${tags.join(", ")}]` : "";
+    const score = typeof r.score === "number" ? `${r.score}/100` : "n/a";
+    const reason = r.reason ? ` (${String(r.reason)})` : "";
+    const dym = r.didYouMean ? ` — did you mean ${String(r.didYouMean)}?` : "";
+    return `${String(r.email ?? "email")} → ${String(r.status ?? "unknown")}${reason}, score ${score}${flagStr}${dym}`;
+}
+async function verifyEmail(email) {
+    const key = process.env.VOUCH_API_KEY?.trim();
+    if (!key) {
+        return errorResult("VOUCH_API_KEY is not set. Add your Vouch API key (vch_live_…) to this server's " +
+            "environment. Get one from the dashboard at https://vouch.fast/dashboard.");
+    }
+    const url = `${apiBase()}/v1/verify?email=${encodeURIComponent(email)}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    let res;
+    try {
+        res = await fetch(url, {
+            headers: {
+                Authorization: `Bearer ${key}`,
+                Accept: "application/json",
+                "User-Agent": `vouch-mcp/${VERSION}`,
+            },
+            signal: controller.signal,
+        });
+    }
+    catch (e) {
+        const aborted = e instanceof Error && e.name === "AbortError";
+        return errorResult(aborted
+            ? `Verification timed out after ${REQUEST_TIMEOUT_MS / 1000}s.`
+            : `Could not reach the Vouch API: ${e instanceof Error ? e.message : String(e)}.`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const raw = await res.text();
+    let body = null;
+    try {
+        body = raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        /* non-JSON body — handled below */
+    }
+    const obj = (body && typeof body === "object" ? body : {});
+    if (!res.ok) {
+        const detail = obj.message || obj.error || raw || `HTTP ${res.status}`;
+        const hint = res.status === 401
+            ? " Check that VOUCH_API_KEY is correct and active."
+            : res.status === 402
+                ? " You're out of verification credits — top up at https://vouch.fast/dashboard."
+                : res.status === 429
+                    ? ` Rate limited${obj.retryAfter ? `; retry after ${String(obj.retryAfter)}s` : ""}.`
+                    : "";
+        return errorResult(`Vouch API error (${res.status}): ${String(detail)}.${hint}`);
+    }
+    if (!body || typeof body !== "object") {
+        return errorResult(`Unexpected response from the Vouch API: ${raw.slice(0, 200)}`);
+    }
+    const text = `${formatSummary(obj)}\n\n\`\`\`json\n${JSON.stringify(obj, null, 2)}\n\`\`\``;
+    return { content: [{ type: "text", text }] };
+}
+async function main() {
+    const server = new McpServer({ name: "vouch", version: VERSION });
+    server.registerTool("verify_email", {
+        title: "Verify email address",
+        description: "Check whether an email address is deliverable using Vouch. Runs syntax validation, MX lookup, " +
+            "a live SMTP probe, and catch-all detection, then returns a verdict (deliverable, undeliverable, " +
+            "risky, or unknown), a 0–100 confidence score, quality flags (disposable, role account, free " +
+            "provider), and a typo suggestion when relevant. Use before sending email or accepting a signup.",
+        inputSchema: {
+            email: z
+                .string()
+                .min(1)
+                .describe("The email address to verify, e.g. jane@example.com"),
+        },
+    }, async ({ email }) => verifyEmail(email.trim()));
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Never write to stdout — it carries the JSON-RPC protocol. stderr is safe.
+    console.error(`[vouch-mcp] v${VERSION} ready (API ${apiBase()})`);
+}
+main().catch((e) => {
+    console.error("[vouch-mcp] fatal:", e);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@datapad-nl/vouch-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Vouch — verify email deliverability (syntax, MX, live SMTP, catch-all) with your Vouch API key.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "email",
+    "email-verification",
+    "deliverability",
+    "vouch",
+    "smtp"
+  ],
+  "homepage": "https://vouch.fast",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Datapad-nl/Vouch.git",
+    "directory": "mcp"
+  },
+  "license": "MIT",
+  "author": "Datapad",
+  "type": "module",
+  "bin": {
+    "vouch-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsx": "^4.21.1",
+    "typescript": "^5"
+  }
+}