# contact-verification-mcp

An MCP server wrapping Melissa's Global Address, Global Email, and Global Phone
verification APIs. Built to accompany the SD Times / Melissa developer article
"Building an MCP Server for a Verification API."

## What this is

Three tools an agent can call to check whether contact data is real before
acting on it, plus a batch tool and a per-session call budget so an agent
can't loop itself into a runaway bill:

- `verify_postal_address`
- `verify_email`
- `verify_phone`
- `verify_batch`

See `src/melissaClient.ts` for the design choices behind the tool
descriptions, the three-state (confirmed / partially confirmed / not
confirmed) results, and why phone line-type is deliberately not exposed.

## Setup

```bash
npm install
cp .env.example .env
# edit .env and set MELISSA_LICENSE_KEY to your own key
npm run build
npm start
```

The server speaks MCP over stdio, so it's meant to be launched by an MCP
client (Claude Code, Claude Desktop, or any other MCP-compatible host), not
run standalone for interactive use.

## Testing

```bash
npm test          # runs entirely against recorded fixtures, no network calls, no key required
npm run typecheck  # type-checks src/ and tests/ together
```

Fixtures in `tests/fixtures/` are marked with a `_source` field: `REAL` means
copied verbatim from Melissa's published OpenAPI examples
(github.com/MelissaData/MelissaCloudAPI-OpenAPI-Specifications); `SYNTHETIC`
means constructed for test coverage because no real example of that shape
exists in Melissa's public spec (failure cases, mainly). Don't treat a
synthetic fixture's exact result codes as verified against a live account.

### Running live tests

```bash
MELISSA_LICENSE_KEY=your-real-key npm run test:live
```

This makes real calls against Melissa's API and costs API credits. It is
never run as part of `npm test` or CI. Do not put a real key in any committed
file; set it as an environment variable at run time only.

## Result code provenance

Every Melissa result code referenced in this codebase (`AV24`, `ES01`,
`ES07`, `ES08`, `ES21`, `PS01`, `PS20`, `PS22`) was confirmed by grep-ing
Melissa's own published OpenAPI spec examples, not guessed or carried over
from an older article draft. Specifically:

- `AV24` is the only `AV`-prefixed code that appears anywhere in Melissa's
  Global Address spec examples. There is no confirmed code for a distinct
  "confirmed to subpremises" tier, so this client does not claim one.
- Global Email's spec examples only ever show `ES`-prefixed codes. No
  `EE`-prefixed code appears anywhere in that spec.
- Global Phone's line-type detection (mobile/landline/VoIP) is documented as
  Premium-mode-only and US/CA-only, so it is not surfaced as a general
  capability here.

If your account's real responses include codes not listed above, that's a
sign this client needs updating, not that the new code is wrong.

## What's not done yet

- Redis-backed cache for multi-instance deployments (currently in-process
  LRU only, see `src/cache.ts`).
- Line-type detection behind a feature flag for accounts with Premium mode
  enabled.
- Broader country coverage testing for Global Address beyond the US/UK/DE
  examples in Melissa's own spec.