yamanahlawat/mcp-server-untitled-ui

Servidor MCP offline para componentes de Untitled UI. Sin claves API, sin llamadas remotas en tiempo de ejecución, sin límites de velocidad.

GitHub
1
Prueba este MCPPatrocinado

Documentación

mcp-server-untitled-ui

El servidor offline del Protocolo de Contexto de Modelo (MCP) para Untitled UI. Sin claves de API. Sin llamadas remotas en tiempo de ejecución. Sin límites de velocidad. Descarga componentes de GitHub una vez, construye un índice local y lo sirve localmente para siempre.

Este servidor MCP proporciona acceso al código fuente de los componentes de Untitled UI, interfaces/props, dependencias e iconos, con capacidades de búsqueda difusa, indicaciones de flujo de trabajo predefinidas y recursos navegables.

Características principales

  • 100% Offline en tiempo de ejecución: Descarga e indexa los componentes e iconos de Untitled UI en la primera ejecución. Los arranques posteriores del servidor son instantáneos y completamente locales.
  • Búsqueda difusa en cascada: Algoritmo de puntuación enriquecido para componentes basado en nombre, exportaciones, subcategoría y ruta.
  • Extracción de interfaces/props de TypeScript: Analiza dinámicamente las declaraciones de interfaces y tipos de TypeScript de los componentes para que el LLM obtenga los tipos de props exactos.
  • Análisis de dependencias internas: Revela las importaciones internas de Untitled UI de un componente — útil al incrustar el código fuente directamente (la instalación oficial por CLI resuelve las dependencias por sí sola).
  • Ejemplos de uso y comando de instalación oficial: Muestra ejemplos de uso reales de .demo.tsx y emite el comando oficial de la CLI de Untitled UI (npx untitledui@latest add <name> --yes) para insertar un componente directamente en tu proyecto — la CLI resuelve todas las dependencias por ti.

Configuración

Para usar este servidor con tu asistente de IA, agrégalo al archivo de configuración de tu cliente. El servidor descargará automáticamente los componentes y construirá el índice de búsqueda en su primera ejecución.

Claude Desktop / Claude Code

Añade esto a tu claude_desktop_config.json:

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

Cursor

  1. Ve a Configuración > Funciones > MCP.
  2. Haz clic en + Añadir nuevo servidor MCP.
  3. Completa:
    • Nombre: untitled-ui
    • Tipo: command
    • Comando: npx -y mcp-server-untitled-ui

Continue / Otros clientes stdio

Configura usando el patrón estándar del protocolo stdio ejecutando npx -y mcp-server-untitled-ui.

Opciones de CLI y configuración manual (opcional)

Si deseas ejecutar manualmente la configuración de descarga/índice o reconstruir la caché local, puedes ejecutar el servidor directamente en tu 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

Experiencia de la primera ejecución

Cuando el servidor se inicia (ya sea manualmente o mediante un cliente MCP) por primera vez, hará lo siguiente:

  1. Descargará el tarball más reciente de componentes desde GitHub (untitleduico/react y untitleduico/icons).
  2. Los extraerá a un directorio temporal.
  3. Analizará e indexará los archivos de componentes .tsx/.ts (ignorando historias, pruebas y módulos de utilidad pura), indexando los archivos .demo.tsx por separado como ejemplos de uso que se vinculan a los componentes que realmente renderizan.
  4. Guardará el índice de búsqueda generado en ~/.mcp-server-untitled-ui/index.json.
  5. Iniciará el servidor MCP stdio.

Los arranques posteriores ejecutan el servidor instantáneamente usando el índice local.

Actualización automática

El servidor registra cuándo se construyó el índice (generatedAt). En cada inicio compara la antigüedad del índice con un TTL (por defecto: 7 días). Si el índice es más antiguo que el TTL, vuelve a descargar y reconstruye el índice silenciosamente antes de iniciar — manteniendo tu biblioteca de componentes actualizada sin ninguna acción del usuario.

Para anular el 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

El TTL también se puede configurar de forma persistente mediante la variable de entorno MCP_SERVER_UNTITLED_UI_REFRESH_DAYS (consulta Variables de entorno a continuación).

Variables de entorno

Las siguientes variables de entorno se pueden usar para personalizar el comportamiento del servidor sin pasar banderas de CLI:

VariableDefaultDescripción
MCP_SERVER_UNTITLED_UI_DATA_DIR~/.mcp-server-untitled-uiAnula el directorio donde se almacenan el índice y la caché. Útil para ejecutar múltiples instancias aisladas o en entornos de CI.
MCP_SERVER_UNTITLED_UI_REFRESH_DAYS7Días antes de que el índice en caché se considere obsoleto y se reconstruya automáticamente al inicio. Establece 0 para reconstruir siempre.
MCP_SERVER_UNTITLED_UI_COMPONENTS_URLGitHub main tarballAnula la URL del tarball de componentes. Útil para fijar una versión específica o apuntar a un espejo privado.
MCP_SERVER_UNTITLED_UI_ICONS_URLGitHub main tarballAnula la URL del tarball de iconos.

