基于MCP协议构建AI组件助手：shadcn-ui-mcp-server实战指南-程序员充电站

1. 项目概述：当AI助手学会“抄作业”

作为一名常年混迹在React、Vue、Svelte多个前端框架生态里的开发者，我深知一个痛点：UI组件库的文档和代码示例，是开发效率的“隐形杀手”。每次要写一个带分页的表格，或者一个复杂的表单验证，都得在官方文档、Stack Overflow、GitHub Issue之间反复横跳，复制粘贴、修修改改，半小时就过去了。更别提当项目需要在React和Vue之间切换时，那种“重新学一遍”的割裂感。

最近，随着AI编程助手的普及，我发现了一个新问题：这些AI，比如Claude、Cursor，它们很聪明，能理解我的需求，但它们在生成UI代码时，往往“知其然不知其所以然”。它们可能会给我一个基础的<button>，但很难直接生成一个符合shadcn/ui设计规范、带完整交互状态、无障碍支持且样式精美的<Button />组件。我需要的是一个能让AI助手直接“接入”真实、高质量组件库的桥梁。

这就是shadcn-ui-mcp-server出现的背景。它不是一个新框架，而是一个协议服务器。简单来说，它把shadcn/ui及其衍生生态（Svelte、Vue、React Native版本）的所有组件源码、示例、配置信息，打包成一个标准化的数据服务。然后，通过Model Context Protocol这个协议，让Claude Desktop、Claude Code、Cursor等AI工具能够直接“查询”和“调用”这些资源。

你可以把它想象成一个为AI定制的、超强的shadcn/ui代码搜索引擎和片段库。当你在AI聊天框里说：“给我一个带暗色模式切换的导航栏”，AI不再需要凭空想象或搜索过时的代码，而是可以直接通过这个MCP服务器，获取到shadcn/ui官方仓库里最新、最地道的navigation-menu组件代码及其演示案例，然后根据你的项目框架（React/Vue/Svelte）生成完全可用的代码。

1.1 核心价值：从“生成代码”到“生成正确且地道的代码”

这个项目的核心价值，在于它解决了AI辅助开发中的一个关键断层：上下文缺失。AI模型在训练时接触了海量代码，但它并不知道你当前项目具体在用哪个版本的shadcn/ui，不知道你选择了Radix UI还是Base UI作为底层，更不知道团队内部约定的代码风格。

shadcn-ui-mcp-server通过MCP协议，为AI补全了这块关键的“项目上下文”。它告诉AI：

有什么：当前可用的所有组件列表（Button, Card, Form, Table...）。
长什么样：每个组件的TypeScript源码、Props定义。
怎么用：组件的演示案例（Demo）和最佳实践。
依赖什么：安装这个组件需要哪些npm包（如@radix-ui/react-dialog）。
怎么组合：完整的“区块”（Blocks），比如一个完整的用户设置页面或数据分析看板。

这样一来，AI生成的代码不再是通用的、可能过时的模板，而是与你项目技术栈严丝合缝、可直接粘贴运行的“正确答案”。这极大地提升了代码的准确性、一致性和开发速度。

1.2 目标用户与适用场景

这个工具非常适合以下几类开发者：

全栈或前端开发者：正在使用或计划使用shadcn/ui生态进行项目开发，希望借助AI提升UI搭建效率。
技术团队负责人：希望统一团队的UI代码规范，减少查阅文档的时间，让新人也能快速产出高质量UI代码。
多框架使用者：需要在React、Vue、Svelte项目中保持相似的UI风格和开发体验。
AI工具深度用户：频繁使用Claude Code、Cursor、Continue.dev等具备MCP能力的编辑器或IDE插件。

典型的使用场景包括：

快速原型搭建：用自然语言描述页面，让AI基于shadcn/ui的Blocks快速生成完整页面代码。
组件查询与学习：不确定<Select>组件如何与表单集成？直接问AI，它能给出结合了react-hook-form和zod的完整示例。
跨框架代码转换：有一个React的<Calendar>组件写得很好，想在Vue项目里用类似的，AI可以参照React版本生成对应的Vue 3组合式API代码。
代码审查与建议：AI可以基于shadcn/ui的最佳实践，对你现有的组件代码提出改进建议。

2. 核心架构与协议解析

要理解shadcn-ui-mcp-server如何工作，我们需要先拆解两个核心概念：Model Context Protocol和服务器内部的数据流转机制。这能帮你明白为什么它比简单的代码片段插件更强大。

