TrueIcon

TrueIcon

TrueIcon は、AI コーディングアシスタントに正確でバージョンに合ったアイコン参照を提供する MCP サーバーです。アシスタントは、プロジェクトで実際に使用しているアイコンパッケージ（lucide-react、react-icons、@heroicons/react、@phosphor-icons/react、@tabler/icons-react、iconoir-react、@fluentui/react-icons、@carbon/icons-react、@ant-design/icons、@mui/icons-material、@radix-ui/react-icons、@remixicon/react、Font Awesome Free パッケージ、Lucide、Heroicons、Tabler、Phosphor の Vue および Svelte パッケージ）を検索し、実際のアイコン名、インポートパス、すぐに貼り付けられる import 行を取得します。

理由

AI アシスタントは、アイコン名をよく推測します。その推測は、存在したことのないアイコンや、数リリース前に名前が変更されたアイコン、別のライブラリのアイコンである場合があり、ビルドが失敗して初めて気付くことになります。TrueIcon はこのギャップを埋めます。

• プロジェクトで使用しているアイコンパッケージとバージョンを読み取ります。
• npm から該当する正確なバージョンをダウンロードし、すべてのアイコンを一度インデックス化します。
• アシスタントが search_icons を呼び出すと、そのバージョンに確実に存在する結果を取得できます。たとえば import { Trash2 } from 'lucide-react'; です。

対応プロバイダー

プロバイダー ID	npm パッケージ	アイコンの命名規則
lucide	lucide-react	Lucide のファイル名。例：trash-2 → Trash2
heroicons	@heroicons/react	<icon>-<size>-<style>。例：trash-24-outline → TrashIcon
react-icons	react-icons	<set>-<icon>。例：fa6-beer-mug-empty → FaBeerMugEmpty
phosphor	@phosphor-icons/react	通常のウェイトでは <icon>、それ以外では <icon>-<weight>。例：trash-bold → weight="bold" を指定した TrashIcon
tabler	@tabler/icons-react	Tabler のアイコン名。例：trash → IconTrash、trash-filled → IconTrashFilled
iconoir	iconoir-react	通常は <icon>、塗りつぶしの場合は <icon>-solid。例：trash-solid → TrashSolid
fluentui	@fluentui/react-icons	<icon>-<style>。style は regular、filled、color のいずれかです。例：delete-regular → DeleteRegular。サイズ固有のバリエーションではなく、スケーラブルな（1em）アイコンのみがインデックス化されます
carbon	@carbon/icons-react	Carbon のエクスポート名をケバブケースで表記します。例：trash-can → TrashCan。バリエーションには -filled、-alt、-color が追加されます。例：accessibility-filled → AccessibilityFilled
antdesign	@ant-design/icons	<icon>-<theme>。theme は outlined、filled、two-tone のいずれかです。例：delete-outlined → DeleteOutlined
mui	@mui/icons-material	MUI のエクスポート名をケバブケースで表記します。例：delete → Delete。テーマには -outlined、-rounded、-sharp、-two-tone が追加されます。例：delete-outlined → DeleteOutlined。基本のアイコンのスタイルは filled です
radix	@radix-ui/react-icons	Radix のアイコン名。例：trash → TrashIcon、github-logo → GitHubLogoIcon
remix	@remixicon/react	Remix のアイコン名。スタイルは -line または -fill です。例：delete-bin-line → RiDeleteBinLine
fontawesome-solid	@fortawesome/free-solid-svg-icons	Font Awesome のアイコン名。例：trash-can → faTrashCan。以前の名前も引き続き解決されます。get_icon は trash-alt または faTrashAlt を faTrashCan として、faSearch を faMagnifyingGlass として検索します
fontawesome-regular	@fortawesome/free-regular-svg-icons	fontawesome-solid と同じです。例：star → faStar
fontawesome-brands	@fortawesome/free-brands-svg-icons	fontawesome-solid と同じです。例：github → faGithub

Vue と Svelte

以下は、上記の React パッケージと同じアートワークをインデックス化します。ただし、各パッケージ固有のコンポーネント名とインポートパスを使用します。

