mcp-szcd-component-helper 0.1.0

package/README.md

@@ -0,0 +1,211 @@
+# MCP Client：szcd 组件库检索助手（客户端）
+
+这是一个 MCP 客户端包，用于连接到远程 MCP 服务器，帮助 AI 智能体查询和分析 szcd 组件库。
+
+## 架构说明
+
+```
+┌─────────────────┐         HTTP         ┌─────────────────┐
+│  同事的机器      │ ◄──────────────────► │  您的机器        │
+│                 │                      │                 │
+│  npm install    │                      │  MCP Server     │
+│  (客户端包)      │                      │  (源码 + 数据)   │
+│                 │                      │                 │
+│  - mcp-proxy    │                      │  - server.js    │
+│  - skill        │                      │  - 组件源码      │
+└─────────────────┘                      └─────────────────┘
+```
+
+**关键点**：
+- 您在本地启动 MCP server（包含源码和数据）
+- 同事通过 npm install 获得客户端包（代理 + skill）
+- 客户端通过 HTTP 连接到您的服务器
+
+## 安装方式
+
+### 对于同事（客户端安装）
+
+```bash
+npm install @szc-ft/mcp-szcd-component-helper
+```
+
+安装后会自动：
+- 安装 MCP 代理脚本
+- 自动配置 skill 到 `~/.trae-cn/skills/szcd-component-helper/`
+
+### 对于您（服务器端）
+
+在您的机器上启动 MCP server：
+
+```bash
+cd mcp/szcd-component-helper
+npm run start:http
+```
+
+服务器默认运行在 http://10.2.16.41:3000
+
+## 配置步骤
+
+### 步骤1：启动服务器（您）
+
+```bash
+cd mcp/szcd-component-helper
+npm run start:http
+```
+
+或指定端口和绑定地址：
+
+```bash
+node src/server.js --http --port=3000 --bind=0.0.0.0
+```
+
+### 步骤2：同事安装客户端包
+
+```bash
+npm install @szc-ft/mcp-szcd-component-helper
+```
+
+### 步骤3：同事配置 IDE/智能体客户端
+
+#### 方式1：通过配置文件（推荐）
+
+编辑您的 IDE 配置文件（如 `.trae/config.json` 或 Claude Code 配置）：
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "command": "npx",
+      "args": ["szcd-mcp-proxy"],
+      "env": {
+        "MCP_SERVER_URL": "http://10.2.16.41:3000"
+      }
+    }
+  }
+}
+```
+
+#### 方式2：通过环境变量
+
+```bash
+export MCP_SERVER_URL="http://10.2.16.41:3000"
+```
+
+然后在配置中使用：
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "command": "npx",
+      "args": ["szcd-mcp-proxy"]
+    }
+  }
+}
+```
+
+## 环境变量说明
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `MCP_SERVER_URL` | MCP 服务器地址 | `http://10.2.16.41:3000` |
+| `MCP_TIMEOUT` | 请求超时时间(毫秒) | `30000` |
+
+## Skill 使用
+
+安装 npm 包后，skill 会自动配置到您的系统中。您可以直接在 IDE 中使用：
+
+```
+用户：szcd 项目中有哪些复合组件？
+助手：我将使用 szcd-component-helper skill 来查询项目中的复合组件。
+```
+
+## MCP 工具列表
+
+- `list_other_components`：列出 `src/other/components/index.js` 导出的组件/工具
+- `get_other_component`：获取某组件的实现路径、types、docs、透传目标与 props 列表（若可解析）
+- `search_component_examples`：在仓库内搜索组件名的用法片段
+- `read_file`：读取仓库内文件（相对路径）
+
+## 服务器部署建议
+
+### 局域网部署
+
+1. **启动 HTTP 服务**：
+   ```bash
+   cd mcp/szcd-component-helper
+   npm run start:http
+   ```
+
+2. **防火墙配置**：
+   - Windows：允许端口 3000 通过防火墙
+   - Linux：`sudo ufw allow 3000`
+
+3. **访问测试**：
+   - 本地测试：`curl http://localhost:3000/health`
+   - 局域网测试：`curl http://<服务器IP>:3000/health`
+
+### 安全建议
+
+1. **使用 API Key**（可选）：
+   ```bash
+   MCP_API_KEY=your-secret-key node src/server.js --http
+   ```
+
+   然后同事在配置中添加：
+   ```json
+   {
+     "env": {
+       "MCP_SERVER_URL": "http://10.2.16.41:3000",
+       "MCP_API_KEY": "your-secret-key"
+     }
+   }
+   ```
+
+2. **限制访问**：
+   - 使用防火墙规则限制访问 IP
+   - 使用 VPN 或内网访问
+
+## 推荐工作流（智能体）
+
+1. `list_other_components` 看有哪些复合组件
+2. `get_other_component` 获取组件实现与 docs/types
+3. `read_file` 打开 `index.tsx/types.ts/*.md`，确认"封装层 props + 透传 props"边界
+4. `search_component_examples` 找到 demo/测试里真实可用的写法
+5. 生成最终业务代码，并引用来源路径（方便人类复核）
+
+## 发布说明
+
+### 发布到 npm
+
+```bash
+cd mcp/szcd-component-helper
+npm login
+npm publish --access public
+```
+
+### 版本更新
+
+```bash
+npm version patch  # 或 minor, major
+npm publish
+```
+
+## 故障排除
+
+### 连接失败
+
+1. 检查服务器是否运行：`curl http://<服务器IP>:3000/health`
+2. 检查防火墙设置
+3. 检查网络连接
+4. 确认 `MCP_SERVER_URL` 配置正确
+
+### Skill 未生效
+
+1. 检查 skill 文件是否存在：`~/.trae-cn/skills/szcd-component-helper/SKILL.md`
+2. 重启 IDE
+3. 检查 IDE 配置文件格式是否正确
+
+## 许可证
+
+MIT

