MCP SensCritique

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

• [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, copyright 2026 kabylesystem.