heroui-v2-mcp

Servidor MCP (Model Context Protocol) para la documentación de componentes de HeroUI v2 (https://v2.heroui.com), código fuente, definiciones de estilo y tokens de tema.

A diferencia del @heroui/react-mcp oficial — que apunta a HeroUI v3 y necesita un Cloudflare Worker desplegado + un bucket R2 + un proyecto PostHog detrás — este es un servidor local independiente: obtiene todo bajo demanda directamente de heroui-inc/heroui@main (la rama que rastrea v2.x) y raw.githubusercontent.com, almacenando en caché los resultados en memoria durante la vida del proceso. No se requiere cuenta en la nube, despliegue de API ni canalización de extracción.

Por qué un proyecto separado

HeroUI v3 (rama v3, sitio heroui.com) y v2 (rama main, sitio v2.heroui.com) son modelos de componentes diferentes e incompatibles — diferente estructura de paquetes, no hay llms.txt en el sitio v2, diferente carpeta de documentación (/docs/components/* vs /docs/react/*), diferente enfoque de estilo (archivos tailwind-variants bajo packages/core/theme/src/components vs lo que sea que use v3). El MCP oficial se niega explícitamente a servir la documentación de v2, por lo que este proyecto refleja su superficie de herramientas pero apunta a las fuentes de datos de v2.

Related MCP server: UI Toolkit MCP Server

Herramientas

Instalación y ejecución

El paquete está publicado en npm como heroui-v2-mcp, por lo que no se requiere clonación ni compilación para usarlo.

Uso desde Claude Code / Claude Desktop / Cursor

Añádelo a tu configuración de MCP — npx lo descarga y ejecuta bajo demanda:

{
  "mcpServers": {
    "heroui-v2": {
      "command": "npx",
      "args": ["-y", "heroui-v2-mcp"]
    }
  }
}

O instálalo globalmente y apunta al binario directamente:

npm install -g heroui-v2-mcp

{
  "mcpServers": {
    "heroui-v2": {
      "command": "heroui-v2-mcp"
    }
  }
}

Desarrollo local (desde el código fuente)

npm install
npm run dev         # tsx --watch, runs src/server.ts directly (no build step)
npm run inspect      # launches @modelcontextprotocol/inspector against src/server.ts
npm run build        # emits dist/server.js

Límites de tasa de GitHub

Los listados de directorios pasan por la API REST de GitHub, que está limitada a 60 solicitudes/hora sin autenticación. Los contenidos de archivos (raw.githubusercontent.com) no están sujetos a ese límite. Si recibes errores 403 al navegar por muchos componentes, establece un token:

export GITHUB_TOKEN=ghp_xxx   # no scopes needed, just raises the rate limit to 5000/hr

Cómo se resuelven los datos

• Lista de componentes = archivos en apps/docs/content/docs/components/*.mdx en la rama main.

• La mayoría de los slugs de documentación se corresponden 1:1 con un paquete packages/components/<slug>. Un puñado de páginas de documentación documentan subcomponentes agrupados en otro paquete (por ejemplo, textarea está dentro de @heroui/input, checkbox-group dentro de @heroui/checkbox) — consulta COMPONENT_PACKAGE_ALIASES en src/constants.ts.

• Las tablas de props/API se extraen del literal JSX <APITable data={[...]} /> incrustado en cada página de documentación .mdx (ese array se evalúa como un literal JS — son datos estáticos del repositorio oficial, no entrada arbitraria/no confiable).

• Los tokens de tema provienen de packages/core/theme/src/colors/{semantic,common}.ts y default-layout.ts.

Almacenamiento en caché

Cada respuesta de GitHub (contenido de archivo o listado de directorio) se almacena en caché en memoria durante 30 minutos (CACHE_TTL_MS en src/constants.ts). Reinicia el proceso para forzar una actualización antes.