package/mcp-proxy.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+import http from "node:http";
+import https from "node:https";
+import readline from "node:readline";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+// 获取配置文件路径
+function getConfigFilePath() {
+    const platform = os.platform();
+    if (platform === 'win32') {
+        return path.join(process.env.USERPROFILE || process.env.HOME, '.szcd-mcp-config.json');
+    } else {
+        return path.join(process.env.HOME || os.homedir(), '.szcd-mcp-config.json');
+    }
+}
+
+// 从配置文件读取配置
+function loadConfigFromFile() {
+    const configPath = getConfigFilePath();
+    try {
+        if (fs.existsSync(configPath)) {
+            const content = fs.readFileSync(configPath, 'utf8');
+            return JSON.parse(content);
+        }
+    } catch (error) {
+        // 配置文件读取失败，使用默认值
+    }
+    return {};
+}
+
+// 加载配置
+const fileConfig = loadConfigFromFile();
+
+// 配置优先级：环境变量 > 配置文件 > 默认值
+const SERVER_URL = process.env.MCP_SERVER_URL || fileConfig.MCP_SERVER_URL || "http://10.2.16.41:3000";
+const SERVER_TIMEOUT = parseInt(process.env.MCP_TIMEOUT || fileConfig.MCP_TIMEOUT || "30000", 10);
+const SERVER_API_KEY = process.env.MCP_API_KEY || fileConfig.MCP_API_KEY || "";
+
+// 调试日志
+const debugLog = fs.createWriteStream("E:\\work\\szcd\\mcp_debug.log", { flags: "a" });
+function log(msg) {
+    debugLog.write(`[${new Date().toISOString()}] ${msg}\n`);
+}
+
+log(`Server URL: ${SERVER_URL}`);
+log(`Timeout: ${SERVER_TIMEOUT}`);
+log(`API Key: ${SERVER_API_KEY ? 'set' : 'not set'}`);
+
+// 使用 readline 处理行输入，比手动处理 buffer 更稳健
+const rl = readline.createInterface({
+    input: process.stdin,
+    terminal: false
+});
+
+rl.on("line", async (line) => {
+    if (!line.trim()) return;
+
+    log(`Received stdin: ${line}`);
+
+    let msgId = null;
+    try {
+        const msg = JSON.parse(line);
+        msgId = msg.id ?? null;
+
+        const response = await forwardToHttp(msg);
+        
+        // 构造一个绝对纯净的 JSON-RPC 响应对象
+        // 防止上游返回多余的字段（如 method）导致 IDE 误判为 Request
+        const cleanResponse = {
+            jsonrpc: "2.0",
+            id: msgId
+        };
+
+        if (response.error) {
+            cleanResponse.error = response.error;
+        } else {
+            // result 字段是必须的，即使是 null (对于成功响应)
+            cleanResponse.result = response.result !== undefined ? response.result : null;
+        }
+
+        const output = JSON.stringify(cleanResponse);
+        log(`Sending stdout: ${output}`);
+        process.stdout.write(output + "\n");
+    } catch (e) {
+        log(`Error: ${e.message}`);
+        // 只有在真的发生处理错误时才返回错误响应
+        // 注意：forwardToHttp 内部已经处理了 HTTP 错误并返回了 JSON-RPC 错误对象
+        // 所以这里的 catch 主要是捕获 JSON.parse 错误或代码逻辑错误
+        process.stdout.write(
+            JSON.stringify({
+                jsonrpc: "2.0",
+                id: msgId,
+                error: { code: -32603, message: `Internal proxy error: ${e.message}` },
+            }) + "\n"
+        );
+    }
+});
+
+async function forwardToHttp(msg) {
+    return new Promise((resolve, reject) => {
+        let path = "/";
+        let method = "GET";
+        let postData = "";
+
+        if (msg.method === "initialize" || msg.method === "ping") {
+            path = "/health";
+            method = "GET";
+        } else if (msg.method === "tools/list") {
+            path = "/tools/list";
+            method = "GET";
+        } else if (msg.method === "tools/call") {
+            path = "/tools/call";
+            method = "POST";
+            postData = JSON.stringify(msg.params || {});
+        } else {
+            resolve({
+                jsonrpc: "2.0",
+                id: msg.id ?? null,
+                error: { code: -32601, message: "Method not found", data: { method: msg.method } },
+            });
+            return;
+        }
+
+        const url = new URL(SERVER_URL);
+        const headers = {};
+        if (method === "POST") {
+            headers["Content-Type"] = "application/json";
+        }
+        if (SERVER_API_KEY) {
+            headers["X-API-Key"] = SERVER_API_KEY;
+            headers.Authorization = `Bearer ${SERVER_API_KEY}`;
+        }
+
+        const isHttps = url.protocol === "https:";
+        const requestImpl = isHttps ? https : http;
+
+        const options = {
+            hostname: url.hostname,
+            port: url.port || (isHttps ? 443 : 3000),
+            path: path,
+            method: method,
+            headers,
+            timeout: SERVER_TIMEOUT,
+            rejectUnauthorized: false, // 忽略 SSL 错误，防止自签名证书导致连接失败
+        };
+
+        const req = requestImpl.request(options, (res) => {
+            let data = "";
+            res.on("data", (chunk) => (data += chunk));
+            res.on("end", () => {
+                try {
+                    // 如果服务器返回非 JSON (例如 502 Bad Gateway HTML)，这里会抛错
+                    const parsed = JSON.parse(data);
+
+                    // 特殊处理 initialize，因为我们需要注入 capabilities
+                    if (msg.method === "initialize") {
+                        resolve({
+                            jsonrpc: "2.0",
+                            id: msg.id ?? null,
+                            result: {
+                                protocolVersion: "2024-11-05",
+                                serverInfo: { name: "mcp-szcd-component-helper-proxy", version: "0.0.1" },
+                                capabilities: { tools: {} },
+                            },
+                        });
+                    } else if (msg.method === "ping") {
+                        resolve({ jsonrpc: "2.0", id: msg.id ?? null, result: {} });
+                    } else {
+                        // 对于 tools/list 和 tools/call，直接返回解析后的结果
+                        // ID 修正会在外层进行
+                        resolve(parsed);
+                    }
+                } catch (e) {
+                    // 如果 JSON 解析失败，说明服务器返回了垃圾数据（可能是 HTML 错误页）
+                    resolve({
+                        jsonrpc: "2.0",
+                        id: msg.id ?? null,
+                        error: { 
+                            code: -32000, 
+                            message: `Server returned invalid JSON. Status: ${res.statusCode}. Raw body: ${data.slice(0, 100)}` 
+                        }
+                    });
+                }
+            });
+        });
+
+        req.on("error", (e) => {
+            resolve({
+                jsonrpc: "2.0",
+                id: msg.id ?? null,
+                error: { code: -32000, message: `HTTP request failed: ${e.message}` }
+            });
+        });
+
+        req.on("timeout", () => {
+            req.destroy();
+            resolve({
+                jsonrpc: "2.0",
+                id: msg.id ?? null,
+                error: { code: -32000, message: "Request timeout" }
+            });
+        });
+
+        if (postData) {
+            req.write(postData);
+        }
+        req.end();
+    });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "mcp-szcd-component-helper",
+    "version": "0.1.0",
+    "description": "MCP client for szcd component library - connects to remote MCP server",
+    "keywords": [
+        "mcp",
+        "szcd",
+        "component",
+        "ai",
+        "agent",
+        "claude",
+        "skill",
+        "proxy"
+    ],
+    "author": "szc-ft",
+    "license": "MIT",
+    "type": "module",
+    "main": "mcp-proxy.js",
+    "bin": {
+        "szcd-mcp-proxy": "mcp-proxy.js"
+    },
+    "files": [
+        "mcp-proxy.js",
+        "skill/",
+        "scripts/",
+        "README.md"
+    ],
+    "engines": {
+        "node": ">=18"
+    },
+    "scripts": {
+        "postinstall": "node scripts/postinstall.js"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/szc-ft/szcd.git",
+        "directory": "mcp/szcd-component-helper"
+    },
+    "bugs": {
+        "url": "https://github.com/szc-ft/szcd/issues"
+    },
+    "homepage": "https://github.com/szc-ft/szcd#readme"
+}

