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

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

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

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.