Address Validator MCP server

Address Validator API

API HTTP payante à la requête (protocole x402, prix par défaut 0.02 USDC) qui prend une adresse de livraison brute et renvoie une adresse standardisée, ses coordonnées, un score de livrabilité et une clé de cache.

1. Présentation

tant qu'aucune preuve de paiement valide n'est fournie.

• Entrée unique payante : POST /validate — refuse en 402 Payment Required

country), latitude/longitude (géocodage Nominatim), deliverability, confidence, degraded et cache_key.

• Sortie : adresse standardisée (line1, line2, city, state, zip,

annuaire x402 / MCP.

• Découverte : GET /manifest décrit le service et son schéma pour un

200 avec degraded: true — jamais une erreur qui laisserait croire à une adresse invalide certaine.

• Résilience : si le fournisseur est injoignable, l'API répond quand même

Critères de succès de la spec, et où ils sont vérifiés automatiquement :

Ce que ce service ne fait pas : aucun rate limiting applicatif (D21) — la limite est tenue au niveau edge par Nginx (nginx-hardening.conf : 10 requêtes/s par IP, rafale 20, 429 au-delà) — et la vérification de paiement on-chain est disponible mais désactivée par défaut (D15 pour le mode par défaut, D27 pour la couche optionnelle). Les deux sont documentés (README.md §7 et §9, SECURITY.md §3 et §6) plutôt que passés sous silence.

2. Démarrage rapide

Prérequis : Python 3.12 (le venv du dépôt tourne en 3.12.10, comme l'image python:3.12-slim du Dockerfile). PostgreSQL et Redis sont facultatifs : sans eux, l'API démarre et se dégrade proprement (/health le dit).

# 1. Environnement virtuel
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt -r requirements-dev.txt

# 2. Configuration (jamais de secret dans le dépôt)
Copy-Item .env.example .env        # renseigner SMARTY_AUTH_ID / API_SECRET_KEY / clés CDP

# 3. Lancer l'API
.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8000

# Vérifications
.\.venv\Scripts\python.exe -m pytest -q                  # suite complète
.\.venv\Scripts\python.exe scripts\run_tests.py          # oracle de tests (rapport JUnit)
.\.venv\Scripts\python.exe scripts\doc_check.py README.md 10   # sections de ce fichier
.\.venv\Scripts\python.exe scripts\e2e_check.py http://127.0.0.1:8000   # recette bout-en-bout

Démarrage conteneurisé : docker compose up -d (voir docker-compose.yml et Dockerfile).

Déploiement en production (VPS Debian 12, Nginx + HTTPS, paiement x402) : DEPLOIEMENTVPS.md** — compte rendu réel, écarts assumés par rapport au plan et points de vigilance d'exploitation.

3. Configuration

Toutes les valeurs viennent de l'environnement ou de .env (pydantic-settings, app/config.py). Une variable inconnue est ignorée (décision D8).

Shortened. The full README is on GitHub.