package/scripts/postinstall.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const SKILL_SOURCE = path.join(PACKAGE_ROOT, 'skill', 'SKILL.md');
+const CONFIG_TEMPLATE = path.join(PACKAGE_ROOT, 'config.template.json');
+
+// 默认的 MCP 服务器地址
+const DEFAULT_MCP_SERVER_URL = 'http://10.2.16.41:3000';
+
+// 获取用户的 skills 目录路径
+function getSkillsDirectory() {
+    const platform = os.platform();
+    let skillsDir;
+    
+    if (platform === 'win32') {
+        // Windows: C:\Users\<username>\.trae-cn\skills
+        skillsDir = path.join(process.env.USERPROFILE || process.env.HOME, '.trae-cn', 'skills');
+    } else {
+        // macOS/Linux: ~/.trae-cn/skills
+        skillsDir = path.join(process.env.HOME || os.homedir(), '.trae-cn', 'skills');
+    }
+    
+    return skillsDir;
+}
+
+// 获取用户的配置文件路径
+function getConfigFilePath() {
+    const platform = os.platform();
+    let configDir;
+    
+    if (platform === 'win32') {
+        // Windows: C:\Users\<username>\.szcd-mcp-config.json
+        configDir = path.join(process.env.USERPROFILE || process.env.HOME, '.szcd-mcp-config.json');
+    } else {
+        // macOS/Linux: ~/.szcd-mcp-config.json
+        configDir = path.join(process.env.HOME || os.homedir(), '.szcd-mcp-config.json');
+    }
+    
+    return configDir;
+}
+
+// 确保 skills 目录存在
+function ensureSkillsDirectory(skillsDir) {
+    if (!fs.existsSync(skillsDir)) {
+        fs.mkdirSync(skillsDir, { recursive: true });
+        console.log(`✓ Created skills directory: ${skillsDir}`);
+    }
+}
+
+// 复制 skill 文件
+function copySkillFile(skillsDir) {
+    const skillName = 'szcd-component-helper';
+    const skillDir = path.join(skillsDir, skillName);
+    
+    // 创建 skill 目录
+    if (!fs.existsSync(skillDir)) {
+        fs.mkdirSync(skillDir, { recursive: true });
+        console.log(`✓ Created skill directory: ${skillDir}`);
+    }
+    
+    // 复制 SKILL.md 文件
+    const skillDest = path.join(skillDir, 'SKILL.md');
+    if (fs.existsSync(SKILL_SOURCE)) {
+        fs.copyFileSync(SKILL_SOURCE, skillDest);
+        console.log(`✓ Copied skill file to: ${skillDest}`);
+    } else {
+        console.warn(`⚠ Skill source file not found: ${SKILL_SOURCE}`);
+    }
+}
+
+// 创建配置文件模板
+function createConfigTemplate() {
+    const configPath = getConfigFilePath();
+    
+    // 如果配置文件已存在，不覆盖
+    if (fs.existsSync(configPath)) {
+        console.log(`✓ Config file already exists: ${configPath}`);
+        console.log(`  To update, edit the file manually or delete it and reinstall`);
+        return;
+    }
+    
+    // 创建配置文件
+    const configContent = {
+        MCP_SERVER_URL: DEFAULT_MCP_SERVER_URL,
+        MCP_TIMEOUT: 30000,
+        MCP_API_KEY: "",
+        _comment: "请修改 MCP_SERVER_URL 为您的 MCP 服务器地址"
+    };
+    
+    try {
+        fs.writeFileSync(configPath, JSON.stringify(configContent, null, 2));
+        console.log(`✓ Created config template: ${configPath}`);
+        console.log(`  Please edit this file to set your MCP server URL`);
+    } catch (error) {
+        console.warn(`⚠ Failed to create config file: ${error.message}`);
+    }
+}
+
+// 显示安装成功信息
+function showSuccessMessage() {
+    const configPath = getConfigFilePath();
+    
+    console.log('\n' + '='.repeat(70));
+    console.log('  szcd-component-helper MCP Client Installed!');
+    console.log('='.repeat(70));
+    console.log('\n📦 Package: @szc-ft/mcp-szcd-component-helper');
+    console.log('\n🔗 This is a CLIENT package that connects to a remote MCP server.');
+    console.log('\n📚 Skill Location:');
+    console.log(`   ${path.join(getSkillsDirectory(), 'szcd-component-helper', 'SKILL.md')}`);
+    console.log('\n⚙️  Configuration:');
+    console.log('\n   1. Config file created:');
+    console.log(`      ${configPath}`);
+    console.log('\n   2. Edit the config file to set your MCP server URL:');
+    console.log(`      "MCP_SERVER_URL": "http://YOUR_SERVER_IP:3000"`);
+    console.log('\n   3. Or set environment variables:');
+    console.log('      export MCP_SERVER_URL="http://YOUR_SERVER_IP:3000"');
+    console.log('\n   4. Configure your IDE/agent client:');
+    console.log('\n   For Claude Code / Trae IDE:');
+    console.log('   {');
+    console.log('     "mcpServers": {');
+    console.log('       "szcd-component-helper": {');
+    console.log('         "command": "npx",');
+    console.log('         "args": ["szcd-mcp-proxy"],');
+    console.log('         "env": {');
+    console.log(`           "MCP_SERVER_URL": "${DEFAULT_MCP_SERVER_URL}"`);
+    console.log('         }');
+    console.log('       }');
+    console.log('     }');
+    console.log('   }');
+    console.log('\n💡 Configuration Priority:');
+    console.log('   1. Environment variables (highest priority)');
+    console.log('   2. Config file (~/.szcd-mcp-config.json)');
+    console.log('   3. Default values (lowest priority)');
+    console.log('\n🌐 Default Server:');
+    console.log(`   ${DEFAULT_MCP_SERVER_URL}`);
+    console.log('   Contact your admin for the correct server URL');
+    console.log('\n📖 Documentation:');
+    console.log('   https://github.com/szc-ft/szcd#readme');
+    console.log('\n' + '='.repeat(70) + '\n');
+}
+
+// 主函数
+function main() {
+    try {
+        console.log('\n🔧 Setting up szcd-component-helper client...\n');
+        
+        const skillsDir = getSkillsDirectory();
+        ensureSkillsDirectory(skillsDir);
+        copySkillFile(skillsDir);
+        createConfigTemplate();
+        showSuccessMessage();
+        
+    } catch (error) {
+        console.error('❌ Error during installation:', error.message);
+        console.error('Please report this issue at: https://github.com/szc-ft/szcd/issues');
+        process.exit(1);
+    }
+}
+
+main();

