Component Harvester MCP Server ✨

Component Harvester MCP Server ✨

この MCP（Model Context Protocol）サーバーは、人気の UI ライブラリから React コンポーネントを調達するための、AI エージェントの頼れる相棒です。UI 要素を見つけ、取得し、プロジェクトへの組み込み方法を理解する作業を自動化し、コードの直接取得と CLI ベースの組み込みガイダンスの両方に対応します。

対応ライブラリ

• Aceternity UI：コンポーネントのコードとメタデータをすべて取得します。
• Shadcn UI：コンポーネントのメタデータ取得と CLI ベースの組み込みガイダンスに対応します。
• (今後さらに追加予定です！)

概要

このサーバーは Aceternity UI と Shadcn UI からコンポーネント情報を取得します。

• Aceternity UI では、コードと依存関係をすべて取得します。
• Shadcn UI では、メタデータ（依存関係や作成されるファイルなど）を取得し、CLI を使ったコンポーネントのインストール方法を案内します。

このサーバーは取得した情報を保存し、AI エージェント（またはあなた）がコンポーネントを組み込むための詳細なプロンプトを生成できます。

エージェント向けプロンプトの例：

• "Aceternity UI から「3D Pin」コンポーネントを取得して、コードと依存関係を表示してください。"
• "Aceternity UI で利用可能なコンポーネントをすべて一覧表示してください。"
• "Shadcn UI の「Alert Dialog」コンポーネントを調べて、組み込み方法を表示してください。"
• "Shadcn UI で利用可能なコンポーネントをすべて一覧表示してください。"

できること 🚀

Component Harvester により、AI エージェントは次のことができます。

1. コンポーネントの検出：Aceternity UI（https://ui.aceternity.com/registry）と Shadcn UI（https://ui.shadcn.com/registry）のメイン JSON レジストリを取得して解析し、利用可能なコンポーネントを自動的に把握します。
2. コンポーネントデータの取得：
   • Aceternity UI：特定のコンポーネントの詳細な構造化 JSON データ（例：https://ui.aceternity.com/registry/[slug].json）を取得します。これには、ソースコード全体、ファイルパス、依存関係などが含まれます。
   • Shadcn UI：メインレジストリ JSON から、特定のコンポーネントのメタデータを直接取得します。依存関係やファイル名などが含まれますが、Shadcn のコンポーネントは CLI で追加するため、ソースコード全体は含まれません。
3. ローカルへの保存：
   • すべてのソースから処理されたコンポーネントの中央インデックス（data/harvested_index.json）を保持します。
   • コンポーネントごとの詳細データを、ソース別のディレクトリに保存します。
     • data/aceternity/[slug].json：Aceternity UI コンポーネントの取得した JSON 全体（コードを含む）を格納します。
     • data/shadcn/[slug].json：メインレジストリから抽出した Shadcn UI コンポーネントのメタデータ（名前、種類、依存関係、ファイル一覧）を保存します。
4. 組み込み手順の生成：詳細なステップ形式のプロンプトを生成します。
   • Aceternity UI 向けプロンプト：手動で組み込むためのコード全体、ファイルパス、依存関係の情報を含みます。
   • Shadcn UI 向けプロンプト：npx shadcn-ui@latest add [slug] の実行方法を案内し、想定されるファイルと依存関係を一覧表示します。

動作の仕組み 🧙‍♂️

1. 全体像の把握：レジストリの処理

サーバーの起動時に、Aceternity UI と Shadcn UI の両方からメインレジストリ JSON を直接取得します。

graph TD
    subgraph Server Startup
        direction LR
        A1[Initiate] --> A2a[Fetch JSON from aceternity.com/registry]
        A2a --> A3a[Parse Aceternity JSON & Cache Slugs]
        A1 --> A2b[Fetch JSON from shadcn.com/registry]
        A2b --> A3b[Parse Shadcn JSON & Cache Metadata]
    end
    A3a --> A4[Server Ready]
    A3b --> A4

• 目的：すばやく検索できるよう、内部マップ（aceternityRegistryData と shadcnRegistryData）を構築します。
  • Aceternity では、正規化されたコンポーネント名をスラッグに対応付けます（例：「3D Pin」->「3d-pin」）。
  • Shadcn では、正規化されたコンポーネント名を、レジストリ内のメタデータオブジェクト全体に対応付けます。

2. お宝探し：特定コンポーネントデータの取得と処理

Aceternity UI： エージェントが Aceternity のコンポーネント（例：「3D Pin」）を要求すると、サーバーはキャッシュ済みのスラッグを使用します。

