# 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](https://docs.astral.sh/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

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

## Configuration

Creer un fichier `.env` a la racine du projet :

```env
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` :

```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

```bash
# 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