contact-verification-mcp

Melissa의 Global Address, Global Email, Global Phone 검증 API를 핑하는 MCP 서버입니다. SD Times / Melissa 개발자 기사 "Building an MCP Server for a Verification API."와 함께 제공되고자 제작된 것을 입니다.

개요

에이전트가 연락처 데이터에 대해 조치를 취하기 전에 해당 데이터가 실제 데이터인지 확인하기 위해 호출할 수 있는 세 가지 도구와, 배치 도구, 그리고 에이전트가 요금 폭주를 일으키는 무한 프에 빠지지 않도록 는 세션별 호횋 예산이 있 있습니다. 위 구성을 제공합입니다:

• verify_postal_address

• verify_email

• verify_phone

• verify_batch

Related MCP server: email-verify

설정

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

이 서버는 stdio를 통해 MCP 프로토콜을 사용합니다. 따라서 대화형 사용을 위한 단독 실행 방식이 아니라 MCP 클라이언트(Claude Code, Claude Desktop 또는 기타 MCP 호환 호스트)가 시작하도록 설계된 서버입니다.

테스트

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

tests/fixtures/에 있는 픽스처는 _source 필드로 표시됩니다. REAL은 Melissa가 배포한 공개 OpenAPI 예시(github.com/MelissaData/MelissaCloudAPI-OpenAPI-Specifications)에서 그대로 복사된 것을 의미하고, SYNTHETIC은 그 형태의 실제 예시가 Melissa의 공개 스펙에 존재하지 않아(주로 실패 케이스) 테스트 커버리지를 위해 임의로 만든 것임을 뜻합니다. 합성 픽스처의 정확한 결과 코드를 실제 계정에서 검증된 것처럼 취급하지 마십시오.

라이브 테스트 실행

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

이 테스트는 Melissa의 API에 실제 요청을 보내므로 API 크레딧을 소모합니다. 이 테스트는 npm test 또는 CI의 일부로 실행되지 않습니다. 커밋된 파일에 실제 키를 절대 포함하지 말고, 실행 시에만 환경 변수로 키를 지정하십시오.

결과(کرد) 코드 출처

이 코드베이스에서 참조하는 모든 Melissa 결과 코드(AV24, ES01, ES07, ES08, ES21, PS01, PS20, PS22)는 Melissa의 공개 OpenAPI 스펙 예제를 grep으로 확인한 것이며, 추측하거나 기존 기사 초안에서 가져온 것이 아닙니다. 구체적인 근거는 다음과 같습니다:

• AV24는 Melissa의 Global Address 스펙 예시에 등자하는 유일한 AV 접두사 코드이다. 별도의 "하위 세부(subpremises)"에 대한 확인 등급을 나타내는 확인된 코드가 없기 때문에, 이 클라이언트는 그 등급을 주장하지 않습니다.

• Global Email 스펙 예시에는 항상 ES 접두사 코드만 표시됩니다. EE 접두사 코드는 해당 스펙 어느 곳에도 나타나지 않습니다.

• Global Phone의 회선 유형 감지(mobile/월드라인/VoIP)는 프리미엄 모드에서만, 그리고 미국/나다에서만 지원되는 기능이므로 여기서는 일반적인 기능으로 제공되지 않습니노.

만약 귀하의 실제 계정 응답에 위에 나열되지 않은 코드가 포함되어 있다면, 그 코드가 잘못되어서가 아니라 이 클라이언트가 업데이되어야 한다는 사실를 나타냅니다.

아직 구현되지 않은 것

• 다중 인엥스 배포를 위한 Redis 기반 캐시 (현재는 인밖 처리 LRU만 사용 가능하며 src/cache.ts 참조)

• $Feature flag를 통해 프리미엄 모드가 계정에 제공하는 회선 유형 감지

• Melissa 자체 스펙예서 미국/영국/독일 예시에만 국한되지 않은 행국의 포적 커버리지 테스트 (Global Address 기준)