yamanahlawat/mcp-server-untitled-ui

Servidor MCP offline para componentes Untitled UI. Sem chaves de API, sem chamadas remotas em tempo de execução, sem limites de taxa.

GitHub

Experimente este MCPPatrocinado

Documentação

mcp-server-untitled-ui

O servidor offline do Model Context Protocol (MCP) para Untitled UI. Sem chaves de API. Sem chamadas remotas em tempo de execução. Sem limites de taxa. Baixa componentes do GitHub uma vez, cria um índice local e o serve localmente para sempre.

Este servidor MCP fornece acesso ao código-fonte dos componentes Untitled UI, interfaces/props, dependências e ícones, com recursos de busca difusa, prompts de fluxo de trabalho pré-construídos e recursos navegáveis.

Principais Recursos

100% Offline em Tempo de Execução: Baixa e indexa os componentes e ícones do Untitled UI na primeira execução. As inicializações subsequentes do servidor são instantâneas e totalmente locais.
Busca Difusa em Cascata: Algoritmo de pontuação rico para componentes baseado em nome, exportações, subcategoria e caminho.
Extração de Interfaces/Props TypeScript: Analisa dinamicamente declarações de interfaces e tipos TypeScript dos componentes para que o LLM obtenha tipos exatos de props.
Análise de Dependências Internas: Revela as importações internas do Untitled UI de um componente — útil ao incorporar o código-fonte diretamente (a instalação oficial via CLI resolve as dependências por conta própria).
Exemplos de Uso e Comando Oficial de Instalação: Apresenta exemplos reais de uso do .demo.tsx e emite o comando oficial da CLI do Untitled UI (npx untitledui@latest add <name> --yes) para adicionar um componente diretamente ao seu projeto — a CLI resolve todas as dependências para você.

Configuração

Para usar este servidor com seu assistente de IA, adicione-o ao arquivo de configuração do seu cliente. O servidor baixará automaticamente os componentes e criará o índice de busca na primeira execução.

Claude Desktop / Claude Code

Adicione isto ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "untitled-ui": {
      "command": "npx",
      "args": ["-y", "mcp-server-untitled-ui"]
    }
  }
}

Cursor

Vá para Configurações > Recursos > MCP.
Clique em + Adicionar Novo Servidor MCP.
Preencha:
- Nome: untitled-ui
- Tipo: command
- Comando: npx -y mcp-server-untitled-ui

Continue / Outros clientes stdio

Configure usando o padrão de protocolo stdio padrão executando npx -y mcp-server-untitled-ui.

Opções de CLI e Configuração Manual (Opcional)

Se você quiser executar manualmente a configuração de download/índice ou reconstruir o cache local, você pode executar o servidor diretamente no seu terminal:

npx mcp-server-untitled-ui [options]

Options:
  --setup              Download/rebuild index only and exit (useful for CI/CD or pre-setup)
  --rebuild            Force re-download from GitHub and rebuild index
  --ttl <days>         Days before the index is automatically refreshed on startup (default: 7)
  --no-auto-refresh    Disable automatic index refresh on startup
  --version            Print server version
  --help               Show this help menu

Experiência da Primeira Execução

Quando o servidor inicia (manualmente ou via um cliente MCP) pela primeira vez, ele irá:

Baixar o tarball mais recente dos componentes do GitHub (untitleduico/react e untitleduico/icons).
Extraí-los para um diretório temporário.
Analisar e indexar arquivos de componentes .tsx/.ts (ignorando stories, testes e módulos utilitários puros), indexando arquivos .demo.tsx separadamente como exemplos de uso que são correspondidos de volta aos componentes que realmente renderizam.
Salvar o índice de busca gerado em ~/.mcp-server-untitled-ui/index.json.
Iniciar o servidor MCP stdio.

As inicializações subsequentes executam o servidor instantaneamente usando o índice local.

Atualização Automática

O servidor rastreia quando o índice foi construído (generatedAt). Em cada inicialização, ele compara a idade do índice com um TTL (padrão: 7 dias). Se o índice for mais antigo que o TTL, ele silenciosamente rebaixa e reconstrói o índice antes de iniciar — mantendo sua biblioteca de componentes atualizada sem nenhuma ação do usuário.

Para substituir o TTL:

# Rebuild if the index is older than 14 days
npx mcp-server-untitled-ui --ttl 14

# Never auto-refresh (serve the cached index indefinitely)
npx mcp-server-untitled-ui --no-auto-refresh

O TTL também pode ser definido persistentemente via a variável de ambiente MCP_SERVER_UNTITLED_UI_REFRESH_DAYS (veja Variáveis de Ambiente abaixo).

Variáveis de Ambiente

As seguintes variáveis de ambiente podem ser usadas para personalizar o comportamento do servidor sem passar flags de CLI:

