MCP Client：szcd 组件库检索助手（客户端）

这是一个 MCP 客户端包，用于连接到远程 MCP 服务器，帮助 AI 智能体查询和分析 szcd 组件库。

架构说明

┌─────────────────┐         HTTP         ┌─────────────────┐
│  同事的机器      │ ◄──────────────────► │  您的机器        │
│                 │                      │                 │
│  npm install    │                      │  MCP Server     │
│  (客户端包)      │                      │  (源码 + 数据)   │
│                 │                      │                 │
│  - mcp-proxy    │                      │  - server.js    │
│  - skill        │                      │  - 组件源码      │
└─────────────────┘                      └─────────────────┘

关键点：

• 您在本地启动 MCP server（包含源码和数据）
• 同事通过 npm install 获得客户端包（代理 + skill）
• 客户端通过 HTTP 连接到您的服务器

安装方式

对于同事（客户端安装）

npm install @szc-ft/mcp-szcd-component-helper

安装后会自动：

• 安装 MCP 代理脚本
• 自动配置 skill 到 ~/.trae-cn/skills/szcd-component-helper/

对于您（服务器端）

在您的机器上启动 MCP server：

cd mcp/szcd-component-helper
npm run start:http

服务器默认运行在 http://10.2.16.41:3000

配置步骤

步骤1：启动服务器（您）

cd mcp/szcd-component-helper
npm run start:http

或指定端口和绑定地址：

node src/server.js --http --port=3000 --bind=0.0.0.0

步骤2：同事安装客户端包

npm install @szc-ft/mcp-szcd-component-helper

步骤3：同事配置 IDE/智能体客户端

方式1：通过配置文件（推荐）

编辑您的 IDE 配置文件（如 .trae/config.json 或 Claude Code 配置）：

{
  "mcpServers": {
    "szcd-component-helper": {
      "command": "npx",
      "args": ["szcd-mcp-proxy"],
      "env": {
        "MCP_SERVER_URL": "http://10.2.16.41:3000"
      }
    }
  }
}

方式2：通过环境变量

export MCP_SERVER_URL="http://10.2.16.41:3000"

然后在配置中使用：

{
  "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 服务：

   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（可选）：

   MCP_API_KEY=your-secret-key node src/server.js --http

   然后同事在配置中添加：

   {
     "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

cd mcp/szcd-component-helper
npm login
npm publish --access public

版本更新

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