Comment construire un registre shadcn/ui que Claude Code et Cursor peuvent vraiment utiliser

1. Publiez un registre qui passe la validation

Commencez par les bases. Chaque item est un fichier JSON qui suit le schéma de registre, avec name, type, files, dependencies et registryDependencies. Placez l’index à une URL stable et chaque item à une URL prévisible :

https://your-site.com/r/registry.json
https://your-site.com/r/button.json
https://your-site.com/r/all.json

Lancez shadcn build pour les générer à partir d’une source registry.json, et validez avant de déployer. La CLI a gagné une étape de validation de registre en mai 2026. Un registre qui échoue à la validation échoue silencieusement pour les agents, qui écriront alors le composant à la main et se tromperont.

Deux détails qui font une vraie différence :

• registryDependencies avec des URL complètes. Quand votre Dialog dépend de votre Button, pointez vers https://your-site.com/r/button.json, pas vers button, sinon la CLI récupère le Button de shadcn/ui à la place.
• Un item all.json qui dépend de tout. Les agents à qui l’on demande de « mettre en place le design system » iront le chercher.

2. Enregistrez un namespace

Depuis l’arrivée des namespaces de registre, un utilisateur ajoute ceci à components.json :

{
  "registries": {
    "@hextaui": "https://hextaui.com/r/{name}.json"
  }
}

Puis installe avec un nom court :

npx shadcn@latest add @hextaui/dialog

Documentez cet extrait sur votre page d’installation et dans votre llms.txt. La forme courte est ce dans quoi le serveur MCP de shadcn effectue ses recherches, donc un registre sans namespace est invisible pour le seul outil que la plupart des agents utilisent pour parcourir les registres.

Si le registre est privé, la forme objet accepte des en-têtes avec des variables d’environnement que la CLI développe et ne journalise jamais :

{
  "registries": {
    "@acme-pro": {
      "url": "https://acme.com/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ACME_TOKEN}"
      }
    }
  }
}

3. Donnez à chaque page de docs un jumeau Markdown

Les agents lisent mal le HTML. Ils lisent bien le Markdown. Faites répondre chaque URL de docs en .md avec le même contenu : description, commande d’installation, source complète, utilisation, exemples, prise en charge du clavier et tableau d’API.

https://hextaui.com/docs/button      -> HTML for people
https://hextaui.com/docs/button.md   -> Markdown for agents

N’écrivez pas le Markdown à la main. Générez-le à partir de la même source que la page pour que les deux ne divergent jamais. Sur HextaUI, la route .md parcourt l’arbre React de la page et le sérialise, donc ajouter un exemple à la page l’ajoute gratuitement au Markdown.

La référence d’API compte le plus ici. Un agent qui peut lire un tableau de props n’hallucine pas un size="xl" qui n’existe pas.

4. Publiez llms.txt et llms-full.txt

llms.txt est un index Markdown à la racine de votre site : ce qu’est le projet, quand l’utiliser, quand ne pas l’utiliser, comment l’installer, et une ligne par page de docs avec son lien .md. llms-full.txt est l’ensemble des pages de docs concaténées, pour les agents qui veulent tout charger d’un coup.

La section « quand ne pas l’utiliser » est celle que les gens sautent et celle qui vous épargne des tickets de support. Si votre registre est réservé à React et Tailwind, dites-le, sinon un agent essaiera de l’installer dans un projet Vue.

Gardez la commande d’installation dans les dix premières lignes. Les agents lisent le haut.

5. Faites tourner un serveur MCP, en lecture seule, sans clé

La CLI shadcn a son propre serveur MCP (npx shadcn@latest mcp) qui cherche dans n’importe quel registre de components.json. Cela couvre les installations. Cela ne couvre ni les docs, ni les raccourcis clavier, ni les exemples.

J’en fais donc tourner un second à https://hextaui.com/mcp, en Streamable HTTP, lecture seule, sans clé d’API, avec cinq outils : search_docs, get_component, get_component_api, get_examples et get_install_command. Claude Code s’y connecte en une ligne :

