# MCP SensCritique

[![CI](https://github.com/kabylesystem/senscritique-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kabylesystem/senscritique-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/senscritique-mcp?logo=npm)](https://www.npmjs.com/package/senscritique-mcp)
[![MCP 2026-07-28](https://img.shields.io/badge/MCP-2026--07--28-5b5bd6)](https://modelcontextprotocol.io/)
[![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
[![License MIT](https://img.shields.io/badge/license-MIT-3da639)](LICENSE)

Une API HTTP et un serveur MCP pour consulter SensCritique et gérer son compte avec une IA.

Le projet est non officiel et open source. Les lectures publiques fonctionnent sans compte. Après une connexion locale, il peut aussi noter une œuvre, supprimer une note, marquer un contenu comme terminé ou en cours, le recommander, l'ajouter aux envies et préparer une critique.

## Installation

Prérequis : Node.js 20 ou plus récent.

La connexion est nécessaire uniquement pour gérer votre compte :

```bash
npx -y senscritique-mcp login
```

Le mot de passe est masqué et n'est jamais enregistré. Seule la session SensCritique est conservée dans `~/.config/senscritique-mcp/session.json`, avec des permissions limitées à votre utilisateur.

### Claude Code

```bash
claude mcp add -s user senscritique -- npx -y senscritique-mcp
```

### Codex

```bash
codex mcp add senscritique -- npx -y senscritique-mcp
```

Redémarrez ensuite votre client. Il lancera automatiquement le serveur local en `stdio`. Aucun token SensCritique n'est transmis au client IA.

### Autres clients MCP

Utilisez cette commande de serveur :

```text
npx -y senscritique-mcp
```

Vous pouvez supprimer ce fichier pour déconnecter le projet. Les utilisateurs avancés peuvent fournir directement une session avec la variable `SENSCRITIQUE_TOKEN`.

## Ce qui fonctionne

| Besoin | API HTTP | Outil MCP |
| --- | --- | --- |
| Rechercher une œuvre | `GET /v1/search` | `senscritique_search_works` |
| Lire une fiche | `GET /v1/works/:id` | `senscritique_get_work` |
| Trouver saisons, épisodes ou morceaux | `GET /v1/works/:id/contents` | `senscritique_get_work_contents` |
| Lire son compte connecté | `GET /v1/me` | `senscritique_get_me` |
| Lire son état sur une œuvre | `GET /v1/me/works/:id` | `senscritique_get_my_work_state` |
| Lire un profil public | `GET /v1/users/:username` | `senscritique_get_user` |
| Parcourir une collection | `GET /v1/users/:username/collection` | `senscritique_get_user_collection` |
| Lire les critiques d'une œuvre | `GET /v1/works/:id/reviews` | `senscritique_get_work_reviews` |
| Noter ou supprimer une note | `POST /v1/works/:id/rating` | `senscritique_rate_work`, `senscritique_unrate_work` |
| Marquer comme terminé | `POST /v1/works/:id/done` | `senscritique_set_done` |
| Marquer comme en cours | `POST /v1/works/:id/current` | `senscritique_set_current` |
| Définir la date de fin | `POST /v1/works/:id/date-done` | `senscritique_set_date_done` |
| Recommander | `POST /v1/works/:id/recommended` | `senscritique_set_recommended` |
| Gérer les envies | `POST /v1/works/:id/wished` | `senscritique_set_wished` |
| Liker une critique | `POST /v1/reviews/:id/liked` | `senscritique_set_review_liked` |
| Préparer une critique | `POST /v1/works/:id/review-draft` | `senscritique_save_review_draft` |

Les réponses utilisent un format stable propre au projet. Le schéma interne de SensCritique ne fuit pas directement dans les applications qui utilisent le bridge.

## Exemples de demandes

```text
Cherche les différentes œuvres qui s'appellent Dune sur SensCritique.
Donne-moi la note et le synopsis du film Dune de 2021.
Montre les dix dernières œuvres de la collection publique de Moizi.
J'ai écouté l'album Discovery de Daft Punk. Trouve le bon album et note-le 9 sur 10.
Trouve la saison 2 de Severance, puis son épisode 10, et note-le 9 sur 10.
Lis les critiques les plus appréciées d'Oppenheimer et like celle de Sergent_Pepper.
Enregistre cette critique comme brouillon et donne-moi le lien pour la publier.
```

Les outils d'écriture demandent une confirmation explicite. L'assistant doit d'abord rechercher l'œuvre afin d'éviter de noter un homonyme.

## Utiliser l'API HTTP

L'API écoute uniquement sur `127.0.0.1:3141` par défaut.

```bash
git clone https://github.com/kabylesystem/senscritique-mcp.git
cd senscritique-mcp
npm install
npm run build
npm run start:api
```

### Rechercher

```bash
curl 'http://127.0.0.1:3141/v1/search?query=Dune&limit=5'
```

Paramètres :

- `query` est obligatoire ;
- `limit` accepte une valeur de 1 à 20.

### Lire une œuvre

```bash
curl 'http://127.0.0.1:3141/v1/works/24698928'
```

### Lire un profil

```bash
curl 'http://127.0.0.1:3141/v1/users/Moizi'
```

### Parcourir une collection

```bash
curl 'http://127.0.0.1:3141/v1/users/Moizi/collection?limit=20&offset=0'
```

`limit` accepte une valeur de 1 à 50. `offset` indique la position de départ.

### Vérifier le service

```bash
curl 'http://127.0.0.1:3141/health'
```

Vous pouvez changer le port :

```bash
PORT=8080 npm run start:api
```

### Modifier son compte

Chaque écriture exige `confirmed: true` dans un corps JSON :

```bash
curl -X POST 'http://127.0.0.1:3141/v1/works/24698928/rating' \
  -H 'content-type: application/json' \
  -d '{"rating":9,"confirmed":true}'
```

Supprimer la note :

```bash
curl -X POST 'http://127.0.0.1:3141/v1/works/24698928/rating' \
  -H 'content-type: application/json' \
  -d '{"rating":null,"confirmed":true}'
```

Les routes `done`, `current`, `recommended` et `wished` reçoivent `enabled: true` ou `enabled: false` avec la même confirmation. `date-done` reçoit une date au format `AAAA-MM-JJ`.

Le like d'une critique utilise la route `/v1/reviews/:id/liked` avec les champs `enabled` et `confirmed`. Le brouillon d'une critique utilise `review-draft` avec `title`, `markdown` et `confirmed`.

## Architecture

```mermaid
flowchart LR
    HTTP[Application HTTP] --> Contract[Contrat stable]
    MCP[Assistant via MCP] --> Contract
    Contract --> Reads[Lectures publiques]
    Reads --> Cache[Cache mémoire]
    Contract --> Writes[Actions confirmées]
    Writes --> Session[Session locale privée]
    Cache --> Adapter[Adaptateur GraphQL]
    Session --> Adapter
    Adapter --> SC[SensCritique]
```

L'API HTTP et le serveur MCP utilisent le même client. Si SensCritique modifie son GraphQL, la correction reste confinée dans `src/senscritique/`.

Le cache réduit les appels répétés :

| Donnée | Durée |
| --- | ---: |
| Recherche | 30 secondes |
| Collection | 1 minute |
| Œuvre et profil | 5 minutes |

Chaque requête vers SensCritique expire après 10 secondes. Les erreurs sont converties en codes stables comme `WORK_NOT_FOUND`, `UPSTREAM_TIMEOUT` ou `INVALID_QUERY`.

Une explication plus détaillée se trouve dans [docs/architecture.md](docs/architecture.md).

## Projets antérieurs

Plusieurs développeurs ont déjà exploré les interfaces de SensCritique :

| Projet | Approche | Dernière activité du code |
| --- | --- | --- |
| [thcolin/senscritique-api](https://github.com/thcolin/senscritique-api) | Parseur PHP des pages et anciens points d'accès JSON | 2017, dépôt archivé |
| [miramo/senscritique-api](https://github.com/miramo/senscritique-api) | Proxy Node.js pour l'ancienne API mobile | 2016, dépôt archivé |
| [NitriKx/senscritique-graphql-api](https://github.com/NitriKx/senscritique-graphql-api) | Client GraphQL TypeScript avec authentification Firebase | 2021 |

Ces dépôts sont de bonnes archives techniques. `senscritique-mcp` est une implémentation indépendante qui cible l'interface utilisée actuellement par le site et ajoute un contrat REST stable ainsi qu'un serveur MCP. Aucun code de ces projets n'a été repris.

## Développement

```bash
npm install
npm run check
npm test
```

Les tests normaux ne contactent pas SensCritique. Ils vérifient notamment que le fichier de session reste privé et que le token n'est envoyé que pour une action authentifiée. Les tests live effectuent uniquement quelques lectures publiques limitées :

```bash
npm run test:live
```

Avec une session locale, `npm run test:write` vérifie aussi une action MCP en réappliquant une note déjà existante, sans changer sa valeur.

La CI compile le projet et exécute les tests locaux sur Node.js 20, 22 et 24. Consultez [CONTRIBUTING.md](CONTRIBUTING.md) avant d'ajouter une route ou un outil.

## Feuille de route

- [x] Recherche d'œuvres
- [x] Fiches publiques
- [x] Profils et collections publiques
- [x] API HTTP locale
- [x] Serveur MCP local
- [x] Session locale privée sans stockage du mot de passe
- [x] Notes, contenus terminés, recommandations et envies
- [x] Saisons, épisodes et morceaux accessibles avant notation
- [x] États en cours et dates de visionnage, écoute ou lecture
- [x] Validation des écritures sur un compte réel
- [x] Lecture et like des critiques publiques
- [x] Brouillons de critiques avec lien direct vers l'éditeur
- [ ] Listes publiques
- [ ] Statistiques avancées
- [ ] Publication et modification de critiques avec Turnstile
- [ ] Limitation de débit pour un hébergement partagé

La notation fonctionne sur tous les types de produits SensCritique : films, séries, saisons, épisodes, albums, morceaux, livres, BD et jeux. Les mutations ont été vérifiées en réappliquant des états existants afin de ne pas modifier la collection utilisée pour le test.

## Limites et usage responsable

SensCritique ne fournit pas d'API publique documentée pour cet usage. Le bridge s'appuie sur l'interface GraphQL utilisée par leur propre frontend. Ces opérations peuvent changer ou disparaître sans préavis.

Le projet ne contourne pas la connexion, ne résout pas de captcha et n'aspire pas le catalogue complet. La publication d'une critique utilise un Turnstile sur le site actuel. Le MCP enregistre donc le brouillon et renvoie le lien de l'éditeur, mais laisse la publication finale à l'utilisateur. Évitez les boucles agressives et respectez les règles de SensCritique.

Ce dépôt n'est ni affilié à SensCritique ni approuvé par SensCritique.

## Licence

[MIT](LICENSE), copyright 2026 kabylesystem.