heroicons-mcp

heroicons-mcp

Model Context Protocol（MCP） サーバーです。Heroicons をリソースおよびツールとして公開し、LLM やエージェント型アプリケーションから利用できます。Bun と MCP TypeScript SDK を使用して構築されています。

Heroicons とは？

Heroicons は、Tailwind CSS の開発元がデザインした、手作りの SVG アイコンの人気ライブラリです。複数のスタイル（Outline、Solid）が用意されており、Web プロジェクトに簡単に組み込めます。

MCP とは？

Model Context Protocol（MCP） は、AI ツールが主要な学習データ以外の情報源から特定のコンテキストを要求するための標準規格です。

この MCP サーバーを使うと、AI コーディングアシスタントやその他のエージェント型アプリケーションから 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 のソースをコンパイルし、build ディレクトリに JavaScript を出力します。

bun run build

使い方

HTTP モード

npx を使って HTTP サーバーを実行できます。

npx heroicons-mcp

これにより HTTP サーバーが起動します（src/http.ts で定義されているとおり、デフォルトのポートは 3000 です）。

または、グローバルにインストールします。

npm install -g heroicons-mcp

次に、実行します。

heroicons-mcp

Stdio モード

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

ローカル開発

MCP サーバーを実行する方法は、主に 2 つあります。

1. HTTP モード

HTTP 通信をサポートするクライアントに適しています。

開発用（Bun を使用）：

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

これにより、デフォルトで HTTP モードとなる src/entry.ts のサーバーが実行されます。

2. Stdio モード

標準入力／出力を介して通信する、Claude Desktop や MCP Inspector などのツールとの直接連携によく使われます。

開発用（Bun を使用）：

bun run src/entry.ts --stdio

AI ツールとの設定

例：Claude Desktop

この MCP サーバーを Claude Desktop で使用するには：

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」サーバーが表示されます。

Note：stdio モードでは、npx heroicons-mcp --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

次に、--stdio フラグを指定して node ./build/entry.js コマンドを使い、Inspector を起動してサーバーに接続します。

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