Icon Mcp

アイコン MCP サーバー

複数のアイコンライブラリを横断する統合検索機能を提供する、強力な Model Context Protocol（MCP）サーバーです。あいまい検索、インテリジェントなキャッシュ、包括的なフィルタリングオプションを備えています。

🚀 機能

• 複数ライブラリのサポート：複数のアイコンライブラリを同時に検索できます
• あいまい検索：Fuse.js を使用した、タイプミスに対応する高度な検索機能
• インテリジェントなキャッシュ：スマートなキャッシュ戦略による高速な応答時間
• 包括的なフィルタリング：ライブラリ、スタイル、カテゴリ、タグなどでフィルタリングできます
• NPM パッケージとの統合：NPM パッケージを通じてアイコンライブラリを自動管理します
• TypeScript：完全な型安全性と優れた開発者エクスペリエンス
• MCP プロトコル：シームレスな統合を実現する標準の Model Context Protocol

📦 対応アイコンライブラリ

• Bootstrap Icons - Bootstrap 向けの公式オープンソース SVG アイコンライブラリ
• Feather - 美しいオープンソースアイコン
• Octicons - GitHub のアイコンライブラリ
• Tabler Icons - 無料のオープンソースアイコン

🛠️ インストール

NPM パッケージ

npm install -g icon-mcp

ソースからインストール

git clone https://github.com/your-org/icon-mcp.git
cd icon-mcp
npm install
npm run build

アイコンインデックスの構築

# Build icon indices from NPM packages
npm run build-icons

🚀 クイックスタート

MCP サーバーとして

# Start the MCP server
npm start

設定

サーバーは環境変数で設定できます。

# Cache configuration
CACHE_TTL=300000          # Cache TTL in milliseconds (default: 5 minutes)
CACHE_MAX_SIZE=1000       # Maximum cache entries (default: 1000)

# Search configuration
DEFAULT_SEARCH_LIMIT=50   # Default search result limit
FUZZY_THRESHOLD=0.3       # Default fuzzy search threshold

# Logging
LOG_LEVEL=info           # Logging level (error, warn, info, debug)

🔌 MCP クライアントの設定

Claude Desktop

Claude Desktop の設定にアイコン MCP サーバーを追加します。

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "icon-search": {
      "command": "npx",
      "args": ["icon-mcp"],
      "env": {
        "CACHE_TTL": "300000",
        "DEFAULT_SEARCH_LIMIT": "50",
        "LOG_LEVEL": "info"
      }
    }
  }
}

VS Code MCP 拡張機能

VS Code の設定で MCP 拡張機能を設定します。

{
  "mcp.servers": [
    {
      "name": "icon-search",
      "command": "npx",
      "args": ["icon-mcp"],
      "cwd": "${workspaceFolder}",
      "env": {
        "CACHE_TTL": "300000",
        "DEFAULT_SEARCH_LIMIT": "50"
      }
    }
  ]
}

ローカル開発環境のセットアップ

ローカルビルドを使用した開発の場合：

{
  "mcpServers": {
    "icon-search-dev": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/icon-mcp",
      "env": {
        "NODE_ENV": "development",
        "LOG_LEVEL": "debug",
        "CACHE_TTL": "60000"
      }
    }
  }
}

Docker の設定

Docker イメージを使用する場合：

{
  "mcpServers": {
    "icon-search-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env",
        "CACHE_TTL=300000",
        "--env",
        "LOG_LEVEL=info",
        "icon-mcp:latest"
      ]
    }
  }
}

クライアント設定用の環境変数

環境変数を使用してサーバーの動作を設定します。

変数	説明	デフォルト	例
CACHE_TTL	キャッシュの有効期間（ミリ秒）	300000	600000
CACHE_MAX_SIZE	キャッシュするエントリの最大数	1000	2000
DEFAULT_SEARCH_LIMIT	検索結果のデフォルト件数	50	100
FUZZY_THRESHOLD	あいまい検索のデフォルトのしきい値（0.0-1.0）	0.3	0.5
LOG_LEVEL	ログの詳細度	info	debug
NODE_ENV	環境モード	production	development

接続の確認

MCP クライアントを設定したら、接続を確認します。

1. サーバーのステータスを確認：MCP クライアントのサーバー一覧にサーバーが表示されていることを確認します
2. 基本ツールをテスト：list_libraries ツールを試して、接続を確認します
3. ログを確認：クライアントのログで接続メッセージを確認します

トラブルシューティング

よくある問題

サーバーが起動しない

# Check if the package is installed
npm list -g icon-mcp

