Cómo construir un registro de shadcn/ui que Claude Code y Cursor puedan usar de verdad

1. Publica un registro que pase la validación

Empieza por lo básico. Cada item es un archivo JSON que sigue el esquema del registro, con name, type, files, dependencies y registryDependencies. Pon el índice en una URL estable y cada item en una predecible:

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

Ejecuta shadcn build para generarlos desde un registry.json de origen, y valida antes de desplegar. La CLI incorporó un paso de validación de registros en mayo de 2026. Un registro que no pasa la validación falla en silencio para los agentes, que entonces escribirán el componente a mano y lo harán mal.

Dos detalles que marcan una diferencia real:

• registryDependencies con URLs completas. Cuando tu Dialog depende de tu Button, apunta a https://your-site.com/r/button.json, no a button, o la CLI traerá el Button de shadcn/ui en su lugar.
• Un item all.json que dependa de todo. Los agentes a los que se les pide "configurar el sistema de diseño" irán directos a él.

2. Registra un namespace

Desde que llegó la función de namespaces de registro, un usuario añade esto a components.json:

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

Y después instala con un nombre corto:

npx shadcn@latest add @hextaui/dialog

Documenta este fragmento en tu página de instalación y en tu llms.txt. La forma corta es lo que busca el servidor MCP de shadcn, así que un registro sin namespace es invisible para la única herramienta que la mayoría de los agentes usa para explorar registros.

Si el registro es privado, la forma de objeto acepta cabeceras con variables de entorno que la CLI expande y nunca registra en los logs:

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

3. Dale a cada página de docs un gemelo en Markdown

Los agentes leen HTML mal. Leen Markdown bien. Haz que cada URL de docs responda en .md con el mismo contenido: descripción, comando de instalación, código fuente completo, uso, ejemplos, soporte de teclado y la tabla de la API.

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

No escribas el Markdown a mano. Genéralo desde la misma fuente que la página para que nunca se desincronicen. En HextaUI la ruta .md recorre el árbol de React de la página y lo serializa, así que añadir un ejemplo a la página lo añade al Markdown gratis.

La referencia de la API es lo que más importa aquí. Un agente que puede leer una tabla de props no se inventa un size="xl" que no existe.

4. Publica llms.txt y llms-full.txt

llms.txt es un índice en Markdown en la raíz de tu sitio: qué es el proyecto, cuándo usarlo, cuándo no, cómo instalarlo y una línea por página de docs con su enlace .md. llms-full.txt es todas las páginas de docs concatenadas, para los agentes que quieren cargarlo todo de una vez.

La sección "cuándo no usarlo" es la que la gente se salta y la que te ahorra tickets de soporte. Si tu registro es solo para React y Tailwind, dilo, o un agente intentará instalarlo en un proyecto de Vue.

Mantén el comando de instalación en las primeras diez líneas. Los agentes leen el principio.

5. Sirve un servidor MCP, de solo lectura y sin clave

La CLI de shadcn tiene su propio servidor MCP (npx shadcn@latest mcp) que busca en cualquier registro de components.json. Eso cubre las instalaciones. No cubre docs, mapas de teclado ni ejemplos.

Así que sirvo un segundo en https://hextaui.com/mcp, Streamable HTTP, de solo lectura, sin clave de API, con cinco herramientas: search_docs, get_component, get_component_api, get_examples y get_install_command. Claude Code se conecta con una línea:

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

Cursor y VS Code aceptan la misma URL en su configuración de MCP. Una vez conectados, "añade un combobox de HextaUI con resultados asíncronos" se convierte en una búsqueda en los docs, una lectura de la API y el comando de instalación correcto, sin adivinar nada por el camino.

Hazlo también descubrible. Publica una tarjeta de servidor en /.well-known/mcp/server-card.json y un server.json en el formato del registro de MCP. Los agentes y las herramientas a su alrededor están empezando a mirar ahí primero.

6. Describe la superficie HTTP con OpenAPI y errores de verdad

Todo lo anterior también es HTTP plano, y los agentes cada vez llaman más a HTTP directamente. Publica un openapi.json con ids de operación y respuestas tipadas. Devuelve los errores como application/problem+json según RFC 9457, con un campo resolution que diga qué hacer a continuación:

{
  "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 agente que recibe un 404 con una pista se recupera. Un agente que recibe una página de error en HTML escribe el componente de memoria.

7. Publica un archivo de skill

Claude Code y una lista creciente de agentes leen archivos SKILL.md que explican cómo usar una herramienta. Pon uno en /.well-known/agent-skills/<name>/SKILL.md: cómo encontrar un componente, leer sus docs e instalarlo, con los comandos exactos. Es una página de Markdown y es la página con más impacto de todo el sitio.

8. Prueba con los agentes, no contigo

Abre un proyecto de Next.js recién creado en Claude Code con tu servidor MCP conectado y sin ningún otro contexto. Pídele que "añada un date picker de <your registry> con rango y una regla que deshabilite los fines de semana". Observa qué hace. Cada suposición errónea es un hueco en tus docs .md o en tu llms.txt.

Después haz lo mismo en Cursor solo con llms.txt y sin MCP. Luego sin nada más que la URL. El registro debería degradarse con elegancia en los tres casos.

Qué consigues con esto

Un agente con el servidor MCP o los docs .md conectados lee la tabla de props en lugar de adivinarla, ejecuta el comando de instalación en lugar de reescribir el componente e instala las dependencias en el orden correcto. La parte de registro de HextaUI fue más o menos una semana de trabajo. La parte de agentes llevó más tiempo, y es la que hizo que el registro fuera usable por quienes hoy hacen la mayoría de las instalaciones.

Si quieres verlo todo en vivo: hextaui.com/llms.txt, cualquier página de docs con .md al final, los docs de MCP y los docs de la API con la especificación OpenAPI.

Preguntas frecuentes

¿Necesito mi propio servidor MCP si la CLI de shadcn ya tiene uno? El MCP de shadcn cubre la búsqueda y la instalación en los registros de components.json. Tu propio servidor cubre docs, APIs y ejemplos. La mayoría de los registros se benefician de ambos.

¿Debería el servidor MCP exigir una clave de API? Para docs públicos, no. Cada clave que exijas es un agente que se rinde. Reserva la autenticación para los items privados y usa tokens bearer mediante las cabeceras de components.json.

¿Cómo genero los docs en Markdown sin duplicar contenido? Renderiza el mismo árbol de componentes que usa la página y serialízalo a Markdown. Una fuente, dos formatos.

¿Qué va en llms.txt? Una descripción, cuándo usarlo y cuándo no, el comando de instalación, el fragmento del namespace y una línea por página de docs con el enlace a su .md.