heroicons-mcp

heroicons-mcp

一个 Model Context Protocol (MCP) 服务，将 Heroicons 作为资源和工具提供给大模型及 Agent 应用。使用 Bun 和 MCP TypeScript SDK 构建。

什么是 Heroicons？

Heroicons 是一个广受欢迎的手工制作 SVG 图标库，由 Tailwind CSS 的创作者设计。图标提供多种样式（Outline、Solid），并且易于集成到 Web 项目中。

什么是 MCP？

Model Context Protocol (MCP) 是一种标准，供 AI 工具从主要训练数据之外的来源请求特定上下文。

此 MCP 服务允许 AI 编码助手和其他 Agent 应用访问 Heroicons 相关信息，从而提供更好的协助和图标搜索能力。

功能

• 将 Heroicons 作为 MCP 资源提供（Outline 和 Solid 样式）
• 提供按名称或关键词搜索图标的工具
• 支持列出所有图标或特定样式中的图标
• 可与 Claude Desktop 和其他 MCP 客户端集成
• 可作为 HTTP 服务或基于 stdio 的 MCP 服务运行

先决条件

• 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

使用方法

HTTP 模式

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

npx heroicons-mcp

这会启动 HTTP 服务（默认端口为 3000，由 src/http.ts 定义）。

也可以全局安装：

npm install -g heroicons-mcp

然后运行：

heroicons-mcp

Stdio 模式

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

本地开发

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

1. HTTP 模式

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

开发时使用 Bun：

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

这会运行 src/entry.ts 中定义的服务，该服务默认使用 HTTP 模式。

2. Stdio 模式

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

开发时使用 Bun：

bun run src/entry.ts --stdio

配置 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" 服务。

注意：npx heroicons-mcp --stdio 命令是推荐的 stdio 模式运行方式。

可用工具（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"）

使用示例

以下是 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>
  );
}

使用 Inspector 在本地测试 MCP

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

首先，确保项目已构建：

bun run build

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

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