contact-verification-mcp

Un servidor MCP que envuelve las API de verificación Global Address, Global Email y Global Phone de Melissa. Creado para acompañar al artículo para desarrolladores de SD Times / Melissa "Construcción de un servidor MCP para una API de verificación".

Qué es esto

Tres herramientas que un agente puede llamar para comprobar si los datos de contacto son reales antes de actuar sobre ellos, más una herramienta por lotes y un presupuesto de llamadas por sesión para que un agente no pueda encadenar llamadas hasta generar una factura descontrolada:

• verify_postal_address

• verify_email

• verify_phone

• verify_batch

Consulta src/melissaClient.ts para conocer las decisiones de diseño tras las descripciones de las herramientas, los resultados de tres estados (confirmado / parcialmente confirmado / no confirmado) y por qué el tipo de línea telefónica no se expone deliberadamente.

Related MCP server: email-verify

Configuración

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

El servidor habla MCP a través de stdio, por lo que está pensado para ser lanzado por un cliente MCP (Claude Code, Claude Desktop o cualquier otro host compatible con MCP), no para ejecutarse de forma independiente con uso interactivo.

Pruebas

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

Las fixtures de tests/fixtures/ están marcadas con un campo _source: REAL significa copiado literalmente de los ejemplos publicados de OpenAPI por Melissa (github.com/MelissaData/MelissaCloudAPI-OpenAPI-Specifications); SYNTHETIC significa construido para cobertura de pruebas porque no existe ningún ejemplo real con esa forma en la especificación pública de Melissa (sobre todo casos de error). No trates los códigos de resultado exactos de una fixture sintética como verificados contra una cuenta real.

Ejecutar las pruebas en vivo

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

Esto hace llamadas reales a la API de Melissa y consume créditos de API. Nunca se ejecuta como parte de npm test ni de CI. No pongas una clave real en ningún archivo que se vaya a commitear; configúrala solo como variable de entorno en tiempo de ejecución.

Procedencia de los códigos de resultado

Todos los códigos de resultado de Melissa a los que se hace referencia en esta base de código (AV24, ES01, ES07, ES08, ES21, PS01, PS20, PS22) se confirmaron haciendo grep en los ejemplos publicados de la propia especificación OpenAPI de Melissa, sin adivinarlos ni arrastrarlos de un borrador anterior del artículo. En concreto:

• AV24 es el único código con prefijo AV que aparece en los ejemplos de la especificación de Global Address. No hay ningún código confirmado para una categoría distinta de "confirmado a nivel de subpremisa", así que este cliente no la reivindica.

• Los ejemplos de la especificación de Global Email solo muestran códigos con prefijo ES. No aparece ningún código con prefijo EE en esa especificación.

• La detección del tipo de línea en Global Phone (móvil / fijo / VoIP) está documentada como exclusiva del modo Premium y solo para EE. UU./Canadá, por lo que no se presenta aquí como una capacidad general.

Si las respuestas reales de tu cuenta incluyen códigos que no aparecen en la lista anterior, es una señal de que este cliente necesita actualizarse, no de que el código nuevo sea incorrecto.

Lo que aún no se ha hecho

• Compatibilidad con caché Redis para despliegues multi-instancia (actualmente solo LRU en proceso; ver src/cache.ts).

• Detección del tipo de línea detrás de una feature flag para cuentas con modo Premium activado.

• Pruebas de cobertura por país de Global Address más amplias que los ejemplos US/UK/DE de la propia especificación de Melissa.