2.1 Model Context Protocol：AI的“外接大脑”标准

MCP不是某个公司的私有产品，而是一个由Anthropic主导的开放协议。你可以把它理解为AI工具的USB-C接口标准。在MCP出现之前，每个AI助手（Claude、GPT等）想连接外部数据源（你的数据库、日历、GitHub），都需要单独开发一套插件系统，既混乱又不通用。

MCP定义了一套标准的“语言”（协议），让任何MCP服务器（提供数据的服务，如本项目）都能与任何MCP客户端（消费数据的AI，如Claude Desktop）进行通信。服务器通过一个名为manifest.json的文件“广告”自己有哪些能力（Tools），客户端则按需调用。

shadcn-ui-mcp-server就是一个典型的MCP服务器。它对外提供的主要“能力”可能包括：

list_components：列出所有可用的组件。
get_component_source：获取某个组件的完整TypeScript源码。
get_component_demo：获取该组件的使用示例代码。
get_block：获取一个完整的UI区块代码（如dashboard-01）。
search_components：根据描述搜索组件。

当你在Claude Code里输入“给我一个对话框组件的代码”，Claude Code（MCP客户端）就会向连接好的shadcn-ui-mcp-server发送一个请求，调用get_component_source工具，参数为{“name”: “dialog”, “framework”: “react”}。服务器收到后，会去shadcn/ui的GitHub仓库找到最新代码返回，Claude再将其整合进回答里。

2.2 服务器内部工作流：数据获取、缓存与交付

这个MCP服务器本身是一个Node.js应用，它的核心工作流可以概括为“获取-处理-缓存-响应”。

第一步：数据源聚合服务器并不存储组件代码本身，而是作为一个智能代理，动态地从四个官方GitHub仓库获取数据：

shadcn/ui(React)
shadcn-svelte(Svelte)
shadcn-vue(Vue)
react-native-reusables(React Native) 它通过GitHub REST API来读取这些仓库的文件结构、获取文件内容。这就是为什么需要一个GitHub Token——为了突破API的速率限制（无Token每小时60次，有Token每小时5000次）。

第二步：请求路由与参数解析当收到一个MCP工具调用请求时，服务器会解析参数：

framework: 决定去哪个仓库找代码。
component_name: 确定目标组件。
ui_library(仅React): 决定是获取基于Radix UI还是Base UI的代码。这是shadcn/uiv4的一个重要特性，允许你选择不同的底层原子组件库。

第三步：智能缓存策略频繁访问GitHub API是不可取的，既慢又容易触发限流。因此，服务器实现了多层缓存：

内存缓存：对高频请求的组件元数据（如列表）进行短期缓存，减少API调用。
文件系统缓存：在本地缓存获取到的组件源码和示例，并设置合理的过期时间。即使GitHub暂时无法访问，服务器也能返回最近可用的数据。
缓存失效：当通过--no-cache参数启动或缓存过期时，会自动刷新数据，确保你获取的不是过时的代码。

第四步：数据格式化与返回获取到原始的代码文件后，服务器会进行简单的处理，比如清理不必要的注释、确保格式统一，然后按照MCP协议规定的JSON格式包装数据，返回给客户端。对于get_block这类请求，它可能需要拼接多个组件文件，形成一个完整的、可运行的示例。

第五步：传输层适配服务器支持三种传输模式，适应不同部署环境：

stdio（标准输入输出）：最简单的方式，适用于本地CLI启动，AI客户端（如Claude Desktop）直接以子进程方式启动该服务器，通过管道通信。
sse（Server-Sent Events）：基于HTTP的长连接，允许服务器主动向客户端推送数据。这是生产部署的关键，意味着你可以在一台服务器上运行一个shadcn-ui-mcp-server实例，然后让团队内所有的IDE或AI工具同时连接它，共享同一个数据源和缓存。
dual（双模式）：同时启用stdio和sse，灵活性最高。

实操心得：缓存的重要性在实际使用中，务必配置GitHub Token。无Token的60次/小时限制在开发时很容易触发，导致后续请求失败。有了Token，5000次的限额对于个人或小团队开发绰绰有余。缓存机制使得即使网络波动，你的AI助手依然能流畅工作，体验上的提升是巨大的。

3. 从零开始：完整安装与配置指南