Variável	Padrão	Descrição
`MCP_SERVER_UNTITLED_UI_DATA_DIR`	`~/.mcp-server-untitled-ui`	Substitui o diretório onde o índice e o cache são armazenados. Útil para executar múltiplas instâncias isoladas ou em ambientes de CI.
`MCP_SERVER_UNTITLED_UI_REFRESH_DAYS`	`7`	Dias antes do índice em cache ser considerado desatualizado e reconstruído automaticamente na inicialização. Defina como `0` para sempre reconstruir.
`MCP_SERVER_UNTITLED_UI_COMPONENTS_URL`	GitHub `main` tarball	Substitui a URL do tarball dos componentes. Útil para fixar uma versão específica ou apontar para um espelho privado.
`MCP_SERVER_UNTITLED_UI_ICONS_URL`	GitHub `main` tarball	Substitui a URL do tarball dos ícones.

Exemplo — armazenar o índice em um cache local do projeto:

MCP_SERVER_UNTITLED_UI_DATA_DIR=./.cache/untitled-ui npx mcp-server-untitled-ui

Como Funciona

O servidor é dividido em duas camadas, cada uma escolhida para evitar os limites de taxa remotos do Untitled UI:

Busca e referência — cache local. Código-fonte dos componentes, props, dependências, exemplos e ícones são servidos a partir de um índice local construído uma vez a partir dos repositórios públicos do GitHub. Navegar e buscar nunca tocam uma API remota, então não há chaves, limites de taxa ou latência por chamada.
Instalação — CLI oficial. Quando você realmente quer um componente em um projeto real, get_install_command entrega para a CLI oficial untitledui. Você obtém o caminho de instalação suportado e atualizado, e a resolução de dependências é trabalho da CLI — não nosso.

Duas maneiras de usar um componente

Incorporar o código-fonte — use get_component, get_component_examples e get_component_dependencies para ler o código e fazer o assistente escrevê-lo (e as importações internas que ele lista) diretamente no seu projeto.
Instalar via CLI — use get_install_command para obter npx untitledui@latest add <name> --yes. Executá-lo copia o componente para o seu projeto junto com todas as dependências que a CLI determinar que ele precisa. A flag --yes executa de forma não interativa (adequada para agentes de IA e CI).

Nota sobre nomes: os nomes dos componentes neste servidor são derivados dos caminhos dos arquivos (kebab-case, ex.: date-picker). A CLI oficial resolve nomes contra seu próprio registro curado, que é em grande parte o mesmo, mas não idêntico — alguns subcomponentes internos (ex.: avatar-label-group) não são instaláveis separadamente e vêm como parte do grupo do componente pai. Se a CLI relatar "Nenhum componente encontrado", instale o componente pai.

Capacidades MCP Expostas

1. Ferramentas

Ferramenta	Parâmetros de Entrada	Descrição
`search_components`	`query` (string), `limit` (número, padrão: 20)	Busca difusa de componentes por nome, categoria, subcategoria ou nome de exportação.
`list_components`	`category` (string), `subcategory` (string, opcional)	Lista todos os componentes em uma categoria (sem diferenciar maiúsculas de minúsculas).
`get_component`	`name` (string)	Recupera o código-fonte TypeScript completo de um componente por nome.
`get_component_file`	`path` (string)	Recupera o código-fonte do componente por caminho relativo.
`search_icons`	`query` (string), `limit` (número, padrão: 20)	Busca nomes de ícones do Untitled UI.
`get_component_props`	`name` (string)	Obtém interfaces/tipos de props TypeScript para um componente.
`get_component_dependencies`	`name` (string)	Mostra importações internas do Untitled UI utilizadas pelo componente.
`get_component_examples`	`name` (string)	Obtém exemplo(s) de uso para um componente a partir de seus arquivos `.demo.tsx` co-localizados.
`get_install_command`	`name` (string)	Obtém o comando oficial da CLI `untitledui` para instalar um componente (a CLI resolve todas as dependências automaticamente).

2. Recursos

Habilita a navegação de recursos no lado do cliente para componentes sem exigir chamadas de ferramentas:

untitled-ui://components — Array JSON de todas as categorias de componentes com contagens.
untitled-ui://components/{category} — Array JSON de componentes sob a categoria especificada.
untitled-ui://components/{category}/{name} — Código-fonte TypeScript bruto completo de um componente específico.
untitled-ui://icons — Lista JSON de todos os ícones.

3. Prompts

Fornece fluxos de trabalho modelados para auxiliar LLMs na construção de telas de UI:

build_component (description): Emite contexto do sistema e corresponde componentes existentes relevantes para a tela de UI que você deseja construir.
map_design_to_components (design_description): Guia o LLM a dividir uma descrição de design visual em seções lógicas e mapeá-las para componentes do Untitled UI.
component_usage (component_name): Gera imports, descrições de props e um exemplo de uso completo para um componente.

Desenvolvimento

Executar Testes

Este projeto usa o executor de testes nativo do Node.js. Você pode executar as suítes de testes executando:

npm test

Executar Localmente

Para executar o servidor localmente durante o desenvolvimento:

npm start

Para forçar uma reconstrução do índice localmente:

node bin/cli.mjs --rebuild

Licença

Este projeto é licenciado sob a Licença MIT.