heroicones-mcp

Un servidor de Protocolo de Contexto de Modelo (MCP) que expone Heroicons como recursos y herramientas para LLM y aplicaciones de agencia. Desarrollado con Bun y el SDK de TypeScript de MCP.

¿Qué es Heroicons?

Heroicons es una popular biblioteca de iconos SVG hechos a mano, diseñada por los creadores de Tailwind CSS. Los iconos están disponibles en varios estilos (contorno, sólido) y son fáciles de integrar en proyectos web.

¿Qué es MCP?

El Protocolo de Contexto del Modelo (MCP) es un estándar para que las herramientas de IA soliciten un contexto específico de fuentes externas a sus datos de entrenamiento principales.

Este servidor MCP permite que los asistentes de codificación de IA y otras aplicaciones de agentes accedan a información sobre Heroicons, lo que permite una mejor asistencia y capacidades de búsqueda de íconos.

Características

Expone Heroicons como recursos MCP (estilos Contorno y Sólido)
Proporciona herramientas para buscar íconos por nombre o palabras clave.
Permite enumerar todos los íconos o íconos dentro de un estilo específico
Listo para la integración con Claude Desktop y otros clientes MCP
Se puede ejecutar como un servidor HTTP o un servidor MCP basado en stdio

Prerrequisitos

Primeros pasos (desarrollo)

1. Clonar el repositorio

git clone https://github.com/SeeYangZhi/heroicons-mcp.git
cd heroicons-mcp

2. Instala Bun (si no lo tienes)

Consulte la guía de instalación oficial de Bun .
Después de la instalación, reinicie su terminal y verifique:

bun --version

3. Instalar dependencias

bun install

4. Construir el proyecto

Esto compila la fuente TypeScript a JavaScript en el directorio build .

bun run build

Uso

Modo HTTP

Puede ejecutar el servidor HTTP usando npx :

npx heroicons-mcp

Esto inicia el servidor HTTP (predeterminado en el puerto 3000, como se define en src/http.ts ).

O instalar globalmente:

npm install -g heroicons-mcp

Luego ejecuta:

heroicons-mcp

Modo estudio

npx heroicons-mcp --stdio
# or if installed globally
heroicons-mcp --stdio

Desarrollo local

Hay dos formas principales de ejecutar el servidor MCP:

1. Modo HTTP

Adecuado para clientes que admiten la comunicación a través de HTTP.

Para desarrollo (usando Bun):

bun run start
# or directly
bun run src/entry.ts

Esto ejecuta el servidor definido en src/entry.ts , que por defecto utiliza el modo HTTP.

2. Modo estudio

A menudo se utiliza para la integración directa con herramientas como Claude Desktop o MCP Inspector, comunicándose a través de entrada/salida estándar.

Para desarrollo (usando Bun):

bun run src/entry.ts --stdio

Configuración con herramientas de IA

Ejemplo: Claude Desktop

Para utilizar este servidor MCP en Claude Desktop :

Abra el archivo de configuración de Claude Desktop:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

(O utiliza tu editor preferido) 2. Agrega el servidor a la sección mcpServers .

Opción A: vía npx :

{
  "mcpServers": {
    "heroicons": {
      "command": "npx",
      "args": ["heroicons-mcp", "--stdio"]
    }
  }
}

Opción B: Apuntar directamente a la salida de la compilación (asegúrese de haber compilado el proyecto usando bun run build ):

{
  "mcpServers": {
    "heroicons": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/heroicons-mcp/build/entry.js", "--stdio"]
    }
  }
}

Reemplace /ABSOLUTE/PATH/TO/heroicons-mcp/build/entry.js con la ruta absoluta real a su archivo entry.js compilado.

Guarde el archivo y reinicie Claude Desktop.
Ahora deberías ver el servidor "heroicons" disponible en el panel de herramientas de Claude.

Nota: El comando npx heroicons-mcp --stdio es el método recomendado para el modo stdio.

Herramientas disponibles (MCP)

Este servidor MCP expone las siguientes herramientas a los asistentes de codificación de IA:

lista_todos_los_iconos

Descripción: Enumera todos los Heroicons disponibles, opcionalmente filtrados por estilo (contorno, sólido).
Parámetros: style (opcional: "contorno" | "sólido")

iconos de búsqueda

Descripción: Busca Heroicons por nombre o palabras clave en todos los estilos.
Parámetros: query (cadena), style (opcional: "contorno" | "sólido")

obtener_ejemplos_de_uso_de_iconos

Descripción: Recupera el uso de ejemplo de JSX para un ícono específico.
Parámetros: name (cadena), style (cadena: "contorno" | "sólido")

Ejemplo de uso

Así es como una herramienta de IA podría utilizar este servidor MCP:

El usuario pide a la herramienta de IA : "Encuéntrame un ícono de 'usuario' de Heroicons, preferiblemente del estilo sólido".
La herramienta de IA llama search_icons :

query : "usuario"
style : "sólido"

El servidor MCP responde con una lista de Heroicons sólidos coincidentes (por ejemplo, UserIcon , UserCircleIcon , UserPlusIcon ).
El usuario solicita a la herramienta : "Mostrar ejemplo de uso de UserIcon".
La herramienta de IA llama a get_icon_usage_examples :

name : "Icono de usuario"
style : "sólido"

El servidor MCP responde con el ejemplo de código JSX:

import { UserIcon } from "@heroicons/react/24/solid";

function Example() {
  return (
    <div>
      <UserIcon className="w-6 h-6 text-blue-500" />
    </div>
  );
}

Prueba de MCP localmente con Inspector

Puede probar el servidor MCP (modo stdio) localmente usando el Inspector MCP .

Primero, asegúrese de que el proyecto esté construido:

bun run build

Luego, inicie el Inspector y conéctelo a su servidor usando el comando node ./build/entry.js con el indicador --stdio :

npx @modelcontextprotocol/inspector node ./build/entry.js --stdio

Esto abrirá la interfaz del Inspector, lo que le permitirá probar de forma interactiva los recursos y las herramientas expuestos por su servidor MCP.

Scripts de desarrollo

bun run dev : inicia el servidor en modo HTTP para desarrollo (usa src/entry.ts ).
bun run dev:stdio : inicia el servidor MCP stdio para desarrollo (usa src/entry.ts --stdio ).
bun run build : Compila TypeScript a JavaScript (salida en build/ ).
bun run lint : limpia el código base usando ESLint.

Recursos

Licencia

Instituto Tecnológico de Massachusetts (MIT)

heroicons-mcp