了解了原理，我们开始动手。这里我将提供一套从零开始、覆盖所有主流方式的详细配置流程，并解释每一步背后的原因。

3.1 环境准备与前置依赖

首先，确保你的系统满足基本要求：

Node.js：版本 >= 18.0.0。这是MCP相关工具链的常见要求。建议使用nvm或fnm这类Node版本管理器，方便切换。
npm 或 pnpm：包管理器。pnpm在速度和磁盘空间上更有优势，但npm完全兼容。
Git：用于克隆仓库（如果需要从源码构建）。
Docker & Docker Compose：如果你计划使用容器化部署。

检查你的环境：

node --version # 应输出 v18.x 或更高 npm --version # 或 pnpm --version docker --version docker-compose --version

3.2 核心安装方式详解

有三种主要方式运行这个服务器，适用于不同场景。

方式一：NPX即时运行（推荐给个人开发者/快速体验）这是最快捷的方式，npx会临时下载并运行包，无需全局安装。

# 最基本运行（React框架，Radix UI，无Token-限速） npx @jpisnice/shadcn-ui-mcp-server # 推荐：附带GitHub Token以获取完整速率 npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_actual_token_here # 指定其他框架 npx @jpisnice/shadcn-ui-mcp-server --framework svelte --github-api-key YOUR_TOKEN npx @jpisnice/shadcn-ui-mcp-server --framework vue --github-api-key YOUR_TOKEN npx @jpisnice/shadcn-ui-mcp-server --framework react-native --github-api-key YOUR_TOKEN # React框架下切换UI基础库（默认为radix） npx @jpisnice/shadcn-ui-mcp-server --ui-library base --github-api-key YOUR_TOKEN

参数解析：

--github-api-key：你的GitHub个人访问令牌。这是提升体验的关键。
--framework：指定要使用的组件库框架。默认为react。
--ui-library：仅对react框架有效。radix（默认）或base。base使用的是MUI Base，提供另一套设计风格的底层原语。

如何获取GitHub Token？

访问 https://github.com/settings/tokens 。
点击Generate new token (classic)。
令牌描述可以写shadcn-ui-mcp-server。
权限选择：令人惊喜的是，对于公开仓库的只读访问，不需要勾选任何scope（权限）。一个无scope的token就足够了。这非常安全。
生成后，立即复制并妥善保存。它只会显示一次。

方式二：全局安装（适合频繁使用）如果你每天都要用，可以全局安装，避免每次运行都重新下载。

npm install -g @jpisnice/shadcn-ui-mcp-server # 安装后，可以直接使用命令 `shadcn-ui-mcp-server` shadcn-ui-mcp-server --github-api-key YOUR_TOKEN --framework vue

方式三：从源码构建与运行（适合开发者或需要定制）如果你想了解内部机制，或为项目做贡献，可以从源码构建。

# 1. 克隆仓库 git clone https://github.com/Jpisnice/shadcn-ui-mcp-server.git cd shadcn-ui-mcp-server # 2. 安装依赖（推荐使用pnpm，项目可能有lock文件） npm install # 或 pnpm install # 3. 构建TypeScript代码 npm run build # 这会执行tsc，将src目录下的代码编译到build目录 # 4. 运行编译后的服务器 node build/index.js --github-api-key YOUR_TOKEN # 5. （可选）开发模式，监听文件变化 npm run dev

3.3 配置AI客户端连接（以Claude Desktop为例）

安装好服务器只是第一步，更重要的是让它和你的AI助手“对话”。这里以最流行的Claude Desktop为例。

方法A：一键安装（最简单）

前往项目的 GitHub Releases页面。
下载最新的.mcpb文件（例如shadcn-ui-mcp-server-v1.0.0.mcpb）。.mcpb是一个打包好的MCP服务器扩展包。
双击下载的.mcpb文件。Claude Desktop 会自动打开并弹出安装向导。
在安装界面，你可以选择输入你的GitHub Token（可选，但强烈建议）。
点击安装。完成后，在Claude Desktop的设置 → MCP Servers 中就能看到它。

方法B：手动配置（更灵活）如果一键安装不成功，或者你想自定义参数，可以手动配置。

打开 Claude Desktop。
进入Settings→Developer→MCP Servers。
点击Add Server。
在配置框中，你需要填写一个JSON配置。以下是一个配置示例，它指定了使用npx运行、传递Token和框架参数：

