Basecoat UI MCP

Servidor MCP Basecoat UI para Astro e HTML

Um servidor de Protocolo de Contexto de Modelo (MCP) offline e orientado à fonte, para compor interfaces Basecoat UI em projetos Astro, HTML estático e Tailwind CSS 4.

Ele fornece às ferramentas de codificação de IA um registro Basecoat pequeno e determinístico, em vez de fazer cada cliente consultar a documentação. A mesma configuração local de stdio pode ser usada por editores e agentes, com cada cliente iniciando seu próprio processo de servidor; o servidor não faz requisições de rede em tempo de execução. A composição segue uma ordem fixa: hierarquia de conteúdo, layout, seleção de componentes, espaçamento, tipografia e, por fim, revisão final.

Quem deve usar

• Agentes e editores que precisam de modelos Basecoat limitados e orientação de dependências.
• Projetos Astro ou HTML estático construídos com Tailwind CSS 4 e basecoat-css.
• Equipes que mantêm tokens de design e orientação de densidade específicos do projeto em DESIGN.md.

Instalação e execução

Requer Node.js 22.14.0 ou mais recente.

Via npm

npm install -g @intellmedia/basecoat-ui-mcp

Configure um cliente MCP:

{
  "mcpServers": {
    "basecoat-ui": {
      "command": "basecoat-ui-mcp",
      "args": [
        "--project-root",
        "path/to/your/application"
      ]
    }
  }
}

Ou invoque a entrada compilada diretamente:

{
  "mcpServers": {
    "basecoat-ui": {
      "command": "node",
      "args": [
        "path/to/node_modules/@intellmedia/basecoat-ui-mcp/dist/server/stdio.js",
        "--project-root",
        "path/to/your/application"
      ]
    }
  }
}

Os tarballs publicados incluem um dist/ pré-construído (prepublishOnly executa npm run build). Checkouts via Git omitem dist/; compile localmente antes de executar a partir de um clone.

A partir da fonte

git clone https://github.com/zygiu-zygis/basecoat-ui-mcp.git
cd basecoat-ui-mcp
npm ci
npm run build
npm start -- --project-root path/to/your/application

--project-root substitui BASECOAT_PROJECT_ROOT, que substitui o diretório de inicialização. Ele seleciona o DESIGN.md do aplicativo host; não é o diretório de instalação do MCP. O servidor expõe apenas stdio.

Ferramentas MCP do Basecoat

• search_components retorna até 8 resumos compactos de {id, name, intent} e nunca retorna marcação.
• get_component_details retorna um modelo Astro ou HTML com dependências e orientação de composição. A resposta JSON completa deve permanecer em ou abaixo de 1.999 bytes UTF-8; entradas superdimensionadas falham de forma segura.
• validate_composition verifica estaticamente até 65.536 bytes UTF-8 de fonte HTML ou Astro e retorna no máximo 24 problemas.

Recursos de design do Basecoat

• basecoat://design/rhythm fornece hierarquia de conteúdo, espaçamento, tipografia, família de componentes e regras de composição estrutural.
• basecoat://integration/astro fornece configuração de Astro, Vite, Tailwind CSS 4, JavaScript seletivo do Basecoat e diálogo nativo.
• basecoat://project/context lê o DESIGN.md do projeto host configurado sob demanda. A saída é limitada a 6.000 bytes UTF-8 e é truncada em uma quebra de linha ou limite de frase quando possível. Links simbólicos e arquivos não regulares são recusados.

Fluxo recomendado:

1. Leia os recursos de ritmo e contexto do projeto.
2. Decida a hierarquia de conteúdo e o layout.
3. Pesquise resumos e solicite detalhes apenas para componentes selecionados.
4. Leia o recurso de integração Astro ao conectar ativos de produção.
5. Valide a fonte final.

Exemplo mínimo de HTML

O aplicativo host fornece sua folha de estilos Tailwind e Basecoat compilada:

<link rel="stylesheet" href="/assets/basecoat.css">
<button type="button" class="btn" data-variant="default">Save changes</button>

Basecoat 1.x usa btn com data-variant e data-size. Componentes interativos listam os módulos JavaScript granulares que o host deve carregar.

Registro e exclusões

O registro Basecoat 1.0.2 verificado contém 39 modelos selecionados:

accordion, alert, alert-dialog, avatar, badge, breadcrumb, button, button-group, card, chart, checkbox, combobox, command, dialog, drawer, dropdown-menu, empty, field, input, input-group, item, kbd, label, native-select, popover, progress, radio-group, scroll-area, select, sidebar, skeleton, slider, switch, table, tabs, textarea, theme-switcher, toast, tooltip

O snapshot de manutenção registra 41 componentes upstream descobertos. pagination e spinner permanecem excluídos da pesquisa e dos detalhes até serem curados manualmente. Slider usa basecoat-css/range, não um módulo slider.

O runtime não possui cliente de rede, dependência de documentação remota, runtime de framework frontend, análise de mídia remota ou ativos de host empacotados. Modelos gerados não podem usar basecoat-css/all; cada controlador é importado explicitamente. Os resultados da pesquisa não contêm marcação, componentes recém-descobertos nunca são promovidos automaticamente e JSON ou HTML nunca é fatiado para caber em um orçamento de resposta.

Casos de uso em Astro e HTML estático

Em Astro, use o recurso de integração para Vite, Tailwind CSS 4, ordenação de CSS, importações seletivas de controladores, conexão nativa de <dialog> e hooks do ClientRouter. Em HTML estático, copie os arquivos de controlador compilados listados de basecoat-css para o diretório de ativos do aplicativo host e preserve a ordem de dependências. Modelos de gráficos exigem Chart.js fornecido pelo host.

Mantenedores podem atualizar o snapshot upstream fixado com npm run sync; este é o único comando que usa HTTPS. Ele valida esquema, exportações, avisos, orçamentos de resposta, direção de versão e substituição atômica antes de alterar o registro.

Desenvolvimento e verificação

npm run typecheck
npm run test
npm run sync -- --check

O desenvolvimento foi assistido por IA. O comportamento e a documentação são verificados contra a fonte verificada, testes de contrato e o registro fixado, em vez de alegações geradas.

Consulte ARCHITECTURE.md para limites de runtime, empacotamento, limites de bytes e política de sincronização.

Autor, licença e atribuição upstream

Criado e mantido por Žygimantas Jasiulionis / Intellmedia sob a Licença MIT.

Basecoat UI é um projeto independente licenciado sob MIT por Ronan Berder. Modelos e metadados adaptados mantêm o aviso completo do Basecoat em THIRD_PARTY_NOTICES.md. O Basecoat adapta padrões de design de shadcn/ui; o aviso preserva essa atribuição. Nenhum CSS do Basecoat ou fonte do shadcn é vendido aqui.