Refero MCP

Busca en styles.refero.design en lenguaje sencillo y añade un archivo DESIGN.md a cualquier proyecto.

Navegación rápida

Qué es esto

Refero Styles es un catálogo beta de unos 200 sitios seleccionados donde alguien ha hecho el arduo trabajo de extraer los colores, la tipografía, el espaciado y las guías de qué hacer y qué no hacer por estilo. Cada entrada incluye un bloque designSystem que es básicamente un DESIGN.md esperando a ser creado.

Este MCP envuelve ese catálogo para que Claude Code pueda buscar en él usando lenguaje natural y añadir un DESIGN.md generado directamente en cualquier proyecto que estés estructurando. Sin copiar y pegar JSON de pestañas del navegador, sin tablas de tokens hechas a mano.

Es para cualquiera que use Claude Code para iniciar una nueva aplicación, presentación o proyecto de cliente y quiera definir el lenguaje de diseño antes de renderizar el primer componente.

Instalación rápida

Una línea:

claude mcp add refero -- npx -y fidgetcoding-refero-mcp

Reinicia Claude Code y empieza a describir el estilo que buscas.

Si quieres una búsqueda por "vibe" (clasificación semántica basada en el resumen poético northStar de cada estilo), proporciona una clave de OpenAI:

claude mcp add refero --env OPENAI_API_KEY=sk-... -- npx -y fidgetcoding-refero-mcp

Sin ella, la búsqueda recurre a la puntuación por palabras clave. Funciona bien, solo que es menos mágico.

Para usuarios de claude_desktop_config.json:

{
  "mcpServers": {
    "refero": {
      "command": "npx",
      "args": ["-y", "fidgetcoding-refero-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "REFERO_MCP_VAULT_DIR": "/absolute/path/to/your/vault"
      }
    }
  }
}

Uso

Algunos prompts que funcionan bien:

"Find me a dark editorial style with a serif and a warm accent."

"Pull the full breakdown for Linear."

"What's similar to Vercel in the Refero catalog?"

"Render Cursor's DESIGN.md — don't save it yet, just show me."

"Save Cursor's DESIGN.md into my PARZVL project."

"Show me only dark-mode brutalist styles, top five."

"Refresh the Refero catalog before we start the design pass."

Más recetas en docs/USAGE.md.

Herramientas

Configuración

Todo es opcional. Los valores predeterminados están elegidos para que el MCP funcione directamente.

Un .env.example para copiar y pegar se incluye en la raíz del repositorio.

No hay un valor predeterminado para REFERO_MCP_VAULT_DIR. El borrador anterior tenía codificada la ruta de mi portátil, lo cual funcionaba genial para exactamente una máquina en la Tierra. El revisor lo detectó. Ahora, si no lo configuras, la herramienta simplemente se niega a escribir: es rudo, pero mejor que soltar archivos en una carpeta que no existe en tu ordenador.

Cómo funciona

No hay una API pública de Refero documentada al momento de escribir esto; la estructura se mapeó empíricamente contra el sitio en vivo. El desglose completo está en docs/api-surface.md para que mi "yo" del futuro no tenga que redescubrirlo.

• Espejo del catálogo local. Refero expone paginación ?page=N pero ignora silenciosamente ?search=, ?q= y ?colorScheme=. Por lo tanto, este MCP recorre las páginas una vez, las refleja localmente bajo REFERO_CACHE_DIR y ejecuta todo el filtrado y clasificación en el lado del cliente.

• Búsqueda por "vibe" mediante northStar. Cada estilo de Refero incluye un resumen poético de una línea llamado northStar. Con OPENAI_API_KEY configurada, el MCP incrusta esos resúmenes con text-embedding-3-small y los clasifica por similitud de coseno con tu consulta. Sin una clave, recurre a la puntuación por palabras clave en northStar + etiquetas + nombre del sitio.

• DESIGN.md generado localmente. Refero no expone un endpoint /design.md. El MCP sintetiza uno a partir de style.fullResult.designSystem (qué hacer, qué no hacer, etiquetas, tema, colores etiquetados por rol). La salida es compatible con las habilidades /stitch-design-taste y /design-taste-frontend.

Solución de problemas

"No styles found" / el catálogo parece vacío. La primera ejecución golpea una caché fría. Pídele a Claude que "refresque el catálogo de Refero" una vez; recorrerá las ~10 páginas con una pausa educada de 250ms y las escribirá en REFERO_CACHE_DIR. Después de eso, la búsqueda es instantánea.

Los resultados de búsqueda parecen basados en palabras clave en lugar de semánticos. Probablemente no tengas OPENAI_API_KEY configurada. Añádela a tu configuración de MCP y reinicia, o apóyate más en el vocabulario del catálogo (industrias más etiquetas como editorial, brutalist, glass).

refero_design_md devuelve markdown pero no escribe en disco. REFERO_MCP_VAULT_DIR no está configurado. Establécelo en la raíz de tu almacén (ruta absoluta) y la herramienta escribirá en <vault>/05-Projects/<NAME>/DESIGN.md. Sin esto, obtienes el markdown en la conversación y puedes pegarlo donde quieras.

Licencia

MIT — ver LICENSE para más detalles.

Autor

Creado por Nate Davidovich / Lorecraft LLC.

• GitHub: lorecraft-io

• npm: lorecraft

• Proyectos hermanos: morgen-mcp, motion-mcp

⤴ volver al inicio

Seguridad: escaneo con gitleaks

Este repositorio incluye una configuración .gitleaks.toml y un asistente scripts/security-scan.sh que escanea el árbol de trabajo en busca de secretos (tokens de GitHub, claves API, JWTs, claves privadas, claves de Anthropic, etc.).

bash scripts/security-scan.sh

Un hook .husky/pre-commit también ejecuta gitleaks protect --staged en cada commit y advierte si gitleaks no está instalado localmente.

Si aún no lo tienes:

• macOS: brew install gitleaks

• Linux: https://github.com/gitleaks/gitleaks/releases