{ "command": "npx", "args": [ "@jpisnice/shadcn-ui-mcp-server", "--github-api-key", "ghp_your_token_here", "--framework", "react" ] }

保存配置。Claude Desktop会尝试启动这个服务器进程。如果状态显示为绿色，说明连接成功。

注意事项：Claude Desktop配置的坑
路径问题：如果npx不在系统PATH中，可能需要使用command的绝对路径（如/usr/local/bin/npx或C:\Users\YourName\AppData\Roaming\npm\npx.cmd）。
参数格式：args必须是一个字符串数组，每个参数独立。不要写成"--github-api-key ghp_xxx"一个字符串。
验证连接：配置后，在Claude Desktop的聊天框中，你可以尝试问：“你现在可以使用哪些工具？” 或者 “列出可用的shadcn组件”。如果AI能正确回应并列出组件，说明配置成功。如果失败，检查Claude Desktop的日志（通常在设置页面有查看日志的选项），里面会有详细的错误信息。

4. 生产级部署：SSE与Docker实战

对于团队协作或个人在多台设备上使用，每次都本地启动服务器很麻烦。这时，SSE传输模式和Docker容器化就派上用场了。你可以将服务器部署在一台云服务器、NAS甚至本地局域网的一台电脑上，让所有设备都能连接。

4.1 理解SSE模式的优势

默认的stdio模式是“一对一”的，一个服务器进程只服务一个客户端。SSE模式则是“一对多”的。

多客户端支持：你的台式机、笔记本、同事的电脑可以同时连接同一个MCP服务器实例。
独立进程：服务器可以长时间运行在后台，不受客户端启动/关闭的影响。
便于监控与管理：作为独立的HTTP服务，你可以方便地添加日志、监控、负载均衡。
适合CI/CD：可以在测试环境中部署一个，供自动化脚本或测试AI调用。

4.2 使用Docker Compose部署（推荐）

项目已经提供了生产就绪的docker-compose.yml，这是最省心的部署方式。

步骤1：准备配置文件在你的服务器上创建一个目录，例如~/shadcn-mcp，并创建两个文件：

docker-compose.yml(直接从项目复制或稍作修改)
.env(用于存放敏感的环境变量，如GitHub Token)

docker-compose.yml示例：

version: '3.8' services: shadcn-ui-mcp: image: ghcr.io/jpisnice/shadcn-ui-mcp-server:latest container_name: shadcn-ui-mcp-server restart: unless-stopped ports: - "7423:7423" # 将容器的7423端口映射到宿主机的7423端口 environment: - MCP_TRANSPORT_MODE=sse - MCP_PORT=7423 - MCP_HOST=0.0.0.0 - GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_TOKEN} # 从.env文件读取 # - UI_LIBRARY=base # 如果需要使用Base UI，取消注释 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:7423/health"] interval: 30s timeout: 10s retries: 3 start_period: 40s logging: driver: "json-file" options: max-size: "10m" max-file: "3"

./env文件内容：

GITHUB_TOKEN=ghp_your_actual_token_here

步骤2：启动服务

cd ~/shadcn-mcp docker-compose up -d

-d参数表示在后台运行。使用docker-compose logs -f可以查看实时日志，确认服务启动成功。

步骤3：验证服务

# 检查容器状态 docker-compose ps # 测试健康检查端点 curl http://localhost:7423/health # 应该返回一个包含状态信息的JSON，如 {"status":"ok"} # 查看日志 docker-compose logs shadcn-ui-mcp

4.3 客户端连接SSE服务器

服务器在7423端口跑起来了，现在需要让AI客户端连接它。

对于Claude Code（命令行工具）：

# 添加一个使用SSE传输的MCP服务器 claude mcp add --scope user --transport sse shadcn-mcp-server http://你的服务器IP:7423/sse # 例如，如果服务器在本地：http://localhost:7423/sse # 如果在局域网另一台机器：http://192.168.1.100:7423/sse

对于Claude Desktop（手动配置）：在MCP Server配置中，不再使用command，而是配置为SSE类型：

{ "mcpServers": { "shadcn-ui": { "transport": "sse", "url": "http://localhost:7423/sse" } } }

对于其他支持MCP的编辑器（如Cursor）：需要在对应编辑器的MCP设置中，添加SSE服务器的URL。具体路径可能为Settings -> AI -> MCP Servers。

4.4 直接使用Docker运行