# Reinstall if needed
npm install -g icon-mcp

権限エラー

# On Unix systems, ensure proper permissions
chmod +x $(which icon-mcp)

アイコンインデックスが見つからない

# Build the icon index
cd /path/to/icon-mcp
npm run build-icons

デバッグモード

トラブルシューティングのためにデバッグログを有効にします。

{
  "mcpServers": {
    "icon-search": {
      "command": "npx",
      "args": ["icon-mcp"],
      "env": {
        "LOG_LEVEL": "debug",
        "NODE_ENV": "development"
      }
    }
  }
}

接続テスト

サーバーを手動でテストします。

# Start the server directly
npx icon-mcp

# Or with debug output
LOG_LEVEL=debug npx icon-mcp

詳細設定

カスタムアイコンライブラリ

アイコンインデックスを設定して、追加のアイコンライブラリを設定します。

# Add custom libraries to package.json dependencies
npm install custom-icon-library

# Rebuild the icon index
npm run build-icons

パフォーマンスの調整

高いパフォーマンスが求められる状況では：

{
  "env": {
    "CACHE_TTL": "1800000",
    "CACHE_MAX_SIZE": "5000",
    "DEFAULT_SEARCH_LIMIT": "100",
    "FUZZY_THRESHOLD": "0.2"
  }
}

メモリの最適化

メモリが制限された環境では：

{
  "env": {
    "CACHE_MAX_SIZE": "500",
    "DEFAULT_SEARCH_LIMIT": "25",
    "NODE_OPTIONS": "--max-old-space-size=512"
  }
}

📖 API リファレンス

利用可能なツール

search_icons

あいまい検索を使用して、すべてのライブラリまたは指定したライブラリからアイコンを名前で検索します。

パラメーター：

• query (string, required)：アイコン名の検索語
• libraries (string[], optional)：検索する特定のライブラリ
• fuzzy (boolean, optional)：あいまい検索を有効にします（デフォルト：true）
• limit (number, optional)：返す結果の最大数（デフォルト：10）
• threshold (number, optional)：あいまい検索のしきい値 0.0-1.0（デフォルト：0.3）
• includeScore (boolean, optional)：一致スコアを含めます（デフォルト：true）

例：

{
  "query": "home",
  "libraries": ["bootstrap-icons", "feather"],
  "fuzzy": true,
  "limit": 20,
  "threshold": 0.3
}

レスポンス：

{
  "query": "home",
  "results": [
    {
      "item": {
        "name": "house",
        "library": "bootstrap-icons",
        "tags": ["house", "home", "building"],
        "style": "regular",
        "path": "node_modules/bootstrap-icons/icons/house.svg",
        "categories": ["navigation"],
        "size": "16x16"
      },
      "score": 0.0
    }
  ],
  "totalResults": 15,
  "searchType": "fuzzy",
  "executionTime": 45,
  "libraries": ["bootstrap-icons", "feather"]
}

get_icon

特定のアイコンに関する詳細情報を取得します。

パラメーター：

• id (string, required)：アイコンの一意な識別子
• library (string, required)：アイコンが含まれるライブラリの名前

例：

{
  "id": "house",
  "library": "bootstrap-icons"
}

list_libraries

利用可能なすべてのアイコンライブラリの一覧を取得します。

パラメーター： なし

レスポンス：

{
  "libraries": ["bootstrap-icons", "feather", "octicons", "lucide", "tabler-icons"],
  "count": 5
}

get_library_info

特定のライブラリに関する詳細情報を取得します。

パラメーター：

• library (string, required)：ライブラリ名

レスポンス：

{
  "name": "bootstrap-icons",
  "displayName": "Bootstrap Icons",
  "description": "Official open source SVG icon library for Bootstrap",
  "version": "1.11.3",
  "iconCount": 1800,
  "categories": ["navigation", "communication", "media", "ui"],
  "styles": ["regular"],
  "isAvailable": true
}

search_by_category

あいまい検索を使用して、カテゴリまたはタグからアイコンを検索します。

パラメーター：

• category (string, required)：検索するカテゴリ名
• libraries (string[], optional)：検索する特定のライブラリ
• fuzzy (boolean, optional)：あいまい検索を有効にします（デフォルト：true）
• limit (number, optional)：返す結果の最大数（デフォルト：10）

🏗️ アーキテクチャ

コアコンポーネント

