heroicons-mcp

一个模型上下文协议 (MCP) 服务器，将 Heroicons 作为资源和工具暴露给大型语言模型 (LLMs) 和代理应用程序。使用 Bun 和 MCP TypeScript SDK 构建。

什么是 Heroicons？

Heroicons 是由 Tailwind CSS 的创建者设计的一个流行的手工 SVG 图标库。这些图标有多种样式（轮廓、实心），并且易于集成到 Web 项目中。

什么是 MCP？

模型上下文协议 (MCP) 是一种标准，允许 AI 工具从其主要训练数据之外的来源请求特定上下文。

这个 MCP 服务器允许 AI 编码助手和其他代理应用程序访问有关 Heroicons 的信息，从而提供更好的辅助和图标搜索功能。

功能

• 将 Heroicons 作为 MCP 资源暴露（轮廓和实心样式）
• 提供按名称或关键词搜索图标的工具
• 允许列出所有图标或特定样式的图标
• 可与 Claude Desktop 和其他 MCP 客户端集成
• 可以作为 HTTP 服务器或基于 stdio 的 MCP 服务器运行

前提条件

• Git
• Bun

开始使用（开发）

1. 克隆仓库

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

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

参考官方的 Bun 安装指南。 安装完成后，重启终端并检查：

bash bun --version

3. 安装依赖

bash bun install

4. 构建项目

这会将 TypeScript 源代码编译为 JavaScript，并存放在 build 目录中。

bash bun run build

使用方法

HTTP 模式

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

bash npx heroicons-mcp

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

或者全局安装：

bash npm install -g heroicons-mcp

然后运行：

bash heroicons-mcp

Stdio 模式

bash npx heroicons-mcp --stdio

或者如果已全局安装

heroicons-mcp --stdio

本地开发

有两种主要方式来运行 MCP 服务器：

1. HTTP 模式

适用于支持通过 HTTP 通信的客户端。

开发模式（使用 Bun）：

bash bun run start

或直接

bun run src/entry.ts

这将运行 src/entry.ts 中定义的服务器，默认为 HTTP 模式。

2. Stdio 模式

通常用于与像 Claude Desktop 或 MCP Inspector 这样的工具直接集成，通过标准输入/输出进行通信。

开发模式（使用 Bun）：

bash bun run src/entry.ts --stdio

与 AI 工具配置

示例：Claude Desktop

要在 Claude Desktop 中使用此 MCP 服务器：

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

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

（或使用你喜欢的编辑器）2. 在 mcpServers 部分添加服务器。

选项 A：通过 npx：

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

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

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

将 /ABSOLUTE/PATH/TO/heroicons-mcp/build/entry.js 替换为你实际的 entry.js 文件的绝对路径。

1. 保存文件并重启 Claude Desktop。
2. 现在你应该可以在 Claude 的工具面板中看到 "heroicons" 服务器。

注意：对于 stdio 模式，推荐使用 npx heroicons-mcp --stdio 命令。

可用工具（MCP）

该 MCP 服务器向 AI 编码助手暴露以下工具：

1. list_all_icons- 描述：列出所有可用的 Heroicons，可按样式（outline 或 solid）进行筛选。

• 参数：style（可选："outline" | "solid"）

1. search_icons

• 描述：通过名称或关键词在所有样式中搜索 Heroicons。
• 参数：query（字符串），style（可选："outline" | "solid"）

1. get_icon_usage_examples

• 描述：获取特定图标的 JSX 示例用法。
• 参数：name（字符串），style（字符串："outline" | "solid"）

示例用法

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

1. 用户向 AI 工具提问：“从 Heroicons 中找一个用户图标，最好是实心风格。”
2. AI 工具调用 search_icons：

• query："user"
• style："solid"

1. MCP 服务器响应，返回匹配的实心 Heroicons 列表（例如，UserIcon、UserCircleIcon、UserPlusIcon）。
2. 用户向工具提问：“显示 UserIcon 的使用示例。”
3. AI 工具调用 get_icon_usage_examples：

• name："UserIcon"
• style："solid"

1. MCP 服务器响应，返回 JSX 代码示例：

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

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

使用 Inspector 在本地测试 MCP

您可以使用 MCP Inspector 本地测试 MCP 服务器（stdio 模式）。

首先，确保项目已构建：

bash bun run build

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

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

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

开发脚本

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

资源

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

许可证

MIT