如果你不想用Docker Compose，也可以直接使用docker run命令：

# 基础运行 docker run -p 7423:7423 ghcr.io/jpisnice/shadcn-ui-mcp-server:latest # 带环境变量（推荐） docker run -p 7423:7423 \ -e MCP_TRANSPORT_MODE=sse \ -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token \ -e UI_LIBRARY=base \ ghcr.io/jpisnice/shadcn-ui-mcp-server:latest # 如果你想进入容器内部检查 docker run -it --entrypoint /bin/sh ghcr.io/jpisnice/shadcn-ui-mcp-server:latest

实操心得：端口与安全
端口选择：7423是作者精心挑选的，因为它像键盘上的“SHADCN”。你可以映射到任何其他端口，如-p 8080:7423。
网络安全：如果你将服务部署在公网（如云服务器），强烈建议不要直接将7423端口暴露给互联网。应该使用反向代理（如Nginx、Caddy）配置HTTPS，并设置防火墙规则，只允许特定的IP（如你的办公室IP）访问。或者，通过SSH隧道进行连接，这是更安全的方式。
资源消耗：这个服务器本身资源消耗很低。一个1核1GB内存的容器实例足以支撑一个小团队的使用。主要开销是网络请求和缓存。

5. 深度使用技巧与工作流整合

安装配置完毕，接下来是如何让它真正融入你的日常开发，发挥最大威力。这里分享一些高阶用法和整合思路。

5.1 框架切换与UI库选择实战

shadcn-ui-mcp-server支持多框架，但你需要根据项目情况做出选择。

场景一：React项目，如何选择radix还是base？

Radix UI（默认）：无样式、无障碍优先的底层原语组件库。shadcn/ui基于它构建，提供了完整的、可定制的样式。这是大多数人的选择，社区生态最丰富，无障碍支持最好。
Base UI：由Material-UI（MUI）团队维护，提供的是Material Design风格的底层组件。如果你或你的团队更喜欢Material Design的设计语言，或者项目本身使用了MUI，那么选择base可以获得更一致的设计基础。
- 启动命令：npx @jpisnice/shadcn-ui-mcp-server --ui-library base
- 环境变量：UI_LIBRARY=base
- 注意：base选项仅对React框架有效。Svelte和Vue版本目前有自己固定的底层实现。

场景二：多框架项目中的使用策略假设你同时维护一个React后台和一个Vue官网。

为每个项目配置独立的MCP服务器：在Claude Desktop中，你可以添加多个MCP服务器配置，并给它们起不同的名字，比如shadcn-react和shadcn-vue。在聊天时，AI可能会同时看到两个服务器的工具，你需要通过提示词引导它使用正确的来源。
使用SSE服务器，动态切换：部署一个SSE服务器，但通过不同的启动参数或环境变量启动多个容器实例，监听不同端口。例如：
```
# React (Radix) 实例 docker run -p 7423:7423 -e FRAMEWORK=react -e UI_LIBRARY=radix ... # Vue 实例 docker run -p 7424:7423 -e FRAMEWORK=vue ...
```
然后在客户端分别连接http://localhost:7423/sse和http://localhost:7424/sse。

5.2 与不同AI工具和编辑器的深度集成

Claude Code (命令行)Claude Code是Anthropic官方的命令行AI工具，对MCP支持最原生。

# 添加本地npx启动的服务器 claude mcp add shadcn-local -- bunx -y @jpisnice/shadcn-ui-mcp-server --github-api-key YOUR_TOKEN # 添加远程SSE服务器 claude mcp add --scope user --transport sse shadcn-remote http://your-server:7423/sse # 查看已配置的服务器 claude mcp list # 移除服务器 claude mcp remove shadcn-local

在Claude Code会话中，你可以直接使用自然语言，如：“使用shadcn组件，帮我创建一个用户个人资料卡片，包含头像、姓名、职位和社交链接。” AI会自动调用相应的工具获取代码。

Cursor & Continue.dev这些新一代的AI原生编辑器也支持MCP。配置方式类似，通常在设置中找到“MCP Servers”或“AI Context”选项。

Cursor：Settings -> AI -> MCP Servers，添加SSE URL或命令行配置。
Continue.dev：在.continue/config.json中配置。它们的优势在于，你可以在编辑器内直接获得代码补全、文件操作等深度集成，而不仅仅是聊天。

