@szc-ft/mcp-szcd-client 0.11.0

package/skill/SKILL.md

@@ -0,0 +1,897 @@
+---
+name: szcd-component-helper
+description: 帮助用户查询和了解 szcd 项目中的组件信息，包括 Cover 层组件、Wrapper 层组件、Ant Design 组件、ProComponents、ProPackages 以及复合组件。支持组件搜索、详情查询、使用示例搜索和文件读取。当用户需要了解 szcd 项目的组件结构、查看组件实现、寻找组件使用示例时，应使用此技能。它是一个前端组件库，全名"@szc-ft/szcd"。这是一个客户端 skill，通过 MCP 协议（SSE 或 HTTP）连接到远程 MCP 服务器。
+compatibility:
+  tools:
+    - web_search
+    - web_fetch
+    - run_command
+    - read
+    - write
+
+---
+
+# szcd 组件助手技能（客户端）
+
+## 概述
+
+此技能提供对 szcd 项目组件的查询和分析能力，帮助用户快速了解项目中的组件结构、实现细节和使用示例。
+
+**重要说明**：这是一个客户端 skill，通过 MCP 协议（SSE 或 HTTP）连接到远程 MCP 服务器。服务器由管理员维护，包含源码和数据。
+
+**版本**：v0.8.0 - 统一版本发布，包含 0.6.x 和 0.7.x 全部功能；新增设计稿图片分析工具（视觉代理/兜底方案），支持 OCR 降级和优先级控制；新增 .traecli agents 目录兼容
+
+## 架构说明
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    连接方式（三选一）                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  方式1: 本地直连 (stdio) — 推荐                              │
+│  ┌─────────────┐     stdio      ┌─────────────────────────┐│
+│  │   IDE/AI    │ ◄─────────────►│  szcd-mcp-server        ││
+│  │   Client    │                │  (本地运行)              ││
+│  └─────────────┘                └─────────────────────────┘│
+│                                                             │
+│  方式2: SSE 远程连接 — 推荐                                   │
+│  ┌─────────────┐     SSE       ┌─────────────────────────┐│
+│  │   IDE/AI    │ ◄────────────►│  MCP Server (SSE 模式)  ││
+│  │   Client    │  GET /sse     │  管理员机器              ││
+│  │             │  POST /message│  (源码 + 数据)           ││
+│  └─────────────┘               └─────────────────────────┘│
+│                                                             │
+│  方式2b: Streamable HTTP 远程连接（Trae CLI 兼容）           │
+│  ┌─────────────┐    HTTP      ┌─────────────────────────┐ │
+│  │   IDE/AI    │ ◄───────────►│  MCP Server (HTTP 模式) │ │
+│  │   Client    │  POST /mcp   │  管理员机器              │ │
+│  │             │              │  (源码 + 数据)           │ │
+│  └─────────────┘              └─────────────────────────┘ │
+│                                                             │
+│  方式3: 代理桥接 (向后兼容)                                   │
+│  ┌─────────────┐  stdio  ┌───────────┐  SSE/HTTP  ┌─────┐│
+│  │   IDE/AI    │◄───────►│mcp-proxy  │◄──────────►│Server││
+│  │   Client    │         │(桥接代理)  │            │     ││
+│  └─────────────┘         └───────────┘            └─────┘│
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 可用工具
+
+### 复合组件工具 (Other Components)
+
+#### 1. list_other_components
+**功能**：列出 `src/other/components/index.js` 中导出的复合组件与工具
+**参数**：无
+**返回**：复合组件列表
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool list_other_components' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请列出项目中的复合组件。
+```
+
+##### Qwen Code 调用示例
+```
+请列出项目中的复合组件。
+```
+
+#### 2. get_other_component
+**功能**：根据组件名获取实现路径、types、docs、透传目标与 props 列表
+**参数**：
+- `name` (string, required): 组件名称
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool get_other_component with name "Query"' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请获取Query组件的详细信息。
+```
+
+##### Qwen Code 调用示例
+```
+请获取Query组件的详细信息。
+```
+
+#### 3. search_component_examples
+**功能**：在仓库内搜索组件名的用法片段（md/js/ts/tsx）
+**参数**：
+- `name` (string, required): 组件名称
+- `maxResults` (number, optional, default: 20): 最大结果数，范围1-50
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool search_component_examples with name "TableOrList" maxResults 10' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请搜索TableOrList组件的使用示例，最多返回10个。
+```
+
+##### Qwen Code 调用示例
+```
+请搜索TableOrList组件的使用示例，最多返回10个。
+```
+
+### Cover层组件工具
+
+#### 4. list_cover_components
+**功能**：列出 src/components/cover/ 目录下的 Cover 层封装组件
+**参数**：无
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool list_cover_components' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请列出Cover层的封装组件。
+```
+
+##### Qwen Code 调用示例
+```
+请列出Cover层的封装组件。
+```
+
+#### 5. get_cover_component
+**功能**：获取 Cover 层组件的详细信息，包括实现路径、Props 定义、透传目标等
+**参数**：
+- `name` (string, required): 组件名称
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool get_cover_component with name "Button"' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请获取Cover层Button组件的详细信息。
+```
+
+##### Qwen Code 调用示例
+```
+请获取Cover层Button组件的详细信息。
+```
+
+### Wrapper层组件工具
+
+#### 6. list_wrapper_components
+**功能**：列出 src/components/wrappers/ 目录下的 Wrapper 层业务组件
+**参数**：无
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool list_wrapper_components' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请列出Wrapper层的业务组件。
+```
+
+##### Qwen Code 调用示例
+```
+请列出Wrapper层的业务组件。
+```
+
+### ProPackages组件工具
+
+#### 7. list_pro_package_components
+**功能**：列出 pro-packages/ 目录下的 ProPackages 组件封装
+**参数**：无
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool list_pro_package_components' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请列出ProPackages的组件封装。
+```
+
+##### Qwen Code 调用示例
+```
+请列出ProPackages的组件封装。
+```
+
+### Ant Design组件工具
+
+#### 8. list_antd_components
+**功能**：列出 Ant Design 组件的分类概览和各分类下的组件数量
+**参数**：无
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool list_antd_components' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请列出Ant Design组件的分类概览。
+```
+
+##### Qwen Code 调用示例
+```
+请列出Ant Design组件的分类概览。
+```
+
+#### 9. list_antd_components_by_category
+**功能**：按分类列出 Ant Design 组件
+**参数**：
+- `category` (enum, optional, default: "通用"): 组件分类，可选值：通用、布局、导航、数据录入、数据展示、反馈、其他
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool list_antd_components_by_category with category "数据录入"' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请按分类列出Ant Design的数据录入组件。
+```
+
+##### Qwen Code 调用示例
+```
+请按分类列出Ant Design的数据录入组件。
+```
+
+#### 10. get_antd_component
+**功能**：获取 Ant Design 组件的详细信息
+**参数**：
+- `name` (string, required): 组件名称
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool get_antd_component with name "Input"' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请获取Ant Design Input组件的详细信息。
+```
+
+##### Qwen Code 调用示例
+```
+请获取Ant Design Input组件的详细信息。
+```
+
+### ProComponents组件工具
+
+#### 11. list_pro_components
+**功能**：列出 ProComponents 组件的分类概览
+**参数**：无
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool list_pro_components' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请列出ProComponents的分类概览。
+```
+
+##### Qwen Code 调用示例
+```
+请列出ProComponents的分类概览。
+```
+
+#### 12. list_pro_components_by_category
+**功能**：按分类列出 ProComponents 组件
+**参数**：
+- `category` (enum, optional, default: "数据录入"): 组件分类，可选值：数据录入、数据展示、布局、反馈
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool list_pro_components_by_category with category "数据展示"' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请按分类列出ProComponents的数据展示组件。
+```
+
+##### Qwen Code 调用示例
+```
+请按分类列出ProComponents的数据展示组件。
+```
+
+#### 13. get_pro_component
+**功能**：获取 ProComponents 组件的详细信息
+**参数**：
+- `name` (string, required): 组件名称
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool get_pro_component with name "ProTable"' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请获取ProTable组件的详细信息。
+```
+
+##### Qwen Code 调用示例
+```
+请获取ProTable组件的详细信息。
+```
+
+### 全局功能工具
+
+#### 14. search_all_components
+**功能**：全局搜索所有层级的组件
+**参数**：
+- `keyword` (string, required): 搜索关键词
+- `type` (enum, optional): 按类型筛选，可选值：cover、wrapper、pro-package、antd、pro-components、other
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool search_all_components with keyword "form" type "pro-components"' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请搜索包含"form"的ProComponents组件。
+```
+
+##### Qwen Code 调用示例
+```
+请搜索包含"form"的ProComponents组件。
+```
+
+#### 15. get_component_library_overview
+**功能**：获取组件库的完整概览
+**参数**：无
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool get_component_library_overview' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请提供组件库的完整概览。
+```
+
+##### Qwen Code 调用示例
+```
+请提供组件库的完整概览。
+```
+
+### 文件操作工具
+
+#### 16. read_file
+**功能**：读取仓库内文件（相对路径）
+**参数**：
+- `path` (string, required): 文件相对路径
+- `maxChars` (number, optional, default: 20000): 最大字符数，范围200-200000
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool read_file with path "src/other/components/Query/index.tsx" maxChars 5000' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请读取src/other/components/Query/index.tsx文件内容，最多5000个字符。
+```
+
+##### Qwen Code 调用示例
+```
+请读取src/other/components/Query/index.tsx文件内容，最多5000个字符。
+```
+
+#### 17. get_accurate_component_doc
+**功能**：获取复合组件的准确Props文档，包含透传机制的详细说明
+**参数**：
+- `name` (string, required): 组件名称
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool get_accurate_component_doc with name "Query"' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请获取Query组件的准确文档，包含透传机制说明。
+```
+
+##### Qwen Code 调用示例
+```
+请获取Query组件的准确文档，包含透传机制说明。
+```
+
+### 缓存管理工具
+
+#### 18. refresh_component_docs
+**功能**：刷新 Ant Design / ProComponents 组件文档缓存
+**参数**：
+- `source` (enum, optional, default: "all"): 刷新来源，可选值：antd、pro-components、all
+
+##### Trae CLI 调用示例
+```bash
+trae -m 'Call MCP tool refresh_component_docs with source "all"' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请刷新所有组件文档缓存。
+```
+
+##### Qwen Code 调用示例
+```
+请刷新所有组件文档缓存。
+```
+
+### 设计稿图片分析工具（兜底/代理）
+
+> **核心定位**：此工具是**兜底机制**，专门解决"用户使用的 LLM 不支持图片理解"的问题。
+>
+> 当用户的 IDE/AI 是纯文本模型（无法直接看设计稿截图）时，由 MCP 服务器调用多模态模型代为"看图"，将图片内容转化为结构化文本返回给用户 LLM，让用户 LLM 基于文字描述生成代码。如果用户的 LLM 本身支持图片输入（如 Claude 4、GPT-4o），则**不需要**使用此工具。
+
+#### 19. analyze_design_image
+**功能**：分析UI设计稿图片，将视觉设计转化为结构化文本描述。支持三通道提取，追求设计稿样式的高度还原：
+
+- **通道1: ConfigProvider Token** — 对齐 tokenConfig.json 结构，精确提取全局 Token 和组件级 Token，自动对比 szcd 默认值生成 themeDiff，输出可直接使用的 `<ConfigProvider theme={...}>` 配置代码
+- **通道2: CSS 覆盖层** — 提取 ConfigProvider Token 无法覆盖的样式属性（布局、伪元素、间距、边框、动画、字体族等），生成组件级 CSS 覆盖代码
+- **通道3: 视觉细节** — 提取渐变色、滚动条、遮罩层、状态变体(hover/focus/active/disabled)等更细粒度的视觉信息，生成全局 CSS 覆盖代码
+
+**降级机制**：
+- 服务器上的多模态模型（Claude/OpenAI）不可用时，自动降级为本地 PaddleOCR 文字识别
+- OCR 降级模式下**不做任何组件推断**，仅返回识别到的原始文字，由用户 LLM 结合组件库 MCP 工具自行映射
+- 可通过环境变量 `DESIGN_ANALYSIS_ORDER` 控制执行顺序（见下方环境变量说明）
+
+**参数**：
+- `imageSource` (string, required): 图片数据：base64编码字符串、HTTP/HTTPS URL、或相对于项目根目录的文件路径
+- `sourceType` (enum, optional, default: "file_path"): 图片来源类型：base64、url、file_path
+
+> **远程连接场景下的图片传递方式说明**：
+> - 当通过 **SSE/HTTP 远程连接** MCP 服务器时，`file_path` 方式**不可用**，因为远端服务器无法访问客户端本地文件系统
+> - **推荐方式**：`base64` — 将图片转为 base64 字符串直接传入，不受网络隔离影响，任何连接方式都可用
+> - **可选方式**：`url` — 要求图片可通过公网 URL 访问
+> - **本地直连**：`file_path` — 仅在本地 stdio 直连模式下可用
+
+- `analysisType` (enum, optional, default: "full"): 分析类型：
+  - `layout` — 仅布局结构
+  - `components` — 布局+组件识别
+  - `tokens` — 布局+组件+样式Token（通道1）
+  - `full` — 完整分析，通道1+2
+  - `pixel_perfect` — 最高还原度，全部三通道+高分辨率+8K输出
+- `pageContext` (string, optional): 页面业务上下文描述
+- `targetLibrary` (enum, optional, default: "auto"): 期望匹配的组件库：szcd、antd、pro-components、auto
+- `outputFormat` (enum, optional, default: "markdown"): 输出格式：
+  - `markdown` — 适合直接阅读
+  - `json` — 适合程序化使用
+  - `structured_text` — 结构化文本
+  - `restoration_code` — 一键输出完整还原代码（ConfigProvider + 组件级CSS + 全局CSS + 还原度评分）
+
+**输出内容**（以 `full` 或 `pixel_perfect` 模式为例）：
+- 页面类型和布局结构
+- 组件识别和 szcd 组件匹配
+- **designTokens** — 对齐 tokenConfig.json 的全局 Token（色阶、字号阶梯、间距阶梯、圆角、阴影等）
+- **componentStyleTokens** — 每个组件的 componentToken（如 Table.rowHoverBg、Button.colorPrimary 等）
+- **themeDiff** — 与 szcd 默认值的差异对比 + 可直接粘贴的 ConfigProvider 代码
+- **cssOverrides** — 组件级 CSS 覆盖（布局、伪元素、间距、边框、动画、字体等 token 无法覆盖的属性）
+- **visualDetails** — 渐变、滚动条、遮罩、状态变体等视觉细节（仅 pixel_perfect 模式）
+- **fidelityScore** — 还原度评分（0-100），含 Token 覆盖率、CSS 覆盖补充率、未覆盖场景清单
+
+##### Trae CLI 调用示例
+```bash
+# 完整分析（通道1+2）
+trae -m 'Call MCP tool analyze_design_image with imageSource "docs/designs/user-list.png" sourceType "file_path" analysisType "full" pageContext "用户管理列表页" targetLibrary "szcd"' --tool-allowance '*:*'
+
+# 最高还原度（全部三通道）+ 一键输出还原代码
+trae -m 'Call MCP tool analyze_design_image with imageSource "docs/designs/user-list.png" sourceType "file_path" analysisType "pixel_perfect" outputFormat "restoration_code" pageContext "用户管理列表页" targetLibrary "szcd"' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请分析 docs/designs/user-list.png 这张设计稿，使用 pixel_perfect 模式，输出还原代码。
+```
+
+##### Qwen Code 调用示例
+```
+请分析 docs/designs/user-list.png 这张设计稿，识别页面布局和组件，匹配 szcd 组件库，使用 pixel_perfect 模式获取最高还原度。
+```
+
+### 样式注入指南工具
+
+#### 20. get_style_injection_guide
+**功能**：查询 szcd 复合组件的样式注入方法。返回指定组件的可用样式 props、注入方式（ModeStyle/TreeBoxStyle/btnStyle/inline style等）、代码示例，以及组件嵌套时的 CSS 穿透路径和智能分配策略。
+
+**适用场景**：
+- 已有设计稿分析结果但需要知道如何将 CSS 注入到组件中
+- 使用 Sketch/Figma MCP 获取了设计规范后需了解 szcd 组件的样式定制方式
+- 开发时需要快速查询某个组件支持哪些样式 props
+
+**参数**：
+- `componentNames` (string[], optional): 要查询的组件名列表，如 ['Query', 'TableOrList', 'LeftTree']。不传则返回所有复合组件的完整指南
+- `includeNesting` (boolean, optional, default: true): 是否包含嵌套注入指南（TemplateMode/ModelOrDrawer 容器场景的 CSS 穿透路径和分配策略）
+- `includeSmartDistribute` (boolean, optional, default: false): 是否包含智能 CSS 分配建议（需要传入 cssOverrides 参数）
+- `cssOverrides` (array, optional): CSS 覆盖列表（用于智能分配），格式与 analyze_design_image 返回的 cssOverrides.perComponent 一致
+- `outputFormat` (enum, optional, default: "markdown"): 输出格式：markdown、json、text
+
+**4种注入方式**：
+- `modeStyle`: ModeStyle prop → styled-components 注入（Query, TableOrList, LeftTree, TitleAndBack, TemplateMode, ModeAvatar）
+- `modeStyleTag`: ModeStyle prop → 动态 `<style>` 标签注入（ModelOrDrawer 专属）
+- `inlineOnly`: 仅 inline style / 全局 CSS（FormItemOrDetailItem, CustomOption, TreeNode）
+- `passthrough`: className/style prop 透传（IconfontWapper）
+
+**嵌套场景**：
+- TemplateMode 的 ModeStyle 可穿透到子组件（通过 `.leftContentBox` / `.rightContentBox_top` / `.rightContentBox_bottom` 定位）
+- ModelOrDrawer DOM 挂载在 document.body，父级穿不透
+
+##### Trae CLI 调用示例
+```bash
+# 查询单个组件
+trae -m 'Call MCP tool get_style_injection_guide with componentNames ["Query"]' --tool-allowance '*:*'
+
+# 查询多个组件含嵌套指南
+trae -m 'Call MCP tool get_style_injection_guide with componentNames ["TemplateMode", "Query", "TableOrList"] includeNesting true' --tool-allowance '*:*'
+
+# 智能 CSS 分配
+trae -m 'Call MCP tool get_style_injection_guide with componentNames ["TemplateMode", "Query"] includeSmartDistribute true cssOverrides [...]' --tool-allowance '*:*'
+```
+
+##### Claude Code 调用示例
+```
+请查询 Query 组件的样式注入方法。
+```
+
+##### Qwen Code 调用示例
+```
+请查询 TemplateMode 和 Query 组件的样式注入指南，包括嵌套场景。
+```
+
+## 安装方式
+
+### 通过 npm 安装
+
+```bash
+npm install @szc-ft/mcp-szcd-component-helper
+```
+
+安装后会自动：
+- 安装 MCP 代理脚本
+- 自动配置 skill 到 `~/.trae-cn/skills/szcd-component-helper/`
+- 创建配置文件模板 `~/.szcd-mcp-config.json`
+
+## 配置步骤
+
+### 步骤1：安装客户端包
+
+```bash
+npm install @szc-ft/mcp-szcd-component-helper
+```
+
+### 步骤2：配置服务器地址
+
+#### 方式1：使用配置文件（推荐）
+
+编辑配置文件 `~/.szcd-mcp-config.json`：
+
+```json
+{
+  "MCP_SERVER_URL": "http://localhost:3456",
+  "MCP_TIMEOUT": 30000,
+  "MCP_API_KEY": ""
+}
+```
+
+#### 方式2：使用环境变量
+
+```bash
+# Linux/macOS
+export MCP_SERVER_URL="http://localhost:3456"
+export MCP_TIMEOUT="30000"
+export MCP_API_KEY="your-api-key"
+
+# Windows (PowerShell)
+$env:MCP_SERVER_URL="http://localhost:3456"
+$env:MCP_TIMEOUT="30000"
+$env:MCP_API_KEY="your-api-key"
+
+# Windows (CMD)
+set MCP_SERVER_URL=http://localhost:3456
+set MCP_TIMEOUT=30000
+set MCP_API_KEY=your-api-key
+```
+
+#### 方式3：在 IDE 配置中设置
+
+**方式3a：使用代理桥接（向后兼容）**
+
+编辑您的 IDE 配置文件（如 `.trae/config.json` 或 Claude Code 配置）：
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "command": "npx",
+      "args": ["szcd-mcp-proxy"],
+      "env": {
+        "MCP_SERVER_URL": "http://localhost:3456",
+        "MCP_TIMEOUT": "30000",
+        "MCP_API_KEY": ""
+      }
+    }
+  }
+}
+```
+
+**方式3b：Trae CLI Streamable HTTP 直连（推荐）**
+
+在 `~/.trae/trae_cli.yaml` 中配置：
+
+```yaml
+mcp_servers:
+    - name: szcd-component-helper
+      url: http://localhost:3456/mcp
+      type: http
+```
+
+**方式3c：本地直连 stdio（推荐，无需远程服务器）**
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "command": "npx",
+      "args": ["szcd-mcp-server", "--stdio"]
+    }
+  }
+}
+```
+
+**方式3d：Qwen Code Streamable HTTP 直连（推荐）**
+
+在 `~/.qwen/settings.json` 中配置：
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "httpUrl": "http://localhost:3456/mcp",
+      "timeout": 30000
+    }
+  }
+}
+```
+
+**方式3e：Qwen Code 本地直连 stdio（推荐，无需远程服务器）**
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "command": "npx",
+      "args": ["szcd-mcp-server", "--stdio"]
+    }
+  }
+}
+```
+
+### 步骤3：验证配置
+
+运行以下命令验证配置是否正确：
+
+```bash
+# 测试服务器连接
+curl http://localhost:3456/health
+
+# 或使用代理脚本测试
+npx szcd-mcp-proxy --test
+```
+
+## 配置优先级
+
+地址获取的优先级顺序：
+
+1. **环境变量**（最高优先级）
+   - `MCP_SERVER_URL`
+   - `MCP_TIMEOUT`
+   - `MCP_API_KEY`
+
+2. **配置文件**（中等优先级）
+   - `~/.szcd-mcp-config.json`
+
+3. **默认值**（最低优先级）
+   - `MCP_SERVER_URL`: `http://localhost:3456`
+   - `MCP_TIMEOUT`: `30000`
+   - `MCP_API_KEY`: ``
+
+## 环境变量说明
+
+### MCP 连接配置
+
+| 变量 | 说明 | 默认值 | 示例 |
+|------|------|--------|------|
+| `MCP_SERVER_URL` | MCP 服务器地址 | `http://localhost:3456` | `http://192.168.1.100:3456` |
+| `MCP_TIMEOUT` | 请求超时时间(毫秒) | `30000` | `60000` |
+| `MCP_API_KEY` | MCP API 密钥（可选） | `` | `your-secret-key` |
+
+### 视觉模型配置（设计稿分析功能必需）
+
+| 变量 | 说明 | 默认值 | 示例 |
+|------|------|--------|------|
+| `VISION_API_KEY` | 视觉模型 API 密钥 | 读取 `ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY` | `sk-ant-...` |
+| `ANTHROPIC_API_KEY` | Claude API 密钥（当使用 Anthropic 时） | `` | `sk-ant-...` |
+| `OPENAI_API_KEY` | OpenAI API 密钥（当使用 OpenAI 时） | `` | `sk-...` |
+| `VISION_PROVIDER` | 视觉模型提供商 | `anthropic` | `anthropic` / `openai` |
+| `VISION_MODEL` | 视觉模型名称 | `claude-sonnet-4-6` | `gpt-4o` |
+| `VISION_API_URL` | 自定义视觉模型 API 地址 | 官方地址 | `https://api.anthropic.com/v1/messages` |
+| `DESIGN_ANALYSIS_ORDER` | 分析优先级：`vision_first` / `ocr_first` / `vision_only` / `ocr_only` | `vision_first` | `ocr_first` |
+| `OCR_SCRIPT_PATH` | 本地 OCR 脚本路径（降级用） | `/usr/local/bin/ocr-image` | `/usr/local/bin/ocr-image` |
+
+### 分析优先级说明
+
+| 值 | 行为 |
+|------|------|
+| `vision_first`（默认） | 先调用多模态模型，失败后降级到本地 OCR |
+| `ocr_first` | 先调用本地 OCR，识别不到文字再尝试多模态模型 |
+| `vision_only` | 只用多模态模型，失败直接报错 |
+| `ocr_only` | 只用本地 OCR，不调用多模态模型，返回原始文字 |
+
+## 使用流程
+
+1. **确定用户需求**：了解用户想要查询的组件信息或文件
+2. **Claude Code自动选择合适的MCP工具**：Claude Code会根据需求自动识别并调用对应的MCP工具
+3. **Claude Code自动连接MCP服务器**：Claude Code通过MCP协议连接到运行在MCP_SERVER_URL的服务器
+4. **MCP服务器执行查询**：服务器接收工具调用请求，执行相应的业务逻辑
+5. **返回结构化结果**：服务器返回JSON格式的结果，AI助手处理并呈现给用户
+
+## 注意事项
+
+- 所有路径都是相对于项目根目录的相对路径
+- 搜索示例时，结果可能会有重复或不相关的内容，需要用户自行筛选
+- 读取文件时，大文件可能会被截断，用户可以通过设置 maxChars 参数来调整
+- **需要确保 MCP 服务器正在运行，否则无法查询数据**
+- **服务器地址从环境变量或配置文件动态获取，无需硬编码**
+- **Claude Code会自动处理MCP协议通信，用户无需手动调用API**
+- **Qwen Code会自动处理MCP协议通信，用户无需手动调用API**
+- **设计稿分析功能需要配置视觉模型 API Key**，未配置时 analyze_design_image 工具会返回错误
+- **设计稿分析会调用外部多模态模型 API**，会产生额外费用（单张约 $0.03~0.05）
+- **设计稿分析结果会自动缓存 24 小时**，同一图片重复查询不会重复计费
+
+## 故障排除
+
+### 连接失败
+
+1. 检查服务器是否运行：`curl ${MCP_SERVER_URL}/health`
+2. 检查防火墙设置
+3. 检查网络连接
+4. 确认 `MCP_SERVER_URL` 配置正确
+5. 检查环境变量是否正确设置
+6. 检查配置文件 `~/.szcd-mcp-config.json` 是否存在
+
+### 配置文件问题
+
+1. 检查配置文件路径：`~/.szcd-mcp-config.json`
+2. 检查 JSON 格式是否正确
+3. 检查文件权限
+
+## 示例对话
+
+### 示例 1：获取组件库概览
+
+**用户**：szcd 组件库有哪些组件？
+**助手**：让我为您查询 szcd 组件库的完整概览。
+
+[助手自动触发MCP工具调用：get_component_library_overview()]
+
+**助手**：以下是 szcd 组件库的概览：
+- Cover 层封装组件：36 个 (路径: src/components/cover)
+- Wrapper 层业务组件：7 个 (路径: src/components/wrappers)
+- ProPackages 封装：8 个 (路径: pro-packages)
+- 复合业务组件：21 个 (路径: src/other/components)
+- Ant Design 官方组件：0 个 (需刷新缓存获取)
+- ProComponents 高级组件：0 个 (需刷新缓存获取)
+
+### 示例 2：搜索组件
+
+**用户**：搜索包含 "table" 的组件
+**助手**：让我在整个组件库中搜索包含 "table" 的组件。
+
+[助手自动触发MCP工具调用：search_all_components({"keyword": "table"})]
+
+**助手**：搜索到以下包含 "table" 的组件：
+- TableOrList（复合组件）
+- ProTable（ProComponents）
+- Table（Ant Design）
+
+### 示例 3：列出 Cover 层组件
+
+**用户**：Cover 层有哪些组件？
+**助手**：让我查询 Cover 层的组件列表。
+
+[助手自动触发MCP工具调用：list_cover_components()]
+
+**助手**：Cover 层有以下组件：
+- Button
+- Input
+- Select
+- DatePicker
+...
+
+### 示例 4：获取 Ant Design 组件信息
+
+**用户**：Ant Design 的 Table 组件有哪些 Props？
+**助手**：让我查询 Ant Design Table 组件的详细信息。
+
+[助手自动触发MCP工具调用：get_antd_component({"name": "Table"})]
+
+**助手**：Ant Design Table 组件的详细信息如下：
+- 中文名：表格
+- 描述：展示行列数据
+- 主要 Props：dataSource、columns、pagination、loading...
+
+### 示例 5：列出复合组件
+
+**用户**：列出项目中的复合组件
+**助手**：让我使用 list_other_components 工具来查询项目中的复合组件。
+
+[助手自动触发MCP工具调用：list_other_components()]
+
+**助手**：以下是 szcd 项目中的复合组件列表：
+- Query
+- TableOrList
+- TitleAndBack
+- LeftTree
+
+这些组件都在 src/other/components/index.js 中导出。
+
+### 示例 6：获取组件详情
+
+**用户**：获取 Query 组件的详情
+**助手**：让我使用 get_other_component 工具来获取 Query 组件的详细信息。
+
+[助手自动触发MCP工具调用：get_other_component({"name": "Query"})]
+
+**助手**：Query 组件的详细信息如下：
+- 实现文件：src/other/components/Query/index.tsx
+- 文档文件：src/other/components/Query/Query.md
+- 导出位置：src/other/components/index.js
+
+### 示例 7：搜索组件示例
+
+**用户**：搜索 TableOrList 组件的使用示例
+**助手**：让我使用 search_component_examples 工具来搜索 TableOrList 组件的使用示例。
+
+[助手自动触发MCP工具调用：search_component_examples({"name": "TableOrList", "maxResults": 10})]
+
+**助手**：以下是 TableOrList 组件的使用示例：
+1. 文件：src/anyMd/TableOrList.json - 包含组件配置信息
+2. 文件：src/anyMd/TableOrList.txt - 包含组件描述信息
+
+### 示例 8：读取文件内容
+
+**用户**：查看 Query 组件的实现代码
+**助手**：让我使用 read_file 工具来读取 Query 组件的实现文件。
+
+[助手自动触发MCP工具调用：read_file({"path": "src/other/components/Query/index.tsx"})]
+
+**助手**：Query 组件的实现代码如下：
+```tsx
+// 这里显示 src/other/components/Query/index.tsx 的内容
+```
+
+## Claude Code与MCP服务交互详解
+
+当用户提出需求时，Claude Code会：
+
+1. **理解用户意图**：分析用户想要获取的信息类型
+2. **选择适当工具**：从MCP服务器提供的工具中选择最合适的
+3. **构建参数**：根据用户输入构建工具调用所需的参数
+4. **发起MCP调用**：通过MCP协议发送工具调用请求到服务器
+5. **处理响应**：接收服务器返回的JSON格式结果
+6. **格式化输出**：将结果以易读的方式呈现给用户