src/
├── index.ts                 # Main MCP server entry point
├── providers/               # Icon provider implementations
│   ├── icon-provider.interface.ts
│   ├── base-npm-provider.ts
│   ├── heroicons.provider.ts
│   ├── bootstrap-icons.provider.ts
│   ├── feather.provider.ts
│   ├── octicons.provider.ts
│   ├── lucide.provider.ts
│   ├── simple-icons.provider.ts
│   └── tabler-icons.provider.ts
├── services/               # Core services
│   ├── search.service.ts   # Unified search service
│   └── cache.service.ts    # Caching service
├── tools/                  # MCP tools
│   └── index.ts           # Icon search tools
├── types/                  # TypeScript type definitions
│   └── index.ts
└── utils/                  # Utility functions
    └── errors.ts

プロバイダーシステム

プロバイダーシステムを使用すると、新しいアイコンライブラリを簡単に追加できます。

export abstract class IconProvider {
  abstract initialize(): Promise<void>;
  abstract searchIcons(query: string, options?: FuseSearchOptions): Promise<FuseResult<Icon>[]>;
  abstract getIcon(id: string): Promise<Icon | null>;
  abstract getAllIcons(): Promise<Icon[]>;
  abstract getInfo(): Promise<IconLibrary>;
}

検索サービス

検索サービスは、すべてのプロバイダーを対象とした統合検索を提供します。

• あいまい検索：設定可能なしきい値を使用し、Fuse.js によって実現
• キャッシュ：TTL と LRU 方式の削除機能を備えたインテリジェントなキャッシュ
• フィルタリング：ライブラリ、スタイル、カテゴリ、タグによる高度なフィルタリング
• パフォーマンス：高速な応答時間を実現するよう最適化

🧪 テスト

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run integration tests
npm run test:integration

# Run performance tests
npm run test:performance

🔧 開発

開発環境のセットアップ

git clone https://github.com/your-org/icon-mcp.git
cd icon-mcp
npm install

# Install icon library dependencies
npm install

# Build the project
npm run build

# Start in development mode
npm run dev

新しいアイコンライブラリの追加

1. NPM の依存関係としてライブラリを追加します。

npm install new-icon-library

2. BaseNpmProvider を継承するプロバイダークラスを作成します。

export class NewLibraryProvider extends BaseNpmProvider {
  constructor() {
    super('new-library', 'New Library', '1.0.0', 'new-icon-library', ['icons/*.svg']);
  }

  protected getDescription(): string {
    return 'Description of the new library';
  }

  protected getSourceUrl(): string {
    return 'https://github.com/library/icons';
  }

  protected getLicense(): string {
    return 'MIT';
  }
}

3. src/providers/index.ts でプロバイダーを登録します。

registry.register(new NewLibraryProvider());

4. scripts/build-index.js にライブラリの設定を追加します。

'new-icon-library': {
  name: 'new-library',
  displayName: 'New Library',
  description: 'Description of the new library',
  sourceUrl: 'https://github.com/library/icons',
  license: 'MIT',
  iconPaths: ['icons/*.svg'],
  styles: ['regular'],
}

コードスタイル

• TypeScript：Strict モードを有効化
• ESLint：TypeScript ルールを設定
• Prettier：一貫性のあるコードフォーマット
• Husky：品質チェック用のコミット前フック

📊 パフォーマンス

• 検索速度：キャッシュを使用した場合、ほとんどのクエリで 100ms 未満
• メモリ使用量：LRU キャッシュによる効率的なメモリ管理
• スケーラビリティ：複数のライブラリにまたがる数千のアイコンに対応
• あいまい検索：最高のパフォーマンスを実現する Fuse.js 設定に最適化

🔒 セキュリティ

• 入力の検証：すべての入力を Zod スキーマで検証
• 出力のサニタイズ：SVG コンテンツを安全に処理
• エラー処理：情報漏えいを防ぐ包括的なエラー処理
• 依存関係：定期的なセキュリティ監査と更新

🤝 コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature/amazing-feature
3. 変更をコミットします：git commit -m 'Add amazing feature'
4. ブランチにプッシュします：git push origin feature/amazing-feature
5. Pull Request を作成します

開発ガイドライン

• 新機能にはテストを作成してください
• TypeScript のベストプラクティスに従ってください
• API の変更に合わせてドキュメントを更新してください
• すべての CI チェックに合格することを確認してください

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。

🙏 謝辞

• 強力なあいまい検索機能を提供する Fuse.js
• 標準プロトコルを提供する Model Context Protocol
• 素晴らしい取り組みをされているすべてのアイコンライブラリのメンテナー

📞 サポート

• 問題報告：GitHub Issues
• ディスカッション：GitHub Discussions
• ドキュメント：Wiki

---

開発者コミュニティのために ❤️ を込めて作られました