senscritique-bridge

License MIT

Une API HTTP et un serveur MCP pour consulter les données publiques de SensCritique.

Le projet est non officiel, open source et pour l'instant en lecture seule. Il permet de rechercher des œuvres, lire une fiche, consulter un profil public et parcourir une collection sans cookie SensCritique.

Essayer en deux minutes

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

Dans un autre terminal :

curl -s 'http://127.0.0.1:3141/v1/search?query=Dune&limit=3' \
  | jq '.items[] | {title, kind, rating, year}'

Exemple de résultat :

{
  "title": "Dune",
  "kind": "movie",
  "rating": 7.3,
  "year": 2021
}

Les notes changent avec le temps. L'exemple montre simplement la forme de la réponse.

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`
Lire un profil public	`GET /v1/users/:username`	`senscritique_get_user`
Parcourir une collection	`GET /v1/users/:username/collection`	`senscritique_get_user_collection`

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.

Brancher le serveur MCP

Après npm run build, ajoutez ce serveur à la configuration de votre client MCP :

{
  "mcpServers": {
    "senscritique": {
      "command": "node",
      "args": [
        "/chemin/absolu/senscritique-bridge/build/mcp.js"
      ]
    }
  }
}

Remplacez /chemin/absolu/ par le chemin réel du dépôt. Le serveur communique en stdio, donc votre client MCP le lance comme un processus local.

Vous pouvez ensuite demander à votre assistant :

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.

Utiliser l'API HTTP

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

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

Architecture

flowchart LR
    HTTP[Application HTTP] --> Contract[Contrat stable]
    MCP[Assistant via MCP] --> Contract
    Contract --> Cache[Cache mémoire]
    Cache --> Adapter[Adaptateur GraphQL]
    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-bridge 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. Les tests live effectuent quelques lectures publiques limitées :

npm run test:live

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
Listes et critiques publiques
Recommandations et statistiques
Authentification locale sûre
Actions de compte avec confirmation explicite
Limitation de débit pour un hébergement partagé

Les écritures, comme noter une œuvre ou modifier une liste, ne seront ajoutées qu'avec une gestion de session qui ne demande jamais de publier son cookie.

Limites et usage responsable

SensCritique ne fournit pas d'API publique documentée pour cet usage. Le bridge s'appuie sur les lectures publiques utilisées 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. Évitez les boucles agressives et respectez les règles de SensCritique.

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

senscritique-bridge