# watch-materials-mcp — Serveur MCP de veille scientifique en science des matériaux

Premier serveur **Model Context Protocol (MCP)** construit _from scratch_ en JavaScript, branché sur Claude Desktop. Objectif : comprendre le protocole MCP de bout en bout et fournir un outil de **veille technique souveraine** sur la science des matériaux et les alliages.

Le serveur tourne en local (process Node.js, communication via stdio) et expose 5 tools que Claude découvre et orchestre automatiquement.

---

## Pourquoi ce projet

Construire un serveur MCP minimal mais réel, qui :

- couvre **deux types de sources** et donc **deux formats de réponse** : XML (ArXiv) et JSON (OpenAlex) ;
- reste **lisible et appropriable** (code commenté, chaque tool autonome) ;
- apporte une vraie valeur métier : croiser preprints et publications validées, et identifier qui publie où (angle souverain).

---

## Les deux sources

| Source       | Format     | Nature                                   | Particularité                        |
| ------------ | ---------- | ---------------------------------------- | ------------------------------------ |
| **ArXiv**    | XML (Atom) | Preprints (non validés par les pairs)    | Parsing via `fast-xml-parser`        |
| **OpenAlex** | JSON       | Articles publiés (validés par les pairs) | Citations, institutions, accès libre |

Travailler les deux formats était un objectif assumé : ArXiv impose un parsing XML (et son piège objet/tableau), OpenAlex se consomme directement en `.json()`.

---

## Les 5 tools

| Tool                               | Source   | Rôle                                                                                                         |
| ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `search_arxiv_materiaux`           | ArXiv    | Recherche de preprints par matériau, triés par date                                                          |
| `last_articles_arxiv_materiaux`    | ArXiv    | Veille large : derniers preprints, tous matériaux confondus                                                  |
| `search_openalex_materiaux`        | OpenAlex | Recherche d'articles publiés par matériau, info accès libre                                                  |
| `last_articles_openalex_materiaux` | OpenAlex | Veille large : dernières publications parues                                                                 |
| `intel_openalex_materiaux`         | OpenAlex | Recherche avancée : **filtre par pays** d'institution + choix du tri (citations ou date) — l'angle souverain |

---

## Installation

Cloner le dépôt puis installer les dépendances (déclarées dans `package.json` : dotenv, zod, @modelcontextprotocol/sdk, fast-xml-parser, @types/node) :

\`\`\`bash
git clone <url-du-depot>
cd materials-mcp
npm install
\`\`\`

> ℹ️ Le `package.json` contient `"type": "module"` : le SDK MCP fonctionne en ESM (`import`/`export`), pas en CommonJS.

### Variable d'environnement

Créer un fichier `.env` à la racine :

```
OPENALEX_MAILTO=ton@email.fr
```

Le `mailto` n'est pas un secret : il sert à intégrer le _polite pool_ d'OpenAlex (requêtes plus stables). Optionnel mais recommandé.

---

## Branchement sur Claude Desktop

Dans `claude_desktop_config.json` (`mcpServers` à la **racine**, pas dans `preferences`) :

```json
{
  "mcpServers": {
    "materials-mcp": {
      "command": "node",
      "args": ["CHEMIN_ABSOLU/watch-materials-mcp/src/server.js"]
    }
  }
}
```

Puis **quitter Claude Desktop complétement** et le relancer. Le serveur doit apparaître dans Réglages → Développeur avec le statut `running`.

---

## Campagne de test réalisé

**Test 1 — Recherche preprints par matériau**

> Requête : `Cherche des preprints récents sur le titane`
> Tool attendu : `search_arxiv_materiaux`
> Vérifier : tri par date, XML parsé (titre/auteurs/date/lien/résumé), ~10 résultats.
> Statut : Réussi

**Test 2 — Veille large preprints**

> Requête : `Donne-moi les 20 derniers preprints en science des matériaux`
> Tool attendu : `last_articles_arxiv_materiaux`
> Vérifier : pas de filtre matériau, tri par date, 20 résultats.
> Statut : Réussi

**Test 3 — Recherche publiés par matériau**

> Requête : `Quels sont les articles publiés sur les superalliages ?`
> Tool attendu : `search_openalex_materiaux`
> Vérifier : JSON, info accès libre affichée, reste dans le domaine matériaux.
> Statut : Réussi

**Test 4 — Veille large publiés**

> Requête : `Les dernières publications parues en science des matériaux`
> Tool attendu : `last_articles_openalex_materiaux`
> Vérifier : pas de filtre matériau, info accès libre. (Voir la note OpenAlex ci-dessous.)
> Statut : Echec (Cause: API OpenAlex qui remonte des dates aberrantes)

**Test 5 — Angle souverain (le test clé)**

> Requête : `Quels articles sur le titane sont publiés par des labos français ?`
> Tool attendu : `intel_openalex_materiaux` avec `pays: "fr"`
> Vérifier : filtre pays appliqué, institutions affichées, en-tête « pays = fr ».
> Statut : Réussi

**Test 6 — Tri par citations explicite**

> Requête : `Les articles les plus cités sur les alliages d'aluminium`
> Tool attendu : `intel_openalex_materiaux` (`triParCitations: true`)
> Vérifier : tri par citations décroissant.
> Statut : Réussi

---

## Note sur l'API OpenAlex (limite connue)

Le tool `last_articles_openalex_materiaux` (veille large triée par date) remonte des **dépôts institutionnels** (thèses, datasets) dont les **métadonnées de date sont parfois erronées** (publications datées 2029–2032 lors d'une recherche effectuée en 2026). Le tri par date s'en trouve pollué et le résultat est peu exploitable en l'état.

**Ce n'est pas un bug du serveur** : le code fait ce qui est demandé, c'est la qualité de la donnée source qui est en cause. La **recherche ciblée par matériau** (`search_openalex_materiaux`) contourne le problème en remontant des articles de revues sérieuses.

Piste d'amélioration : ajouter `type:article` au filtre pour exclure thèses et datasets.

---

## Choix d'architecture

Le formatage des réponses est **volontairement dupliqué** dans chaque tool plutôt que factorisé dans un utilitaire commun. Ce choix assumé pour ce premier serveur privilégie l'apprentissage, la lisibilité et l'autonomie de chaque tool : on lit un tool de bout en bout sans naviguer entre fichiers.

La factorisation d'un `formatResponse` mutualisé est prévue pour le serveur suivant.

---

## Stack

- JavaScript (ESM) + Node.js
- `@modelcontextprotocol/sdk` — protocole MCP
- `zod` — validation des paramètres des tools
- `fast-xml-parser` — parsing du XML d'ArXiv
- `dotenv` — variable d'environnement (`mailto` OpenAlex)
- Client : Claude Desktop (transport stdio)