Component Harvester MCP Server ✨

Component Harvester MCP 服务 ✨

这个 MCP（Model Context Protocol）服务是你的 AI Agent 在热门 UI 库中寻找 React 组件的得力助手。它会自动查找、获取 UI 元素，并说明如何将其集成到你的项目中，同时支持直接采集代码和基于 CLI 的集成指导。

支持的库

• Aceternity UI：完整组件代码和元数据采集。
• Shadcn UI：组件元数据采集和基于 CLI 的集成指导。
• (即将推出更多！)

简介；

此服务会获取 Aceternity UI 和 Shadcn UI 的组件信息。

• 对于 Aceternity UI，它会获取完整代码和依赖项。
• 对于 Shadcn UI，它会获取元数据（例如依赖项、创建的文件），并告知你如何使用其 CLI 安装组件。

服务会存储这些信息，并可为 AI Agent（或你！）生成详细的提示词，帮助集成这些组件。

Agent 提示词示例：

• "从 Aceternity UI 获取 '3D Pin' 组件，并向我展示代码和依赖项。"
• "列出 Aceternity UI 中所有可用的组件。"
• "扫描 Shadcn UI 中的 'Alert Dialog' 组件，并向我展示如何集成它。"
• "列出 Shadcn UI 中所有可用的组件。"

它能做什么？🚀

Component Harvester 可帮助 AI Agent：

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，它会将规范化的组件名称映射到其 slug（例如，"3D Pin" -> "3d-pin"）。
  • 对于 Shadcn，它会将规范化的组件名称映射到注册表中的完整元数据对象。

2. 寻宝：获取／处理特定组件数据

Aceternity UI： 当 Agent 请求 Aceternity 组件（例如，“3D Pin”）时，服务会使用缓存的 slug。

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： 当 Agent 请求 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）：包含所有来源组件的清单，其中包含名称、来源、slug、描述、对应 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" }

未来展望：后续增强 🗺️

• 更智能的提示词生成：在提示词中提供更多结合上下文的建议。
• 拓展支持范围：增加对更多组件库的支持。
• 手动刷新缓存：提供按需重新触发注册表获取的工具。
• 增强错误处理：持续提升稳健性。

我们期待让组件集成变得更加顺畅快捷！