1. 项目概述用AI重构你的架构图绘制体验作为一名在软件工程领域摸爬滚打了十多年的老兵我深知一个清晰的架构图对于理解复杂系统、进行技术讨论和编写文档的价值。但我也同样清楚画图这件事有多“反人类”——要么是手绘在白板上拍完照就再也看不清要么是用绘图工具一个个拖拽、对齐、连线半天时间就耗进去了再或者用文本工具比如Mermaid生成虽然快但布局混乱、样式单一想微调一下简直无从下手。最近我在尝试用AI辅助编程时发现了一个能彻底解决这个痛点的项目excalidraw-architect-mcp。这本质上是一个MCPModel Context Protocol服务器它充当了你的AI助手比如Cursor、Windsurf里的AI和Excalidraw绘图工具之间的“翻译官”和“布局引擎”。简单来说你不再需要告诉AI“在这里画一个方框坐标是(100,200)”你只需要告诉它“我需要一个包含API网关、用户服务和PostgreSQL的架构图”AI负责理解你的意图并描述结构而这个MCP服务器则负责把所有枯燥、易错的布局计算、样式应用工作全包了。这个项目最吸引我的是它精准地切中了“语义”与“像素”之间的鸿沟。大语言模型擅长理解关系和概念但让它去精确计算每个图形的位置和大小它很容易“幻觉”出重叠、错乱的布局。而这个MCP服务器则把AI从“美工”的岗位上解放出来让它专注于自己擅长的“架构师”角色。最终生成的.excalidraw文件布局工整、样式专业可以直接导入Excalidraw进行进一步的微调或分享。对于需要频繁进行系统设计、代码库梳理或技术文档编写的开发者来说这无疑是一个生产力倍增器。2. 核心设计思路分离“是什么”与“在哪里”要理解excalidraw-architect-mcp的价值我们需要先拆解它背后的核心设计哲学。传统的AI画图流程是“端到端”的你提出需求AI直接生成一份包含所有坐标、尺寸信息的Excalidraw JSON。这个流程存在一个根本性缺陷布局是硬编码的。AI并不真正理解“层次布局”、“避免交叉”、“均匀分布”这些视觉设计原则它只是在模仿训练数据中的坐标模式这必然导致输出不稳定。2.1 问题拆解为什么AI不擅长直接画图AI模型尤其是基于Transformer架构的大语言模型其强项在于序列预测和语义理解。当你让它“画一个架构图”时它理解“API网关”、“数据库”、“微服务”这些概念并能推断出它们之间的关系。但是将这些关系映射到二维平面的具体坐标x, y, width, height是一个完全不同的优化问题。这涉及到图布局算法如何自动安排节点位置使得连接线总长度最短、交叉最少、布局层次清晰视觉样式不同技术组件如Kafka vs PostgreSQL是否有约定俗成的图标或颜色表示可编辑性生成的图是否易于后续修改如果我想“在数据库前加个缓存”是局部调整还是需要推倒重来让AI直接输出坐标相当于让一位建筑师既负责设计房屋结构又亲自去砌每一块砖。结果就是“幻觉”频出盒子重叠、连线穿盒而过、布局拥挤不堪。2.2 解决方案引入专用布局引擎excalidraw-architect-mcp的聪明之处在于它引入了一个专用的、确定性的布局引擎作为中间层。整个工作流被清晰地分为两步AI负责“语义建模”AI将你的自然语言描述转换成一个结构化的、与视觉无关的“关系图”。这个图只包含节点组件和边连接以及它们的类型和标签。例如[节点: 类型‘api_gateway’ 标签‘Nginx’] --[边: 类型‘http’]-- [节点: 类型‘service’ 标签‘User Service’]。MCP服务器负责“视觉渲染”MCP服务器接收这个关系图调用内部的Sugiyama分层布局算法一种经典的自动布局算法计算出每个节点的最优位置和大小。同时它内置了一个丰富的组件样式库能根据节点类型如‘kafka’ ‘postgresql’自动应用对应的背景色、图标和边框样式。这种“语义-视觉”分离的架构带来了几个决定性优势布局质量稳定可靠每次生成的图都遵循相同的布局规则杜绝了随机重叠。样式专业统一技术栈可视化符合业界常见实践看图一目了然。支持自然语言迭代因为MCP服务器可以读取已生成的.excalidraw文件解析出现有结构所以你可以在原图基础上用自然语言进行修改“在数据库前加个Redis缓存”服务器会重新计算布局而不是在错误的位置上硬塞一个图形。实操心得这个设计模式非常值得借鉴。它本质上是一种“AI 确定性工具”的混合智能系统。AI处理模糊、开放性的语义理解而将那些有明确算法、需要精确计算的任务交给专用工具。我们在构建自己的AI应用时也可以思考哪些环节可以拆解出来用更可靠的传统代码实现。3. 环境配置与快速上手理论讲完了我们来点实际的。下面是我在本地环境macOS从零开始配置并使用excalidraw-architect-mcp的完整过程我会把每一步的意图和可能遇到的坑都讲清楚。3.1 基础环境准备首先你需要一个支持MCP协议的AI IDE。目前最主流的选择是Cursor和Windsurf。我以Cursor为例因为它对MCP的支持非常直接。确保你安装的是较新版本的Cursor。其次你需要Python环境。项目推荐使用uv一个快速的Python包安装器和解析器但用传统的pip也完全没问题。我两种方式都会演示。3.2 安装MCP服务器方法一使用pip安装最通用打开你的终端执行以下命令。这会将excalidraw-architect-mcp作为全局命令行工具安装。pip install excalidraw-architect-mcp安装完成后可以通过运行excalidraw-architect-mcp --help来验证是否成功。如果看到帮助信息说明安装正确。方法二使用uvx临时运行无需安装如果你不想污染全局环境或者想快速尝鲜可以使用uvx。首先确保安装了uvcurl -LsSf https://astral.sh/uv/install.sh | sh然后uvx excalidraw-architect-mcp这个命令会临时下载并运行该MCP服务器。当你关闭终端会话它就不会留下痕迹。注意事项如果你的网络环境访问PyPI较慢可以考虑配置pip的国内镜像源。对于uv可以通过设置环境变量UV_INDEX_URL来加速。3.3 配置Cursor IDE这是关键一步需要告诉Cursor有一个新的“工具”即MCP服务器可供其内部的AI调用。在你的项目根目录或者你的用户主目录下找到或创建Cursor的MCP配置文件。路径通常是~/.cursor/mcp.json全局配置或者你项目目录下的.cursor/mcp.json项目级配置。我推荐使用项目级配置这样配置只对当前项目生效。编辑这个JSON文件。如果文件不存在就新建一个。内容如下{ mcpServers: { excalidraw-architect: { command: excalidraw-architect-mcp, transport: stdio } } }excalidraw-architect这是你给这个服务器起的名字可以自定义但后续AI调用时会用到。command: excalidraw-architect-mcp告诉Cursor启动哪个命令。因为我们用pip全局安装了所以直接写命令名即可。transport: stdio通信方式为标准输入输出这是MCP服务器最常见的通信模式。保存文件。重要你需要完全重启Cursor包括关闭所有Cursor窗口再重新打开。仅仅重启编辑器标签页是不够的必须让Cursor主进程重新加载配置。3.4 安装并理解“Diagram Design Skill”项目作者提供了一个名为“Diagram Design Skill”的提示词文件。这不是必须的但强烈推荐安装。你可以把它理解为教AI如何更好地使用excalidraw-architect-mcp这个工具的“说明书”或“最佳实践指南”。这个Skill文件做了以下几件事设定边界告诉AI单个架构图建议包含6-15个节点详细流程图建议10-25个节点。避免生成过于复杂、无法阅读的巨图。定义拓扑规则建议数据流方向如从左到右定义常见的架构模式如三层架构、事件驱动架构中各组件的相对位置。规范标签指导AI如何为连线和节点编写清晰、简洁的标签。映射技术栈提醒AI可以利用MCP内建的50多种技术样式库。安装方法Cursor用户 在终端中一次性执行以下命令mkdir -p ~/.cursor/skills/excalidraw-diagram-design \ curl -o ~/.cursor/skills/excalidraw-diagram-design/SKILL.md \ https://raw.githubusercontent.com/BV-Venky/excalidraw-architect-mcp/main/.skills/excalidraw-diagram-design/SKILL.md这个命令会在你的Cursor技能目录下创建文件夹并下载Skill文件。之后Cursor的AI在生成图表时会自动参考这个文件中的指导原则。我的体会安装这个Skill后AI生成的图表描述即传给MCP的结构化数据质量有明显提升。它会更自觉地控制图表规模并使用更规范的技术名称从而触发MCP的自动样式功能。这印证了一个好想法对于复杂的AI工具提供“使用指南”能极大提升最终输出效果和用户体验。4. 核心功能实战从指令到专业图表配置妥当现在让我们看看它到底能做什么。以下是我测试的几个核心场景包含了具体的操作指令、AI的思考过程以及最终成果分析。4.1 场景一从零创建微服务架构图这是最常用的场景。假设我正在设计一个简单的电商后端系统。我的指令在Cursor Chat中输入“为我创建一个微服务架构图包含以下组件一个Nginx作为API网关一个认证服务一个用户服务一个订单服务。数据存储使用PostgreSQL用Redis作为缓存服务间通过Kafka进行异步通信。另外需要一个Prometheus和Grafana做监控。”AI的思考与行动AI首先会识别出这是一个create_diagram工具的适用场景。接着它会参考Diagram Design Skill决定将组件数量控制在合理范围本例约9个节点并规划一个从左到右的数据流。AI在脑海中或者说在它的上下文里构建一个结构化描述。它不会直接想坐标而是想“有一个‘api_gateway’类型的节点标签是‘Nginx’。它连接到‘auth_service’和‘user_service’……”等等。最终AI调用excalidraw-architect-mcp的create_diagram工具传入类似下面的结构化数据这是简化的示意{ nodes: [ {id: 1, type: load_balancer, label: Nginx}, {id: 2, type: service, label: Auth Service}, {id: 3, type: service, label: User Service}, {id: 4, type: service, label: Order Service}, {id: 5, type: database, label: PostgreSQL}, {id: 6, type: cache, label: Redis}, {id: 7, type: message_queue, label: Kafka}, {id: 8, type: monitoring, label: Prometheus}, {id: 9, type: monitoring, label: Grafana} ], edges: [ {source: 1, target: 2, label: 路由}, {source: 1, target: 3, label: 路由}, {source: 3, target: 5, label: 读写}, {source: 3, target: 6, label: 缓存}, {source: 4, target: 7, label: 发布订单事件} // ... 更多连接 ] }MCP服务器收到请求启动它的布局引擎Sugiyama算法工作首先它会自动识别出“Nginx”是一个入口点可能将其放在最左侧。“Auth Service”和“User Service”可能被放在同一层垂直排列因为它们都直接从网关接收流量。“PostgreSQL”和“Redis”可能被放在更右侧作为数据层。监控组件Prometheus, Grafana可能被识别为与核心业务流关联较弱被算法放置在底部作为独立的“子图”。样式库应用根据type字段自动上色加图标。“load_balancer”类型的Nginx可能获得一个特定的绿色和负载均衡器图标“database”类型的PostgreSQL是蓝色和数据库圆柱图标“message_queue”类型的Kafka是橙色和流数据图标。几秒钟后AI会在聊天中回复告诉我图表已生成并提供一个.excalidraw文件的下载链接或直接显示预览。我点击后一个布局工整、颜色区分度高的专业架构图就展现在眼前。Nginx的框体会自动拉伸宽度以清晰展示其连接多个下游服务的关系。4.2 场景二迭代修改现有图表图表不是一次性的。随着设计深入我需要修改。我的指令“在刚才生成的架构图中在PostgreSQL数据库前面添加一个Redis缓存层用于缓存用户查询结果。”AI的思考与行动AI需要先知道“刚才的图表”是什么。它可能会使用get_diagram_info工具如果上下文保留了图表引用或者直接依赖我上传的.excalidraw文件。理解我的意图是“添加一个‘缓存’类型的节点并建立它与‘User Service’和‘PostgreSQL’的连接”。调用modify_diagram工具传入现有图表的状态和我的修改指令。MCP服务器执行修改操作。关键在这里它不是简单地把新节点放在某个随机位置。它会将新的Redis缓存节点插入到现有的图结构中。重新运行布局算法根据新的拓扑结构再次计算所有节点的最优位置。这意味着整个图表会进行一次优雅的重新排列新加入的节点会自然地融入现有布局所有重叠和交叉都会被重新优化。保持所有已有的样式。最终我得到的是一个更新后、布局依然完美的图表。这个过程模拟了真实设计讨论中我们在白板上不断添加、移动便利贴的体验但完全由自然语言驱动。4.3 场景三转换现有Mermaid图表很多文档里已经用Mermaid写了流程图但想要更美观、可交互的版本。我的指令“帮我把下面的Mermaid流程图转换成Excalidraw图表。”然后我粘贴一段Mermaid代码例如graph TD A[客户端请求] -- B{Nginx网关} B -- C[用户服务] B -- D[订单服务] C -- E[(PostgreSQL)] D -- F[(Redis)]AI的思考与行动AI识别出这是mermaid_to_excalidraw工具的适用场景。它解析我提供的Mermaid语法提取出节点和边的信息。调用mermaid_to_excalidraw工具将解析出的结构传递给MCP服务器。MCP服务器进行转换。这里有一个细节Mermaid中的[(PostgreSQL)]语法可能被映射为database类型从而触发PostgreSQL的专属样式。而普通的[ ]方块可能被映射为默认的service类型。同样经过布局引擎的计算输出一个视觉效果远超原Mermaid文本的Excalidraw图表。避坑技巧在转换复杂的Mermaid图时有时AI对Mermaid语法的解析可能不完美。一个更稳妥的做法是先让AI用create_diagram工具根据你对流程的文字描述重新生成。这样能更好地利用MCP的样式库和布局能力。5. 深入原理布局引擎与样式系统要真正用好这个工具有必要稍微深入了解下它的两大核心技术支柱布局引擎和样式系统。这能帮助你在指令不理想时知道如何调整。5.1 Sugiyama分层布局算法浅析MCP服务器使用的Sugiyama算法是绘制有向无环图DAG的经典算法。它的目标就是产生“层次清晰、边交叉少、边长短”的布局。其工作流程可以简化为四步环移除如果图中存在循环比如A-B, B-C, C-A算法会暂时反转一些边的方向将其变为无环图以便布局最后再恢复。节点分层算法将所有节点分配到不同的水平层Layer上。理想情况下所有的边都从上一层指向下一层。它会通过一个称为“最长路径”或“网络单纯形”的方法来最小化边的跨度。同层节点排序在每一层内部调整节点的左右顺序目标是减少边与边之间的交叉。这是一个NP难问题算法会使用启发式方法如重心法来找到一个好的解。计算最终坐标根据层序和同层排序为每个节点分配具体的(x, y)坐标并绘制边。边通常被绘制为带有“弯折点”的折线或曲线以绕过中间的节点。这解释了为什么生成的图总是“从左到右”或“从上到下”流向清晰且盒子很少重叠。因为算法在底层就强制了这种层次结构。当你看到网关节点被自动拉宽那是因为算法识别出它是一个连接了多个下层节点的“枢纽”为了视觉清晰将其尺寸进行了调整。5.2 技术组件样式库样式库是一个将技术关键词映射到视觉属性的查找表。在MCP服务器的代码中可能有一个类似下面的Python字典TECH_STYLES { “postgresql”: { “backgroundColor”: “#336791”, “icon”: “database”, “strokeColor”: “#1e4a6e” }, “kafka”: { “backgroundColor”: “#231f20”, “icon”: “message-square”, “strokeColor”: “#000000” }, “redis”: { “backgroundColor”: “#a41e11”, “icon”: “zap”, “strokeColor”: “#8a1a0f” }, “nginx”: { “backgroundColor”: “#009639”, “icon”: “layers”, “strokeColor”: “#006b2d” }, # ... 更多技术 }当AI在节点描述中使用了“type”: “database”, “label”: “PostgreSQL”时MCP服务器会匹配“postgresql”关键词并应用对应的蓝色背景和数据库图标。如果标签是“MySQL”它可能匹配到同一个“database”类型但使用不同的颜色。注意事项样式匹配依赖于AI使用的标签名称。尽量使用标准的技术名称如“Kafka”而不是“消息队列”以确保能触发正确的样式。你可以在Skill文件中自定义或扩展这个映射关系。6. 高级技巧与最佳实践经过一段时间的深度使用我总结出一些能让excalidraw-architect-mcp发挥更大效能的技巧。6.1 编写更有效的AI指令模糊的指令导致模糊的结果。要让AI生成你想要的图指令需要具体。不佳指令“画一个系统架构图。”优秀指令“创建一个三层Web应用架构图。前端是React SPA通过CDNCloudFront分发。后端是一个REST API服务用Node.js表示连接一个PostgreSQL数据库和一个Redis缓存。后端部署在Docker容器中由Kubernetes编排。请使用从左到右的数据流方向。”关键要素明确层级和边界如“三层架构”。指定技术栈使用具体的名称React, PostgreSQL, Redis, Kubernetes。指明数据流向“从左到右”。定义范围说明是“高层级概览”还是“详细数据流”。6.2 管理复杂性与多图表策略再强大的自动布局也解决不了信息过载的问题。一个包含50个节点的图表无论如何排列都难以阅读。策略遵循Skill文件中的建议进行分层分解。Level 1 - 上下文图显示系统与外部用户、系统的交互。节点数8。Level 2 - 容器图显示系统内部的主要进程、容器、存储。节点数在6-15之间。Level 3 - 组件图深入某个服务内部显示其关键类和模块。节点数在10-25之间。你可以这样指挥AI“为我们的‘订单处理系统’先创建一个容器级架构图聚焦于微服务、数据库和消息队列。” 生成并保存后 “现在为其中的‘支付服务’创建一个组件级详细图展示其内部的控制器、业务逻辑层、数据访问层以及与外部支付网关的交互。”6.3 与Excalidraw生态无缝集成生成的.excalidraw文件是标准格式这带来了巨大的灵活性。在VS Code中编辑安装“Excalidraw Editor”扩展可以直接在VS Code或Cursor中打开.excalidraw文件进行微调比如移动一两个你觉得位置不够好的图标或者添加一些手绘风格的注释。导入Excalidraw.com将文件拖入 excalidraw.com 的网页可以启动在线协作邀请同事一起评审、修改。导出为图像在Excalidraw中可以轻松导出为PNG、SVG嵌入到你的设计文档、Confluence或PPT中。版本控制.excalidraw文件是JSON格式可以很好地被Git管理。你可以看到架构图随着代码的演变历史。6.4 自定义与扩展如果你是Python开发者这个项目是开源的意味着你可以深度定制。添加自定义样式你可以fork项目在样式库中添加你们公司内部特有的技术栈或组件样式。调整布局参数觉得默认的节点间距太大或太小可以修改布局算法中的间距、层距等参数。开发新工具MCP协议是开放的。理论上你可以让这个服务器做更多事比如从Kubernetes清单文件自动生成部署拓扑图。7. 常见问题与故障排查在实际使用中你可能会遇到一些问题。以下是我遇到和收集的一些典型情况及其解决方法。问题现象可能原因解决方案Cursor AI完全不响应图表相关指令或说“没有可用工具”。1. MCP配置未生效。2.excalidraw-architect-mcp命令在系统PATH中找不到。1.重启Cursor确保完全关闭所有Cursor进程再打开。2.检查配置路径确认mcp.json文件在正确位置项目目录或用户主目录。3.验证命令在终端直接运行excalidraw-architect-mcp --help看是否正常输出。如果不检查pip安装或uv安装。AI生成了图表描述但调用MCP工具后报错或返回空结果。1. AI生成的节点/边数据结构不符合MCP工具预期。2. 图表过于复杂超出处理能力。1.简化指令让AI生成更小、更简单的图表。2.检查Skill确保已安装Diagram Design Skill引导AI生成规范的结构。3.查看日志在Cursor设置中开启MCP调试日志如果支持查看具体错误信息。生成的图表布局奇怪节点堆在一起或跑到画布外。1. 图中存在意外的循环依赖干扰了分层布局算法。2. 节点标签过长影响了间距计算。1.审查关系检查你的描述中是否存在循环逻辑如A依赖BB又依赖A。尝试简化关系使其更接近有向无环图。2.使用简短标签节点名称尽量简短详细说明可以放在后续文档中。技术组件没有显示预期的颜色或图标。AI在节点描述中使用的type或label未能匹配到内置样式库。1.使用标准技术名在指令中明确使用“PostgreSQL”、“Kafka”、“Redis”等标准名称。2.手动指定类型在指令中尝试明确告诉AI“请将‘我们的消息中间件’节点的类型设置为‘message_queue’标签为‘Kafka’。”想修改的图表找不到或AI无法识别“当前图表”。AI的上下文丢失了之前生成的图表引用。1.上传文件将之前生成的.excalidraw文件直接上传到当前AI聊天会话中。2.明确引用在指令中提供图表的文件名或唯一标识。一个典型的排查流程从简单开始先用一个非常简单的指令测试如“画一个包含客户端、服务器和数据库的三节点图”确认整个链路是通的。检查配置如果简单指令也失败回头检查安装和配置步骤尤其是重启Cursor这一步。分步验证观察AI的思考过程。它是否识别出了应该使用create_diagram工具它构建的JSON结构是否合理你可以要求AI“只输出你准备发送给MCP工具的结构化数据先不要调用”以此来检查中间产物。查阅源码与社区项目是开源的遇到复杂问题可以去GitHub仓库的Issue页面搜索或提问。这个工具代表了一种高效的AI应用模式让专业的人或工具做专业的事。AI负责理解和翻译你的意图而专门的引擎负责执行精确、复杂的计算任务。它解决的远不止是“画图”这个表面问题更深层次的是降低了系统设计思维的可视化门槛让开发者能更流畅地将脑海中的架构转化为可协作、可迭代、可存档的视觉资产。无论是用于新人的入职引导、技术方案评审还是单纯的个人学习笔记它都能显著提升效率和质量。我个人的工作流已经深度整合了它每当需要梳理思路或向他人解释一个复杂设计时我的第一反应不再是打开绘图软件而是对AI说“来帮我把这个画出来看看。”