Starwind UI

Proporciona herramientas para ayudar a los desarrolladores a trabajar con componentes de Starwind UI.

Documentación

Starwind UI MCP Server

Official MCP Registry · io.github.starwind-ui/mcp

Un servidor TypeScript Model Context Protocol para Starwind UI v3 y Starwind Pro. Proporciona a los clientes de IA orientación actualizada y consciente del framework para proyectos de Astro y React.

Inicio rápido

Para la guía de configuración de clientes mantenida, consulta la documentación de MCP de Starwind UI.

Codex (~/.codex/config.toml):

[mcp_servers.starwind_ui]
command = "npx"
args = ["-y", "@starwind-ui/mcp"]
enabled = true

Claude Code (.mcp.json) o Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "starwind-ui": {
      "command": "npx",
      "args": ["-y", "@starwind-ui/mcp"]
    }
  }
}

Reinicia el cliente o recarga sus servidores MCP después de cambiar la configuración.

Modelo v3

Starwind UI v3 tiene tres superficies relacionadas. El MCP las mantiene distintas:

Superficie	Qué representa	Comportamiento del MCP
Componentes estilizados	Componentes de UI propiedad de la copia con implementaciones de Astro y/o React	Buscar e instalar con `starwind_search` y `starwind_add`
Primitivas	Adaptadores de Astro y React de nivel inferior, respaldados por Starwind Runtime cuando corresponda	Buscar con `surface: "primitive"`; instalar con el comando `primitives add` de v3
Runtime	APIs de comportamiento neutrales al framework	Obtener con `starwind_docs` usando el tema o la superficie Runtime

El servidor valida estas capas contra el ai-manifest.json versionado, almacena en caché los datos validados y recurre a una instantánea v3 incluida si el sitio no está disponible.

Herramientas

Herramienta	Propósito
`starwind_init`	Generar comandos de inicialización v3 para un proyecto Astro o React existente. Pro es opcional.
`starwind_add`	Validar solicitudes y generar comandos de instalación o instalación diferida para componentes estilizados, primitivas o bloques Pro solo de Astro.
`starwind_search`	Buscar componentes estilizados, primitivas y bloques Pro con metadatos y filtros de framework.
`starwind_docs`	Resolver documentación exacta de componentes, primitivas, Runtime, migración y framework.
`starwind_migrate`	Inspeccionar un proyecto y generar orientación de migración v2 a v3 segura y centrada en la interacción.

Las llamadas a herramientas devuelven tanto texto JSON legible como structuredContent de MCP.

Requisitos y comportamiento

Los comandos CLI v3 generados requieren Node.js 22.12.0 o más reciente.
starwind_init se dirige a proyectos existentes de Astro 5+ o React 18+ y permite que la CLI detecte automáticamente el framework a menos que se proporcione framework.
Los bloques gratuitos del catálogo @starwind-pro/* funcionan después de la inicialización ordinaria. Los bloques de pago requieren autorización explícita; pasa pro: true solo cuando sea necesario.
Los bloques de Starwind Pro actualmente se dirigen a Astro. Las búsquedas de React los omiten, y las solicitudes de adición de React los rechazan explícitamente.
La migración es interactiva por defecto. Establece yes: true solo cuando se pretenda un comportamiento de respaldo y sobrescritura.
El contexto del gestor de paquetes y del proyecto se detecta localmente cuando es posible, y los comandos de adición pasan el gestor de paquetes resuelto a la CLI. Ninguna herramienta ejecuta el comando generado.

Actualización de gratuito a Pro

El MCP mantiene Pro descubrible sin forzar la configuración de pago. Los resultados de búsqueda enlazan al catálogo Pro, los bloques Pro gratuitos siguen siendo instalables directamente, y los resultados de pago incluyen una ruta estructurada de proUpgrade con enlaces de compra e instalación.

Para un proyecto Astro existente, el MCP recomienda:

pnpm dlx starwind@latest setup --yes

El comando de configuración detecta automáticamente el gestor de paquetes del proyecto, por lo que no necesita una bandera --package-manager. Prepara el registro Pro y .env.local; reemplaza el marcador de posición STARWIND_LICENSE_KEY con la clave comprada, luego ejecuta el deferredCommand devuelto. Trata la clave como sensible: mantén .env.local fuera del control de versiones y nunca expongas la clave en registros o código del lado del cliente. Un proyecto inicializado con pro: true recibe el comando init --pro equivalente en su lugar.

Desarrollo

pnpm build
pnpm lint
pnpm test:run

Ejecuta la prueba opcional del contrato de manifiesto de producción con:

RUN_LIVE_CONTRACT_TESTS=1 pnpm test:run src/utils/starwind_live_contract.test.ts

Licencia

MIT. Ver LICENSE.