contact-verification-mcp

Ein MCP-Server, der die Global-Address-, Global-Email- und Global-Phone-Verifizierung-APIs von Melisa kapselt. Er wurde als Begleitprojekt zum SD-Times-/Melissa-Entwicklerartikel „Entwicklung eines MCP-Servers für eine Verifizierungs-API“ erstellt.

Was das ist

Drei Werkzeuge, die ein Agent aufrufen kann, um zu prüfen, ob Kontaktdaten echt sind, bevor er darauf reagiert, plus ein Batch-Werkzeug und ein Aufrufbudget pro Sitzung, damit ein Agent sich nicht in eine uferlose Rechnung verstricken kann:

• verify_postal_address

• verify_email

• verify_phone

• verify_batch

Siehe src/melissaClient.ts für die Design-Entscheidungen hinter den Tool-Beschreibungen, die Drei-Zustand-Ergebnisse (bestätigt / teilweise bestätigt / nicht bestätigt) und dafür, warum der Telefon-Leitungstyp bewusst nicht offengelegt wird.

Related MCP server: email-verify

Einrichtung

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

Der Server spricht MCP über stdio. Er ist also dafür gedacht, von einem MCP-Client (Claude Code, Claude Desktop oder einem anderen MCP-kompatiblen Host) gestartet zu werden – nicht, eigenständig für die interaktive Nutzung ausgeführt zu werden.

Tests

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

Die Fixtures in tests/fixtures/ sind mit einem _source-Feld markiert: REAL bedeutet, dass das Fixture wörtlich aus Melissas veröffentlichten OpenAPI-Beispielen übernommen wurde (github.com/MelissaData/MelissaCloudAPI-OpenAPI-Specifications); SYNTHETIC bedeutet, dass es für die Testabdeckung konstruiert wurde, weil es in Melissas öffentlicher Spezifikation kein reales Beispiel dieser Form gibt (hauptsächlich Fehlerfälle). Die genauen Ergebnis-Codes eines synthetischen Fixtures sind nicht als gegen einen Live-Account verifiziert zu behandeln.

Live-Tests ausführen

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

Dabei werden echte Aufrufe gegen Melissas API ausgeführt und API-Guthaben verbraucht. Sie werden nie als Teil von npm test oder in CI ausgeführt. Kein echter Schlüssel darf in eine eingecheckte Datei geschrieben werden; er ist ausschließlich zur Laufzeit als Umgebungsvariable zu setzen.

Herkunft der Ergebnis-Codes

Jeder in dieser Codebasis referenzierte Melissa-Ergebnis-Code (AV24, ES01, ES07, ES08, ES21, PS01, PS20, PS22) wurde per grep über Melissas eigene veröffentlichte OpenAPI-Spezifikationsbeispiele bestätigt, nicht geraten oder aus einem älteren Artik-Entwurf üübernommen. Im Einzelnen:

• AV24 ist der einzige AV-präfixierte Code, der irgendwo in den Global-Address-Beispielen von Melisa vorkommt. Es gibt keinen bestätigten Code für eine eigene Stufe „bestätigt bis Untereinheit“, daher erhebt dieser Client keinen solchen Anspruch.

• Die Spezifikationsbeispiele von Global Email zeigen ausschließlich ES-präfixierte Codes. Ein EE-präfixierter Code kommt an keiner Stelle dieser Spezifikation vor.

• Die Leitungstyp-Erkennung von Global Phone (mobile/Festnetz/VoIP) ist laut Dokumentation nur im Premium-Modus und nur für US/CA verfügbar; sie wird hier also nicht als allgemeine Fähigkeit ausgewiesen.

Wenn die realen Antworten Ihres Kontos Codes enthalten, die in der obigen Liste nicht aufgeführt sind, ist das ein Zeichen dafür, dass dieser Client aktualisiert werden muss, und nicht, dass der neue Code falsch ist.

Was noch nicht erledigt ist

• Redis-gestützter Cache für Multi-Instanz-Betrieb (bis jetzt nur eine In-Prozess-LRU, sieh src/cache.ts).

• Leitungstyp-Erkennung hinter einem Feature-Flag für Konten mit aktivem Premium-Modus.

• Umfangreichere Länder-Tests für Global Address über die in Melissalem US-/UK-/DE-Beispiele -Beispielen hinaus.