# Extracteur de documents — Collecte, IA, MCP

## URL publique du serveur MCP

**https://mcp-dernier-sofiane.onrender.com/mcp**

- Endpoint SSE (clients plus anciens) : `https://mcp-dernier-sofiane.onrender.com/sse`
- Statut du service : `https://mcp-dernier-sofiane.onrender.com/health`

> Hébergé sur le plan gratuit Render : l'instance s'endort après une période
> d'inactivité. Le premier appel peut prendre 30 à 50 secondes, les suivants
> sont immédiats.

## Tester le serveur

### Option 1 — Connecter le serveur à Claude

Dans Claude : Settings → Connectors → **+** → *Add custom connector*.

| Champ | Valeur |
|---|---|
| Name | `Extracteur Documents` |
| Server URL | `https://mcp-dernier-sofiane.onrender.com/mcp` |

Laisser les *Advanced settings* vides (le serveur n'utilise pas OAuth), puis
cliquer sur **Add**. Le connecteur s'active ensuite depuis le bouton **+** de
l'interface de chat.

### Option 2 — MCP Inspector

```bash
npx @modelcontextprotocol/inspector
```

Transport `Streamable HTTP`, URL `https://mcp-dernier-sofiane.onrender.com/mcp`,
puis **Connect** → onglet **Tools** → **List Tools**.

## Questions d'exemple

Une fois le connecteur actif, ces questions déclenchent les outils du serveur.
Claude choisit lui-même l'outil approprié.

**Vérifier la connexion**

> Quels documents as-tu à disposition ?

→ appelle `lister_documents` et renvoie le contenu du corpus.

**Voir la structuration IA (partie 2)**

> Extrais les données structurées du fichier `1.txt` et présente-les sous forme de tableau.

→ appelle `extraire_donnees_fichier` : titre, résumé, personnes, lieux,
organisations, œuvres, dates, thèmes et sentiment.

**Lire une source brute**

> Montre-moi le texte brut de `1.txt` sans traitement IA.

→ appelle `lire_document`. Utile pour comparer l'entrée et la sortie.

**Rechercher dans le corpus**

> Quels documents de mon corpus parlent de musique ? Résume les points communs.

→ appelle `rechercher_documents` sur les données déjà structurées.

**Enchaîner plusieurs outils**

> Prends trois documents, extrais leurs données, puis dis-moi quelles personnes et quels lieux reviennent le plus souvent.

→ enchaîne `lister_documents`, plusieurs `extraire_donnees_fichier`, puis agrège.

**Déclencher la collecte (partie 1)**

> Collecte les données des 2 derniers jours, puis liste ce qui a été ajouté.

→ appelle `collecter_donnees` (API Wikimedia) puis `lister_documents`.
Les trois parties du projet dans une seule conversation.

> Note : le système de fichiers de Render est éphémère. Les documents collectés
> en ligne disparaissent au redéploiement suivant ; le corpus versionné dans
> `data/` est toujours restauré au démarrage.

---

Projet en trois parties, conformément à l'énoncé.

| Partie | Fichier | Rôle |
|---|---|---|
| 1. Collecte sans IA | `src/collecte.ts` | Récupère les articles mis en avant sur Wikipédia via l'API publique Wikimedia et les écrit en `.txt` dans `data/` |
| 2. Structuration IA | `src/extraction.ts` | Envoie le texte brut à OpenAI, valide la réponse avec zod, met le résultat en cache dans `data/extrait/` |
| 3. Serveur MCP | `src/index.ts` | Expose les outils MCP aux clients IA (Claude Desktop, etc.) |

Source de données : `https://api.wikimedia.org/feed/v1/wikipedia/en/featured/{AAAA}/{MM}/{JJ}` (API publique, sans clé).

## Installation

```bash
npm install
cp .env.example .env   # puis renseigner OPENAI_API_KEY
```

## Utilisation

```bash
npm run collecte -- 7        # partie 1 : importe 7 jours d'articles dans data/
npm run extraction           # partie 2 : structure tous les .txt et affiche le JSON
npm run extraction -- 1.txt  # partie 2 : un seul fichier
npm run dev                  # partie 3 : serveur MCP en local
```

Vérification rapide : `curl http://localhost:3000/health`

## Outils MCP exposés

| Outil | Description |
|---|---|
| `lister_documents` | Liste les `.txt` du corpus |
| `lire_document` | Texte brut d'un fichier |
| `extraire_donnees_fichier` | Données structurées d'un fichier (via OpenAI) |
| `extraire_tout` | Données structurées de tout le corpus |
| `rechercher_documents` | Recherche un terme dans les données structurées |
| `collecter_donnees` | Relance la collecte Wikimedia |

Schéma renvoyé par l'extraction :

```json
{
  "titre": "…",
  "resume": "…",
  "langue_source": "anglais",
  "personnes": [], "lieux": [], "organisations": [],
  "oeuvres": [], "dates": [], "themes": [],
  "sentiment": "neutre"
}
```

## Connexion d'un client IA

Endpoint principal (Streamable HTTP) : `https://mcp-dernier-sofiane.onrender.com/mcp`
Endpoint SSE (clients plus anciens) : `https://mcp-dernier-sofiane.onrender.com/sse`

Configuration type pour un client local :

```json
{
  "mcpServers": {
    "extracteur-documents": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp-dernier-sofiane.onrender.com/mcp"]
    }
  }
}
```

## Déploiement

Le serveur écoute sur `process.env.PORT`, il fonctionne tel quel sur Render, Railway ou Fly.io.

- Build : `npm run build`
- Start : `npm start`
- Variable d'environnement à définir : `OPENAI_API_KEY`

Le système de fichiers de ces plateformes est éphémère : commitez le dossier `data/`
dans le dépôt git pour que le corpus soit présent au démarrage. Les extractions
générées en ligne (`data/extrait/`) seront perdues à chaque redéploiement, mais
seront simplement recalculées à la demande.