livewire-flux-mcp

Livewire Flux MCP

Livewire Flux の Livewire Flux コンポーネントとレイアウトにアクセスできる MCP（Model Context Protocol）サーバーです。このサーバーを使用すると、AI アシスタントは Flux のコンポーネントとレイアウトのドキュメントを必要に応じて取得、検索できます。

⚠️免責事項

これは個人プロジェクトであり、Livewire Flux とは関係ありません。

概要

この MCP サーバーは Livewire Flux のドキュメントをスクレイピングし、構造化されたアクセスを提供することで、AI アシスタントが次のことをできるようにします。

• https://fluxui.dev/components/ から特定の Flux コンポーネントのドキュメントを取得する
• https://fluxui.dev/layouts/ から特定の Flux レイアウトのドキュメントを取得する
• API の詳細、props、使用パターンを含むコンポーネントとレイアウトのリファレンスセクションにアクセスする
• コンポーネントとレイアウトのドキュメントを検索する
• 利用可能なすべての Flux コンポーネントを一覧表示する
• flux:icon コンポーネントで使用できるすべての Heroicons を閲覧、検索する
• Flux 公式サイトから最新のドキュメントに直接アクセスする
• 高パフォーマンスなキャッシュにより、24 時間の有効期限で最適な応答速度を実現する

Laravel Boost だけではだめな理由

Boost はすでに search-docs ツールで Flux をインデックス化しているため、多くの質問にはそれで十分です。ただし、次の 2 点には対応していません。

• 対象を絞った回答。 search-docs は 17k 件のドキュメントを対象にしたセマンティック検索なので、範囲の広い Flux に関する質問では、数千トークンに及ぶダンプが返されることがあります（laravel/boost#290）。このサーバーは、指定された 1 つのコンポーネントページとそのリファレンスセクションを取得します。
• Pro ティアへの対応。 Boost に同梱されている fluxui-development スキルにはコンポーネント一覧がハードコードされており、有料の Flux ライセンスが必要なコンポーネントをエージェントに知らせません。このサーバーはティア情報をリアルタイムで読み取り、該当するコンポーネントを明示するため、エージェントが公開できないマークアップを作成しなくなります。

Boost を利用している場合は、npx livewire-flux-mcp install で両方を連携できます。詳しくは AI ガイドラインとスキルをご覧ください。両者は相互に補完します。Laravel、Livewire、Pest などには Boost を引き続き使い、Flux への回答にはこのサーバーをお使いください。

エージェントをセットアップする

サーバーは stdio 経由で動作し、npx で起動するため、グローバルにインストールする必要はありません。エージェントごとに設定方法が異なるため、以下からお使いのものを選んでください。

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

claude mcp add --transport stdio --scope project flux-docs -- npx -y livewire-flux-mcp

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

codex mcp add flux-docs -- npx -y livewire-flux-mcp

[mcp_servers.flux-docs]
command = "npx"
args = ["-y", "livewire-flux-mcp"]

gemini mcp add --scope project flux-docs npx -y livewire-flux-mcp

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

