Email Verification MCP Server

A TypeScript MCP server that exposes a clean, well-typed verify_email tool for email verification.

The tool returns a structured result that an agent can consume:

• valid
• invalid
• risky
• reason
• individual check results
• metadata such as domain, provider, cache status, and lookup latency

It also includes a simple human-friendly CLI mode for demos, testing, and Loom recordings.

What This Project Does

This project implements Option A: MCP server.

It provides an MCP server over STDIO with the following tools:

Tool	Purpose
verify_email	Verifies an email address and returns valid, invalid, or risky with a reason
mcping	Confirms that the server is alive
mchelp	Shows help for available tools and topics

The main required tool is:

verify_email({
  email: "test@gmail.com"
})

Highlights

• MCP-ready: Uses the official @modelcontextprotocol/server package.
• Well-typed interface: Input and output schemas are defined with Zod.
• Structured output: Returns machine-readable structuredContent for agents.
• Readable output: Returns clear text output for humans.
• Simple CLI demo mode: Run npm run verify -- test@gmail.com instead of writing raw JSON-RPC.
• Validation pipeline: Syntax, domain, MX, and disposable-provider checks.
• Mock backend support: Includes a deterministic backend layer suitable for local testing.
• STDIO-safe logging: MCP mode keeps stdout clean for JSON-RPC transport.

Quick Start

cd /Users/satvikkesarwani/Desktop/tvaram
npm install
npm run build

Loom Demo Commands

Use these commands to quickly prove the system is ready.

1. Build the project

npm run build

2. Verify a valid email

npm run verify -- test@gmail.com

Expected style of output:

Email Verification Result
=========================

Email: test@gmail.com
Verdict: VALID - Safe to send
Reason: Email appears valid

Checks
------
Syntax: PASS
Domain exists: PASS
MX records: PASS
Disposable address: PASS - not disposable

Details
-------
Domain: gmail.com
Provider: not detected
Cached result: no
Lookup time: 1 ms

Recommendation
--------------
This address passed the available checks. It looks suitable for normal outreach.

3. Verify a risky disposable email

npm run verify -- test@guerrillamail.com

This should return a RISKY verdict because the domain is a known disposable email provider.

4. Verify an invalid email

npm run verify -- invalid-email

This should return an INVALID verdict because the email syntax is wrong.

5. Ping the server

npm run ping

This confirms the server package is responding.

CLI Usage

The project supports short CLI commands for human testing:

npm run verify -- test@gmail.com
npm run verify -- test@guerrillamail.com
npm run verify -- invalid-email
npm run ping
npm run help

You can also run the compiled file directly:

node build/index.js verify_email test@gmail.com
node build/index.js verify test@gmail.com
node build/index.js mcping
node build/index.js mchelp verify_email

Run without arguments to start the actual MCP server:

npm start

MCP Tool Interface

Tool Name

verify_email

Input Schema

{
  email: string;
  options?: {
    checkMx?: boolean;
    checkDisposable?: boolean;
    timeoutMs?: number;
  };
}

Output Schema

{
  email: string;
  status: "valid" | "invalid" | "risky";
  reason: string;
  checks: {
    syntax: boolean;
    domain: boolean;
    mx?: boolean;
    disposable?: boolean;
  };
  metadata: {
    domain: string;
    provider?: string;
    cached: boolean;
    latencyMs: number;
  };
}

Example Structured Result

{
  "email": "test@gmail.com",
  "status": "valid",
  "reason": "Email appears valid",
  "checks": {
    "syntax": true,
    "domain": true,
    "mx": true,
    "disposable": true
  },
  "metadata": {
    "domain": "gmail.com",
    "cached": false,
    "latencyMs": 1
  }
}

How MCP Clients Use It

The server uses STDIO transport. MCP clients should start it with:

node build/index.js

Example client configuration:

{
  "mcpServers": {
    "email-verifier": {
      "command": "node",
      "args": ["/Users/satvikkesarwani/Desktop/tvaram/build/index.js"]
    }
  }
}

The simple CLI commands are only for humans and demos. The MCP server mode remains available when the file is started without CLI arguments.

Available Scripts

Command	Description
npm run build	Compiles TypeScript into build/
npm start	Starts the MCP server over STDIO
npm run verify -- <email>	Runs human-friendly email verification
npm run ping	Runs a quick server status check
npm run help	Shows CLI help
npm test	Runs the test command
npm run lint	Runs the lint command

Verification Flow

1. Normalize the email address
2. Check the in-memory cache
3. Validate email syntax
4. Extract and validate the domain
5. Check MX records when enabled
6. Check disposable email providers when enabled
7. Fall back to the mock backend when needed
8. Return both readable text and structured content

Project Structure

tvaram/
├── src/
│   ├── config/
│   │   └── index.ts
│   ├── services/
│   │   ├── cache.ts
│   │   ├── mock-backend.ts
│   │   ├── retry.ts
│   │   └── verification.ts
│   ├── types/
│   │   ├── errors.ts
│   │   └── verification.ts
│   ├── utils/
│   │   ├── dns.ts
│   │   └── logger.ts
│   ├── validation/
│   │   ├── disposable.ts
│   │   ├── domain.ts
│   │   ├── pipeline.ts
│   │   └── syntax.ts
│   └── index.ts
├── build/
├── package.json
├── tsconfig.json
└── README.md

Configuration

Configuration lives in:

src/config/index.ts

Current defaults:

Area	Setting	Default
Server	name	email-verifier
Server	version	1.0.0
DNS	timeout	2000 ms
DNS	retries	1
Cache	max size	10000
Cache	TTL	1 hour
Retry	max attempts	3
Circuit breaker	threshold	5 failures
Circuit breaker	reset timeout	30 seconds
Mock backend	error rate	0.01

Design Notes

• The MCP server writes protocol responses to stdout.
• Logs are written to stderr so JSON-RPC messages are not corrupted.
• CLI mode silences logs for clean human-readable output.
• Zod schemas keep the tool input and output explicit and agent-friendly.
• The verification backend is mockable so the MCP interface can be tested without depending on a paid or external verification API.

Limitations

• This is not full SMTP mailbox verification.
• DNS behavior can vary by network and resolver.
• Disposable detection depends on the embedded blocklist.
• The mock backend is deterministic and useful for testing, but it is not a production deliverability provider.

Submission Summary

This project satisfies the assignment requirement:

An MCP server exposing at least one tool, for example verify_email(address), returning a structured result: valid, invalid, or risky plus a reason.

The implementation includes:

• MCP server over STDIO
• verify_email tool
• Zod input/output schemas
• structured agent-readable result
• readable human output
• CLI demo commands
• TypeScript build setup