Starwind UI

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

Um servidor TypeScript Model Context Protocol para Starwind UI v3 e Starwind Pro. Ele fornece aos clientes de IA orientações atuais e cientes do framework para projetos Astro e React.

Início rápido

Para o guia de configuração do cliente mantido, consulte a documentação do MCP do Starwind UI.

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

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

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

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

Reinicie o cliente ou recarregue seus servidores MCP após alterar a configuração.

Modelo v3

O Starwind UI v3 tem três superfícies relacionadas. O MCP as mantém distintas:

Superfície	O que representa	Comportamento do MCP
Componentes estilizados	Componentes de UI de propriedade da cópia com implementações Astro e/ou React	Pesquisar e instalar com starwind_search e starwind_add
Primitivas	Adaptadores Astro e React de nível inferior, apoiados pelo Starwind Runtime quando aplicável	Pesquisar com surface: "primitive"; instalar com o comando v3 primitives add
Runtime	APIs de comportamento neutras em relação ao framework	Buscar com starwind_docs usando o tópico ou superfície Runtime

O servidor valida essas camadas contra o ai-manifest.json versionado, armazena em cache os dados validados e recorre a um snapshot v3 incluído se o site estiver indisponível.

Ferramentas

Ferramenta	Finalidade
starwind_init	Gerar comandos de inicialização v3 para um projeto Astro ou React existente. Pro é opcional.
starwind_add	Validar solicitações e gerar comandos de instalação ou instalação adiada para componentes estilizados, primitivas ou blocos Pro somente Astro.
starwind_search	Pesquisar componentes estilizados, primitivas e blocos Pro com metadados e filtros de framework.
starwind_docs	Resolver documentação exata de componentes, primitivas, Runtime, migração e framework.
starwind_migrate	Inspecionar um projeto e gerar orientações seguras de migração v2 para v3, priorizando a interatividade.

As chamadas de ferramenta retornam tanto texto JSON legível quanto structuredContent do MCP.

Requisitos e comportamento

• Os comandos CLI v3 gerados exigem Node.js 22.12.0 ou mais recente.
• starwind_init tem como alvo projetos existentes Astro 5+ ou React 18+ e permite que a CLI detecte automaticamente o framework, a menos que framework seja fornecido.
• Blocos gratuitos do catálogo @starwind-pro/* funcionam após a inicialização comum. Blocos pagos exigem autorização explícita; passe pro: true somente quando necessário.
• Os blocos Starwind Pro atualmente têm como alvo Astro. As pesquisas React os omitem, e as solicitações de adição React os rejeitam explicitamente.
• A migração é interativa por padrão. Defina yes: true somente quando o comportamento de backup e sobrescrita for pretendido.
• O contexto do gerenciador de pacotes e do projeto é detectado localmente quando possível, e os comandos de adição passam o gerenciador de pacotes resolvido para a CLI. Nenhuma ferramenta executa o comando gerado.

Atualização do gratuito para o Pro

O MCP mantém o Pro detectável sem forçar a configuração paga. Os resultados da pesquisa vinculam ao catálogo Pro, os blocos Pro gratuitos permanecem diretamente instaláveis, e os resultados pagos incluem um caminho estruturado proUpgrade com links de compra e instalação.

Para um projeto Astro existente, o MCP recomenda:

pnpm dlx starwind@latest setup --yes

O comando de configuração detecta automaticamente o gerenciador de pacotes do projeto, portanto não precisa de um sinalizador --package-manager. Ele prepara o registro Pro e .env.local; substitua o espaço reservado STARWIND_LICENSE_KEY pela chave comprada e, em seguida, execute o deferredCommand retornado. Trate a chave como sensível: mantenha .env.local fora do controle de versão e nunca exponha a chave em logs ou código do lado do cliente. Um projeto inicializado com pro: true recebe o comando init --pro equivalente em vez disso.

Desenvolvimento

pnpm build
pnpm lint
pnpm test:run

Execute o teste de contrato de manifesto de produção opcional com:

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

Licença

MIT. Consulte LICENSE.

Segurança