# 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:

```ts
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

```bash
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

```bash
npm run build
```

### 2. Verify a valid email

```bash
npm run verify -- test@gmail.com
```

Expected style of output:

```text
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

```bash
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

```bash
npm run verify -- invalid-email
```

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

### 5. Ping the server

```bash
npm run ping
```

This confirms the server package is responding.

## CLI Usage

The project supports short CLI commands for human testing:

```bash
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:

```bash
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:

```bash
npm start
```

## MCP Tool Interface

### Tool Name

```text
verify_email
```

### Input Schema

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

### Output Schema

```ts
{
  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

```json
{
  "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:

```bash
node build/index.js
```

Example client configuration:

```json
{
  "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

```text
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

```text
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:

```text
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