La plupart des documentations de SDK sont écrites pour un humain qui les lit un mardi à 14 h. De plus en plus, le premier lecteur est un assistant de code, et son problème est différent : il a besoin d’être sûr, et la prose ne lui donne pas cette certitude.
Je réglais ce problème en publiant toute la référence du SDK dans un seul fichier en texte brut, que l’assistant récupérait d’un coup. L’idée était raisonnable, mais elle a mal vieilli. Un bloc de prose reste de la prose : l’assistant la lit, la résume, et quelques centaines de lignes plus loin, il écrit un nom de méthode qui n’a jamais figuré dans le fichier. Et un document tenu à côté du code finit par s’en écarter, ce qui est justement l’erreur qu’une référence ne peut pas se permettre.
Deux choses l’ont remplacé, et toutes deux sont plus strictes.
Les types sont la référence
@kookee/sdk est livré avec ses déclarations TypeScript. Installez le paquet, et la référence est sur le disque, dans le contexte de l’assistant, sous une forme qu’il ne peut pas mal retenir :
npm install @kookee/sdkLe prompt devient court, parce que la précision se trouve dans les types et non dans le prompt :
Créez un blog avec le paquet
@kookee/sdk, déjà installé. Une page de liste (/blog) avec filtre par tags, recherche et pagination, et une page de détail (/blog/:slug) avec le contenu HTML rendu et des réactions emoji. Next.js App Router, avec le chargement des données dans les server components. Lisez la clé dansprocess.env.KOOKEE_API_KEY.
L’assistant écrit kookee.blog.list({ page, limit, tags, search, locale }) parce que c’est la signature, pas parce qu’il s’est souvenu d’un paragraphe. Et quand je modifie une méthode, les déclarations changent dans la même version : il n’y a pas de second document à oublier de mettre à jour. C’était le vrai argument contre le fichier texte : il pouvait être faux, et une référence qui peut être fausse est pire que pas de référence du tout, parce qu’on lui fait confiance.
La forme de réponse sur laquelle il s’appuie est celle que vous recevez :
const response = await kookee.blog.list({ page: 1, limit: 10, tags: ['engineering'] });
response.data; // BlogEntryListItem[]
response.total; // 25
response.totalPages; // 3Si vous préférez intégrer des pages toutes faites plutôt que de les générer, @kookee/react fournit des composants de blog rendus côté serveur : voir Créer un blog avec les composants React.
Le contenu, c’est l’autre moitié
Les types disent à l’assistant ce qu’il peut appeler. Ils ne disent rien de ce que contient votre projet, et la moitié des erreurs d’une première intégration viennent de ce manque : un slug de catégorie qui n’existe pas, un champ que le code ne lit jamais, une page vide qui s’avère être un projet vide.
Connectez donc l’assistant à vos vraies données :
claude mcp add --transport http kookee https://api.kookee.dev/api/mcp \
--header "Authorization: Bearer $KOOKEE_MCP_TOKEN"Le prompt change alors de nature. « Créez une page de journal des modifications » devient :
Lisez les entrées de mon journal des modifications, puis créez une page qui les affiche telles qu’elles sont réellement structurées.
Et il les lit vraiment. Il découvre que le type de changement se trouve dans un tableau fields et non sur l’entrée elle-même, que deux entrées n’ont pas de version, que vos catégories suivent une logique de nommage et vos tags une autre. La page qu’il écrit correspond à vos données, pas à un exemple générique. Et comme il peut aussi écrire, ce qui manque, il peut le corriger dès qu’il le remarque.
Ce qu’il vous faut encore
Un projet Kookee avec au moins un article publié. Un projet vide donne une page vide, et c’est difficile à distinguer d’un bug.
Une clé API, depuis Connexions → Clés API, pour l’application. Elle n’accède qu’au contenu publié, vous pouvez donc la mettre sans risque dans un bundle client.
Un jeton MCP personnel, depuis Connexions → Serveur MCP, si vous voulez que l’assistant lise votre vrai contenu. Lecture seule suffit pour cela. Gardez-le tout de même hors de votre code : il lit vos brouillons.
Au-delà du blog
La même formule vaut pour chaque section :
Créez un centre d’aide avec une navigation par catégories, une recherche sémantique et des pages d’articles.
Créez une page de journal des modifications groupée par type de changement, avec des réactions emoji.
Construisez-les une par une. Les trois à la fois donnent un diff que personne ne relit attentivement, et c’est ainsi qu’un bug plausible part en production.
Le fil conducteur : arrêtez de demander à un assistant de se souvenir de votre API, et donnez-lui quelque chose qu’il ne peut pas mal retenir. Les types, et les données elles-mêmes.