# Game Platforms MCP

Serveur MCP (Model Context Protocol) exposant une base de jeux vidéo enrichie par IA, pour savoir sur quelles plateformes un jeu est disponible et s'il est exclusif à un constructeur (Sony, Microsoft, Nintendo, PC, Mobile), plus deux enrichissements IA inédits : le style visuel et le pays du studio.

Projet réalisé dans le cadre du cours "Projet IA" (Nathanaël Khodl). Écrit en JavaScript pur (aucune étape de compilation nécessaire).

**Serveur déployé en ligne :** `https://game-platforms-mcp.onrender.com/mcp`
**Dépôt GitHub :** `https://github.com/Socami/first-mcp-project`

## Architecture du projet

Le projet suit les 3 parties demandées dans la consigne :

1. **Collecte de données (sans IA)** — `src/scripts/fetchData.js` interroge l'[API publique RAWG](https://rawg.io/apidocs) (base de données de jeux vidéo, gratuite) en deux temps :
   - Les jeux les plus populaires toutes plateformes confondues (tri `-added`)
   - Les 100 jeux les mieux notés (tri `-rating`) sur chaque plateforme ciblée individuellement (Nintendo Switch, PlayStation 4, PlayStation 5, Xbox One, Xbox Series S/X), pour garantir une vraie couverture de chaque écosystème plutôt que de dépendre uniquement de la popularité globale (qui sous-représente des franchises comme Zelda ou Mario)

   L'endpoint liste de RAWG ne renvoyant pas les développeurs, le script fait en plus un appel détail `/api/games/{id}` par jeu pour les récupérer. Résultat final : **~450 jeux** sauvegardés dans `data/raw-games.json`.

2. **Traitement des données avec IA** — `src/scripts/structureData.js` enrichit ces données avec 3 informations qui n'existent PAS dans RAWG, produites en **un seul élément structuré** (un schéma Zod unique, un seul appel OpenAI par lot via `responses.parse` + `zodTextFormat`) :
   - **Familles de constructeurs** : regroupe les plateformes brutes (ex: "PlayStation 5", "Xbox Series S/X") en familles standardisées (Sony, Microsoft, Nintendo, PC, Mobile, Autre). L'exclusivité est ensuite calculée en code à partir de ce résultat, pour rester fiable à 100%.
   - **Style visuel** (`artStyle`) : Réaliste, Cartoon, Pixel Art, Anime, Rétro ou Autre, déduit par **analyse d'image réelle** (vision de `gpt-4o-mini`, OpenAI) sur la capture d'écran du jeu — pas une supposition à partir du nom.
   - **Pays du studio** (`studioCountry`) : déduit de la connaissance générale du modèle OpenAI sur l'industrie du jeu vidéo. Répond "Inconnu" quand l'IA n'est pas sûre plutôt que d'inventer une réponse.

   Le résultat est sauvegardé dans `data/games.json`.

3. **Serveur MCP** — `src/mcp/server.js` expose ces données via 6 outils, utilisables par n'importe quel client compatible MCP (Claude Desktop, MCP Inspector, etc.) :
   - `search_games` — recherche par nom, genre et/ou plateforme
   - `games_by_platform` — tous les jeux disponibles sur une plateforme donnée
   - `exclusive_games` — tous les jeux exclusifs à un constructeur donné
   - `is_exclusive` — statut d'exclusivité complet d'un jeu précis
   - `games_by_art_style` — jeux par style visuel
   - `games_by_studio_country` — jeux développés par des studios d'un pays donné

## Prérequis

- Node.js 18 ou plus récent
- Une clé API RAWG (gratuite) : https://rawg.io/apidocs (bouton "Get API key")
- Une clé API OpenAI : https://platform.openai.com/api-keys

## Installation

```bash
npm install
cp .env.example .env
# Puis remplir .env avec tes deux clés API
```

## Utilisation en local

```bash
# 1. Collecter les données brutes depuis RAWG
npm run fetch-data

# 2. Structurer les données avec l'IA (familles, style visuel, pays)
npm run structure-data

# 3. Lancer le serveur MCP en local
npm run dev
```

Le serveur écoute sur `http://localhost:3000`, avec l'endpoint MCP sur `POST /mcp`.

> Le dépôt contient déjà un `data/games.json` généré (~450 jeux), pour que le serveur démarre sans erreur. Lance `npm run fetch-data` puis `npm run structure-data` pour le régénérer avec tes propres clés API.

> **À savoir sur `structure-data`** : l'analyse du style visuel envoie une vraie image à OpenAI pour chaque jeu (par lots de 5, `BATCH_SIZE` dans `structureData.js`), ce qui prend du temps et coûte un peu plus cher que du texte pur. Avec ~450 jeux, compte 15 à 25 minutes et moins d'1€ sur ta clé API OpenAI. Pour un premier test rapide, tu peux réduire `PAGES_TO_FETCH` dans `fetchData.js`.

## Déploiement en ligne (Render)

