# Poligraph MCP Server

[![Listed in france-mcp-servers](https://img.shields.io/badge/listed%20in-france--mcp--servers-blue)](https://github.com/bsab/france-mcp-servers)

Serveur [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) qui expose les données publiques de [Poligraph](https://poligraph.fr/) comme tools pour les clients MCP compatibles.

Permet aux journalistes, chercheurs et citoyens d'interroger des données documentées sur la vie politique française en langage naturel.

## Utilisation rapide

### Serveur distant

Le serveur HTTP Streamable est déployé à l'adresse :

```
https://mcp.poligraph.fr/mcp
```

La [page d’accueil du serveur](https://mcp.poligraph.fr/) présente les outils, les garanties de
lecture seule et les configurations rapides pour les clients MCP compatibles.

L’adresse `https://poligraph-mcp.vercel.app/mcp` reste disponible comme alias de
compatibilité.

#### Claude Desktop

Ajoutez dans votre configuration MCP :

```json
{
  "mcpServers": {
    "poligraph": {
      "type": "streamable-http",
      "url": "https://mcp.poligraph.fr/mcp"
    }
  }
}
```

#### Claude Code

```bash
claude mcp add poligraph --transport http https://mcp.poligraph.fr/mcp
```

#### ChatGPT

Le parcours principal prévu pour ChatGPT est l’OpenAI Plugins Directory, via une soumission MCP-only. Un parcours facultatif et distinct vers le GPT Store reste possible avec un GPT personnalisé et une Action OpenAPI. L’issue `poligraph#737` concerne uniquement ce second parcours et ne bloque pas la soumission MCP. PoliGraph n’est pas encore présenté comme soumis, accepté ou publié dans ces annuaires.

Le [dossier technique marketplace](docs/marketplace/README.md) rassemble les éléments préparatoires et les points restant à traiter.

Le serveur expose déjà les métadonnées MCP utiles aux clients compatibles :

- `annotations` avec `readOnlyHint: true` sur tous les tools ;
- `_meta` pour les états d'invocation ;
- `structuredContent` en complément du rendu textuel.

### Politique Origin

Les clients serveur-à-serveur n’ont pas besoin d’envoyer un en-tête HTTP `Origin`. Lorsqu’un
client en envoie un, sa valeur doit correspondre exactement à une origine autorisée. La
variable `MCP_ALLOWED_ORIGINS` permet d’ajouter des origines HTTPS exactes, séparées par des
virgules, après observation officielle. Les wildcards, chemins, paramètres et fragments sont
refusés.

Le serveur HTTP local écoute uniquement sur `127.0.0.1`. Il autorise automatiquement
`http://127.0.0.1:<port>` et `http://localhost:<port>` en complément de la politique commune.
Cette configuration ne vaut pas validation préalable d’un client Claude ou OpenAI.

## Informations publiques

L’éditeur public du serveur est l’Association Sankofa.

- Site du serveur : https://mcp.poligraph.fr/
- Politique de confidentialité : https://poligraph.fr/confidentialite
- Conditions d’utilisation : https://poligraph.fr/conditions-utilisation
- Support : https://poligraph.fr/support
- Mentions légales : https://poligraph.fr/mentions-legales
- Signalement de sécurité : [SECURITY.md](SECURITY.md)

Le support public est accessible sur https://poligraph.fr/support. Les vulnérabilités non
divulguées ne doivent pas être publiées dans une issue GitHub. Utilisez la procédure décrite
dans [SECURITY.md](SECURITY.md).

### Installation locale (stdio)

```bash
git clone https://github.com/ironlam/poligraph-mcp.git
cd poligraph-mcp
npm install
npm run build
```

Puis configurez votre client MCP pour exécuter :

```json
{
  "mcpServers": {
    "poligraph": {
      "command": "node",
      "args": ["/chemin/absolu/vers/poligraph-mcp/build/index.js"]
    }
  }
}
```

## Tools disponibles (19)

### Exemples de requêtes

Les tools peuvent être utilisés à partir de questions en langage naturel, par exemple :

- « Quels députés publiés représentent actuellement la Seine-et-Marne ? »
- « Compare les votes de deux parlementaires sur les scrutins liés aux retraites. »
- « Quelles affaires judiciaires publiées concernent cette personnalité, et quel rôle lui est attribué dans chacune ? »

Le serveur sélectionne le tool adapté et renvoie les données publiques disponibles avec leurs sources et leurs limites.

### Politiciens

| Tool | Description |
| --- | --- |
| `search_politicians` | Rechercher des personnalités publiées par nom, parti ou mandat |
| `get_politician` | Fiche publique : mandats, déclarations, fact-checks et compteurs judiciaires séparés par rôle |
| `get_politician_relations` | Relations publiques documentées par Poligraph |

### Affaires judiciaires

| Tool | Description |
| --- | --- |
| `list_affairs` | Affaires publiées avec filtres, rôle, sources et sémantique éditoriale canonique |
| `get_politician_affairs` | Affaires publiées d'une personnalité avec filtre de rôle |

### Votes parlementaires

| Tool | Description |
| --- | --- |
| `list_votes` | Scrutins parlementaires |
| `get_politician_votes` | Votes enregistrés et statistiques publiables d'un parlementaire |
| `get_vote_stats` | Cohésion, scrutins divisifs et statistiques globales |

### Mandats

| Tool | Description |
| --- | --- |
| `list_mandates` | Mandats publics ; les dates non vérifiées ne sont pas présentées comme ancienneté |

### Partis politiques

| Tool | Description |
| --- | --- |
| `list_parties` | Liste des partis avec filtres |
| `get_party` | Fiche publique : membres, filiation et classification documentée |

### Fact-checks

| Tool | Description |
| --- | --- |
| `list_factchecks` | Fact-checks publics issus des sources autorisées |
| `get_politician_factchecks` | Fact-checks publics mentionnant une personnalité |
| `get_factcheck_stats` | Statistiques agrégées du corpus public de fact-checks |

### Élections

| Tool | Description |
| --- | --- |
| `list_elections` | Élections françaises avec filtres |
| `get_election` | Candidatures, résultats et participation sans convertir les valeurs inconnues en faux |

### Géographie

| Tool | Description |
| --- | --- |
| `get_department_stats` | Statistiques sur les élus publiés par département |
| `get_deputies_by_department` | Députés publiés en exercice dans un département |

### Recherche

| Tool | Description |
| --- | --- |
| `search_advanced` | Recherche combinée sur le corpus public |

## Architecture

```text
src/
├── index.ts
├── server.ts
├── http.ts
├── api.ts                # client API borné : timeout, taille, erreurs
├── editorial.ts          # règles de rendu fail-safe du contrat public
├── tools/
│   ├── politicians.ts
│   ├── affairs.ts
│   ├── votes.ts
│   ├── legislation.ts
│   ├── factchecks.ts
│   ├── parties.ts
│   ├── elections.ts
│   ├── mandates.ts
│   └── departments.ts
└── tests/
    ├── editorial.test.ts
    └── api-contract.test.ts
api/
└── mcp.ts
```

**Transports supportés :**

- **stdio** pour un client local ;
- **HTTP Streamable** pour le serveur Express ou Vercel.

## Développement

```bash
npm run dev
npm run build
npm run start:http
npm run inspect
npm run test:unit
npm run test:contract
npm run test:build
```

`test:unit` vérifie les invariants éditoriaux déterministes. `test:contract` effectue le smoke test contre l'API publique déployée.

## Contrat éditorial public

Le MCP ne se connecte pas directement à la base de données et n'utilise ni service key ni endpoint d'administration. Il consomme exclusivement l'API publique Poligraph.

Pour les affaires judiciaires :

- seules les données publiées par le contrat public sont consommées ;
- le rôle (`DIRECT`, mention, victime, plaignant…) est distinct du statut de la procédure ;
- les libellés de statut, catégorie, prudence, certitude et maturité sont fournis par le contrat canonique Poligraph ;
- si cette sémantique canonique est absente, le MCP n'affiche pas le code interne comme signification éditoriale ;
- le total legacy tous rôles est exposé par le MCP sous `legacyPublishedAffairsCountAllRoles`, uniquement pour compatibilité structurée, et n'est pas présenté comme indicateur à charge ;
- les compteurs par rôle font foi pour la présentation.

Pour les données incomplètes :

- `null` ou champ absent ne signifie jamais `0` ou `false` ;
- un taux de participation n'est rendu que si son état de publication est explicitement `AVAILABLE` ;
- une date de prise de fonction n'est utilisée comme ancienneté que si le contrat la marque explicitement `AVAILABLE`.

Les champs textuels issus des sources publiques sont traités comme des **données**, jamais comme des instructions adressées au modèle.

## Sources

Poligraph agrège des sources publiques, institutionnelles et éditoriales documentées, notamment l'Assemblée nationale, le Sénat, la HATVP, Wikidata et des organismes de fact-checking. Voir [poligraph.fr/sources](https://poligraph.fr/sources) pour le détail.

## Licence

MIT