FactCheck MCP Toolkit

FactCheck MCP Toolkit

Serveur MCP pour la verification automatisee de declarations politiques chiffrees, connecte aux APIs statistiques institutionnelles.

Le LLM compatible MCP (ex: Claude Desktop) utilise les outils exposes par ce serveur pour verifier des affirmations factuelles contre les donnees officielles de l'INSEE, Eurostat, la Banque mondiale et l'OCDE.

Fonctionnalites

• Resolution d'indicateurs — Traduit les termes courants du debat politique ("chomage", "dette publique", "inflation") vers les codes d'indicateurs officiels via une ontologie de 30 entrees avec regles de desambiguisation
• Donnees INSEE — Recherche, metadonnees et series temporelles depuis le BDM (Banque de donnees macroeconomiques) via pynsee
• Comparaisons internationales — Donnees Eurostat (UE27), Banque mondiale (217 pays) et OCDE, avec classements par pays
• Fact-checks existants — Recherche dans les bases Google Fact Check Tools et scoring de check-worthiness via ClaimBuster
• Detection de cherry-picking — Analyse de robustesse temporelle par perturbation des bornes de dates, avec score de robustesse 0-1
• Comparaison de valeurs — Ecart absolu/relatif entre valeur declaree et valeur reelle, avec qualification indicative (negligeable/significatif/majeur)
• Cache persistant — diskcache avec TTL par source (24h INSEE, 12h Eurostat, 7j Banque mondiale, 1h Google FC)

Outils MCP exposes (18)

| Module | Outils | Description | |--------|--------|-------------| | resolver | resolve_indicator | Resolution de termes vers codes indicateurs | | insee | insee_search_indicators, insee_get_indicator_metadata, insee_get_data, insee_search_geography | Donnees macroeconomiques francaises | | eurostat | eurostat_search_datasets, eurostat_get_data, eurostat_get_ranking, eurostat_get_dataset_structure | Donnees europeennes comparatives | | worldbank | worldbank_search_indicators, worldbank_get_data, worldbank_get_country_ranking | Donnees mondiales | | oecd | oecd_search_datasets, oecd_get_data | Donnees OCDE via SDMX | | factcheck | lookup_existing_factchecks, score_check_worthiness | Fact-checks existants + scoring | | cherry_picking | analyze_cherry_picking | Detection de cherry-picking temporel | | compare | compare_values | Comparaison valeur declaree vs reelle |

Prerequis

• Python 3.12+
• uv (gestionnaire de paquets)
• Cles API (optionnelles) : Google Fact Check (Google Cloud Console), ClaimBuster (idir.uta.edu)

Aucune cle API necessaire pour : INSEE BDM, Eurostat, Banque mondiale, OCDE (gratuits et ouverts).

Installation

git clone <repo-url>
cd factcheck-mcp
uv sync

Configuration

Creer un fichier .env a la racine du projet :

GOOGLE_FACTCHECK_API_KEY=votre_cle_google
CLAIMBUSTER_API_KEY=votre_cle_claimbuster
FACTCHECK_CACHE_DIR=~/.cache/factcheck-mcp

Les outils fonctionnent sans cles API (les fonctions Google FC et ClaimBuster retournent des listes vides au lieu de planter).

Integration Claude Desktop

Ajouter dans ~/.config/claude/claude_desktop_config.json :

{
  "mcpServers": {
    "factcheck": {
      "command": "uv",
      "args": ["run", "--directory", "/chemin/vers/factcheck-mcp", "factcheck-mcp"],
      "env": {
        "GOOGLE_FACTCHECK_API_KEY": "votre_cle",
        "CLAIMBUSTER_API_KEY": "votre_cle"
      }
    }
  }
}

Verification

Depuis Claude Desktop, demander :

"Le chomage en France a baisse de 2 points depuis 2020, verifie cette affirmation."

Le LLM invoquera les outils MCP pour :

1. Chercher des fact-checks existants
2. Resoudre "chomage" vers le taux de chomage BIT de l'INSEE
3. Recuperer les donnees reelles
4. Comparer et produire un rapport avec sources

Developpement

# Lancer les tests unitaires (152 tests)
uv run pytest

# Lancer les tests en mode verbose
uv run pytest -v

# Lancer les tests d'integration (APIs reelles, necessite reseau)
uv run pytest -m integration

# Lancer le serveur en mode standalone (debug)
uv run factcheck-mcp

# Lint et formatage
uv run ruff check src/ tests/
uv run ruff format src/ tests/

Architecture

src/factcheck_mcp/
├── server.py              # Serveur FastMCP, enregistrement des 18 outils
├── tools/                 # Implementations MCP (un module par source)
│   ├── resolver.py        # Resolution d'indicateurs via ontologie YAML
│   ├── insee.py           # 4 outils INSEE (pynsee)
│   ├── eurostat.py        # 4 outils Eurostat
│   ├── worldbank.py       # 3 outils Banque mondiale (wbgapi)
│   ├── oecd.py            # 2 outils OCDE (sdmx1)
│   ├── factcheck.py       # Google Fact Check + ClaimBuster (httpx)
│   ├── cherry_picking.py  # Analyse de robustesse temporelle
│   └── compare.py         # Comparaison de valeurs avec qualification
├── core/                  # Infrastructure partagee
│   ├── models.py          # 12 modeles Pydantic
│   ├── cache.py           # Cache diskcache avec TTL par source
│   ├── config.py          # Configuration pydantic-settings
│   ├── errors.py          # 6 exceptions metier
│   └── retry.py           # Backoff exponentiel pour rate-limiting
└── ontology/              # Donnees statiques
    ├── indicators.yaml    # 30 indicateurs politiques -> codes sources
    └── geographies.yaml   # Noms geographiques -> codes INSEE/ISO

Principes de conception

• Serveur unique — Un seul processus MCP expose tous les outils
• Verdict LLM-assiste — Le serveur fournit donnees brutes + metriques, le LLM formule le verdict
• Fonctions synchrones — fastmcp les execute automatiquement dans un threadpool
• Degradation gracieuse — Cles API manquantes ou APIs indisponibles ne font pas planter le serveur
• Zero cout — Toutes les APIs utilisees sont gratuites

Licence

MIT