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

v0.10.0

Published

3 days ago

MCP server for szcd component library - built with @modelcontextprotocol/sdk, supports stdio/SSE/dual modes

0High
0Medium
0Low

zzj-new

mcp szcd component ai agent claude skill proxy sse

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

szcd 组件库 MCP 助手 — 基于 @modelcontextprotocol/sdk 构建，支持 stdio / SSE / dual 三种运行模式。

版本历史

v0.9.1

update-mcp-url.js 模块化重构：从单文件 ~370 行拆分为薄编排器 + 各 lib 模块 syncMcpUrl() 导出
- lib/trae-cli.js — Trae CLI YAML + CLI 命令同步
- lib/trae-ide.js — Trae CN mcp.json 同步
- lib/claude-code.js — Claude Code CLI + ~/.claude.json 同步
- lib/qwen-code.js — Qwen Code CLI + 扩展 manifest + settings.json 同步
Qwen Code syncMcpUrl 统一 SSE 模式：CLI 命令和 settings.json 均使用 type: "sse" + /sse 端点，与扩展默认配置一致

v0.9.0

Qwen Code 扩展机制：从手动改 settings.json + 复制 skills/agents 升级为 Extension 扩展安装方式
- 扩展目录: ~/.qwen/extensions/szcd-component-helper/
- qwen-extension.json 声明 MCP 服务器、skills、agents、commands
- 支持 qwen extensions install/uninstall/disable/enable 完整生命周期
- contextFileName 自动注入 QWEN.md 上下文
- 支持 settings 配置（如 MCP_SERVER_URL 环境变量）
postinstall 自动安装扩展：优先使用 qwen extensions install，回退到直接复制扩展目录
自动清理旧配置：移除 settings.json 中的 mcpServers 条目、旧的 skills/ 目录
扩展内置 skills/agents/commands：不再需要手动复制文件到 ~/.qwen/skills/ 等目录

v0.8.5

移除 get_vision_config 工具：该工具为内部诊断用途，不应暴露给用户，已从服务端和所有文档中移除

v0.8.4

Qwen Code 默认使用 SSE 模式：用户级 ~/.qwen/settings.json 从 Streamable HTTP (httpUrl) 切换为 SSE 模式 (type: "sse", url)，更成熟稳定
项目级 MCP 配置禁用：项目级 .qwen/settings.json 中 mcpServers 迁移到 _mcpServers_disabled 前缀 key，避免重复注册；用户级 SSE 已覆盖
项目级 skill/agent 复制注释：postinstall 不再复制项目级 skill 和 agent 到 .qwen/skills，用户级已包含
CLI 命令同步：qwen mcp add --transport sse 替代 --transport http

v0.7.5

直接文件操作同步 IDE 配置：不再仅依赖 CLI 命令，直接读写配置文件确保同步成功
- ~/.trae/trae_cli.yaml — Trae CLI 主配置（YAML 解析 + 修改）
- ~/.trae-cn/mcp.json — Trae CN IDE（SSE 模式）
- ~/.claude.json — Claude Code 用户级配置
PROJECT_ROOT 自动推导：从 node_modules 边界自动推导项目根目录，无需手动指定
Claude Code 配置同步：postinstall 自动配置 Claude Code MCP 服务器
OpenCode 兼容：自动生成 opencode.json 配置文件
postinstall 模块化重构：按 IDE 兼容方向抽离为独立模块
- scripts/lib/common.js — 通用工具（常量、安全保护、文件操作、配置读取）
- scripts/lib/trae.js — Trae CLI / Trae CN 兼容逻辑
- scripts/lib/opencode.js — OpenCode 兼容逻辑
szcd-mcp-url 自定义命令：新增 /szcd-mcp-url slash command，一键更新 MCP 服务器地址并同步所有 IDE 配置
szcd-mcp-update-url CLI：新增 npx szcd-mcp-update-url <url> 命令行工具

v0.6.0

localtunnel 内网穿透：支持通过 localtunnel 暴露端口，无公网 IP 也可远程访问
- PM2 守护隧道进程（mcp-tunnel），固定子域名 --subdomain szcd
- 隧道看门狗脚本（tunnel-watchdog.js），5 分钟心跳检测 + 自动重建
PM2 三进程架构：mcp-szcd（服务）+ mcp-tunnel（隧道）+ mcp-watchdog（看门狗）

