@rocketverifier/mcp 1.0.0

package/README.md

@@ -0,0 +1,100 @@
+# @rocketverifier/mcp
+
+Official [Model Context Protocol](https://modelcontextprotocol.io) server for [RocketVerifier](https://rocketverifier.com). Verify emails, run bulk verification jobs, and check deliverability signals directly from Claude, ChatGPT, Cursor, or any MCP-compatible AI assistant — no code required.
+
+## Tools
+
+| Tool | Credits | Description |
+|---|---|---|
+| `verify_email` | 1 | Real-time single email verification |
+| `create_bulk_job` | 1 per email | Submit up to 100,000 emails for bulk verification |
+| `get_job_status` | free | Check progress/summary counts of a bulk job |
+| `get_job_results` | free | Fetch paginated per-email results |
+| `list_jobs` | free | List recent bulk jobs |
+| `cancel_job` | free | Cancel a pending/processing job and refund credits |
+| `check_credits` | free | Check credit balance and usage |
+| `check_disposable` | free | Check if an email/domain is disposable |
+| `mx_lookup` | free | Look up MX records for a domain |
+| `check_domain_auth` | free | Score SPF/DMARC/DKIM and get fix recommendations |
+
+## Get an API key
+
+Sign up at [app.rocketverifier.com](https://app.rocketverifier.com) and grab a key from **Dashboard → API Keys**. For testing without consuming credits, use a sandbox key (`rv_test_...`) with `@sandbox.rocketverifier.com` addresses (e.g. `deliverable@sandbox.rocketverifier.com`).
+
+## Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "rocketverifier": {
+      "command": "npx",
+      "args": ["-y", "@rocketverifier/mcp"],
+      "env": {
+        "ROCKETVERIFIER_API_KEY": "rv_live_your_api_key"
+      }
+    }
+  }
+}
+```
+
+## Cursor
+
+Add to `.cursor/mcp.json` (project) or your global MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "rocketverifier": {
+      "command": "npx",
+      "args": ["-y", "@rocketverifier/mcp"],
+      "env": {
+        "ROCKETVERIFIER_API_KEY": "rv_live_your_api_key"
+      }
+    }
+  }
+}
+```
+
+## ChatGPT / other remote-MCP clients
+
+If your client supports remote (Streamable HTTP) MCP servers, you can skip the npm install entirely and connect straight to RocketVerifier's hosted endpoint:
+
+```
+URL:  https://api.rocketverifier.com/mcp
+Auth: Bearer rv_live_your_api_key
+```
+
+## Run manually
+
+```bash
+ROCKETVERIFIER_API_KEY=rv_live_your_api_key npx @rocketverifier/mcp
+```
+
+## Example prompts
+
+- "Verify whether jane@acme.com is deliverable."
+- "Check if mailinator.com is a disposable email provider."
+- "Run a domain authentication check on rocketverifier.com and tell me what DNS records I'm missing."
+- "Verify this list of 200 emails in bulk and summarize how many are risky."
+- "How many RocketVerifier credits do I have left?"
+
+## Configuration
+
+| Environment variable | Required | Description |
+|---|---|---|
+| `ROCKETVERIFIER_API_KEY` | Yes | Your RocketVerifier API key (`rv_live_...` or `rv_test_...`) |
+| `ROCKETVERIFIER_BASE_URL` | No | Override the API base URL (default `https://api.rocketverifier.com`) |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run dev   # watch mode
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+interface CreateServerOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+declare function createServer(options: CreateServerOptions): McpServer;
+
+export { createServer };