プロバイダー ID	npm パッケージ	アイコンの命名規則
lucide-vue	@lucide/vue	lucide と同じです。例：trash → Trash
lucide-vue-next	lucide-vue-next	lucide と同じです。@lucide/vue が推奨され、上流では非推奨ですが、現在も広く使われています
lucide-svelte5	@lucide/svelte	lucide と同じです（Svelte 5）
lucide-svelte	lucide-svelte	lucide と同じです。@lucide/svelte が推奨され、上流では非推奨です
heroicons-vue	@heroicons/vue	heroicons と同じです。例：trash-24-outline → @heroicons/vue/24/outline の TrashIcon
tabler-vue	@tabler/icons-vue	tabler と同じです。例：trash → IconTrash
tabler-svelte	@tabler/icons-svelte	tabler と同じです
phosphor-vue	@phosphor-icons/vue	phosphor と同じです。例：trash-bold → weight="bold" を指定した PhTrash
phosphor-svelte	phosphor-svelte	phosphor と同じです。例：trash-bold → weight="bold" を指定した TrashIcon

Heroicons に公式の Svelte パッケージはありません。Angular パッケージはまだサポートされていません。

ツールでは、プロバイダー ID または npm パッケージ名（"lucide" または "lucide-react"）を指定できます。使用例のスニペットはインポート行で、React、Vue、Svelte で同じように使えます。Phosphor の各ウェイトはすべて同じコンポーネントを使うため、レコードの style を weight プロパティに渡してください（例：<TrashIcon weight="bold" />）。使用例のスニペットにはインポートのみが示されています。Font Awesome のインポート対象はコンポーネントではなくアイコン定義です。@fortawesome/react-fontawesome を使ってレンダリングしてください（例：<FontAwesomeIcon icon={faTrashCan} />）。

インストール

TrueIcon の実行には Node.js 20 以降が必要です。

# Run without installing (this is what the MCP configs below do)
npx -y trueicon

# Or install globally and run the `trueicon` binary
npm i -g trueicon
trueicon

trueicon は stdio MCP サーバーです。MCP クライアントが起動します。手動で実行すると、trueicon: v<version> running on stdio を stderr に出力し、stdin で JSON-RPC を待ち受けます。

クイックスタート

1. MCP クライアント（Claude Code、Claude Desktop、またはVS Code と Cursor）に TrueIcon を登録します。
2. アシスタントにアイコンを尋ねます。

ほとんどのプロジェクトでは、これだけで準備完了です。TrueIcon は、package.json に記載されたアイコンパッケージと、node_modules にインストールされたバージョンを検出します。各パッケージの初回検索時にダウンロードとインデックス化が行われるため、数秒かかります。以降の検索ではローカルキャッシュが使われます。

設定

検索対象となるアイコンパッケージ

• デフォルトでは、package.json の dependencies または devDependencies に記載されている、サポート対象のすべてのパッケージが対象です。
• プロジェクトに .iconmcp.json がある場合は、そこに記載されているパッケージのみが対象です。一部のアイコンパッケージだけを検索する場合、package.json に記載されていないパッケージ（たとえば、UI キット経由で導入されたもの）を追加する場合、またはバージョンを固定する場合に使用します。

{
  "providers": [
    { "package": "lucide-react" },
    { "package": "react-icons", "version": "5.3.0" },
    { "package": "@heroicons/react", "version": "^2.1.0" }
  ]
}

フィールド	型	必須	意味
providers	配列	はい	検索対象のアイコンパッケージです。項目がある場合、パッケージの選択に package.json は使用されません。
providers[].package	文字列	はい	サポート対象のプロバイダーの npm パッケージ名です。例：lucide-react、@lucide/vue、@tabler/icons-svelte（サポート対象のプロバイダーを参照）。
providers[].version	文字列	いいえ	正確なバージョンまたは npm のバージョン範囲です。インストール済みのバージョンより優先されます（バージョンを参照）。
semantic	bool	いいえ	意味ベースの検索を有効にします（デフォルトは false）。以下を参照してください。

• .iconmcp.json に記載されたサポート対象外のパッケージはスキップされ、search_icons が警告として報告します。
• JSON が無効、またはエントリの形式が不正な場合、ツールはファイル名と不正なフィールドを示すエラーを返します。
• どちらのファイルにもサポート対象のパッケージが記載されていない場合、search_icons は検索したディレクトリを示すエラーを返します。ツール呼び出しに provider を渡すこともできます。

意味ベースの検索（オプトイン）