VS Code (通过扩展)虽然VS Code本身不原生支持MCP，但可以通过安装Continue或Cursor等扩展来获得类似能力。本质上，你是通过这些扩展的MCP功能来连接shadcn-ui-mcp-server。

5.3 编写高效的AI提示词（Prompt）

要让AI更好地利用这个工具，你的提问方式很重要。低效的提问得到模糊的答案，高效的提问得到可直接运行的代码。

低效提示：

“给我一个按钮。”

高效提示：

“请使用shadcn/ui的Button组件，创建一个主要操作按钮，文字是‘提交’，带加载状态，点击时调用一个名为handleSubmit的异步函数，在加载时显示一个加载图标并禁用按钮。我需要完整的React函数组件代码。”

更高阶的提示技巧：

指定框架和库：“基于shadcn/ui for Vue 3，用<FormField>、<FormItem>、<FormControl>和<FormMessage>构建一个邮箱输入表单字段，使用zod验证，确保邮箱格式正确且必填。”
请求完整区块：“我需要一个类似shadcn/ui官网‘Dashboard’示例中的卡片，用来显示月度收入，包含一个趋势图表（可以用占位符<div>模拟）和对比百分比。”
结合上下文：“在我当前这个Next.js 14 App Router项目里，上面有一个<Card>组件了。请在这个卡片内部，添加一个<Tabs>组件，包含‘概述’和‘设置’两个标签页，<TabsContent>里放一些示例文本。”
请求解释：“在返回代码的同时，请解释一下<DialogPortal>和<DialogOverlay>在这个对话框组件里分别起什么作用？”

AI在接收到这些具体、上下文丰富的提示后，会更有针对性地调用MCP工具，获取最相关的组件源码和示例，组合成你需要的答案。

5.4 自定义与扩展思路

如果你有开发能力，这个开源项目还为你提供了自定义的可能性。

修改默认框架：如果你团队主要用Svelte，可以修改源码，将默认框架从react改为svelte，避免每次启动都要加参数。
添加私有组件库：项目的核心是从GitHub API获取数据。理论上，你可以修改数据获取层，让它指向你们公司内部GitLab或私有GitHub仓库中的、遵循shadcn/ui类似结构的组件库。这样，AI助手就能为你们的私有设计系统服务了。
增加新的工具：MCP协议允许你定义新的工具。例如，你可以增加一个validate_component_usage工具，让AI检查一段给定的代码是否遵循了你们团队使用shadcn组件的特定规范。

注意事项：网络与缓存问题
首次加载慢：首次启动或长时间未使用后，服务器需要从GitHub拉取数据并构建缓存，这可能会导致前几次请求响应较慢。这是正常现象，后续请求会很快。
缓存失效：如果你发现AI返回的代码不是最新的（例如，组件API已更新），可以在启动服务器时添加--no-cache参数强制刷新缓存，或者重启服务器（它会根据内置的缓存过期策略自动更新）。
GitHub API限制：即使有Token，也有5000次/小时的限制。对于极高频的团队使用，需要考虑搭建一个中间缓存代理，或者定期将仓库镜像到本地。

6. 常见问题排查与实战经验

在实际使用中，你可能会遇到一些问题。这里我整理了一份常见问题速查表，以及我踩过的一些坑。

6.1 连接与配置问题

问题现象	可能原因	解决方案
Claude Desktop显示MCP服务器“连接失败”或“错误”。	1.`npx`命令路径问题。 2. GitHub Token无效或未设置。 3. 网络问题，无法访问GitHub API。 4. 服务器启动参数错误。	1. 在Claude Desktop配置中使用`command`的绝对路径。 2. 检查Token是否过期，或在命令行中先用`npx ... --github-api-key TOKEN`测试。 3. 运行`curl -I https://api.github.com`测试网络。 4. 查看Claude Desktop日志获取具体错误信息。
AI助手没有显示shadcn相关的工具。	1. MCP服务器未成功连接。 2. 需要重新启动AI客户端。 3. 在某些客户端中，工具需要手动“激活”或通过特定指令调用。	1. 确认服务器状态为“已连接”。 2. 完全退出并重启Claude Desktop/Cursor。 3. 尝试在聊天中直接询问：“你现在可以使用哪些工具？”或“列出shadcn组件”。
使用SSE模式时，客户端无法连接到`http://localhost:7423/sse`。	1. 服务器未在SSE模式下运行。 2. 防火墙阻止了7423端口。 3. Docker容器端口映射错误。	1. 确保启动命令包含`--mode sse`或`MCP_TRANSPORT_MODE=sse`。 2. 检查服务器日志，确认正在监听端口。 3. 对于Docker，检查`docker-compose ps`和`docker port <container_id>`。
错误信息：`Rate limit exceeded`。	未提供GitHub Token，或Token已用尽速率限制。	务必提供有效的GitHub个人访问令牌。无Token的60次/小时限制极易触发。生成一个新Token即可。

