Heroicons MCP

🚀 heroicons-mcp

heroicons-mcp 是一个基于 Model Context Protocol (MCP) 的服务器，它将 Heroicons 作为资源和工具，提供给大语言模型（LLMs）和智能代理应用程序使用。该项目使用 Bun 和 MCP TypeScript SDK 构建。

🚀 快速开始

开发环境准备

在开始之前，你需要安装以下工具：

• Git
• Bun

开发步骤

1. 克隆仓库

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

2. 安装 Bun（如果你还没有安装）

请参考官方 Bun 安装指南进行安装。安装完成后，重启终端并检查版本：

bun --version

3. 安装依赖

bun install

4. 构建项目

此命令会将 TypeScript 源代码编译为 JavaScript，并输出到 build 目录中。

bun run build

✨ 主要特性

• 将 Heroicons 作为 MCP 资源公开（包括 Outline 和 Solid 两种样式）。
• 提供按名称或关键字搜索图标的工具。
• 支持列出所有图标或特定样式的图标。
• 可与 Claude Desktop 和其他 MCP 客户端集成。
• 可以作为 HTTP 服务器或基于标准输入输出的 MCP 服务器运行。

📦 安装指南

HTTP 模式

你可以使用 npx 来运行 HTTP 服务器：

npx heroicons-mcp

此命令将启动 HTTP 服务器（默认端口为 3000，在 src/http.ts 中定义）。

或者，你也可以全局安装：

npm install -g heroicons-mcp

然后运行：

heroicons-mcp

标准输入输出模式

npx heroicons-mcp --stdio
# 如果你已经全局安装
heroicons-mcp --stdio

💻 使用示例

基础用法

以下是一个 AI 工具使用此 MCP 服务器的示例：

1. 用户向 AI 工具提问：“从 Heroicons 中为我找一个 'user' 图标，最好是 Solid 样式的。”
2. AI 工具调用 search_icons 方法：
   • query："user"
   • style："solid"
3. MCP 服务器响应：返回匹配的 Solid 样式的 Heroicons 列表（例如 UserIcon、UserCircleIcon、UserPlusIcon）。
4. 用户要求工具展示 UserIcon 的使用示例。
5. AI 工具调用 get_icon_usage_examples 方法：
   • name："UserIcon"
   • style："solid"
6. MCP 服务器响应：返回 JSX 代码示例：

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

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

高级用法

你可以在本地使用 MCP Inspector 来测试 MCP 服务器（标准输入输出模式）。 首先，确保项目已经构建：

bun run build

然后启动 Inspector 并使用 node ./build/entry.js 命令和 --stdio 标志将其连接到你的服务器：

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

这将打开 Inspector 界面，允许你交互式地测试 MCP 服务器公开的资源和工具。

📚 详细文档

与 AI 工具的配置

示例：Claude Desktop

要在 Claude Desktop 中使用此 MCP 服务器，请按照以下步骤操作：

1. 打开你的 Claude Desktop 配置文件：

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

（或者使用你喜欢的编辑器） 2. 将服务器添加到 mcpServers 部分。 选项 A：通过 npx：

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

选项 B：直接指向构建输出（确保你已经使用 bun run build 构建了项目）：

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

请将 /ABSOLUTE/PATH/TO/heroicons-mcp/build/entry.js 替换为你实际的 entry.js 文件的绝对路径。 3. 保存文件并重启 Claude Desktop。 4. 你现在应该可以在 Claude 的工具面板中看到 "heroicons" 服务器。

可用工具（MCP）

此 MCP 服务器向 AI 编码助手公开了以下工具：

1. list_all_icons
   • 描述：列出所有可用的 Heroicons，可根据样式（outline、solid）进行过滤。
   • 参数：style（可选："outline" | "solid"）
2. search_icons
   • 描述：在所有样式中按名称或关键字搜索 Heroicons。
   • 参数：query（字符串），style（可选："outline" | "solid"）
3. get_icon_usage_examples
   • 描述：获取特定图标的 JSX 使用示例。
   • 参数：name（字符串），style（字符串："outline" | "solid"）

🔧 技术细节

该项目使用 Bun 和 MCP TypeScript SDK 构建，支持 HTTP 服务器和标准输入输出模式的 MCP 服务器。以下是一些开发脚本：

• bun run dev：以 HTTP 模式启动服务器进行开发（使用 src/entry.ts）。
• bun run dev:stdio：以标准输入输出模式启动 MCP 服务器进行开发（使用 src/entry.ts --stdio）。
• bun run build：将 TypeScript 编译为 JavaScript（输出到 build/ 目录）。
• bun run lint：使用 ESLint 对代码进行检查。

📄 许可证

本项目采用 MIT 许可证。

🔗 相关资源

• Heroicons
• Model Context Protocol
• MCP Inspector
• MCP TypeScript SDK
• Bun