v0.5.1

postinstall 安全保护：防止安装脚本导致 CPU/内存爆炸
- 递归调用守卫、全局超时保护、命令可用性检测、安全执行封装
增强 Claude Code 兼容性：改进代理请求头，确保与 Claude Code 的正确通信
更好的错误处理：针对 406 "Not Acceptable" 错误的特殊处理

架构

┌─────────────────────────────────────────────────────────────┐
│                    连接方式                                   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  方式1: 本地直连 (stdio) — 推荐                              │
│  ┌─────────────┐     stdio      ┌─────────────────────────┐│
│  │   IDE/AI    │ ◄─────────────►│  szcd-mcp-server        ││
│  │   Client    │                │  (本地运行)              ││
│  └─────────────┘                └─────────────────────────┘│
│                                                             │
│  方式2: SSE 远程连接                                         │
│  ┌─────────────┐     SSE       ┌─────────────────────────┐│
│  │   IDE/AI    │ ◄────────────►│  MCP Server             ││
│  │   Client    │  GET /sse     │  GET /sse + POST /message││
│  └─────────────┘               └─────────────────────────┘│
│                                                             │
│  方式3: Streamable HTTP（Trae CLI 兼容）                     │
│  ┌─────────────┐    HTTP      ┌─────────────────────────┐ │
│  │   IDE/AI    │ ◄───────────►│  MCP Server             │ │
│  │   Client    │  POST /mcp   │  Streamable HTTP 端点    │ │
│  └─────────────┘              └─────────────────────────┘ │
│                                                             │
│  方式4: 代理桥接 (向后兼容)                                   │
│  ┌─────────────┐  stdio  ┌───────────┐  SSE/HTTP  ┌─────┐│
│  │   IDE/AI    │◄───────►│mcp-proxy  │◄──────────►│Server││
│  │   Client    │         │(桥接代理)  │            │     ││
│  └─────────────┘         └───────────┘            └─────┘│
└─────────────────────────────────────────────────────────────┘

安装

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

安装后自动配置：

Trae CLI: ~/.trae/trae_cli.yaml + ~/.trae-cn/mcp.json
Trae CN Skills: ~/.trae-cn/skills/szcd-component-helper/SKILL.md
Claude Code: ~/.claude.json + ~/.claude/skills/szcd-component-helper/SKILL.md
Qwen Code Extension: ~/.qwen/extensions/szcd-component-helper/（MCP + Skills + Agents + Commands + Context）
OpenCode: <项目>/opencode.json
Slash Command: ~/.trae-cn/commands/szcd-mcp-url.md + <项目>/.claude/commands/szcd-mcp-url.md
配置文件: ~/.szcd-mcp-config.json

使用方式

方式1: 本地直连 stdio（推荐）

无需远程服务器，IDE 直接启动本地 MCP 进程：

{
  "mcpServers": {
    "szcd-component-helper": {
      "command": "npx",
      "args": ["szcd-mcp-server", "--stdio"]
    }
  }
}

方式2: SSE 远程连接

管理员先启动服务器：

node src/server.js --sse --port=3456 --bind=0.0.0.0

客户端通过代理桥接：

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

方式3: Streamable HTTP（Trae CLI 兼容）

管理员先启动服务器：

node src/server.js --sse --port=3456 --bind=0.0.0.0

Trae CLI 配置（~/.trae/trae_cli.yaml）：

mcp_servers:
    - name: szcd-component-helper
      url: http://YOUR_SERVER_IP:3456/mcp
      type: http

方式4: 代理桥接（向后兼容）

方式5: Qwen Code 扩展（推荐）

Qwen Code 使用 Extension 扩展机制集成 MCP 服务器、skills、agents 和 commands。

安装扩展（推荐）：

# 从本地路径安装
qwen extensions install /path/to/szcd-component-helper/qwen-extension

# 或从 npm 安装
qwen extensions install @szc-ft/mcp-szcd-component-helper

安装后自动包含：

MCP 服务器（SSE 模式连接 localhost:3456/sse）
Skill（szcd-component-helper — 组件库查询能力）
Agent（szcd-component-expert — 组件库专家）
Command（/szcd-mcp-url — 更新 MCP 服务器地址）
Context（QWEN.md — 组件库上下文）

扩展管理：