{
    "servers": {
        "flux-docs": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

code --add-mcp '{"name":"flux-docs","command":"npx","args":["-y","livewire-flux-mcp"]}'

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

サーバーを登録すると、エージェントにツールが存在することは伝わります。しかし、いつ使うべきかまでは伝わりません。さらに、Laravel Boost プロジェクトでは実際に使われません。Boost には、Flux の検索を独自の search-docs ツールに送信し、コンポーネントの一覧をハードコードした fluxui-development スキルが同梱されているためです。このパッケージには、それを解決するガイダンスが含まれています。

npx livewire-flux-mcp install

インストーラーは該当するものを検出します。composer.json に livewire/flux-pro があれば fluxui-pro ガイドラインキーを選択し、livewire/flux があれば fluxui-free を選択します。また、.claude/ ディレクトリがあればサブエージェントを追加します。--boost または --claude で対象を絞り込み、--path <dir> で別の場所を指定するか、--dry-run でプレビューできます。その後、php artisan boost:update を実行して Boost にファイルを読み込ませてください。

上書きについて。 スキルは意図的に置き換えます。Boost はカスタムスキルを最後に解決し、フロントマターの name をキーにするため、上書きを適用するには fluxui-development を一致させる必要があります。ガイドラインが上書きされることはありません。そのパスに既存のファイルがある場合も、Flux パッケージ自体に同梱されたガイドラインがある場合も、当パッケージのブロックより下に保持されます。このブロックは {{-- livewire-flux-mcp:begin --}} マーカーで区切られているため、再実行してもそのセクションだけが更新されます。インストーラーが書き込んでいないファイルは、--force を指定しない限り変更されません。

元に戻すには、インストールしたファイルを削除して php artisan boost:update を実行してください。Boost が独自のバージョンを復元します。

Laravel Boost は Composer パッケージからのみガイドラインとスキルを自動検出するため、npm パッケージからそれらを自動登録することはできません。このインストーラーは、カスタムガイドラインとスキル用に Boost が指定するパスにファイルを書き込むため、機能し、boost:update の実行後も維持されます。

ご支援のお願い

皆さん、こんにちは。

このパッケージを気に入っていただけましたか？役に立ち、プロジェクトにうまく適合していますか？

皆さんのお役に立てることをうれしく思います。私の活動をご支援いただけたら、とてもありがたいです。

次のような方法もあります 😃：

• スポンサーになってください 😎
• コーヒー ☕ またはピザ 🍕 をおごってください
• このリポジトリに「スター ⭐」を付けてください（無料です 😉）

利用可能な MCP ツール

サーバーは4つの MCP ツールを提供します。

1. fetch_flux_docs - コンポーネントまたはレイアウトのドキュメントを取得します

   • component（任意）：ドキュメントを取得する特定のコンポーネント名
   • layout（任意）：ドキュメントを取得する特定のレイアウト名（例：「header」、「sidebar」）
   • version（任意）：対象とする Flux のメジャーバージョン — 'v1' または 'v2'（デフォルトは 'v2'）
   • 利用可能な場合、リファレンスセクションを自動的に含めます
   • https://fluxui.dev/components/{component} または https://fluxui.dev/layouts/{layout}（v2）から取得します。version='v1' の場合は https://v1.fluxui.dev/components/{component} にルーティングします
   • ページが有料の Flux コンポーネントの場合、応答の先頭に [NOTICE] This is a Flux Pro component … の行が追加されます

2. list_flux_components - 利用可能な Flux コンポーネントをすべて一覧表示します

   • version（任意）：'v1' または 'v2'（デフォルトは 'v2'）
   • tier（任意）：'free'、'pro'、または 'all'（デフォルトは 'all'）。'all' の場合、各コンポーネントに [Pro] または [Free] が付記されます。v1 では Pro ティアがないため、tier 引数は無視されます
   • コンポーネント名とそのドキュメントのパスを提供します

3. list_flux_layouts - 利用可能な Flux レイアウトをすべて一覧表示します

   • version（任意）：'v1' または 'v2'（デフォルトは 'v2'）。v1 の場合、HTTP リクエストを行わず、「layouts are not available in v1」という簡潔な通知を返します
   • レイアウト名とそのドキュメントのパスを提供します
   • レイアウト名は fluxui.dev/layouts から読み込まれます。そのインデックスが利用できない場合は、fluxui.dev/components のサイト全体のナビゲーションを代わりに使用します。どちらの場合も、個々の /layouts/{name} ページには影響しません

4. list_flux_component_icons - flux:icon コンポーネントで利用可能な Heroicons をすべて一覧表示します

   • variant（任意）：アイコンのバリアントで絞り込みます（outline、solid、mini、micro）
   • search（任意）：アイコン名を絞り込む検索語句
   • Heroicons の GitHub リポジトリから実際のアイコン名を取得します
   • 各バリアントの使用例、サイズ、GitHub リンクを提供します
   • Flux の適切な構文で、利用可能なアイコンをすべて網羅した一覧を返します

使用例

MCP サーバーを起動すると、AI アシスタントは次のように使用できます。

• 特定のコンポーネントのドキュメントを取得する：「Button コンポーネントのドキュメントを表示して」
• 特定のレイアウトのドキュメントを取得する：「header レイアウトのドキュメントを表示して」
• 利用可能なコンポーネントを一覧表示する：「利用できる Flux コンポーネントを教えて」
• 利用可能なレイアウトを一覧表示する：「利用できる Flux レイアウトを教えて」
• 利用可能なアイコンをすべて閲覧する：「flux:icon で利用できる Heroicons をすべて表示して」
• 特定のアイコンを検索する：「outline バリアントの矢印アイコンをすべて探して」
• アイコンの使用例を取得する：「solid バリアントの user アイコンはどう使うの？」

サーバーは fluxui.dev/components、fluxui.dev/layouts の最新ドキュメントと、GitHub の Heroicons を自動的に取得し、AI アシスタントが利用しやすい構造化形式で提示します。コンポーネントまたはレイアウトのドキュメントを取得する際は、メインコンテンツと、詳細な API 情報を含むリファレンスセクションの両方を含めます。

バージョン

Flux には2つのメジャーバージョンがあり、MCP サーバーはどちらもサポートしています。

• v2（デフォルト）— 現在のホストは fluxui.dev です。version を省略するか、'v2' に設定すると使用されます。コンポーネント、レイアウト、Pro ティアの判別をサポートします。
• v1 — レガシーホストは v1.fluxui.dev です。version='v1' の場合に使用されます。コンポーネントのみをサポートします。Flux v1 には /layouts ルートも Pro ティアもありません。list_flux_layouts は HTTP リクエストを行わずに v1 で利用できないことを知らせる通知を返し、list_flux_components では v1 の tier が無視されます。

version 引数は fetch_flux_docs、list_flux_components、list_flux_layouts で受け付けられます。list_flux_component_icons はバージョンに依存しません（Heroicons は Flux のバージョン管理に含まれません）。

Pro ティアについて

Flux v2 の一部のコンポーネントは、有料の Flux Pro ライセンスでのみ利用できます。MCP サーバーでは、次の 2 つの方法でこれを示します。

• 取得時の通知。 fetch_flux_docs が Pro のコンポーネントを取得すると、応答の先頭に [NOTICE] This is a Flux Pro component — requires a paid Flux license. という 1 行が追加されます。
• 一覧表示時のティアフィルター。 list_flux_components では、Pro コンポーネントを非表示にする tier='free'、Pro コンポーネントのみを表示する tier='pro'、またはすべてを一覧表示する tier='all'（デフォルト）を指定できます。tier='all' の場合、各名前の横に [Pro]／[Free] の注釈が付きます。

Pro コンポーネントの一覧は fluxui.dev/pricing をもとにしており、サーバーにはハードコードされたフォールバックが組み込まれています。そのため、料金ページにアクセスできない場合でも、ティアフィルターは正しく機能します。

MCP サーバーを手動で登録する

エディターがエージェントのセットアップで紹介している 6 つのエディターに含まれていない場合は、次の情報を使用してサーバーを手動で登録してください。

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

-y を指定すると、初回起動時のインストール確認がスキップされます。stdio サーバーはこの確認に応答できません。

パフォーマンスとキャッシュ

MCP サーバーには、最適なパフォーマンスを実現するインテリジェントなキャッシュ機能が含まれています。

• 24 時間のキャッシュ有効期限 - 新鮮さとパフォーマンスのバランスを取るため、コンテンツは 1 日間キャッシュされます
• 自動キャッシュ管理 - 期限切れのエントリーは自動的にクリーンアップされます
• インテリジェントなキャッシュキー - パラメーター（コンポーネント、レイアウト、バージョン、ティア、バリアント）ごとに異なるキャッシュエントリーを使用します
• GitHub API のレート制限対策 - Heroicons の取得時に GitHub API の制限に達するのを防ぎます
• 即時応答 - キャッシュされたリクエストは、数秒ではなく数ミリ秒で返されます

キャッシュの動作

• ドキュメントのリクエスト：コンポーネント／レイアウトとバージョンの組み合わせごとにキャッシュされます
• コンポーネントの一覧：グローバルにキャッシュされます（毎日更新）
• レイアウトの一覧：グローバルにキャッシュされます（毎日更新）
• アイコンの一覧：バリアントと検索条件の組み合わせごとにキャッシュされます
• キャッシュの保存先：メモリー内（サーバーの再起動時にリセットされます）

キャッシュシステムは、キャッシュがない場合、1 回のリクエストで最大 4 回の GitHub API 呼び出しを行う可能性がある list_flux_component_icons ツールで特に効果を発揮します。

変更履歴

最近の変更については、CHANGELOGをご覧ください。

コントリビューション

詳細については、CONTRIBUTINGをご覧ください。

セキュリティの脆弱性

セキュリティの脆弱性の報告方法については、セキュリティポリシーをご確認ください。

クレジット

• Maurizio
• すべてのコントリビューター

ライセンス

MIT License（MIT）です。詳細については、ライセンスファイルをご覧ください。