MCP SensCritique

License MIT

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 :

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

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

Codex

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 :

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

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.

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

Rechercher

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

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

Lire un profil

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

Parcourir une collection

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

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

Vous pouvez changer le port :

PORT=8080 npm run start:api

Modifier son compte

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

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 :

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

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.

Projets antérieurs

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

Projet	Approche	Dernière activité du code
thcolin/senscritique-api	Parseur PHP des pages et anciens points d'accès JSON	2017, dépôt archivé
miramo/senscritique-api	Proxy Node.js pour l'ancienne API mobile	2016, dépôt archivé
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

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 :

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 avant d'ajouter une route ou un outil.

Feuille de route

Recherche d'œuvres
Fiches publiques
Profils et collections publiques
API HTTP locale
Serveur MCP local
Session locale privée sans stockage du mot de passe
Notes, contenus terminés, recommandations et envies
Saisons, épisodes et morceaux accessibles avant notation
États en cours et dates de visionnage, écoute ou lecture
Validation des écritures sur un compte réel
Lecture et like des critiques publiques
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.

MCP SensCritique