@szc-ft/mcp-szcd-client 0.34.2 → 0.38.0

package/qwen-extension/skills/shadcn-design-to-code/references/install-pitfalls.md

@@ -0,0 +1,526 @@
+# shadcn MCP 实测坑 + 审计清单
+
+> 2026-06-29 实测 shadcn 官方 MCP（`npx shadcn@latest mcp`）v1.0.0 在 Qwen Code stdio 模式下发现的问题
+> 必读：违反 = 报错或拿到错误数据
+
+## 坑 1：list/search 不传 `registries` 必报错
+
+**症状**：
+```json
+{
+  "result": {
+    "content": [{
+      "type": "text",
+      "text": "No registries are configured. Add registries to components.json (use get_project_registries to inspect) or pass them explicitly."
+    }]
+  }
+}
+```
+
+**根因**：
+`get_project_registries` 能从 `components.json` 隐式识别 `@shadcn` 默认 registry，但 `list_items_in_registries` / `search_items_in_registries` 不行——必须显式传 `registries: ["@shadcn"]`。
+
+**复现步骤**：
+```bash
+# ❌ 报错
+mcp__shadcn__list_items_in_registries(limit=10)
+# → "No registries are configured..."
+
+# ✅ 工作
+mcp__shadcn__list_items_in_registries(registries=["@shadcn"], limit=10)
+# → Found 363 items in registries @shadcn
+```
+
+**SKILL.md 工作流必须强制要求**：
+
+```python
+# 错误的工具调用
+mcp__shadcn__list_items_in_registries(limit=10)  # ❌
+
+# 正确的工具调用
+mcp__shadcn__list_items_in_registries(registries=["@shadcn"], limit=10)  # ✅
+
+# 搜索也一样
+mcp__shadcn__search_items_in_registries(query="dialog")  # ❌
+mcp__shadcn__search_items_in_registries(registries=["@shadcn"], query="dialog")  # ✅
+```
+
+**自动修复**（在 SKILL.md 步骤 4 头部加规则）：
+
+```
+对所有 mcp__shadcn__list_items_in_registries / search_items_in_registries 调用：
+- 必须显式传 registries: ["@shadcn"]（除非用户配置了其他 namespace）
+- 例外：get_project_registries 不需要
+```
+
+## 坑 2：view_items 只返回元信息，不返回源码
+
+**症状**：
+```json
+{
+  "result": {
+    "content": [{
+      "type": "text",
+      "text": "## dialog\n\n**Type:** registry:ui\n**Files:** 1 file(s)\n**Dependencies:** @radix-ui/react-dialog\n"
+    }]
+  }
+}
+```
+
+只有 3 行元信息：Type / Files / Dependencies。**没有组件源码、没有 Props、没有 variants、没有示例代码。**
+
+**根因**：
+shadcn 设计的预期是"view 拿元信息 → add 拿源码"两步走。view 是元数据查询工具，不是源码查询工具。
+
+**复现步骤**：
+```bash
+# ❌ 拿不到源码
+mcp__shadcn__view_items_in_registries(items=["@shadcn/dialog"])
+# → 只有 3 行元信息
+
+# ✅ 拿源码
+mcp__shadcn__get_add_command_for_items(items=["@shadcn/dialog"])
+# → "npx shadcn@latest add @shadcn/dialog"
+$ npx shadcn@latest add @shadcn/dialog
+# → 下载到 components/ui/dialog.tsx
+$ cat components/ui/dialog.tsx
+# → 完整源码
+```
+
+**正确的工作流**（4 步）：
+
+```
+1. mcp__shadcn__view_items_in_registries(items=["@shadcn/<name>"])
+   → 看 Type 判断是否合适（registry:ui 是组件，registry:example 是示例，registry:block 是完整 block）
+   → 看 Dependencies 知道要装什么
+
+2. mcp__shadcn__get_item_examples_from_registries(query="<name>-demo")
+   → 拿 demo 用法（参考，不直接复制到生产代码）
+
+3. mcp__shadcn__get_add_command_for_items(items=["@shadcn/<name>", ...])
+   → 拿 npx add 命令
+
+4. 本地执行 npx shadcn@latest add @shadcn/<name> ...
+   → 真实源码下载到 components/ui/<name>.tsx
+
+5. read_file 读 components/ui/<name>.tsx
+   → 拿真实 Props / variants / API
+```
+
+**反模式（浪费 token）**：
+
+```
+❌ 调 view_items 5 次想拿 5 个组件的源码
+   → 只拿到 5 份 3 行元信息，没有源码
+
+❌ 用 view_items 的输出当组件文档写代码
+   → 没有 Props 怎么写 <Button variant="?">？
+
+✅ 调 view_items 1 次拿元信息 → add → read_file → 真实 Props
+```
+
+## 坑 3：view_items 找不到某些组件（如 data-table）
+
+**症状**：
+```json
+{
+  "result": {
+    "content": [{
+      "type": "text",
+      "text": "Error (NOT_FOUND): The item at https://ui.shadcn.com/r/styles/new-york/data-table.json was not found.\n\n💡 Check if the item name is correct and the registry URL is accessible.\n\nContext: {\n  \"url\": \"https://ui.shadcn.com/r/styles/new-york/data-table.json\"\n}"
+    }]
+  }
+}
+```
+
+**根因**：
+- 一些组件（如 `data-table` / `chart`）在 `https://ui.shadcn.com/docs/components/<name>` 有文档
+- 但**不在** `https://ui.shadcn.com/r/styles/new-york/<name>.json` 这个 registry URL 中
+- view_items 走 registry URL，找不到就报 NOT_FOUND
+
+**修复**：
+- `data-table` 走 shadcn 官方文档 https://ui.shadcn.com/docs/components/data-table 复制代码
+- `chart` 同上 https://ui.shadcn.com/docs/components/chart
+- 一些特殊组件（block 的 dashboard-01）走 `@shadcn/dashboard-01`
+
+**已知"view_items 找不到但实际可用"清单**：
+- `data-table` → https://ui.shadcn.com/docs/components/data-table
+- `chart` → https://ui.shadcn.com/docs/components/chart
+- `breadcrumb` 部分版本
+- `sonner` 部分版本（可能要 `@shadcn/sonner` 而非 `@shadcn/toast`）
+
+## 坑 4：search_items 返回 `[object Promise]` 字段
+
+**症状**：
+```
+- button (registry:ui) [@shadcn] 
+  Add command: `[object Promise]`
+```
+
+**根因**：
+list_items / search_items 返回的列表项中，每项有一个"Add command"字段。但该字段的渲染在某些情况下是异步的，没等待 Promise resolve 就序列化了，显示为 `[object Promise]`。
+
+**影响**：
+不影响 list/search 的核心功能（你仍然能拿到组件清单），但**`Add command` 字段不可用**。
+
+**修复**：
+要拿 add 命令必须单独调 `get_add_command_for_items`，不能依赖 list/search 返回的字段。
+
+```python
+# ❌ 依赖 list 返回的 Add command
+items = list_items_in_registries(registries=["@shadcn"])
+for item in items:
+    cmd = item['add_command']  # "[object Promise]" 错的
+    run(cmd)  # 跑不了
+
+# ✅ 单独调 get_add_command_for_items
+add_cmd = get_add_command_for_items(items=["@shadcn/button", "@shadcn/card"])
+# → "npx shadcn@latest add @shadcn/button @shadcn/card"
+run(add_cmd)  # 正确
+```
+
+## 坑 5：跨 components.json 路径
+
+**症状**：
+shadcn MCP 通过 `process.cwd()` 找 `components.json`。如果 IDE 在 `~/projects/foo/` 启动，但 `components.json` 在 `~/projects/foo/app/`，MCP 找不到。
+
+**根因**：
+shadcn CLI 早期版本默认 `components.json` 在项目根，但 Next.js 项目可能放在子目录。
+
+**修复**：
+- 确保 `components.json` 在 `process.cwd()` 目录下
+- 或者用 `pnpm dlx shadcn@latest mcp init --client qwen` 让它自动初始化
+
+## 坑 6：npx 首次启动慢
+
+**症状**：
+第一次 `npx -y shadcn@latest mcp` 要 10-30 秒下载。
+
+**根因**：
+npx 每次都重新拉最新版本。
+
+**修复**：
+```json
+// .mcp.json 用固定版本，避免每次下载
+{
+  "mcpServers": {
+    "shadcn": {
+      "command": "npx",
+      "args": ["-y", "shadcn@1.0.0", "mcp"]  // 固定版本
+    }
+  }
+}
+```
+
+或全局安装：
+```bash
+npm install -g shadcn
+# .mcp.json
+{
+  "mcpServers": {
+    "shadcn": {
+      "command": "shadcn",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+---
+
+## 审计清单（来自 shadcn MCP `get_audit_checklist`）
+
+代码生成后必跑：
+
+```json
+{
+  "tool": "mcp__shadcn__get_audit_checklist",
+  "result": {
+    "checklist": [
+      "Ensure imports are correct i.e named vs default imports",
+      "If using next/image, ensure images.remotePatterns next.config.js is configured correctly.",
+      "Ensure all dependencies are installed.",
+      "Check for linting errors or warnings",
+      "Check for TypeScript errors",
+      "Use the Playwright MCP if available."
+    ]
+  }
+}
+```
+
+展开解读：
+
+### 1. Imports 检查
+
+shadcn 组件**都用 named imports**（不导出 default）：
+
+```tsx
+// ✅ 正确
+import { Button } from "@/components/ui/button"
+import { Card, CardHeader, CardContent, CardFooter } from "@/components/ui/card"
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@/components/ui/form"
+
+// ❌ 错误
+import Button from "@/components/ui/button"
+import * as Card from "@/components/ui/card"
+```
+
+### 2. next/image 配置
+
+如果用 shadcn 的 Avatar 等组件引用了 next/image 优化，需要在 `next.config.js` 配置：
+
+```js
+// next.config.js
+module.exports = {
+  images: {
+    remotePatterns: [
+      { protocol: "https", hostname: "images.unsplash.com" },
+      { protocol: "https", hostname: "avatars.githubusercontent.com" },
+    ],
+  },
+}
+```
+
+### 3. 依赖安装
+
+shadcn 装组件时**自动安装依赖**（从 `package.json` 读 deps）。但如果手动复制源码，需要：
+
+```bash
+# shadcn 装组件后会自动装这些（如果缺）
+npm install class-variance-authority clsx tailwind-merge
+npm install @radix-ui/react-slot @radix-ui/react-dialog @radix-ui/react-dropdown-menu ...
+npm install lucide-react
+```
+
+### 4. Lint 错误
+
+常见 lint 错误：
+
+```tsx
+// ❌ 错误：未使用的 import
+import { Card, CardTitle, CardDescription } from "@/components/ui/card"
+// 只用了 Card，其他未用
+
+// ❌ 错误：inline-style 写错
+<div style={{ color: red }}>  // 缺引号
+<div style={{ color: "red" }}>  // ✅
+
+// ❌ 错误：className 拼错
+<div className="bg-prmary">  // bg-primary
+<div className="bg-primary">  // ✅
+```
+
+### 5. TypeScript 错误
+
+常见 TS 错误：
+
+```tsx
+// ❌ 错误：Props 类型不匹配
+<Input type="email" value={123} onChange={() => {}} />
+// Input 期望 value: string
+
+// ❌ 错误：缺少必填 prop
+<FormField name="email" />  // 必须有 control prop
+
+// ❌ 错误：as 转换
+<Button asChild>  // 需要 Button 内部支持 asChild（cva variants）
+```
+
+### 6. Playwright MCP 验证（可选）
+
+如有 Playwright MCP server，跑 e2e 验证：
+- 点击所有按钮能触发 onClick
+- 切换 Tab 内容变化
+- 提交表单触发 onSubmit
+- Dialog 打开/关闭正常
+
+---
+
+## 实测有用的 3 个工具组合
+
+### 组合 1：浏览 + 安装
+
+```python
+# 列 50 个 UI 组件
+mcp__shadcn__list_items_in_registries(registries=["@shadcn"], types=["ui"], limit=50)
+# → 选 5 个要用的
+
+# 安装
+mcp__shadcn__get_add_command_for_items(items=[
+  "@shadcn/button", "@shadcn/card", "@shadcn/dialog", "@shadcn/form", "@shadcn/input"
+])
+# → "npx shadcn@latest add @shadcn/button @shadcn/card ..."
+```
+
+### 组合 2：搜索 + 拿 demo
+
+```python
+# 搜对话框
+mcp__shadcn__search_items_in_registries(registries=["@shadcn"], query="dialog")
+# → dialog, alert-dialog, dialog-demo, command-dialog, drawer-dialog
+
+# 拿 dialog 的 demo
+mcp__shadcn__get_item_examples_from_registries(registries=["@shadcn"], query="dialog-demo")
+# → 完整 demo 代码
+```
+
+### 组合 3：审计 + 修复
+
+```python
+# 跑审计
+mcp__shadcn__get_audit_checklist()
+# → 6 项清单
+
+# 检查 import 正确性（手动）
+# 跑 tsc / eslint
+# 跑 dev server 看是否启动
+```
+
+---
+
+## 经验沉淀（持续更新）
+
+### 经验 1：先装 block 再装组件
+
+如果 Sketch 是常见场景（Dashboard / 登录 / 定价），**优先装对应 block**：
+
+```bash
+# Dashboard
+npx shadcn@latest add @shadcn/dashboard-01
+# → 包含 sidebar + 4 stat + 2 chart + 1 table 全套
+
+# 登录
+npx shadcn@latest add @shadcn/login-01
+# → 居中表单 + 背景
+```
+
+block 装完后，按需修改其内部组件样式（直接改源码）。
+
+### 经验 2：types 过滤节省 token
+
+```python
+# 全量列（363 个，含 style / example / block / hook）
+list_items_in_registries(registries=["@shadcn"], limit=10)
+# → "index (registry:style) [@shadcn]" 等
+
+# 只列 UI 组件（~50 个，节省 90% token）
+list_items_in_registries(registries=["@shadcn"], types=["ui"], limit=50)
+# → 只列 button, card, dialog ...
+
+# 只列 example（找 demo 用）
+list_items_in_registries(registries=["@shadcn"], types=["example"], limit=20)
+```
+
+**types 枚举**：
+- `lib` - 工具库
+- `block` - 完整页面 block
+- `component` - 业务组件
+- `ui` - UI 基础组件
+- `hook` - React hooks
+- `page` - 完整页面
+- `file` - 单文件
+- `theme` - 主题
+- `style` - 样式文件
+- `item` - 通用
+- `base` - 基础
+- `font` - 字体
+
+### 经验 3：用 limit + offset 翻页
+
+363 个 item 一次拿不完：
+
+```python
+# 第 1 页
+list_items_in_registries(registries=["@shadcn"], limit=100)
+# → "More items available. Use offset: 100 to see the next page."
+
+# 第 2 页
+list_items_in_registries(registries=["@shadcn"], limit=100, offset=100)
+
+# 第 3 页
+list_items_in_registries(registries=["@shadcn"], limit=100, offset=200)
+# → 第 201-263 个（剩 63 个）
+
+# 第 4 页
+list_items_in_registries(registries=["@shadcn"], limit=100, offset=300)
+# → 第 301-363 个
+```
+
+实战中**不需要全量列**——按需 search 就够了：
+```python
+# 知道名字就直接 view
+view_items_in_registries(items=["@shadcn/button", "@shadcn/card"])
+
+# 不知道名字用 search
+search_items_in_registries(registries=["@shadcn"], query="chart")
+```
+
+### 经验 4：dark mode 配色落地
+
+shadcn 默认支持 dark mode。**注意：dark mode 不是组件特性，是 CSS 变量切换**。
+
+```tsx
+// 组件代码完全不变
+<Card>
+  <CardHeader>
+    <CardTitle>标题</CardTitle>
+  </CardHeader>
+</Card>
+
+// 切换 dark mode 只需要在 html 加 class="dark"
+<html className="dark">
+```
+
+落地时 **globals.css 必须写完整 dark 段**：
+
+```css
+:root {
+  --background: 0 0% 100%;
+  --foreground: 222.2 47.4% 11.2%;
+  /* ... */
+}
+
+.dark {
+  --background: 222.2 47.4% 11.2%;
+  --foreground: 210 40% 98%;
+  /* ... 暗色版 */
+}
+```
+
+如果从 Sketch 提取了 light 模式 token，**自动推导 dark 模式**：
+- 背景色：取反（白→深色）
+- 文字色：取反（深→浅色）
+- 边框色：取反
+- 品牌色：保持或微调
+
+### 经验 5：响应式断点策略
+
+shadcn 默认 Tailwind 断点：
+- `sm`: 640px
+- `md`: 768px
+- `lg`: 1024px
+- `xl`: 1280px
+- `2xl`: 1536px
+
+**Sketch 默认是桌面 1440px 宽**。从桌面推导响应式：
+
+```
+桌面 4 列 → mobile 1 列
+grid-cols-1 md:grid-cols-2 lg:grid-cols-4
+
+桌面 3 列 → mobile 1 列
+grid-cols-1 md:grid-cols-2 lg:grid-cols-3
+
+桌面 2 列 → mobile 1 列
+grid-cols-1 lg:grid-cols-2
+
+桌面 1 列 → 永远 1 列
+grid-cols-1
+```
+
+**移动端优先**写法（推荐）：
+```tsx
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+  {/* 移动端 1 列，平板 2 列，桌面 3 列 */}
+</div>
+```