Ejemplo — almacena el índice en una caché local del proyecto:

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

Cómo funciona

El servidor se divide en dos capas, cada una elegida para evitar los límites de velocidad remotos de Untitled UI:

  • Búsqueda y referencia — caché local. El código fuente de los componentes, props, dependencias, ejemplos e iconos se sirven desde un índice local construido una vez a partir de los repositorios públicos de GitHub. Navegar y buscar nunca tocan una API remota, por lo que no hay claves, ni límites de velocidad, ni latencia por llamada.
  • Instalación — CLI oficial. Cuando realmente quieres un componente en un proyecto real, get_install_command entrega el control a la CLI oficial untitledui. Obtienes la ruta de instalación compatible y actualizada, y la resolución de dependencias es trabajo de la CLI, no nuestro.

Dos formas de usar un componente

  1. Incrustar el código fuente — usa get_component, get_component_examples y get_component_dependencies para leer el código y hacer que el asistente lo escriba (junto con las importaciones internas que lista) directamente en tu proyecto.
  2. Instalar mediante la CLI — usa get_install_command para obtener npx untitledui@latest add <name> --yes. Al ejecutarlo, copia el componente en tu proyecto junto con todas las dependencias que la CLI determine que necesita. La bandera --yes se ejecuta de forma no interactiva (adecuada para agentes de IA y CI).

Nota sobre los nombres: los nombres de los componentes en este servidor se derivan de las rutas de archivo (kebab-case, p. ej. date-picker). La CLI oficial resuelve los nombres contra su propio registro curado, que es en gran medida el mismo pero no idéntico — algunos subcomponentes internos (p. ej. avatar-label-group) no se pueden instalar por separado y vienen como parte de su grupo de componente principal. Si la CLI informa "No se encontraron componentes", instala el componente principal en su lugar.

Capacidades MCP expuestas

1. Herramientas

HerramientaParámetros de entradaDescripción
search_componentsquery (string), limit (number, default: 20)Búsqueda difusa de componentes por nombre, categoría, subcategoría o nombre de exportación.
list_componentscategory (string), subcategory (string, optional)Lista todos los componentes de una categoría (sin distinción de mayúsculas/minúsculas).
get_componentname (string)Recupera el código fuente completo de TypeScript de un componente por nombre.
get_component_filepath (string)Recupera el código fuente del componente por ruta relativa.
search_iconsquery (string), limit (number, default: 20)Busca nombres de iconos de Untitled UI.
get_component_propsname (string)Obtén las interfaces/tipos de props de TypeScript para un componente.
get_component_dependenciesname (string)Muestra las importaciones internas de Untitled UI utilizadas por el componente.
get_component_examplesname (string)Obtén ejemplos de uso de un componente desde sus archivos .demo.tsx ubicados en el mismo directorio.
get_install_commandname (string)Obtén el comando oficial de la CLI untitledui para instalar un componente (la CLI resuelve todas las dependencias automáticamente).

2. Recursos

Habilita la navegación de recursos del lado del cliente para componentes sin requerir llamadas a herramientas:

  • untitled-ui://components — Matriz JSON de todas las categorías de componentes con recuentos.
  • untitled-ui://components/{category} — Matriz JSON de componentes bajo la categoría especificada.
  • untitled-ui://components/{category}/{name} — Código fuente TypeScript sin procesar completo de un componente específico.
  • untitled-ui://icons — Lista JSON de todos los iconos.

3. Indicaciones

Proporciona flujos de trabajo con plantillas para ayudar a los LLM a construir pantallas de interfaz de usuario:

  • build_component (description): Emite contexto del sistema y empareja componentes existentes relevantes para la pantalla de interfaz que deseas construir.
  • map_design_to_components (design_description): Guía al LLM para dividir una descripción de diseño visual en secciones lógicas y mapearlas a componentes de Untitled UI.
  • component_usage (component_name): Genera importaciones, descripciones de props y un ejemplo de uso completo para un componente.

Desarrollo

Ejecutar pruebas

Este proyecto utiliza el ejecutor de pruebas nativo de Node.js. Puedes ejecutar las suites de pruebas ejecutando:

npm test

Ejecutar localmente

Para ejecutar el servidor localmente durante el desarrollo:

npm start

Para forzar una reconstrucción del índice localmente:

node bin/cli.mjs --rebuild

Licencia

Este proyecto está licenciado bajo la Licencia MIT.