graph TD
    B0[Agent Request: scan_aceternity_component] --> B1[MCP Server]
    B1 --> B2{Slug in Aceternity Cache?}
    B2 -- Yes --> B3[Construct URL: aceternity.com/registry/slug.json]
    B3 --> B4[Fetch Component JSON via Axios]
    B4 -- Full JSON Data --> B5[Parse & Store Full Component Data]
    B5 --> B6[Update Main Index & In-Memory Cache]
    B6 --> B7[Report Success]
    B2 -- No --> B8[Report Not Found]

• 取得データ：コンポーネントの JSON 全体。すべてのファイルのソースコードが含まれます。

Shadcn UI： エージェントが Shadcn のコンポーネント（例：「Alert Dialog」）を要求すると：

graph TD
    C0[Agent Request: scan_shadcn_component] --> C1[MCP Server]
    C1 --> C2{Component in Shadcn Cache?}
    C2 -- Yes --> C3[Retrieve Metadata from Cache]
    C3 -- Metadata (files, deps) --> C4[Store This Metadata as Component's Data]
    C4 --> C5[Update Main Index & In-Memory Cache]
    C5 --> C6[Report Success]
    C2 -- No --> C7[Report Not Found]

• 処理されるデータ：https://ui.shadcn.com/registry からすでに取得済みのメタデータ（依存関係、ファイル一覧など）。Shadcn では個別の [slug].json が提供されていないため、取得しません。

3. 記録の保持：コンポーネントの保存

処理済みのすべてのコンポーネントデータは、次の場所に保存されます。

1. 個別の JSON ファイル：
   • data/aceternity/[slug].json：Aceternity UI コンポーネントの完全な JSON（コード、ファイル、依存関係）を保存します。
   • data/shadcn/[slug].json：メインレジストリから抽出した Shadcn UI コンポーネントのメタデータ（名前、種類、依存関係、ファイル一覧）を保存します。
2. 中央インデックスファイル（data/harvested_index.json）：すべてのソースの全コンポーネントをまとめたマニフェストです。名前、ソース、スラッグ、説明、個別の JSON ファイルへのパス、最終スキャン時刻などのメタデータが含まれます。

   {
     "aceternity:3DPin": { /* ... metadata ... */ },
     "shadcn:AlertDialog": { /* ... metadata ... */ }
   }
   

インメモリキャッシュ（inMemoryIndexCache）は、このインデックスを複製し、すばやくアクセスできるようにします。

4. 設計図：統合プロンプトの生成

get_aceternity_component_prompt および get_shadcn_component_prompt ツールは、保存されたデータを統合手順に変換します。

• Aceternity UI のプロンプト：完全なコード、ファイルパス、依存関係の情報が含まれます。
• Shadcn UI のプロンプト：npx shadcn-ui@latest add [slug] の使用方法を案内し、想定されるファイルと依存関係を一覧表示します。

ツール紹介：MCP サーバーエンドポイント 🛠️

共通ツール

• list_harvested_components：インデックスに保存されているすべてのコンポーネントを一覧表示します。
  • 入力：{ "source": "aceternity" | "shadcn" | "all" }（任意）

Aceternity UI ツール

• scan_aceternity_component：Aceternity UI コンポーネントの完全なデータを取得して保存します。
  • 入力：{ "componentName": "string" }
• get_aceternity_component_prompt：スキャン済みの Aceternity UI コンポーネントについて、詳細な統合ガイド（コード付き）を生成します。
  • 入力：{ "componentName": "string" }

Shadcn UI ツール

• list_shadcn_components：Shadcn UI レジストリキャッシュで利用できるすべてのコンポーネントを一覧表示します。
  • 入力：{}
• scan_shadcn_component：メインレジストリから Shadcn UI コンポーネントのメタデータを処理して保存します。
  • 入力：{ "componentName": "string" }
• get_shadcn_component_prompt：Shadcn UI コンポーネントの統合ガイド（CLI 中心）を生成します。
  • 入力：{ "componentName": "string" }

今後の展望：将来的な機能強化 🗺️

• よりスマートなプロンプト生成：プロンプトで、より状況に応じたアドバイスを提供します。
• 対応範囲の拡大：さらに多くのコンポーネントライブラリへの対応を追加します。
• 手動キャッシュ更新：必要に応じてレジストリの取得を再実行するツールを追加します。
• エラー処理の強化：堅牢性を高めるための継続的な改善を行います。

コンポーネントの統合をよりスムーズかつ迅速にできることを楽しみにしています！