1. Pousse ce projet sur un dépôt GitHub.
2. Sur [render.com](https://render.com), crée un nouveau **Web Service** connecté à ton dépôt.
3. Configuration :
   - **Build command** : `npm install`
   - **Start command** : `npm start`
4. Aucune variable d'environnement n'est nécessaire pour le serveur en ligne : il lit uniquement `data/games.json` et ne fait aucun appel API au démarrage. (`RAWG_API_KEY` et `OPENAI_API_KEY` ne servent qu'aux scripts `fetch-data` / `structure-data`, lancés en local.)
5. Avant de déployer (ou juste après), lance `npm run fetch-data` et `npm run structure-data` **en local**, puis commit le fichier `data/games.json` généré dans ton dépôt (le serveur en ligne le lira directement).
6. Une fois déployé, ton URL publique sera de la forme `https://ton-projet.onrender.com`, et l'endpoint MCP : `https://ton-projet.onrender.com/mcp`.

> Le plan gratuit de Render met le service en veille après 15 minutes d'inactivité. Le premier appel après une pause peut prendre jusqu'à 50 secondes le temps que l'instance redémarre — c'est normal.

## Connecter le serveur à Claude Desktop

1. Ouvre **Claude Desktop** (télécharger sur [claude.com/download](https://claude.com/download)).
2. Va dans les **Paramètres** → cherche la section **Connecteurs**.
3. Clique sur **Ajouter un connecteur personnalisé**.
4. Colle l'URL du serveur : `https://game-platforms-mcp.onrender.com/mcp`
5. Pour **Authentification**, choisis **Aucun** (le serveur ne demande ni OAuth ni clé API).
6. Valide. Le connecteur doit apparaître comme actif.
7. Démarre une nouvelle conversation et pose une question en langage naturel (voir exemples ci-dessous) : Claude choisit automatiquement le bon outil.

## Tester avec MCP Inspector (outil de référence du protocole)

Alternative à Claude Desktop pour inspecter et tester chaque outil individuellement, avec une interface dédiée :

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

Ouvre l'URL affichée dans le terminal, ajoute un nouveau serveur avec le transport **Streamable HTTP** et l'URL `https://game-platforms-mcp.onrender.com/mcp`, connecte-toi, puis va dans l'onglet **Tools** → **List Tools** pour voir et appeler chaque outil directement.

## Tester en ligne de commande (curl)

```bash
curl -s -X POST https://game-platforms-mcp.onrender.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"exclusive_games","arguments":{"manufacturer":"Nintendo"}}}'
```

## Exemples de prompts par outil

**`search_games` — recherche par nom, genre et/ou plateforme**
- *« Cherche des jeux qui ont "witcher" dans le nom. »*
- *« Trouve-moi des RPG disponibles sur PC. »*
- *« Quels jeux d'action sont sortis sur PlayStation 5 ? »*

**`games_by_platform` — tous les jeux d'une plateforme**
- *« Montre-moi les jeux disponibles sur Nintendo Switch. »*
- *« Liste 30 jeux jouables sur PC. »*
- *« Qu'est-ce qui tourne sur Xbox Series S/X ? »*

**`exclusive_games` — les exclusivités d'un constructeur**
- *« Quels jeux sont exclusifs à Sony ? »*
- *« Donne-moi les exclusivités Nintendo. »*
- *« Y a-t-il des jeux exclusifs à Microsoft dans la base ? »*

**`is_exclusive` — statut d'exclusivité d'un jeu précis**
- *« Est-ce que Grand Theft Auto V est exclusif à une plateforme ? »*
- *« The Last of Us est dispo où exactement ? »*
- *« Bloodborne est-il une exclusivité ? Sur quel constructeur ? »*

**`games_by_art_style` — jeux par style visuel (déduit par analyse d'image IA)**
- *« Quels jeux ont un style cartoon ? »*
- *« Montre-moi des jeux en pixel art. »*
- *« Je cherche des jeux au style visuel réaliste. »*

**`games_by_studio_country` — jeux selon le pays du studio (estimation IA)**
- *« Quels jeux viennent de studios japonais ? »*
- *« Liste des jeux développés en Pologne. »*
- *« Montre-moi des jeux faits par des studios français. »*

**Questions combinées (le client enchaîne plusieurs outils)**
- *« Trouve un jeu exclusif à Sony, puis dis-moi de quel pays vient son studio. »*
- *« Parmi les jeux Nintendo Switch, lesquels ont un style pixel art ? »*

## Limites connues

- Les données RAWG datent du dernier `fetch-data` (import ponctuel, pas de synchronisation en temps réel).
- `studioCountry` est une estimation du modèle IA, pas une donnée vérifiée : fiable pour les gros studios connus, "Inconnu" pour les plus petits plutôt qu'une réponse inventée.
- Certains jeux triés par note (`-rating`) peuvent être des titres peu connus très bien notés par un petit nombre de joueurs.

## Structure des fichiers

```
game-mcp-project/
├── src/
│   ├── scripts/
│   │   ├── fetchData.js       # Partie 1 : collecte (sans IA)
│   │   └── structureData.js   # Partie 2 : structuration IA
│   └── mcp/
│       └── server.js          # Partie 3 : serveur MCP
├── data/
│   ├── raw-games.json         # Généré par fetch-data
│   └── games.json             # Généré par structure-data (lu par le serveur)
├── package.json
└── .env.example
```