6.2 使用与功能问题

问题现象	可能原因	解决方案
AI返回的代码是旧的，不是`shadcn/ui`最新版本的。	服务器缓存了旧数据。	1. 重启MCP服务器，缓存会在一段时间后过期更新。 2. 在启动命令中添加`--no-cache`参数（如果该参数存在）。 3. 手动删除服务器缓存目录（具体位置需查看服务器文档或源码）。
请求Svelte或Vue组件时，AI返回“未找到”或错误。	1. 服务器启动时未指定对应框架。 2. 该组件在目标框架的版本中可能名称不同或尚未实现。	1. 确认启动命令中包含`--framework svelte`或`--framework vue`。 2. 先让AI列出所有可用组件，确认目标组件是否存在。不同框架的组件实现进度可能有差异。
AI生成的代码缺少样式或导入语句。	MCP服务器主要提供组件逻辑代码和结构。`shadcn/ui`的样式需要额外安装和配置。	1. 确保你的项目已经按照`shadcn/ui`官方文档初始化了样式（如`globals.css`中引入了`@tailwind base;`等）。 2. AI生成的代码通常包含组件导入，但你可能需要手动安装底层依赖包，如`npm install @radix-ui/react-dialog`。可以提示AI：“请同时给出安装所需npm包的命令。”
在React项目中使用`--ui-library base`，但生成的组件样式很奇怪。	Base UI的样式体系与Radix UI不同。你的项目可能没有配置Base UI的主题。	如果你选择Base UI，需要按照`shadcn/ui`官方文档中关于Base UI的安装指南，额外配置主题提供商。AI可能不会自动处理这部分全局配置。

6.3 性能与优化

问题：感觉AI调用工具反应有点慢。
- 排查：这可能是网络问题（访问GitHub慢），也可能是AI模型本身处理速度的问题。首先，在服务器本地运行，测试直接请求一个组件（如果可以的话）的速度。其次，确保使用了GitHub Token，避免因限流导致的延迟。
问题：Docker容器占用了较多内存。
- 排查：这是正常的Node.js应用内存占用。你可以通过Docker Compose文件限制容器的资源：
```
services: shadcn-ui-mcp: ... deploy: resources: limits: memory: 512M # 限制最大内存为512MB reservations: memory: 256M # 预留256MB内存
```

6.4 我的实战经验与建议

Token是必选项，不是可选项：无Token的体验非常差，几乎无法正常使用。花2分钟生成一个Token，是开启顺畅体验的第一步。
为团队部署SSE服务器：即使只有两三个人，在内部网络部署一个SSE服务器也能带来巨大便利。大家共享缓存，减少重复的GitHub API请求，并且配置一次，处处可用。
明确你的主框架：虽然支持多框架很棒，但建议在启动服务器时固定一个主要使用的框架。频繁切换框架参数容易混淆，也可能导致缓存混乱。可以为每个框架部署独立的SSE实例。
将MCP服务器视为“知识源”而非“代码生成器”：它的最大价值在于提供准确、地道的代码片段。最终的组件集成、状态管理、业务逻辑串联，仍然需要你或AI根据具体项目上下文来完成。把它当作一个超级智能的、永不遗忘的代码片段库。
关注上游更新：shadcn/ui及其兄弟框架在快速迭代。关注Jpisnice/shadcn-ui-mcp-server这个项目的Release，及时更新到最新版本，以获取对新组件和新特性的支持。

这个工具的出现，标志着AI辅助开发正从“生成通用代码”向“生成符合特定项目上下文和最佳实践的代码”迈进。它缩小了AI能力与生产级代码需求之间的差距。虽然目前它围绕shadcn/ui生态，但其MCP协议的设计思路，为未来连接任何设计系统、内部组件库乃至API文档，都提供了一个清晰的蓝图。对于追求效率和代码质量的前端团队来说，现在就是开始尝试并构建自己AI工作流的最佳时机。