1. 这个需求到底在解决什么问题前端开发日常里有一件特别消耗心力的事设计稿在蓝湖上更新了设计师在群里艾特你问“还原了吗”你打开蓝湖对着标注量间距、取色值、看切图改完一版推上去设计师又说“这个圆角不对”“间距差了2px”。来回几轮下来真正写业务逻辑的时间被切得稀碎。这个项目的出发点很直接把 Cursor 和蓝湖通过 MCP 协议打通让 AI 编辑器能直接读取蓝湖上的设计稿数据包括图层结构、标注信息、色值、间距、字体规格然后由 Cursor 里的 AI 直接生成或修改前端代码。设计师再问“还原了吗”的时候你打开 Cursor 让它对着蓝湖链接跑一遍代码层面的还原度直接拉满剩下的只是微调。适合谁来参考三类人最受益。第一类是日常和蓝湖打交道的前端开发者尤其是做中后台系统、组件库、活动页面的同学第二类是对 MCP 协议感兴趣、想把自己常用的设计工具或内部平台接入 AI 编辑器的技术人第三类是团队里负责提效的工具链维护者想给团队搭一套“设计稿到代码”的半自动化流程。需要提前说清楚的是MCP 本身是一个开放协议蓝湖官方是否提供现成的 MCP Server 取决于其产品迭代节奏。我实际落地时采用的是“蓝湖开放接口 自建 MCP Server”的方案这也是目前最可控、最稳定的做法。下面会把整套思路、关键细节、实操步骤和踩过的坑全部摊开讲。2. 整体方案设计与选型思路2.1 为什么是 MCP 而不是直接写脚本最开始我试过最土的办法写个 Node 脚本调蓝湖接口拉数据然后手动粘贴到 Cursor 对话框里让 AI 改代码。这个方案跑了两天就放弃了原因有三个。第一每次都要手动触发脚本、复制结果、切换窗口操作链路太长第二蓝湖的接口返回数据结构比较复杂直接丢给 AI 容易超出上下文或者被无关信息干扰第三脚本和 Cursor 之间没有状态共享AI 不知道当前项目用的是什么组件库、什么样式方案。MCP 的价值就在这里。它本质上是一套标准化的“工具调用协议”让 AI 编辑器能够以结构化的方式发现和调用外部能力。你可以把它理解成给 Cursor 装了一个“蓝湖插件”但这个插件不是写死在编辑器里的而是通过协议动态注册工具。Cursor 在需要的时候会自动调用get_design_spec这类工具拿到结构化的设计稿数据再结合当前代码上下文做修改。提示MCP 是协议层面的东西不是某个具体软件。你可以用任何语言实现 Server 端只要遵循协议规范即可。我选的是 Node.js因为前端团队维护成本最低。2.2 蓝湖数据获取的三种路径对比在动手之前我把能拿到蓝湖设计稿数据的方式都摸了一遍整理成下面这张表方便你根据自己团队的情况选型。方式可行性数据完整度维护成本适用场景蓝湖官方开放平台 API高中高低有权限申请、团队版以上蓝湖网页端接口逆向中高高个人学习、临时验证手动导出标注文件解析高中低小团队、低频使用我最终走的是官方开放平台 API 这条路。虽然需要申请权限但接口稳定、字段规范不会因为蓝湖前端改版就挂掉。网页端接口逆向虽然能拿到更细的数据但维护成本太高不适合作为长期方案。2.3 整体架构拆解整套流程分成四层。最底层是蓝湖的数据源通过开放 API 获取设计稿的图层树、标注、切图等信息。第二层是 MCP Server负责把蓝湖的原始数据转换成 AI 容易理解的结构化格式并注册成 Cursor 可调用的工具。第三层是 Cursor 的 Agent 能力它在收到“根据蓝湖设计稿修改这个页面”的指令后会自动调用 MCP Server 提供的工具拿到设计数据再结合项目里的组件库和样式规范生成代码。最上层是开发者只需要在对话框里描述需求或者在规则文件里预设好项目规范。这个架构的好处是解耦。蓝湖接口变了只改 Server 的数据转换层项目规范变了只改 Cursor 的规则文件AI 模型升级了其他层完全不用动。3. 核心细节解析与实操要点3.1 蓝湖开放接口的鉴权与数据拉取蓝湖开放平台的鉴权走的是access_token机制。你需要在蓝湖团队设置里创建一个应用拿到client_id和client_secret然后通过 OAuth2 的客户端模式换取 token。这个 token 有有效期我实测下来大概是两小时所以 Server 端必须做自动刷新不能写死。拉取设计稿数据的核心接口是获取图层详情。你需要传入project_id、page_id、layer_id这几个参数。实际使用中我建议先调“获取页面列表”接口让 AI 知道这个项目下有哪些页面然后再按需拉取具体页面的图层树。一次性拉全量数据容易撑爆上下文按需拉取才是正解。// 蓝湖 token 获取示例Node.js async function getLanhuToken() { const res await fetch(https://openapi.lanhuapp.com/oauth2/token, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ client_id: process.env.LANHU_CLIENT_ID, client_secret: process.env.LANHU_CLIENT_SECRET, grant_type: client_credentials }) }); const data await res.json(); return data.access_token; }拿到 token 之后每次请求都要在 header 里带上Authorization: Bearer token。这里有个坑蓝湖的 token 刷新没有 refresh_token过期了只能重新走客户端模式换取。所以我在 Server 里做了一个定时任务每小时刷新一次避免请求时才发现过期。3.2 MCP Server 的工具设计MCP Server 的核心是“工具注册”。你需要定义清楚每个工具叫什么名字、接收什么参数、返回什么结构。工具设计得好不好直接决定 AI 能不能用对。我注册了四个工具。第一个是list_projects列出当前账号能访问的蓝湖项目让 AI 知道有哪些设计稿可用。第二个是list_pages传入项目 ID返回页面列表。第三个是get_layer_tree传入页面 ID返回该页面的完整图层树包含每个图层的名称、类型、位置、尺寸。第四个是get_layer_spec传入具体图层 ID返回详细的标注信息包括色值、字体、间距、圆角、阴影等。注意工具描述description一定要写清楚使用场景和参数含义。Cursor 的 Agent 是根据描述来决定调不调、怎么调的。描述写得含糊AI 就会乱调或者不调。// MCP 工具注册示例简化版 server.tool( get_layer_spec, 获取蓝湖设计稿中指定图层的详细标注信息包括色值、字体、间距、圆角等。当需要还原某个具体组件的样式时调用此工具。, { layerId: { type: string, description: 蓝湖图层的唯一标识 ID } }, async ({ layerId }) { const spec await fetchLayerSpec(layerId); return { content: [{ type: text, text: JSON.stringify(spec) }] }; } );3.3 Cursor 侧的规则配置Cursor 的 Agent 能力很强但如果不给约束它生成的代码可能和你项目里的规范完全不搭。比如你项目用的是 Tailwind它给你生成一堆内联样式你项目用的是 React它给你写成 Vue。解决办法是在项目根目录放一个.cursorrules文件把项目规范写清楚。我通常会写这几块内容技术栈说明框架、语言、样式方案、组件库使用规范优先用哪个组件库的哪个组件、样式单位约定px 还是 rem间距用几的倍数、文件组织方式组件放哪个目录样式文件怎么命名。# .cursorrules 示例片段 - 本项目使用 React 18 TypeScript Tailwind CSS - 所有组件优先使用 shadcn/ui 组件库不要自己写基础组件 - 间距统一使用 Tailwind 的 spacing scale不要写任意值 - 颜色使用 tailwind.config.js 中定义的主题色不要硬编码色值 - 组件文件放在 src/components 目录下每个组件一个文件夹有了这个规则文件Cursor 在调用蓝湖 MCP 拿到设计数据后会自动把色值映射到主题色、把间距映射到 spacing scale生成的代码直接就能用。3.4 数据格式转换的关键细节蓝湖返回的图层数据是嵌套的树形结构直接丢给 AI 会有两个问题一是层级太深AI 容易迷失二是包含大量 AI 不需要的元信息浪费上下文。我的做法是在 MCP Server 里做一层“扁平化 裁剪”。把图层树拍平成一个列表每个图层只保留 AI 真正需要的字段名称、类型、位置、尺寸、样式属性。同时给每个图层生成一个“路径标识”比如Header/Logo/Icon这样 AI 在描述修改位置时能精确对应。另外蓝湖的色值有时候是rgba(0,0,0,0.5)这种格式有时候是#00000080需要统一转换成项目里使用的格式。字体信息也要做映射蓝湖上的字体名称可能和项目里定义的不完全一致需要在 Server 里维护一张映射表。4. 完整实操流程与关键环节4.1 环境准备与依赖安装先确保你的开发机上有 Node.js 18 以上版本因为 MCP 的官方 SDK 对 Node 版本有要求。然后创建一个新的项目目录初始化 npm。mkdir lanhu-mcp-server cd lanhu-mcp-server npm init -y npm install modelcontextprotocol/sdk axios dotenvmodelcontextprotocol/sdk是官方提供的 MCP Server 开发包axios用来发 HTTP 请求dotenv用来管理环境变量。装完之后在项目根目录创建.env文件把蓝湖的client_id和client_secret写进去。LANHU_CLIENT_IDyour_client_id LANHU_CLIENT_SECRETyour_client_secret提示.env文件一定要加到.gitignore里不要把密钥提交到代码仓库。4.2 MCP Server 的完整实现Server 的主体逻辑分三块鉴权管理、数据拉取、工具注册。鉴权管理负责 token 的获取和自动刷新我用了简单的内存缓存加定时器。数据拉取封装了蓝湖的几个核心接口做了错误重试和超时处理。工具注册就是前面说的四个工具。import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; const server new Server( { name: lanhu-mcp, version: 1.0.0 }, { capabilities: { tools: {} } } ); // 注册工具 server.setRequestHandler(tools/list, async () ({ tools: [ { name: list_projects, description: 列出当前账号可访问的蓝湖项目, inputSchema: { type: object, properties: {} } }, { name: get_layer_spec, description: 获取指定图层的详细标注信息, inputSchema: { type: object, properties: { layerId: { type: string, description: 图层 ID } }, required: [layerId] } } ] })); server.setRequestHandler(tools/call, async (request) { const { name, arguments: args } request.params; if (name list_projects) { const projects await fetchProjects(); return { content: [{ type: text, text: JSON.stringify(projects) }] }; } if (name get_layer_spec) { const spec await fetchLayerSpec(args.layerId); return { content: [{ type: text, text: JSON.stringify(spec) }] }; } }); const transport new StdioServerTransport(); await server.connect(transport);这段代码是骨架实际落地时还要加上错误处理、日志输出、token 刷新逻辑。日志建议输出到 stderr因为 stdout 被 MCP 协议占用了往 stdout 写日志会干扰协议通信。4.3 在 Cursor 中配置 MCP ServerCursor 的 MCP 配置入口在设置里的 Features 选项卡下面。找到 MCP Servers 区域点击添加填入 Server 的启动命令。因为我用的是 stdio 传输方式所以命令就是node /path/to/your/server.js。配置保存后Cursor 会自动启动这个 Server 进程并在 Agent 模式下把注册的工具暴露出来。你可以在对话框里输入“列出蓝湖项目”来验证连接是否正常。如果返回了项目列表说明整条链路已经通了。注意Cursor 启动 MCP Server 时使用的是它自己的环境变量不会自动读取你项目里的.env文件。所以要么在配置里显式传入环境变量要么在 Server 代码里用绝对路径加载.env。4.4 实际使用从设计稿到代码的完整演示假设设计师在蓝湖上更新了一个“用户卡片”组件我需要把这个更新同步到代码里。操作流程是这样的。第一步在 Cursor 对话框里输入“帮我根据蓝湖上‘用户中心’项目的‘个人资料页’设计稿更新 UserCard 组件设计稿的页面 ID 是 xxx。”第二步Cursor 的 Agent 会自动调用list_pages确认页面存在然后调用get_layer_tree拉取页面图层树找到名为“UserCard”的图层组。第三步Agent 继续调用get_layer_spec获取该图层组下每个子图层的详细标注包括头像的圆角、用户名的字号字重、签名的颜色、间距等。第四步Agent 结合.cursorrules里的项目规范把蓝湖的色值映射到主题色把间距映射到 Tailwind 的 spacing scale生成修改后的组件代码。第五步我 review 一下生成的代码确认无误后直接提交。整个过程从输入指令到拿到可用代码大概两分钟。4.5 参数映射与单位换算的实操细节蓝湖上的设计稿通常是以 750px 或 375px 为基准的移动端稿或者是 1440px 的桌面端稿。而项目里可能用的是 rem 或者 vw。这个换算必须在 MCP Server 里处理好不能让 AI 去算因为 AI 算数容易出错。我的做法是在 Server 里加一个配置项指定设计稿基准宽度和目标单位。比如设计稿是 375px 基准项目用 remroot font-size 是 16px那么换算公式就是rem px / 16。Server 在返回标注数据时直接把 px 转换成 rem 再给 AI。function pxToRem(px, baseWidth 375, rootFontSize 16) { return (px / baseWidth * rootFontSize).toFixed(4); }字体大小的映射也要注意。蓝湖上可能写的是“苹方-简 中黑 16px”项目里用的是text-base font-medium。这个映射关系需要在 Server 里维护一张表或者写在.cursorrules里让 AI 去映射。我倾向于在 Server 里做因为更可控。5. 常见问题与排查技巧实录5.1 连接类问题速查现象可能原因排查方法解决方案Cursor 里看不到 MCP 工具Server 启动失败查看 Cursor 的 MCP 日志检查 node 路径和脚本路径工具调用返回鉴权失败token 过期或无效打印 token 值确认检查 client_id/secret加自动刷新请求超时网络问题或接口限流用 curl 直接调接口测试加重试机制降低请求频率返回数据为空项目/页面 ID 错误先调 list 接口确认 ID确认账号有该项目的访问权限5.2 数据不准的排查思路有时候 AI 生成的代码和设计稿对不上不一定是 AI 的问题可能是数据在传输过程中丢了精度。我遇到过蓝湖返回的色值是#FF0000但 AI 生成的是red虽然视觉上一样但不符合项目规范。后来在 Server 里加了一层色值标准化统一转成大写十六进制问题就解决了。还有一种情况是图层名称重复。蓝湖上设计师可能给多个图层起了同样的名字比如好几个“矩形”。这时候get_layer_spec按名称查找就会出错。解决办法是让 AI 用图层 ID 而不是名称来定位或者在 Server 里给每个图层生成唯一路径。5.3 上下文超限的处理技巧一个复杂页面的图层树可能有几百个节点全部塞给 AI 会超出上下文窗口。我的处理策略是“按需拉取 摘要优先”。先让 AI 拉取图层树的摘要版本只包含顶层结构和图层名称AI 判断需要修改哪个部分后再拉取该部分的详细标注。另外在 Server 返回数据时可以主动裁剪掉 AI 不需要的字段。比如切图的 URL、图层的历史版本信息、设计师的备注等这些对代码生成没有帮助反而占用上下文。5.4 我踩过的三个坑第一个坑是 stdio 传输的日志污染。最开始我把调试日志用console.log输出结果 MCP 协议通信直接挂了。后来改成console.error才正常。这个坑花了我一个下午才定位到。第二个坑是 token 刷新的并发问题。多个工具调用同时发现 token 过期同时去刷新导致重复请求。后来加了一个 Promise 锁确保同一时间只有一个刷新请求在跑。第三个坑是 Cursor 版本更新导致的配置失效。有一次 Cursor 升级后MCP 配置的格式变了之前能用的配置突然不生效。建议把 MCP 配置也纳入版本管理升级后及时对照官方文档调整。5.5 性能优化的几个实用手段蓝湖接口的响应速度不算快一个复杂页面的图层树拉取可能要两三秒。如果 AI 在一次对话里连续调用多次体验会很差。我在 Server 里加了一层内存缓存同一个图层 ID 的标注数据缓存五分钟重复请求直接返回缓存结果。另外可以把常用的项目 ID 和页面 ID 预加载到缓存里AI 第一次调用时就能秒回。这个预加载可以在 Server 启动时做也可以在 Cursor 空闲时触发。6. 进阶玩法与团队协作建议6.1 把组件库文档也接进来光有设计稿数据还不够AI 还需要知道项目里有哪些现成组件可用。我把团队组件库的文档也做成了一个 MCP 工具AI 在生成代码前会先查一下有没有现成组件避免重复造轮子。这个工具的实现思路和蓝湖类似就是把组件文档结构化后注册成工具。6.2 设计稿变更的自动检测更进一步可以做一个定时任务定期拉取蓝湖上指定项目的最新版本和本地缓存的版本做 diff。一旦发现设计稿有更新自动在 Cursor 里创建一个任务让 AI 评估需要修改哪些代码。这样设计师改完稿你这边就能收到一个“待处理”的代码修改建议而不是被追着问“还原了吗”。6.3 团队共享配置的最佳实践如果团队多人使用建议把 MCP Server 部署成一个内部服务而不是每个人本地跑一个。这样 token 管理、缓存、日志都集中在一处维护成本更低。Cursor 侧只需要配置一个指向内部服务的连接即可。配置文件和.cursorrules一定要纳入 Git 管理新同学 clone 下来就能用。蓝湖的密钥通过环境变量注入不要写在配置文件里。6.4 关于还原度验收的思考工具能解决“代码和设计稿一致”的问题但解决不了“设计稿本身是否合理”的问题。我实际用下来发现AI 有时候会忠实地还原设计稿里的一些不合理之处比如间距用了 13px 这种非标准值。这时候需要在.cursorrules里加一条规则遇到非标准值优先映射到最近的标准值并在注释里说明。另外还原度验收最好还是人工过一遍。AI 生成的代码在结构上没问题但交互细节、边界情况、响应式表现还是需要人来把关。工具的价值是把你从“量间距、取色值”这种机械劳动里解放出来让你有更多精力关注真正重要的东西。这个方案我跑了大概三个月团队里前端同学的平均页面还原时间从原来的两三个小时缩短到四十分钟左右设计师在群里艾特“还原了吗”的频率明显下降。当然前期搭 Server、调规则文件、处理各种边界情况也花了不少时间但一次投入长期受益这笔账怎么算都划算。