.iconmcp.json で "semantic": true に設定すると、search_icons に意味ベースのランキングが追加されます。各クエリは小さなローカルモデル（all-MiniLM-L6-v2、約90MB。transformers.js のキャッシュに一度だけダウンロード）で埋め込み表現に変換され、インデックス作成時に生成されたアイコンごとのベクトルと照合されます。意味ベースの候補は、相互順位融合を用いてキーワード検索の結果と統合されるため、正確な名前の一致が優先されつつ、「remove background」のような概念的なクエリから eraser が見つかることもあります。

{
  "providers": [{ "package": "lucide-react" }],
  "semantic": true
}

意味ベースの検索は @huggingface/transformers 上で動作します。これは オプションのピア依存関係であり、デフォルトではインストールされません。そのため、このフラグを有効にしないインストールは軽量なままです。意味ベースの検索を有効にするには、trueicon とともに一度だけインストールします（約400MB）。

npm install @huggingface/transformers

フラグが有効でもパッケージが見つからない場合、search_icons と get_icon はキーワードのみのインデックスにフォールバックし、インストールコマンドを記載した1行の警告を返します。

フラグを切り替えると、インデックスが一度再構築されます（ベクトルは各レコードとともに index.json に保存され、埋め込みモデルは meta.json に記録されます）。すべてローカルで処理されるため、データがマシンの外部に送信されることはありません。TRUEICON_SEMANTIC=1（または 0）を指定すると、1回の実行に限ってフラグの設定を上書きできます。

プロジェクトのディレクトリ

TrueIcon は、プロジェクトディレクトリから package.json、.iconmcp.json、node_modules を読み込みます。次のうち、最初に該当する場所を選択します。

1. 設定されている場合は $TRUEICON_PROJECT_DIR。
2. MCP クライアントがサーバーと共有するフォルダー（MCP ルート）のうち、package.json または .iconmcp.json を含むもの。VS Code など、ルートに対応したクライアントは作業中のフォルダーを TrueIcon に伝えるため、設定なしで開いているプロジェクトに追従します。
3. これらのファイルのいずれかを含む場合は、サーバーの作業ディレクトリ。Claude Code はプロジェクト内でサーバーを起動するため、この方法でディレクトリを検出します。
4. それ以外の場合は、最初の共有フォルダー。共有フォルダーがなければ、作業ディレクトリ。

list_providers には、使用中のディレクトリと、どのルールで選択されたかが表示されるため、クライアントの動作を確認できます。

環境変数

変数	デフォルト値	用途
TRUEICON_PROJECT_DIR	共有フォルダー、ない場合は作業ディレクトリ	package.json と .iconmcp.json を含むプロジェクトのルート
TRUEICON_CACHE	~/.trueicon/cache	ダウンロードしたパッケージとインデックスの保存場所
TRUEICON_SEMANTIC	.iconmcp.json のフラグ	この実行でセマンティック検索を強制的にオン／オフにする 1／0

バージョン

自動検出

プロバイダーのバージョンは、次の順序で決定されます。

1. 指定されている場合は、ツール呼び出しに渡された version 引数。
2. .iconmcp.json に設定されたプロバイダーの version。
3. node_modules にインストールされているバージョン。プロジェクトディレクトリから各親ディレクトリの順に確認するため、モノレポのルートにホイストされたパッケージも見つかります。
4. プロジェクトの package.json に宣言されたパッケージのバージョン範囲。まず dependencies を確認し、次に devDependencies を確認します。

いずれも見つからない場合、ツールはバージョンを固定するか、パッケージを package.json に追加するよう求めます。TrueIcon はロックファイルを読み取らず、node_modules 内のファイルを使うのではなく、npm から独自のパッケージをダウンロードします。範囲が指定されている場合は、その範囲のベースバージョンをインデックス化します。たとえば、^0.460.0 は [email protected] をインデックス化します。a || b の範囲では、最初の部分のみが対象です。npm install を実行する前は、そのベースバージョンが実際に取得されるバージョンより古い場合があるため、正確なバージョンが重要な場合は .iconmcp.json で固定してください。

バージョンポリシー

インデックスはメジャー.マイナーをキーとして作成されます。

• パッチバージョンは無視されます。 0.460.x 全体で1つのインデックスが使われます。0.460.0 から作成されたインデックスは、0.460.3 のリクエストにも応答します。
• マイナーバージョンが変わると、専用のインデックスが作成されます。 lucide-react を 0.460 から 0.461 に上げると、次回の検索時に新しいインデックスが作成され、手動での操作は不要です。
• メジャーバージョンは厳密に区別されます。 メジャーバージョンが異なる場合は、必ず別のインデックスが使用され、他のメジャーバージョンのインデックスが使われることはありません。
• キャッシュ済みのインデックスは、同梱の synonyms.json の変更（ハッシュで検出）またはインデックス形式の変更時に自動的に再構築されます。