# 查看已安装扩展
/extensions

# 禁用扩展
qwen extensions disable szcd-component-helper

# 启用扩展
qwen extensions enable szcd-component-helper

# 卸载扩展
qwen extensions uninstall szcd-component-helper

# 更新扩展
qwen extensions update szcd-component-helper

修改 MCP 服务器地址：

编辑 ~/.qwen/extensions/szcd-component-helper/qwen-extension.json 中的 mcpServers 配置，或使用 /szcd-mcp-url 命令。

手动配置（不使用扩展）：

如果不使用扩展机制，也可以在 ~/.qwen/settings.json 中手动配置：

{
  "mcpServers": {
    "szcd-component-helper": {
      "type": "sse",
      "url": "http://YOUR_SERVER_IP:3456/sse"
    }
  }
}

注意：项目级 .qwen/settings.json 中的 mcpServers 已迁移到 _mcpServers_disabled，扩展机制已覆盖，无需项目级重复配置。

工具过滤（可选，用于 settings.json 手动配置时）：

{
  "mcpServers": {
    "szcd-component-helper": {
      "type": "sse",
      "url": "http://localhost:3456/sse",
      "includeTools": ["list_other_components", "get_other_component", "search_component_examples"],
      "trust": true
    }
  }
}

服务器启动命令

直接启动

# stdio 模式（默认，本地 IDE 使用）
node src/server.js --stdio

# SSE 模式（远程/多客户端）
node src/server.js --sse --port=3456 --bind=0.0.0.0

# Dual 模式（同时支持 stdio + SSE）
node src/server.js --dual --port=3456 --bind=0.0.0.0

# 向后兼容：--http 等同于 --sse
node src/server.js --http --port=3456

# 带 API Key 认证
node src/server.js --sse --port=3456 --apiKey=your-secret-key

PM2 进程守护（推荐生产环境）

# 启动（自动读取 ecosystem.config.cjs 配置）
pm2 start ecosystem.config.cjs

# 常用管理命令
pm2 list                    # 查看进程状态
pm2 logs mcp-szcd           # 查看日志
pm2 restart mcp-szcd        # 重启
pm2 stop mcp-szcd           # 停止
pm2 delete mcp-szcd         # 删除

# 开机自启
pm2 save                    # 保存当前进程列表
pm2 startup                 # 生成开机自启脚本

PM2 配置说明（ecosystem.config.cjs）：

mcp-szcd：MCP 服务进程，崩溃后自动恢复，最多重启 10 次，内存限制 500MB
mcp-tunnel：localtunnel 内网穿透进程，固定子域名 szcd，自动重连，最多重启 30 次，内存限制 200MB
mcp-watchdog：隧道看门狗进程，5 分钟心跳检测 + 自动重建，最多重启 10 次，内存限制 100MB
日志输出：./logs/pm2-out.log + ./logs/pm2-error.log

内网穿透（公网访问）

服务器没有公网 IP 时，可通过 localtunnel 暴露端口：

# 安装
npm install -g localtunnel

# 启动隧道（已集成到 PM2，随 mcp-szcd 一起启动，固定子域名 szcd）
pm2 start ecosystem.config.cjs

# 查看当前公网地址
pm2 logs mcp-tunnel --lines 1 --nostream

启动后会输出类似 your url is: https://szcd.loca.lt 的公网地址（使用固定子域名，重启后 URL 不变）。

看门狗自动守护：mcp-watchdog 进程每 5 分钟检测隧道健康状态，不可达时自动重建。

{
  "mcpServers": {
    "szcd-component-helper": {
      "type": "sse",
      "url": "https://xxx-xxx.loca.lt/sse"
    }
  }
}

注意事项：

使用固定子域名 szcd，重启后 URL 不变（需 localtunnel 服务端支持）
首次访问浏览器会显示确认页面，API 请求需加 Bypass-Tunnel-Reminder: true 请求头
看门狗会自动检测并重建不可达的隧道

配置

配置文件 `~/.szcd-mcp-config.json`