package/dist/index.js

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// src/client.ts
+var RocketVerifierApiError = class extends Error {
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "RocketVerifierApiError";
+  }
+  code;
+  statusCode;
+  details;
+};
+var RocketVerifierClient = class {
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error(
+        "A RocketVerifier API key is required. Set the ROCKETVERIFIER_API_KEY environment variable."
+      );
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl || "https://api.rocketverifier.com").replace(/\/$/, "");
+    this.timeoutMs = options.timeoutMs ?? 3e4;
+  }
+  async request(method, path, query, body) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0 && value !== "") {
+          url.searchParams.set(key, value);
+        }
+      }
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await fetch(url.toString(), {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": "@rocketverifier/mcp/1.0.0"
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      const data = await response.json().catch(() => ({}));
+      if (!response.ok) {
+        const error = data.error || {};
+        throw new RocketVerifierApiError(
+          error.message || `HTTP ${response.status}`,
+          error.code || "unknown_error",
+          response.status,
+          error.details
+        );
+      }
+      return data;
+    } catch (err) {
+      if (err instanceof RocketVerifierApiError) throw err;
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new RocketVerifierApiError("Request timed out", "timeout", 408);
+      }
+      throw new RocketVerifierApiError(
+        err instanceof Error ? err.message : "Network error",
+        "network_error",
+        0
+      );
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  verifyEmail(email) {
+    return this.request("POST", "/v1/verify", void 0, { email });
+  }
+  createBulkJob(emails, name) {
+    return this.request("POST", "/v1/verify/bulk", void 0, { emails, name });
+  }
+  getJobStatus(jobId) {
+    return this.request("GET", `/v1/jobs/${encodeURIComponent(jobId)}`);
+  }
+  getJobResults(jobId, page = 1, limit = 100, classification) {
+    return this.request("GET", `/v1/jobs/${encodeURIComponent(jobId)}/results`, {
+      page: String(page),
+      limit: String(limit),
+      classification
+    });
+  }
+  listJobs(page = 1, limit = 20, status) {
+    return this.request("GET", "/v1/jobs", { page: String(page), limit: String(limit), status });
+  }
+  cancelJob(jobId) {
+    return this.request("DELETE", `/v1/jobs/${encodeURIComponent(jobId)}`);
+  }
+  getCredits() {
+    return this.request("GET", "/v1/credits");
+  }
+  checkDisposable(emailOrDomain) {
+    const isEmail = emailOrDomain.includes("@");
+    return this.request("POST", "/v1/tools/disposable-check", void 0, {
+      email: isEmail ? emailOrDomain : void 0,
+      domain: isEmail ? void 0 : emailOrDomain
+    });
+  }
+  mxLookup(domain) {
+    return this.request("GET", "/v1/tools/mx-lookup", { domain });
+  }
+  checkDomainAuth(domain) {
+    return this.request("GET", "/v1/tools/domain-auth", { domain });
+  }
+};
+
+// src/server.ts
+function textResult(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
+function errorResult(error) {
+  if (error instanceof RocketVerifierApiError) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `RocketVerifier API error (${error.code}, HTTP ${error.statusCode}): ${error.message}`
+        }
+      ]
+    };
+  }
+  return {
+    isError: true,
+    content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }]
+  };
+}
+function createServer(options) {
+  const client = new RocketVerifierClient({ apiKey: options.apiKey, baseUrl: options.baseUrl });
+  const server = new McpServer({
+    name: "rocketverifier",
+    version: "1.0.0"
+  });
+  server.registerTool(
+    "verify_email",
+    {
+      title: "Verify Email",
+      description: "Verify whether a single email address is deliverable using RocketVerifier. Returns deliverability status (deliverable, undeliverable, risky, unknown), a confidence score, and details about the domain and mailbox. Costs 1 credit per call unless the email is an @sandbox.rocketverifier.com test address.",
+      inputSchema: {
+        email: z.string().describe("The email address to verify, e.g. user@example.com")
+      }
+    },
+    async ({ email }) => {
+      try {
+        return textResult(await client.verifyEmail(email));
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "create_bulk_job",
+    {
+      title: "Create Bulk Verification Job",
+      description: "Submit a list of email addresses (up to 100,000) for asynchronous bulk verification. Returns a job ID you can poll with get_job_status / get_job_results. Costs 1 credit per unique email.",
+      inputSchema: {
+        emails: z.array(z.string()).min(1).describe("List of email addresses to verify"),
+        name: z.string().optional().describe("Optional name to identify this job")
+      }
+    },
+    async ({ emails, name }) => {
+      try {
+        return textResult(await client.createBulkJob(emails, name));
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "get_job_status",
+    {
+      title: "Get Bulk Job Status",
+      description: "Check the progress and summary counts (valid/invalid/risky/unknown) of a bulk verification job.",
+      inputSchema: {
+        jobId: z.string().describe("The job ID returned by create_bulk_job")
+      }
+    },
+    async ({ jobId }) => {
+      try {
+        return textResult(await client.getJobStatus(jobId));
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "get_job_results",
+    {
+      title: "Get Bulk Job Results",
+      description: "Fetch paginated per-email results for a completed or in-progress bulk verification job.",
+      inputSchema: {
+        jobId: z.string().describe("The job ID to fetch results for"),
+        page: z.number().int().min(1).optional().describe("Page number, default 1"),
+        limit: z.number().int().min(1).max(1e3).optional().describe("Results per page, default 100"),
+        classification: z.enum(["valid", "invalid", "risky", "catch_all", "disposable", "unknown"]).optional().describe("Filter results to a single classification")
+      }
+    },
+    async ({ jobId, page, limit, classification }) => {
+      try {
+        return textResult(await client.getJobResults(jobId, page, limit, classification));
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "list_jobs",
+    {
+      title: "List Bulk Jobs",
+      description: "List your recent bulk verification jobs, optionally filtered by status.",
+      inputSchema: {
+        page: z.number().int().min(1).optional().describe("Page number, default 1"),
+        limit: z.number().int().min(1).max(100).optional().describe("Jobs per page, default 20"),
+        status: z.enum(["pending", "processing", "completed", "failed", "cancelled"]).optional().describe("Filter jobs by status")
+      }
+    },
+    async ({ page, limit, status }) => {
+      try {
+        return textResult(await client.listJobs(page, limit, status));
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "cancel_job",
+    {
+      title: "Cancel Bulk Job",
+      description: "Cancel a pending or in-progress bulk verification job and refund unused credits.",
+      inputSchema: {
+        jobId: z.string().describe("The job ID to cancel")
+      }
+    },
+    async ({ jobId }) => {
+      try {
+        return textResult(await client.cancelJob(jobId));
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "check_credits",
+    {
+      title: "Check Credit Balance",
+      description: "Get the current RocketVerifier credit balance and usage for today and this month.",
+      inputSchema: {}
+    },
+    async () => {
+      try {
+        return textResult(await client.getCredits());
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "check_disposable",
+    {
+      title: "Check Disposable Email",
+      description: "Free tool (no credits): check whether an email address or domain belongs to a known disposable/temporary email provider.",
+      inputSchema: {
+        emailOrDomain: z.string().describe('An email address or bare domain, e.g. "user@mailinator.com" or "mailinator.com"')
+      }
+    },
+    async ({ emailOrDomain }) => {
+      try {
+        return textResult(await client.checkDisposable(emailOrDomain));
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "mx_lookup",
+    {
+      title: "MX Lookup",
+      description: "Free tool (no credits): look up MX records for a domain to confirm it can receive email.",
+      inputSchema: {
+        domain: z.string().describe('Domain to look up, e.g. "example.com"')
+      }
+    },
+    async ({ domain }) => {
+      try {
+        return textResult(await client.mxLookup(domain));
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "check_domain_auth",
+    {
+      title: "Check Domain Email Authentication",
+      description: "Free tool (no credits): analyze SPF, DMARC, and common DKIM selectors for a domain. Returns a 0-100 deliverability authentication score and concrete DNS fix recommendations.",
+      inputSchema: {
+        domain: z.string().describe('Domain to analyze, e.g. "example.com"')
+      }
+    },
+    async ({ domain }) => {
+      try {
+        return textResult(await client.checkDomainAuth(domain));
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  const apiKey = process.env.ROCKETVERIFIER_API_KEY;
+  if (!apiKey) {
+    console.error(
+      "Error: ROCKETVERIFIER_API_KEY environment variable is required.\nGet an API key at https://app.rocketverifier.com/dashboard/api-keys and set it, e.g.:\n  ROCKETVERIFIER_API_KEY=rv_live_xxx npx @rocketverifier/mcp"
+    );
+    process.exit(1);
+  }
+  const server = createServer({
+    apiKey,
+    baseUrl: process.env.ROCKETVERIFIER_BASE_URL
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("RocketVerifier MCP server running on stdio.");
+}
+main().catch((error) => {
+  console.error("Fatal error starting RocketVerifier MCP server:", error);
+  process.exit(1);
+});
+export {
+  createServer
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@rocketverifier/mcp",
+  "version": "1.0.0",
+  "description": "Official RocketVerifier MCP server - verify emails from Claude, ChatGPT, Cursor, and any MCP-compatible AI assistant",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "rocketverifier-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "email",
+    "verification",
+    "email-verification",
+    "rocketverifier",
+    "ai",
+    "claude",
+    "chatgpt",
+    "cursor",
+    "llm-tools"
+  ],
+  "author": "RocketVerifier",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rocketverifier/mcp-server.git"
+  },
+  "homepage": "https://docs.rocketverifier.com/mcp",
+  "bugs": {
+    "url": "https://github.com/rocketverifier/mcp-server/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}