Claude での使用

Claude Code

プロジェクトディレクトリから TrueIcon を追加します。

claude mcp add trueicon -- npx -y trueicon

または、プロジェクトのルートに .mcp.json をコミットして、チームで共有します。

{
  "mcpServers": {
    "trueicon": {
      "command": "npx",
      "args": ["-y", "trueicon"]
    }
  }
}

Claude Code はプロジェクトディレクトリでサーバーを起動するため、設定なしでその場所にある package.json を見つけます。別の場所から実行される場合は、"env": { "TRUEICON_PROJECT_DIR": "/absolute/path/to/project" } を追加してください。

Claude Desktop

Claude Desktop はプロジェクトディレクトリでサーバーを起動しないため、TRUEICON_PROJECT_DIR を設定してください。お使いのバージョンの Claude Desktop がサーバーとフォルダーを共有する場合は、TrueIcon は代わりにそれらのフォルダーを使用します。list_providers で選択されたディレクトリを確認できます。claude_desktop_config.json を編集してください。macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json です。

{
  "mcpServers": {
    "trueicon": {
      "command": "npx",
      "args": ["-y", "trueicon"],
      "env": {
        "TRUEICON_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

ファイルを編集した後、Claude Desktop を再起動してください。

VS Code と Cursor での使用

この README の上部にあるインストールバッジを使用してください。TRUEICON_PROJECT_DIR に ${workspaceFolder} を設定した状態で TrueIcon が追加され、現在開いているプロジェクトが検索対象になります。

VS Code で手動追加するには、プロジェクトに .vscode/mcp.json を作成してください。

{
  "servers": {
    "trueicon": {
      "command": "npx",
      "args": ["-y", "trueicon"],
      "env": {
        "TRUEICON_PROJECT_DIR": "${workspaceFolder}"
      }
    }
  }
}

Cursor では、.cursor/mcp.json の "mcpServers" 内に同じエントリを使用してください。

ツール

各ツールは、単一の JSON テキストブロックを返します。失敗した場合は、ブロックが {"error": "..."} となり、MCP の結果には isError: true が設定されます。

search_icons

インデックスを検索し、インポート文を含む関連度順の結果を返します。

Argument	Type	Required	Description
query	string	yes	アイコンに描かれているもの。例："trash"
provider	string	no	プロバイダー ID またはパッケージ。デフォルト：プロジェクトが使用するすべてのプロバイダー（「検索対象のアイコンパッケージ」を参照）
version	string	no	バージョンまたは範囲。デフォルト：バージョンの説明に従って解決されます
style	string	no	完全一致するスタイルのフィルター。例："outline"、"solid"、"filled"（tabler）、"regular"（fluentui）、"two-tone"（antdesign、mui）、"line"（remix）、"brands"（Font Awesome）、または phosphor の "bold" などのウェイト。Lucide アイコンはすべて outline です。carbon の基本アイコンと radix アイコンにはスタイルがありません
set	string	no	完全一致するセットのフィルター。例：react-icons の "fa6" または "md"
limit	integer	no	結果の最大数。1～50、デフォルトは 10

呼び出し例：

{ "query": "trash", "provider": "lucide", "limit": 3 }

応答：

{
  "results": [
    { "name": "trash", "importName": "Trash", "importPath": "lucide-react", "package": "lucide-react",
      "version": "0.460.0", "style": "outline", "set": "lucide",
      "usage": "import { Trash } from 'lucide-react';", "score": 0 },
    { "name": "trash-2", "importName": "Trash2", "importPath": "lucide-react", "package": "lucide-react",
      "version": "0.460.0", "style": "outline", "set": "lucide",
      "usage": "import { Trash2 } from 'lucide-react';", "score": 0.02 },
    { "name": "delete", "importName": "Delete", "importPath": "lucide-react", "package": "lucide-react",
      "version": "0.460.0", "style": "outline", "set": "lucide",
      "usage": "import { Delete } from 'lucide-react';", "score": 0.6 }
  ]
}

検索の仕組み：

• provider、style、set は、大文字と小文字を区別しない完全一致のフィルターです。ランキングの前に適用されます。

• 候補は、アイコン名、インポート名、キーワード、タグに対する Fuse.js のあいまい検索で取得します。多少の入力ミスは許容されます。"detele" で Delete が見つかります。

• 名前がクエリに一致するアイコンが上位になります。スタイルの接尾辞を除いた名前で比較します（delete-bin-line → delete-bin）：

  1. 名前がクエリと一致：delete で delete、delete-outlined、DeleteRegular が見つかります
  2. 名前がクエリで始まる：delete-bin-line
  3. 名前にクエリのフレーズが含まれる："arrow right" で circle-arrow-right が見つかります
  4. クエリのすべての単語が名前、同義語、またはタグに含まれる：trash で restore-from-trash が見つかり、trash → delete の同義語を介して delete も見つかります

  同じレベルでは、名前の短いものが先になります。そのため、単純なアイコンが複合アイコンより上位になり（restore-from-trash より delete が先）、各アイコンのスタイルはデフォルトのスタイルを先頭にまとめて表示されます。クエリに番号が含まれていない限り、バリアント番号は無視されるため、trash では trash、次に trash-2 の順で表示されます。それ以外（入力ミスなど）はあいまい検索のスコアに従います。

• score は 0（完全一致）から 1 までの値で、低いほど良好です。上記のランキングを反映しているため、複数のプロバイダーの結果を統合してスコア順に並べても、順位情報は失われません。

• 複数単語のクエリはトークンに分割されます。各単語を個別に照合し、すべての単語に一致するアイコンのみを残して、平均スコア順に並べます。そのため、"trash can" で trash-can アイコンが見つかります。短いキーワードのクエリ（"trash"、"settings"、"beer"）では、引き続き最も幅広く検索します。

• たとえば、バージョンを解決できない、またはダウンロードに失敗したなどの理由でプロバイダーのいずれかが失敗した場合、そのプロバイダーの結果はスキップされ、理由を示す warnings 配列が返されます。他のプロバイダーからは引き続き結果が返されます。

list_providers

引数はありません。TrueIcon が参照するプロジェクトディレクトリとその特定方法、プロジェクトが使用するプロバイダーと解決済みのバージョン、さらに TrueIcon がサポートするすべてのプロバイダーを返します。

{
  "project": { "dir": "/Users/you/code/my-app", "source": "roots" },
  "providersFrom": "package.json",
  "configured": [
    { "id": "lucide", "package": "lucide-react", "version": "1.47.0", "source": "node_modules" },
    { "id": "heroicons", "package": "@heroicons/react", "version": "^2.1.0", "source": "package.json" }
  ],
  "registry": [
    { "id": "react-icons", "package": "react-icons", "description": "Aggregated icon sets (Font Awesome, Material, Feather, and more) as React components" },
    { "id": "lucide", "package": "lucide-react", "description": "Lucide icons as React components" },
    { "id": "heroicons", "package": "@heroicons/react", "description": "Heroicons by the Tailwind CSS team as React components" },
    { "id": "phosphor", "package": "@phosphor-icons/react", "description": "Phosphor icons in six weights (thin, light, regular, bold, fill, duotone) as React components" },
    { "id": "tabler", "package": "@tabler/icons-react", "description": "Tabler icons (outline and filled) as React components" },
    { "id": "iconoir", "package": "iconoir-react", "description": "Iconoir icons (regular and solid) as React components" },
    { "id": "fluentui", "package": "@fluentui/react-icons", "description": "Microsoft Fluent UI System icons (regular, filled and color) as React components" },
    { "id": "carbon", "package": "@carbon/icons-react", "description": "IBM Carbon Design System icons as React components" },
    { "id": "antdesign", "package": "@ant-design/icons", "description": "Ant Design icons (outlined, filled and two-tone) as React components" },
    { "id": "mui", "package": "@mui/icons-material", "description": "Material UI icons (filled, outlined, rounded, sharp and two-tone) as React components" },
    { "id": "radix", "package": "@radix-ui/react-icons", "description": "Radix UI icons (15x15) as React components" },
    { "id": "remix", "package": "@remixicon/react", "description": "Remix Icon (line and fill) as React components" },
    { "id": "fontawesome-solid", "package": "@fortawesome/free-solid-svg-icons", "description": "Font Awesome Free solid icons, rendered with @fortawesome/react-fontawesome" },
    { "id": "fontawesome-regular", "package": "@fortawesome/free-regular-svg-icons", "description": "Font Awesome Free regular icons, rendered with @fortawesome/react-fontawesome" },
    { "id": "fontawesome-brands", "package": "@fortawesome/free-brands-svg-icons", "description": "Font Awesome Free brand logos, rendered with @fortawesome/react-fontawesome" },
    { "id": "lucide-vue", "package": "@lucide/vue", "description": "Lucide icons as Vue components" },
    { "id": "lucide-vue-next", "package": "lucide-vue-next", "description": "Lucide icons as Vue components (deprecated package, replaced by @lucide/vue)" },
    { "id": "lucide-svelte5", "package": "@lucide/svelte", "description": "Lucide icons as Svelte 5 components" },
    { "id": "lucide-svelte", "package": "lucide-svelte", "description": "Lucide icons as Svelte components (deprecated package, replaced by @lucide/svelte)" },
    { "id": "heroicons-vue", "package": "@heroicons/vue", "description": "Heroicons by the Tailwind CSS team as Vue components" },
    { "id": "tabler-vue", "package": "@tabler/icons-vue", "description": "Tabler icons (outline and filled) as Vue components" },
    { "id": "tabler-svelte", "package": "@tabler/icons-svelte", "description": "Tabler icons (outline and filled) as Svelte components" },
    { "id": "phosphor-vue", "package": "@phosphor-icons/vue", "description": "Phosphor icons in six weights as Vue components" },
    { "id": "phosphor-svelte", "package": "phosphor-svelte", "description": "Phosphor icons in six weights as Svelte components" }
  ]
}

• project.source は、"TRUEICON_PROJECT_DIR"、（MCP クライアントが共有したフォルダーである）"roots"、または（サーバーの作業ディレクトリである）"cwd" です。「プロジェクトのディレクトリ」を参照してください。
• providersFrom は "iconmcp.json"、"package.json"、またはサポート対象のパッケージがどちらにも記載されていない場合は null です。
• 各プロバイダーの source は、バージョンの取得元である "iconmcp.json"、"node_modules"、または "package.json" を示します。バージョンを取得できる場所がない場合、version と source は null です。TrueIcon がサポートしていない .iconmcp.json 内のパッケージでは、id は null です。

get_icon

アシスタントがすでに把握している名前のアイコンについて、レコード全体とインポート文を取得します。

Argument	Type	Required	Description
name	string	yes	アイコン名（"trash-2"）またはインポート名（"Trash2"）。まず完全一致を検索し、その後、大文字と小文字を区別せずに検索します
provider	string	yes	プロバイダー ID またはパッケージ
version	string	no	バージョンまたは範囲。デフォルト： Versions の説明に従って解決されます

呼び出し例：

{ "name": "Trash2", "provider": "lucide" }

応答：

{
  "id": "[email protected]:trash-2",
  "name": "trash-2",
  "importName": "Trash2",
  "importPath": "lucide-react",
  "provider": "lucide",
  "package": "lucide-react",
  "version": "0.460.0",
  "style": "outline",
  "set": "lucide",
  "categories": [],
  "tags": [],
  "keywords": ["trash", "2", "delete", "remove", "bin", "garbage", "rubbish"],
  "svg": "<path d=\"M3 6h18\"/><path d=\"M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6\"/>…",
  "usage": "import { Trash2 } from 'lucide-react';"
}

svg はアイコンの内部 SVG マークアップで、ルートの <svg> 要素の子要素を指します。Heroicons では、すべてのサイズとスタイルで同じインポート名（TrashIcon）が使用されます。特定のバリエーションを取得するには、"trash-24-outline" のように完全なバリエーション名を渡します。

ping

{"status":"ok","server":"trueicon"} を返すヘルスチェックです。

インデックス作成とキャッシュ

ツールが初めて [email protected] を必要とするとき、TrueIcon は次の処理を行います。

1. https://registry.npmjs.org からパッケージの tarball をダウンロードし、sha512 の整合性を検証して、キャッシュに展開します。
2. プロバイダーのアダプターを使って、パッケージに含まれるファイルを解析します。コードは実行されません。アイコンはコンパイル済みソースから読み取られます。
3. index.json（アイコンごとに 1 件のレコード）と meta.json（正確なバージョン、同義語のハッシュ、インデックス形式、ビルド時刻）を書き込みます。

以降の呼び出しでは index.json のみを読み取ります。クエリ時にパッケージファイルに触れることはありません。node_modules から TrueIcon が読み取るのは、インストール済みバージョンを取得するための各アイコンパッケージの package.json のみで、そこに変更を加えることはありません。複数のツール呼び出しで同じインデックスが同時に必要になった場合は、1 回のダウンロードを共有します。

キャッシュのルートは ~/.trueicon/cache、または設定されている場合は $TRUEICON_CACHE です。

~/.trueicon/cache/
├── [email protected]/          # extracted package + index.json + meta.json
├── [email protected]/             # extracted package + index.json + meta.json
├── [email protected]/         # extracted @heroicons/react package
└── @heroicons/[email protected]/        # index.json + meta.json for @heroicons/react

• ダウンロード先は <package>@<major.minor> です。スコープ付きの名前はフラット化され、@heroicons/react は heroicons-react になります。最後に .download-complete マーカーが書き込まれ、これがないディレクトリは不完全なものとして置き換えられます。
• インデックスの保存先は <package>@<major.minor>/index.json と meta.json です。スコープなしのパッケージでは、ダウンロード先と同じディレクトリになります。
• キャッシュは安全に削除できます。必要に応じて再構築されますが、その際はネットワークアクセスが必要です。

各レコードの keywords には、名前の各部分、タグ、同梱の synonyms.json による同義語の展開が組み合わされています。展開はインデックス作成時に追加されるため、クエリ時に特別な処理をしなくても "bin" で Trash2 が見つかります。

貢献

git clone https://github.com/manikumarkv/trueicon.git
cd trueicon
npm ci
npm run build      # compile to dist/
npm test           # vitest
npm run lint       # eslint
npm run typecheck  # tsc --noEmit

CI では、プッシュとプルリクエストのたびに、Node 20 および 22 で lint、型チェック、テストを実行します。

Claude Code on the web では、SessionStart フック（.claude/hooks/session-start.sh）がセッション開始時に依存関係をインストールするため、これらのコマンドをすぐに実行できます。サンドボックスではオプションのセマンティック検索依存関係に含まれるネイティブモジュールのダウンロードがブロックされるため、--ignore-scripts を指定してインストールします。その環境では、依存関係を必要とするセマンティックテストはスキップされます。

テスト

コマンド	検証内容	ネットワーク
npm test	tests/fixtures/ にある小規模なフィクスチャを使って、24 個すべてのプロバイダーについて、アダプターの解析と各ツール（search_icons、get_icon、list_providers）を検証します	いいえ
npm run smoke	実際の npm パッケージを使って各プロバイダーを検証します。複数の固定リリースと現在の最新リリースを対象に、アイコン数とよく知られたアイコンをいくつか確認します	はい

フィクスチャは編集されない限り変更されないため、上流でプロバイダーのパッケージ形式が変更されても検出できません。npm run smoke なら検出できます。一部のプロバイダーのみを確認するには、npm run smoke -- lucide tabler を実行します。CI では、src/providers/、src/indexer/、src/cache/ に変更があるプルリクエスト、および毎週月曜日に最新リリースを対象として実行します。

ローカルでのテストとデバッグ

これらのスクリプトはサーバーをビルドし、最新バージョンの 24 個すべてのプロバイダーを一覧表示するサンプルプロジェクト playground/ に対して実行します。.cache/dev/ に別のキャッシュを使用するため、実際の ~/.trueicon キャッシュには影響しません。

# Call one tool and print the result
npm run dev:call -- list_providers
npm run dev:call -- search_icons query="trash can" limit=5
npm run dev:call -- search_icons query=trash provider=lucide version=1.47.0
npm run dev:call -- get_icon name=Trash2 provider=lucide

# Open the MCP Inspector web UI on the local build
npm run dev:inspect

# Same, with the Node debugger on port 9229
npm run dev:debug

• 引数は key=value 形式のペアです。数値とブール値は解析されるため、limit=5 は数値として送信されます。
• 別のプロジェクト： TRUEICON_PROJECT_DIR にそのプロジェクトの package.json と .iconmcp.json を使ってテストするパスを設定します。例：TRUEICON_PROJECT_DIR=~/code/my-app npm run dev:inspect。
• インデックスの再構築： --fresh を追加すると、最初に開発用キャッシュが削除されます。例：npm run dev:call -- --fresh search_icons query=trash。アダプターを変更した後に使用します。
• ブレークポイント： npm run dev:debug を実行し、VS Code で Debug: Attach to Node Process を使用するか、Chrome で chrome://inspect を開きます。ソースマップが有効なので、src/ 以下の .ts ファイルでブレークポイントが機能します。ブレークポイントを設定したら、インスペクターからツールを呼び出します。
• ログ： stdout は MCP プロトコルに使用されるため、ログには console.error を使います。ログは dev:call の場合はターミナルに、dev:inspect の場合はインスペクターのサーバーログに表示されます。
• 手動テスト用プロンプト： playground/TEST-PROMPTS.md は、MCP クライアントで playground に対して実行するプロンプトと、想定されるツール呼び出しおよび結果をまとめたチェックリストです。すべてのツール、15 個すべてのプロバイダー、ランキング、設定エラー、セマンティック検索を網羅しています。リリース前に実行してください。

synonyms.json の拡張

src/synonyms/synonyms.json は、用語を追加の検索語に対応付けます。

{
  "trash": ["delete", "remove", "bin", "garbage", "rubbish"],
  "logout": ["sign-out", "signout", "exit", "leave"]
}

• キーはアイコンの名前の各部分（名前を - で分割したもの）とタグに対して照合されます。trash-2 はキー trash に一致します。
• 値はそのアイコンの keywords に追加されます。
• 展開は一方向です。bin でも delete という名前のアイコンを見つけられるようにするには、"trash": ["bin"] と "delete": ["bin"] の両方を追加するか、逆方向のエントリーを追加します。
• キーと値は小文字で記述し、各キーに空でない文字列の配列を指定してください。tests/synonyms.test.ts で確認します。
• このファイルを変更するとハッシュが変わるため、次回の検索時にキャッシュされたインデックスが自動的に再構築されます。

プロバイダーの追加

1. src/providers/registry.ts に、安定した id、npm の package、短い description を登録します。
2. src/providers/adapters/<provider>.ts にアダプターを作成し、parseIcons(packageDir: string): RawIcon[] をエクスポートします（src/providers/adapter.ts を参照）。展開済みのパッケージディレクトリを受け取り、アイコンごとに 1 つの RawIcon を返します。
   • name：kebab-case で、パッケージ内で一意にします。レコード ID の一部になるためです。adapter.ts の toKebabCase を使用してください。パッケージ内にコンポーネント名が重複するバリアントがある場合は、heroicons、react-icons、phosphor、iconoir の各アダプターと同様に、バリアントを名前に追加します。
   • importName と importPath：ユーザーがインポートする正確なエクスポート名とモジュール指定子です。
   • svg：SVG の内部マークアップです。LiteralCursor（src/providers/jsLiteral.ts）は、コードを実行せずに JS のオブジェクトリテラルと配列リテラルを解析します。toSvgAttrs と renderSvg（src/providers/svg.ts）は React の props を SVG マークアップに変換し、parseCreateElement はコンパイル済みの createElement(...) ツリーを読み取ります。
   • style、set、categories、tags は任意です。
   • 既存のアダプターと同様に、アダプターの先頭にパッケージのファイル構成を説明するコメントを記述します。
3. src/providers/adapters/index.ts のプロバイダー ID に対応する ADAPTERS に追加して、組み込みます。
4. テストします。 パッケージの構成を反映した、いくつかの実際のアイコンファイルとアダプターがスキップする必要のあるファイルを含む、小規模な固定フィクスチャを tests/fixtures/<provider>/ に追加します。続いて、既存のアダプターテストと同様に、名前のマッピング、インポートパス、SVG 出力、buildIndex のレコード ID を網羅する tests/adapters/<provider>.test.ts を追加します。登録済みのプロバイダーにアダプターがない場合、tests/adapters/common.test.ts が失敗します。
5. tests/providers-tools.test.ts の CASES にケースを追加して、ツールのテストにも加えます。フィクスチャ、検索クエリ、正確なインポート行を含むアイコン 1 つ、パッケージに非推奨のエイリアスがある場合はそのエイリアスを指定します。登録済みのプロバイダーにケースがない場合、テストは失敗します。
6. scripts/smoke.mjs の TARGETS に、有名なインポート名をいくつかと、実際の数を大きく下回る最小アイコン数を追加します。その後、npm run smoke -- <provider> を実行し、公開済みの実際のパッケージに対して確認します。

ライセンス

MIT © 2026 manikumarkv