claude mcp add --transport http hextaui https://hextaui.com/mcp

Cursor et VS Code acceptent la même URL dans leur config MCP. Une fois connectés, « ajoute une combobox HextaUI avec des résultats asynchrones » devient une recherche dans les docs, une lecture de l’API et la bonne commande d’installation, sans devinette entre les deux.

Rendez-le aussi découvrable. Publiez une server card à /.well-known/mcp/server-card.json et un server.json au format du registre MCP. Les agents et les outils qui les entourent commencent à regarder là en premier.

6. Décrivez la surface HTTP avec OpenAPI et de vraies erreurs

Tout ce qui précède est aussi du simple HTTP, et les agents appellent de plus en plus HTTP directement. Publiez un openapi.json avec des identifiants d’opération et des réponses typées. Renvoyez les erreurs en application/problem+json (RFC 9457) avec un champ resolution qui dit quoi faire ensuite :

{
  "type": "https://hextaui.com/docs/api#not-found",
  "title": "Component not found",
  "status": 404,
  "detail": "No component named 'modal'.",
  "resolution": "Try 'dialog' or 'alert-dialog'. The catalog is at /mcp/index.json."
}

Un agent qui reçoit un 404 avec une piste s’en remet. Un agent qui reçoit une page d’erreur HTML écrit le composant de mémoire.

7. Publiez un fichier de skill

Claude Code et une liste croissante d’agents lisent des fichiers SKILL.md qui expliquent comment utiliser un outil. Mettez-en un à /.well-known/agent-skills/<name>/SKILL.md : comment trouver un composant, lire ses docs et l’installer, avec les commandes exactes. C’est une page de Markdown, et c’est la page au meilleur levier de tout le site.

8. Testez avec les agents, pas avec vous-même

Ouvrez un projet Next.js vierge dans Claude Code avec votre serveur MCP connecté et aucun autre contexte. Demandez-lui d’« ajouter un date picker depuis <your registry> avec une plage et une règle de week-ends désactivés ». Regardez ce qu’il fait. Chaque mauvaise supposition est une lacune de vos docs .md ou de votre llms.txt.

Faites ensuite la même chose dans Cursor avec seulement llms.txt et sans MCP. Puis avec rien d’autre que l’URL. Le registre doit se dégrader proprement à travers les trois.

Ce que cela vous apporte

Un agent connecté au serveur MCP ou aux docs .md lit le tableau des props au lieu de le deviner, lance la commande d’installation au lieu de réécrire le composant, et installe les dépendances dans le bon ordre. Le côté registre de HextaUI a représenté environ une semaine de travail. Le côté agents a pris plus longtemps, et c’est la partie qui a rendu le registre utilisable par ceux qui font aujourd’hui l’essentiel des installations.

Si vous voulez voir tout cela en direct : hextaui.com/llms.txt, n’importe quelle page de docs avec .md en suffixe, les docs MCP et les docs de l’API avec la spec OpenAPI.

FAQ

Ai-je besoin de mon propre serveur MCP si la CLI shadcn en a un ? Le MCP de shadcn couvre la recherche et l’installation dans tous les registres de components.json. Votre propre serveur couvre les docs, les API et les exemples. La plupart des registres gagnent à avoir les deux.

Le serveur MCP doit-il exiger une clé d’API ? Pas pour des docs publiques. Chaque clé que vous exigez est un agent qui abandonne. Réservez l’authentification aux items privés et utilisez des bearer tokens via les en-têtes de components.json.

Comment générer les docs Markdown sans dupliquer le contenu ? Rendez le même arbre de composants que la page et sérialisez-le en Markdown. Une source, deux formats.

Que met-on dans llms.txt ? Une description, quand l’utiliser et quand ne pas l’utiliser, la commande d’installation, l’extrait de namespace, et une ligne par page de docs pointant vers son .md.