package/skill/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: szcd-component-helper
+description: 帮助用户查询和了解 szcd 项目中的组件信息，包括列出复合组件、获取组件详情、搜索组件示例和读取项目文件。当用户需要了解 szcd 项目的组件结构、查看组件实现、寻找组件使用示例时，应使用此技能。它是一个前端组件库，全名"@szc-ft/szcd"。这是一个客户端 skill，通过 HTTP 连接到远程 MCP 服务器。
+compatibility:
+  tools:
+    - web_search
+    - web_fetch
+    - run_command
+    - read
+    - write
+
+---
+
+# szcd 组件助手技能（客户端）
+
+## 概述
+
+此技能提供对 szcd 项目组件的查询和分析能力，帮助用户快速了解项目中的组件结构、实现细节和使用示例。
+
+**重要说明**：这是一个客户端 skill，通过 HTTP 连接到远程 MCP 服务器。服务器由管理员维护，包含源码和数据。
+
+## 架构说明
+
+```
+┌─────────────────┐         HTTP         ┌─────────────────┐
+│  您的机器        │ ◄──────────────────► │  管理员机器      │
+│                 │                      │                 │
+│  npm install    │                      │  MCP Server     │
+│  (客户端包)      │                      │  (源码 + 数据)   │
+│                 │                      │                 │
+│  - mcp-proxy    │                      │  - server.js    │
+│  - skill        │                      │  - 组件源码      │
+└─────────────────┘                      └─────────────────┘
+```
+
+## 安装方式
+
+### 通过 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://10.2.16.41:3000",
+  "MCP_TIMEOUT": 30000,
+  "MCP_API_KEY": ""
+}
+```
+
+#### 方式2：使用环境变量
+
+```bash
+# Linux/macOS
+export MCP_SERVER_URL="http://10.2.16.41:3000"
+export MCP_TIMEOUT="30000"
+export MCP_API_KEY="your-api-key"
+
+# Windows (PowerShell)
+$env:MCP_SERVER_URL="http://10.2.16.41:3000"
+$env:MCP_TIMEOUT="30000"
+$env:MCP_API_KEY="your-api-key"
+
+# Windows (CMD)
+set MCP_SERVER_URL=http://10.2.16.41:3000
+set MCP_TIMEOUT=30000
+set MCP_API_KEY=your-api-key
+```
+
+#### 方式3：在 IDE 配置中设置
+
+编辑您的 IDE 配置文件（如 `.trae/config.json` 或 Claude Code 配置）：
+
+```json
+{
+  "mcpServers": {
+    "szcd-component-helper": {
+      "command": "npx",
+      "args": ["szcd-mcp-proxy"],
+      "env": {
+        "MCP_SERVER_URL": "http://10.2.16.41:3000",
+        "MCP_TIMEOUT": "30000",
+        "MCP_API_KEY": ""
+      }
+    }
+  }
+}
+```
+
+### 步骤3：验证配置
+
+运行以下命令验证配置是否正确：
+
+```bash
+# 测试服务器连接
+curl http://10.2.16.41:3000/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://10.2.16.41:3000`
+   - `MCP_TIMEOUT`: `30000`
+   - `MCP_API_KEY`: ``
+
+## 环境变量说明
+
+| 变量 | 说明 | 默认值 | 示例 |
+|------|------|--------|------|
+| `MCP_SERVER_URL` | MCP 服务器地址 | `http://10.2.16.41:3000` | `http://192.168.1.100:3000` |
+| `MCP_TIMEOUT` | 请求超时时间(毫秒) | `30000` | `60000` |
+| `MCP_API_KEY` | API 密钥（可选） | `` | `your-secret-key` |
+
+## 可用工具
+
+### 1. 列出复合组件
+
+**功能**：列出 src/other/components/index.js 中导出的所有复合组件与工具
+
+**使用场景**：当用户需要了解项目中有哪些自定义复合组件时
+
+**调用方式**：
+```bash
+POST ${MCP_SERVER_URL}/tools/call
+Content-Type: application/json
+
+{
+  "name": "list_other_components",
+  "arguments": {}
+}
+```
+
+**示例**：
+```
+用户：列出项目中的复合组件
+助手：我将使用 list_other_components 工具来查询项目中的复合组件。
+```
+
+### 2. 获取组件详情
+
+**功能**：根据组件名获取实现路径、types、docs、透传目标与 props 列表
+
+**参数**：
+- `name`：组件名称（必填）
+
+**调用方式**：
+```bash
+POST ${MCP_SERVER_URL}/tools/call
+Content-Type: application/json
+
+{
+  "name": "get_other_component",
+  "arguments": { "name": "组件名称" }
+}
+```
+
+**使用场景**：当用户需要了解某个特定组件的详细信息时
+
+**示例**：
+```
+用户：获取 Query 组件的详情
+助手：我将使用 get_other_component 工具来获取 Query 组件的详细信息。
+```
+
+### 3. 搜索组件示例
+
+**功能**：在仓库内搜索组件名的用法片段（支持 md/js/ts/tsx 文件）
+
+**参数**：
+- `name`：组件名称（必填）
+- `maxResults`：最大结果数（可选，默认 20，范围 1-50）
+
+**调用方式**：
+```bash
+POST ${MCP_SERVER_URL}/tools/call
+Content-Type: application/json
+
+{
+  "name": "search_component_examples",
+  "arguments": { 
+    "name": "组件名称",
+    "maxResults": 10
+  }
+}
+```
+
+**使用场景**：当用户需要查看某个组件的使用示例时
+
+**示例**：
+```
+用户：搜索 TableOrList 组件的使用示例
+助手：我将使用 search_component_examples 工具来搜索 TableOrList 组件的使用示例。
+```
+
+### 4. 读取项目文件
+
+**功能**：读取仓库内文件（使用相对路径）
+
+**参数**：
+- `path`：文件相对路径（必填）
+- `maxChars`：最大字符数（可选，默认 20000，范围 200-200000）
+
+**调用方式**：
+```bash
+POST ${MCP_SERVER_URL}/tools/call
+Content-Type: application/json
+
+{
+  "name": "read_file",
+  "arguments": { 
+    "path": "文件相对路径",
+    "maxChars": 20000
+  }
+}
+```
+
+**使用场景**：当用户需要查看项目中特定文件的内容时
+
+**示例**：
+```
+用户：查看 src/other/components/Query/index.tsx 文件
+助手：我将使用 read_file 工具来读取 src/other/components/Query/index.tsx 文件的内容。
+```
+
+## 使用流程
+
+1. **确定用户需求**：了解用户想要查询的组件信息或文件
+2. **选择合适的工具**：根据需求选择对应的工具
+3. **获取服务器地址**：从环境变量或配置文件获取 MCP_SERVER_URL
+4. **执行查询**：通过代理调用远程 MCP 服务器的工具
+5. **呈现结果**：将查询结果以清晰、结构化的方式呈现给用户
+
+## 注意事项
+
+- 所有路径都是相对于项目根目录的相对路径
+- 搜索示例时，结果可能会有重复或不相关的内容，需要用户自行筛选
+- 读取文件时，大文件可能会被截断，用户可以通过设置 maxChars 参数来调整
+- **需要确保 MCP 服务器正在运行，否则无法查询数据**
+- **服务器地址从环境变量或配置文件动态获取，无需硬编码**
+
+## 故障排除
+
+### 连接失败
+
+1. 检查服务器是否运行：`curl ${MCP_SERVER_URL}/health`
+2. 检查防火墙设置
+3. 检查网络连接
+4. 确认 `MCP_SERVER_URL` 配置正确
+5. 检查环境变量是否正确设置
+6. 检查配置文件 `~/.szcd-mcp-config.json` 是否存在
+
+### Skill 未生效
+
+1. 检查 skill 文件是否存在：`~/.trae-cn/skills/szcd-component-helper/SKILL.md`
+2. 重启 IDE
+3. 检查 IDE 配置文件格式是否正确
+
+### 配置文件问题
+
+1. 检查配置文件路径：`~/.szcd-mcp-config.json`
+2. 检查 JSON 格式是否正确
+3. 检查文件权限
+
+## 示例对话
+
+### 示例 1：列出复合组件
+
+**用户**：szcd 项目中有哪些复合组件？
+**助手**：我来查询 szcd 项目中的复合组件列表。
+
+[通过代理调用 list_other_components 工具，使用配置的服务器地址]
+
+**助手**：以下是 szcd 项目中的复合组件列表：
+- Query
+- TableOrList
+- TitleAndBack
+- LeftTree
+
+这些组件都在 src/other/components/index.js 中导出。
+
+### 示例 2：获取组件详情
+
+**用户**：Query 组件的实现文件在哪里？
+**助手**：我来查询 Query 组件的详细信息。
+
+[通过代理调用 get_other_component 工具，参数：{"name": "Query"}]
+
+**助手**：Query 组件的详细信息如下：
+- 实现文件：src/other/components/Query/index.tsx
+- 文档文件：src/other/components/Query/Query.md
+- 导出位置：src/other/components/index.js
+
+### 示例 3：搜索组件示例
+
+**用户**：我想看看 TableOrList 组件的使用示例
+**助手**：我来搜索 TableOrList 组件的使用示例。
+
+[通过代理调用 search_component_examples 工具，参数：{"name": "TableOrList", "maxResults": 10}]
+
+**助手**：以下是 TableOrList 组件的使用示例：
+1. 文件：src/anyMd/TableOrList.json - 包含组件配置信息
+2. 文件：src/anyMd/TableOrList.txt - 包含组件描述信息
+
+### 示例 4：读取文件内容
+
+**用户**：查看 Query 组件的实现代码
+**助手**：我来读取 Query 组件的实现文件。
+
+[通过代理调用 read_file 工具，参数：{"path": "src/other/components/Query/index.tsx"}]
+
+**助手**：Query 组件的实现代码如下：
+```tsx
+// 这里显示 src/other/components/Query/index.tsx 的内容
+```