Heroicons MCP

🚀 heroicons-mcp

heroicons-mcp是一個基於模型上下文協議（Model Context Protocol，MCP）構建的服務器，它將Heroicons圖標庫作為資源和工具，提供給大語言模型（LLMs）和智能代理應用程序使用。該項目使用Bun和MCP的TypeScript SDK開發。

🚀 快速開始

heroicons-mcp是一個將Heroicons圖標庫通過MCP協議暴露給AI工具的服務器。藉助它，AI編碼助手和其他智能應用可以獲取Heroicons的相關信息，實現更好的輔助和圖標搜索功能。

✨ 主要特性

• 將Heroicons（包括輪廓和實心兩種樣式）作為MCP資源進行暴露。
• 提供按名稱或關鍵詞搜索圖標的工具。
• 支持列出所有圖標或特定樣式的圖標。
• 可與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
# 或者如果已經全局安裝
heroicons-mcp --stdio

本地開發運行方式

1. HTTP模式

適用於支持通過HTTP進行通信的客戶端。 開發環境運行（使用Bun）：

bun run start
# 或者直接運行
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，可根據樣式（輪廓或實心）進行過濾。
   • 參數：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’圖標，最好是實心樣式的。”
2. AI工具調用search_icons：
   • query："user"
   • style："solid"
3. MCP服務器響應：返回匹配的實心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，並使用node ./build/entry.js命令和--stdio標誌將其連接到你的服務器：

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許可證。