Shadcn UI MCP 服务器

这是一个 Model Context Protocol (MCP) 服务器的 TypeScript 实现，旨在帮助 AI 助手访问和使用 shadcn/ui 组件。该服务器充当 Claude 等 AI 模型与 shadcn/ui 之间的桥梁，使助手能够获取组件源代码、演示和安装指南。

项目概述

此 MCP 服务器提供工具和资源来帮助 AI 助手：

• 获取 shadcn/ui 组件源代码
• 获取组件演示代码和使用示例
• 生成 shadcn/ui 组件的安装说明
• 提供特定于框架的安装指南

项目结构

shadcn-ui-mcp-unofficial/
├── build/             # 编译后的 JavaScript 文件
│   ├── handler.js
│   ├── http.js
│   ├── index.js
│   ├── prompts.js
│   ├── resource-templates.js
│   ├── resources.js
│   ├── tools.js
│   ├── schemas/       # 编译后的 schema
│   │   └── component.js
│   └── types/         # 编译后的类型定义
│       ├── component.js
│       └── doc.js
├── docs/              # 文档资源
│   └── images/        # 文档图片
│       ├── chat-interface.png
│       └── server-configured.png
├── src/               # TypeScript 源代码文件
│   ├── handler.ts     # 请求处理程序实现
│   ├── http.ts        # HTTP 服务器实现
│   ├── index.ts       # 服务器入口点
│   ├── prompts.ts     # Prompt 定义
│   ├── resource-templates.ts # 安装指南模板
│   ├── resources.ts   # 组件列表的资源定义
│   ├── tools.ts       # 组件检索的工具定义
│   ├── schemas/       # 用于验证的 JSON schema
│   │   └── component.ts
│   ├── types/         # TypeScript 类型定义
│   │   ├── component.ts
│   │   └── doc.ts
│   └── utils/         # 实用函数和 API 客户端
│       ├── api.ts
│       ├── axios.ts
│       └── cache.ts
├── package.json       # 项目依赖和脚本
├── README.md          # 项目文档
├── startup.sh         # 用于清理、构建和启动服务器的脚本
├── todo.md            # 项目 TODO 列表
└── tsconfig.json      # TypeScript 配置

快速开始

前提条件

• Node.js (建议 v18 或更高版本)
• npm

安装

npm install

运行服务器

使用启动脚本来清理、构建和启动服务器：

bash startup.sh

或者运行单个命令：

npm run clean
npm run build
npm run start # 在默认端口启动 MCP 检查器

功能特性

工具

此 MCP 服务器实现了以下工具：

1. get_component

检索 shadcn/ui 组件的源代码。

• 参数:
  • componentName (string): shadcn/ui 组件的名称 (例如, "accordion", "button")
• 返回值: 请求的组件的源代码

2. get_component_demo

检索演示代码，说明如何使用 shadcn/ui 组件。

• 参数:
  • componentName (string): shadcn/ui 组件的名称 (例如, "accordion", "button")
• 返回值: 显示如何使用组件的演示代码

资源

此 MCP 服务器提供以下资源：

1. resource:get_components

返回所有可用的 shadcn/ui 组件的列表。

资源模板

此 MCP 服务器实现了以下资源模板：

1. resource-template:get_install_script_for_component

根据包管理器首选项生成组件安装脚本。

• 参数:
  • packageManager (string): 要使用的包管理器 (npm, pnpm, yarn, bun)
  • component (string): 要安装的组件

2. resource-template:get_installation_guide

为 shadcn/ui 提供特定于框架的安装指南。

• 参数:
  • framework (string): 要使用的框架 (next, vite, remix, 等)
  • packageManager (string): 要使用的包管理器 (npm, pnpm, yarn, bun)

实现细节

GitHub 集成

服务器直接从 shadcn/ui GitHub 存储库获取组件信息，特别是来自：

• 主要的 shadcn-ui/ui 存储库
• 包含最新组件的 v4 应用程序

服务器在查找组件时会尝试多个路径，因为某些组件是直接命名的（例如，button.tsx），而其他组件可能位于目录结构中（例如，accordion/accordion.tsx）。

错误处理

服务器实现了强大的错误处理来处理以下情况：

• 组件不存在或已重命名
• 对 GitHub 的网络请求失败
• 提供了无效的参数

可扩展性

服务器设计为易于扩展：

• 通过更新 tools.ts 文件来添加新工具
• 通过更新 resources.ts 文件来添加新资源
• 通过更新 resource-templates.ts 文件来添加新资源模板

调试

MCP 检查器可帮助您调试服务器。 当您使用 npm run start 运行服务器时，检查器会在控制台输出中指示的 URL（通常是 http://127.0.0.1:6274）提供一个 Web 界面。

附加资源

• Model Context Protocol 文档
• MCP Typescript SDK
• Shadcn UI 文档
• 构建 MCP 服务器 by Craig Strolia-Davis

使用示例

本节提供在不同环境中如何使用 shadcn/ui MCP 服务器的视觉示例。

VS Code 代理模式集成

shadcn/ui MCP 服务器可以与 VS Code 的代理模式集成，以便为 AI 助手提供对 shadcn/ui 组件的直接访问。

在 VS Code 中设置

1. 打开您的 VS Code settings.json 文件
2. 添加 MCP 服务器配置：

"mcp": {
    "servers": {
        "shadcnui": {
            "type": "sse",
            "url": "http://localhost:3001/sse"
        }
    }
}

与 VS Code 代理模式一起使用

以下是使用 VS Code 代理模式的 shadcn/ui MCP 服务器的示例：

1. 列出可用工具

   • MCP 服务器显示可用的工具，例如 get_component 和 get_component_demo。
   • 

2. 获取组件源代码

   • AI 助手检索特定组件的源代码，例如 button.tsx。
   • 

在 SSE 模式下运行

服务器发送事件 (SSE) 模式允许其他应用程序通过 HTTP 连接到您的 MCP 服务器。 这对于与 VS Code 代理模式等工具集成非常有用。

要在 SSE 模式下运行服务器：

1. 构建并启动 HTTP 服务器：

npm run start:http

2. 您应该看到类似于以下的输出：

MCP server listening on port 3001
SSE endpoint available at http://localhost:3001/sse
Message endpoint available at http://localhost:3001/messages

3. 服务器现在已准备好接受连接。 您可以配置 VS Code 或其他 MCP 客户端以连接到 http://localhost:3001/sse 的 SSE 端点。

测试 SSE 端点

您可以使用 curl 测试您的 SSE 端点是否正常工作：

curl -N http://localhost:3001/sse

这应该开始从服务器流式传输事件，表明 SSE 端点工作正常。

故障排除

常见问题

1. 连接被拒绝: 确保服务器正在运行，并且端口未被防火墙阻止。
2. 找不到组件: 检查组件名称是否正确，并且存在于 shadcn/ui 库中。
3. VS Code 未连接: 验证 settings.json 配置是否具有正确的 URL。

调试技巧

• 使用 npm run start 运行时，使用 http://127.0.0.1:6274 上的 MCP 检查器来调试请求/响应流程。
• 检查控制台输出中的错误消息。
• 确保您具有网络连接以访问 shadcn/ui GitHub 存储库。