Miaoduo MCP 使用指南(VDI内网环境）

1. 网络访问路径

Miaoduo MCP Server 通过 HTTPS 访问多个远程服务获取设计稿数据。完整网络链路如下：

1.1 MCP 包安装（首次启动）

Claude Code

本地 Node.js 进程执行 npmx
HTTPS → registry.npmjs.org (Cloudflare CDN, 104.16.x.x)
下载 @miaoduo/miaoduo-mcp-server 包

1.2 API 请求（获取设计稿 HTML / 截图）

Claude Code

MCP Server（本地 Node.js 进程）
HTTPS：443
api.miaoduo.com
CNAME → tooLinux-ng.yuanfudao.com（猿辅导基础设施）
阿里云 ECS 北京区（59.110.157.251 / 123.56.0.237）
openresty 反向代理 → Next.js 应用服务

1.3 静态资源加载（设计稿中的图片、SVG）

前端渲染 / AI 解析 HTML

HTTPS：443
miaoduo.fbcontent.cn
CNAME → miaoduo.fbcontent.cn.w.cdngsLb.com（阿里云 CDN 全站加速）
Tengine 边缘节点（多地域 PoP，就近分配）
回源至对象存储

1.4 完整拓扑总结

阿里云 ECS 北京
HTTPS :443

包安装（首次）
HTTPS :443

API 数据（HTML/截图）
HTTPS :443

设计稿图片/SVG
本地环境

Claude Code

MCP Server（Node.js 进程）
npm registry

Cloudflare

104.16.x.x
api.miaoduo.com

CNAME ↓

toolmix-ng.

yuanfudao.com
59.110.157.251

123.56.0.237

openresty → Next.js
miaoduo.fbcontent.cn

CNAME ↓

*.w.cdngslb.com

（阿里云 CDN）

Tengine 边缘节点

1.5 已知问题：Windows环境下curl TLS握手失败

客户端 TLS 后端访问 api.miaoduo.com 说明

curl（Git Bash）| Schannel | SSL/TLS握手超时 | Windows Schannel 与服务端 TLS 不兼容

PowerShell/.NET | .NET SslStream | 正常 | .NET 有独立的 TLS 实现

Node.js | OpenSSL | 正常 | MCP Server 实际使用此通道，不受影响

浏览器 | 各自实现 | 正常 | Chrome/Edge 使用 BoringSSL

MCP Server 基于 Node.js（OpenSSL）运行，网络本身可用。若 MCP 启动失败（spawn npx ENOENT），需将配置中的 command 改为 npx.cmd（Windows 特有问题）。

2. 需要开通的域名

确保以下域名在防火墙/代理白名单中放行 HTTPS（443）：

域名	CNAME 解析目标	云厂商	用途
api.miaoduo.com	toolmix-ng.yuanfudao.com → 59.110.157.251/123.56.0.237	阿里云 ECS 北京	MCP API 主服务（获取节点 HTML、截图等）
miaoduo.fbcontent.cn	*.w.cdngslb.com → 多地域 PoP 节点	阿里云 CDN（Tengine）	静态资源（设计稿中的图片、SVG、字体等）
.oss-.aliyuncs.com	---	阿里云OSS	CDN回源地址（对象存储，实际图片存放位置）
registry.npmjs.org	104.16.x.x	Cloudflare	npx 首次运行时下载 @miaoduo/miaoduo-mcp-server 包

注意：阿里云 CDN 的边缘节点 IP 会动态变化，建议按域名而非 IP 配置白名单。

3. 工具使用

3.1 MCP 配置

全局配置文件 ~/claude.json或~/.claude/.mcp.json

（Windows: C:\Users\<用户名>\claude.json或C:\Users\<用户名>\.claude\.mcp.json）：

json 复制代码

"mcpServers": {
  "miaoduo": {
    "command": "npx",
    "args": ["-y", "@miaoduo/miaoduo-mcp-server@latest"],
    "env": {
      "MIAODUO_TOKEN": "<你的token>"
    }
  }
}

token获取

3.2 可用工具

MCP 提供两个工具：

get_miaoduo_node - 获取节点 HTML
- 返回设计节点的完整高保真 HTML（含内联 CSS），可直接用于构建 UI 组件。
- 参数：docId - 文档 ID（URL 中 /file/ 后的部分）；nodeId - 节点 ID（URL 参数 nodeId，需 URL 解码，如 1490%3A0 -> 1490:0）
get_miaoduo_node_screenshot - 获取节点截图
- 返回设计节点的 base64 编码截图，用于视觉参考。参数与上述相同。

3.3 URL 解析示例

设计稿 URL 格式：
https://miaoduo.com/file/{docId}?nodeId={nodeId}&type=dev

示例：

URL: https://miaoduo.com/file/gwcoYSEeEgCSy1dzsu6BN1m?nodeId=1490%3A0&type=dev

docId: gwcoYSEeEgCSy1dzsu6BN1m

nodeId: 1490:0

3.4 典型工作流

用户提供 miaoduo 设计稿 URL
同时调用截图和 HTML 两个工具（并行获取）
截图用于理解整体视觉效果
HTML 用于提取颜色、间距、字体、布局等细节
基于 HTML 中的样式信息实现 Vue/React 组件

3.5 HTML 转组件注意事项

保留所有图片 URL 和内联 CSS 效果，不要生成新图片或 SVG
将 background-image: url('...') 转换为框架对应语法
不要通过 URL 导入 Web 字体，HTML 中引用的字体用户已拥有
优先精确还原视觉效果，再考虑响应式适配

3.6 故障排查

症状	原因	解决
spawn npx ENOENT	Windows 下找不到 npx	`command` 改为 `npx.cmd`
MCP 状态 unhealthy	启动失败累计次数过多	删除 `~/.claude/mcp-health-cache.json` 后重启
fetch failed	网络不通或 TLS 问题	检查 `api.miaoduo.com:443` 是否可达
截图/HTML 返回空	nodeId 不正确	确认 URL 中 nodeId 已正确解码（`%3A -> :`）