{
  "MCP_SERVER_URL": "http://localhost:3456",
  "MCP_TIMEOUT": 30000,
  "MCP_API_KEY": ""
}

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | MCP_SERVER_URL | MCP 服务器地址 | http://localhost:3456 | | MCP_TIMEOUT | 请求超时时间(毫秒) | 30000 | | MCP_API_KEY | API 密钥（可选） | 空 | | VISION_API_KEY | 视觉模型 API 密钥（设计稿分析） | 读取 ANTHROPIC_API_KEY 或 OPENAI_API_KEY | | VISION_PROVIDER | 视觉模型提供商 | anthropic | | VISION_MODEL | 视觉模型名称 | claude-sonnet-4-6 | | VISION_API_URL | 自定义视觉模型 API 地址 | 官方地址 | | DESIGN_ANALYSIS_ORDER | 分析优先级：vision_first / ocr_first / vision_only / ocr_only | vision_first | | OCR_SCRIPT_PATH | 本地 OCR 脚本路径（降级用） | /usr/local/bin/ocr-image |

配置优先级：环境变量 > 项目级配置(.szcd-mcp-config.json) > 用户级配置(~/.szcd-mcp-config.json) > IDE 配置 > 默认值

快速更新 MCP 服务器地址

使用 /szcd-mcp-url slash command 或 CLI 命令一键同步所有 IDE 配置：

# 指定新 URL
npx szcd-mcp-update-url http://10.2.16.41:3456

# 使用配置文件中已有的 URL 同步 IDE
npx szcd-mcp-update-url

同步的配置文件：

~/.szcd-mcp-config.json — szcd 自身配置
~/.trae/trae_cli.yaml — Trae CLI 主配置
~/.trae-cn/mcp.json — Trae CN IDE（SSE 模式）
~/.claude.json — Claude Code 用户级配置
~/.qwen/extensions/szcd-component-helper/qwen-extension.json — Qwen Code 扩展配置

MCP 工具列表

| 工具 | 说明 | |------|------| | list_other_components | 列出复合组件与工具 | | get_other_component | 获取组件实现路径、types、docs、透传目标与 props | | search_component_examples | 搜索组件用法片段 | | read_file | 读取仓库内文件 | | get_accurate_component_doc | 获取组件准确 Props 文档 | | list_cover_components | 列出 Cover 层组件 | | get_cover_component | 获取 Cover 层组件详情 | | list_wrapper_components | 列出 Wrapper 层组件 | | list_pro_package_components | 列出 ProPackages 组件 | | list_antd_components | 列出 Ant Design 组件分类概览 | | list_antd_components_by_category | 按分类列出 Ant Design 组件 | | get_antd_component | 获取 Ant Design 组件详情 | | list_pro_components | 列出 ProComponents 分类概览 | | list_pro_components_by_category | 按分类列出 ProComponents | | get_pro_component | 获取 ProComponents 组件详情 | | search_all_components | 全局搜索所有层级组件 | | get_component_library_overview | 组件库完整概览 | | analyze_design_image | 视觉代理/兜底：当用户 LLM 不支持图片时，代为解析设计稿，返回结构化文本描述 |

验证

# 测试服务器健康
curl http://localhost:3456/health

# 测试代理连接
npx szcd-mcp-proxy --test

故障排除

连接失败：

检查服务器是否运行：curl http://<IP>:3456/health
检查防火墙设置
确认 MCP_SERVER_URL 配置正确
使用 npx szcd-mcp-update-url 重新同步 IDE 配置

Skill 未生效：

检查 skill 文件：~/.trae-cn/skills/szcd-component-helper/SKILL.md
重启 IDE

隧道不可达：

检查隧道进程：pm2 list 确认 mcp-tunnel 运行中
查看看门狗日志：pm2 logs mcp-watchdog
手动重建：pm2 restart mcp-tunnel

许可证

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

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

版本历史

v0.9.1

v0.9.0

v0.8.5

v0.8.4

v0.7.5

v0.6.0

v0.5.1

架构

安装

使用方式

方式1: 本地直连 stdio（推荐）

方式2: SSE 远程连接

方式3: Streamable HTTP（Trae CLI 兼容）

方式4: 代理桥接（向后兼容）

方式5: Qwen Code 扩展（推荐）

服务器启动命令

直接启动

PM2 进程守护（推荐生产环境）

内网穿透（公网访问）

配置

配置文件 ~/.szcd-mcp-config.json

环境变量

快速更新 MCP 服务器地址

MCP 工具列表

推荐工作流

验证

故障排除

许可证

配置文件 `~/.szcd-mcp-config.json`