contact-verification-mcp

MCP-сервер, оборачивающий API верификации Melissa (Global Address, Global Email и Global Phone). Создан в качестве дополнения к статье для разработчиков SD Times / Melissa «Разработка MCP-сервера для API верификации».

Что это

Три инструмента, которые агент может вызвать, чтобы проверить, являются ли контактные данные настоящими, прежде чем действовать на их основе, плюс пакетный инструмент и лимит вызовов на сессию, чтобы агент не мог зациклиться и накрутить бесконтрольный счёт:

• verify_postal_address

• verify_email

• verify_phone

• verify_batch

Проектные решения, стоящие за описаниями инструментов, трёх состояний результата (подтверждено / частично подтверждено / не подтверждено) и того, почему тип телефоновой линии на мер ne раскрвается, описаны в src/melissaClient.ts.

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

Сервер рабоTaет by MCP через stdio, поэтому предназначен для запуска MCP-клиентом (Staude Code, Staude 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/фixtures/ помечены полем _source: REAL означает, что дословно скопировано из опубликованных OpenAPI-примеров Melissa (github.com/MelissaData/MelissaCloudAPI-OpenAPI-Specifications); SYNTHETIC означает, что создано для попротия теста, потому что реально такого примера в публичной спецификации Melissa не существует (в осноном прихо, это сбочные случаи). Не расценивайте точные код начатой резулята синтетической фикстуры как выверенные на живом инв аккаунте.

Запуск живых тестов

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

Такое тестирование выполняет реальные вызовы к API оказаний Melissa и расхodusет API-кредиты. Оно никогда не запускается в составе npm test или CI. Не помещайте настоящую ключ в какой-либо закоммичённый файл; задвайе его только в виде переменной окружия на время выполея.

Исходные коды результатов

Каждый код результата Melissa, на котору ссылается эта кодовая база (AV24, ES01, ES07, ES08, ES21, PS01, PS20, PS22), был подтверждён с помощью grep по опубликованным примерам из OpenAPI-спецификации самой Melissa, а не угадан и не перенесён из старого черновика статьы. Актульно:

• AV24 — единственный код с префиксом AV, котору встречается в примерах спецификации Global Address. Подтверждённого кода для отдельного уровня «подтверждено на уровне subpremises» нет, поэтому этот клиент такой код не заявляет.

• В примерах спецификации Global Email встречаются только коды с префиксом ES. Код с префиксом EE не появляется нигде в этой спецификации.

• Determineление типа телефной линии в Global Phone (мобильный став/стационарный/VoIP) документировано как доступное только в режиме Premium и только для US/CA, поэтому здес оно не предстаётся в качестве общей возмож распределения.

Если в реальных ответах вашего аккаунта есть коды, не перечисленные выше, это знаком что данный клиент требует обновления, а не то, что новый код ошибочен.

Что ещё не сделено

• Кэш на Redis для многонстанциинных развёрт (сейса только внутрипроцессовый LRU, см. src/cache.ts).

• Определение типа линии с фичой (feature flag) для аккантов с взведом Premium.

• Более широкое тестирование покрытия по странам для Global Address акже, в примерах с US/UK/DE in своим рель самым Melissa.