Excalidraw架构图AI分析：基于MCP协议实现草图智能解析与转换-编程实验室

1. 项目概述：当白板工具遇上AI架构师

如果你和我一样，经常在白板上画架构图、流程图，然后花大量时间整理成规范的文档，那你一定会对这个项目感兴趣。excalidraw-architect-mcp不是一个独立的应用，而是一个MCP（Model Context Protocol）服务器。它的核心价值在于，将我们熟悉的、自由手绘风格的 Excalidraw 白板，与强大的 AI 助手（比如 Claude Desktop）无缝连接起来。

简单来说，它让 AI 助手“看懂”了你的草图。你不再需要费力地向 AI 描述：“这里有一个用户，通过 API Gateway 访问 Lambda 函数，后面连着 DynamoDB...”。你只需要在 Excalidraw 上画出这个草图，然后直接问你的 AI 助手：“帮我分析一下这个架构的瓶颈在哪里？” 或者 “把这个架构图转换成 PlantUML 代码。” 这个 MCP 服务器就是中间的“翻译官”和“执行器”。

我最初接触这个项目，是因为在团队协作中，架构评审经常在白板上进行，但后续的文档化、合规检查、成本估算都是繁琐的重复劳动。这个工具的出现，相当于给我们的创意和讨论过程装上了一套自动化流水线。它解决的不仅仅是“画图”的问题，更是“理解图”、“分析图”和“基于图进行创作”的问题。无论你是架构师、开发者，还是产品经理，只要你的工作流中涉及可视化设计和系统思考，这个工具都能显著提升你的效率。

2. 核心原理与MCP协议解析

要理解excalidraw-architect-mcp的价值，必须先搞懂 MCP 是什么。MCP，全称 Model Context Protocol，是由 Anthropic 公司提出的一种开放协议。你可以把它想象成 AI 模型的“外设驱动标准”。

2.1 MCP：AI的“手”和“眼”

在没有 MCP 之前，像 Claude、ChatGPT 这样的 AI 助手，其能力主要局限于文本对话。它们知道很多事情，但无法直接操作你的电脑、读取特定格式的文件或与专业软件交互。MCP 协议定义了一套标准，允许开发者创建“服务器”（Server）。这些服务器就像一个个专用的工具包，AI 模型可以通过标准的“调用”方式，使用这些工具。

excalidraw-architect-mcp就是一个这样的工具包服务器。它向 AI 模型（如 Claude）暴露了几个关键能力：

读取（Read）：从指定的 Excalidraw 文件（.excalidraw或.excalidrawlib）中解析出所有图形元素、文字、箭头连接关系。
分析（Analyze）：理解这些元素构成的语义，比如识别出哪些矩形代表“服务”，哪些箭头代表“数据流”，哪些图标是“数据库”。
转换（Transform）：将 Excalidraw 的图形数据转换成其他格式，如 PlantUML、Mermaid、甚至 Markdown 表格形式的架构描述。
生成（Generate）：基于对现有图的理解，创建新的、符合某种规范或模板的图形元素。

当你在 Claude Desktop 中安装了对应的 MCP 服务器后，Claude 就“获得”了这些能力。你上传一个 Excalidraw 文件，Claude 在背后会通过 MCP 协议调用这个服务器，获取文件的结构化信息，然后基于这些信息来回答你的问题或执行你的指令。

2.2 项目架构拆解

这个项目的代码结构清晰地反映了其作为 MCP 服务器的定位：

excalidraw-architect-mcp/ ├── src/ │ ├── tools/ # 核心工具定义 │ │ ├── analyze.ts # 架构分析工具 │ │ ├── convert.ts # 格式转换工具 │ │ └── ... # 其他工具（如生成、验证） │ ├── parsers/ # 解析器 │ │ └── excalidrawParser.ts # 解析.excalidraw JSON结构 │ ├── converters/ # 转换器 │ │ ├── plantUMLConverter.ts │ │ ├── mermaidConverter.ts │ │ └── ... │ └── server.ts # MCP服务器主入口 ├── package.json └── ...

核心工作流如下：

用户指令：你在 Claude 中输入：“请分析我上传的aws-architecture.excalidraw文件中的安全风险。”
MCP调用：Claude 识别出这是一个需要调用excalidraw-architect工具的请求，通过 MCP 协议向本地运行的excalidraw-architect-mcp服务器发送请求，附上文件路径和操作指令（analyze_architecture）。
服务器处理：服务器收到请求后，启动对应的工具（如src/tools/analyze.ts）。该工具会：
- 调用解析器（excalidrawParser）读取并解析 JSON 文件。
- 遍历所有图形元素，应用一套内置的“语义理解”规则（例如，包含“DB”文字的矩形可能是数据库；红色箭头可能表示错误流）。
- 执行安全检查逻辑（例如，识别出公网可访问的组件是否缺少防火墙、敏感数据是否明文传输）。
结果返回：服务器将分析结果（一段结构化的文本报告）通过 MCP 协议返回给 Claude。
AI整合回复：Claude 接收到这份报告，结合其自身的知识库，组织成一段易于理解的、带有建议的自然语言回复呈现给你。

注意：MCP 服务器运行在你的本地环境，你的 Excalidraw 文件数据不会上传到云端（除非你使用的 AI 助手本身有上传功能）。这为处理敏感的企业架构图提供了良好的隐私基础。

3. 环境配置与实战安装指南

理论讲完了，我们动手把它跑起来。整个过程可以分为三步：配置 Claude Desktop、安装 MCP 服务器、进行连接测试。我会以 macOS 环境为例，Windows 和 Linux 用户只需在命令上稍作调整。

3.1 前置条件准备

首先，确保你的系统已经具备以下环境：

Node.js: 版本 18 或更高。这是运行该 MCP 服务器的基础。可以在终端输入node -v检查。
Claude Desktop: 从 Anthropic 官网下载并安装。这是目前最主流的使用 MCP 的客户端。
Git: 用于克隆项目代码。
一个 Excalidraw 文件：用于测试。你可以从 Excalidraw 官网画一个简单的流程图并导出为.excalidraw文件，或者用项目提供的示例文件。

3.2 安装 MCP 服务器

项目的安装方式非常灵活，提供了两种主流方法：直接从源码运行，或者通过@modelcontextprotocol的 CLI 工具安装。

方法一：源码运行（推荐，便于调试和自定义）

克隆项目：打开终端，找一个合适的目录，执行以下命令。

git clone https://github.com/BV-Venky/excalidraw-architect-mcp.git cd excalidraw-architect-mcp

安装依赖：项目使用 TypeScript 开发，需要安装依赖包。
```
npm install
```
实操心得：如果遇到网络问题，可以尝试配置 npm 镜像源：npm config set registry https://registry.npmmirror.com。安装完成后，建议运行一次npm run build来编译 TypeScript 代码，确保没有语法错误。
运行服务器：你可以直接使用npm start来启动服务器。但更常见的做法是使用npx直接运行编译后的入口文件。查看package.json中的bin字段，通常配置了启动命令。

方法二：使用 MCP CLI 工具安装（最简洁）

Anthropic 提供了一个官方的 MCP 服务器管理工具mcp，可以通过它直接安装社区发布的服务器。

安装 MCP CLI：

npm install -g @modelcontextprotocol/cli

安装 excalidraw-architect 服务器：
```
mcp install excalidraw-architect
```
这个命令会自动从 npm 仓库或 GitHub 找到对应的包并进行安装配置。这是最“傻瓜式”的方法，适合不想折腾的用户。

3.3 配置 Claude Desktop

这是最关键的一步，告诉 Claude Desktop 去哪里找我们刚刚安装的“工具”。

打开Claude Desktop应用。
进入配置界面。在 macOS 上，点击顶部菜单栏的Claude->Settings...->Developer标签页。在 Windows 上，通常在设置或高级选项中。
找到MCP Servers配置部分。这里是一个 JSON 数组，用于配置多个 MCP 服务器。
编辑配置。你需要添加一个如下所示的配置块：

{ "mcpServers": { "excalidraw-architect": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/YOUR/excalidraw-architect-mcp/build/index.js" ] } } }

重要参数解释：

"excalidraw-architect"：这是你给这个服务器起的名字，Claude 内部会引用它。
"command": "node"：指定用 Node.js 环境来运行这个服务器。
"args"：这里的路径必须替换为你本地项目的绝对路径，指向编译后的入口文件（通常是build/index.js或dist/index.js）。如果你使用方法二（mcp install）安装，配置可能会自动生成，路径也不同。

踩坑记录：最大的坑就是路径问题。一定要使用绝对路径。在 macOS/Linux 上，可以在终端进入项目build目录，输入pwd命令获取完整路径。在 Windows 上，右键点击文件“属性”可以查看路径。路径错误会导致 Claude 无法启动服务器，在开发者工具的控制台（View->Developer->Toggle Developer Tools）中可以看到连接失败的报错。

保存配置并完全重启 Claude Desktop。仅仅关闭窗口不行，需要从任务栏/程序坞彻底退出再重新打开。

3.4 验证安装成功

重启 Claude 后，如何确认工具已经就绪？

直接询问：在 Claude 的聊天框中输入：“你现在有哪些可用的工具？” 或者 “What tools do you have access to?”。如果配置成功，Claude 的回复中应该会列出excalidraw-architect及相关工具，例如analyze_excalidraw,convert_to_plantuml等。
查看日志：启动 Claude 时，如果你打开了开发者工具的控制台，在Console标签页下，可以看到 MCP 服务器初始化的日志，如[MCP] Starting server: excalidraw-architect，连接成功后会有相应提示。
进行测试：上传一个简单的.excalidraw文件，然后对 Claude 说：“请描述一下这个图里画了什么。” 如果 Claude 能够准确说出图中的形状、文字和连接关系，而不是让你“上传图片”，那就说明 MCP 服务器正在正常工作，Claude 已经能“看懂”Excalidraw 文件了。

4. 核心功能深度体验与用例解析

安装配置只是开始，真正的威力在于如何使用。excalidraw-architect-mcp提供了一系列工具，我们可以把它们归纳为四大类：解析洞察、格式转换、智能生成和架构治理。下面我们结合具体场景，看看如何用它来解决实际问题。

4.1 场景一：从草图到规范文档（解析与转换）

痛点：在头脑风暴会议中，我们在 Excalidraw 上快速绘制了一个微服务架构草图。会议结束后，我需要将其整理成团队知识库要求的 PlantUML 格式，并附上一份架构说明文档。

传统做法：对照草图，手动在 PlantUML 编辑器里重新绘制，并撰写文档。耗时耗力，且容易出错。

使用 MCP 的工作流：

将会议产生的.excalidraw文件保存到本地。
在 Claude 中上传该文件。
给 Claude 指令：“将这张架构图转换为 PlantUML 代码，并生成一份 Markdown 格式的架构概述，包括服务组件列表、数据流向说明和潜在的单点故障。”
Claude 会调用convert_to_plantuml和analyze_architecture工具。
几秒钟后，你得到两份输出：
- 一份可以直接粘贴到 PlantUML 渲染工具中的代码。
- 一份结构清晰的 Markdown 文档。

背后的技术细节：convert_to_plantuml工具并不是简单地把矩形变成rectangle，箭头变成-->。它尝试进行语义映射。例如，Excalidraw 中一个画了数据库圆柱图标的矩形，会被映射为 PlantUML 的database组件。箭头上的文字标签，会被转换为->上的注释。工具还会尝试保持图形的相对布局，虽然 PlantUML 是自动布局，但通过分组和注释，可以尽量还原设计意图。

4.2 场景二：架构评审与风险分析（智能分析）

痛点：作为 Tech Lead，我需要评审团队提交的架构设计图，快速识别出不符合最佳实践或存在安全隐患的设计。

传统做法：凭经验肉眼扫描，在图上做标记，然后写评审意见。对于复杂架构，容易遗漏。

使用 MCP 的工作流：

收到架构图文件。
指令：“分析此架构图，列出所有面向公网的服务组件，检查它们是否都有负载均衡器或防火墙保护。同时，识别图中是否存在数据存储组件直接暴露给前端的情况。”
Claude 调用analyze_architecture工具，并可能结合其自身的网络安全知识。
输出一份检查清单，例如：
- [风险] 组件 ‘UserAPI’ (矩形) 被标记为‘Public’，但未连接到任何负载均衡器图形。
- [建议] 组件 ‘Frontend’ 直接连接到 ‘Redis Cache’。建议增加一个API层进行隔离。
- [合规] 所有数据库组件均位于标记为‘Private Subnet’的区域内，符合安全规范。

工具的能力边界：需要注意的是，这种分析基于图形元素的文本标签和相对位置。如果设计师没有用“Public”、“DB”等文字标签，或者安全组、防火墙是以非标准图形表示的，工具可能无法识别。因此，它更适合作为辅助审查和提示，而非完全自动化的审计工具。团队可以借此约定一些 Excalidraw 绘图规范（比如用特定颜色表示网络区域，用固定图标表示组件类型），从而最大化工具的效用。

4.3 场景三：快速原型与迭代（智能生成）

痛点：我需要为一个新的“文件上传处理管道”设计架构。我从一个基础模板开始，但想快速生成几个备选方案（如使用 SQS 队列 vs. 使用 Kafka）。

传统做法：复制粘贴基础图，然后手动修改组件和连线，效率低下。

使用 MCP 的工作流：

准备好一个基础的、包含“用户上传”、“处理服务”、“存储”三个元素的 Excalidraw 文件。
指令：“基于我上传的草图，生成一个引入消息队列（用标准队列图标）进行异步解耦的变体架构图。请输出新的 Excalidraw JSON 内容。”
Claude 调用generate_variant或类似工具（如果项目实现了的话），理解当前架构的意图，并插入一个消息队列组件，重新连接箭头。
你获得一段新的 Excalidraw JSON 代码。你可以将其保存为.excalidraw文件并打开，就得到了一个衍生设计。

进阶用法：你甚至可以要求：“生成三个不同的高可用方案，分别基于主动-被动、多活区域和负载均衡器集群。” AI 会利用其对架构模式的知识，结合 MCP 工具的图形生成能力，快速产出可视化草图，极大地加速了设计探索阶段。

4.4 场景四：架构资产管理与知识沉淀（治理与转换）

痛点：公司内有成百上千个历史架构图，格式不一（Visio, PPT, 图片），难以搜索、管理和复用。

使用 MCP 的工作流：

标准化：利用convert_to_mermaid工具，将所有能转换为 Excalidraw 的架构图，统一转换成 Mermaid 文本格式。Mermaid 是文本化的图表语言，非常适合用 Git 进行版本管理。
建立索引：使用analyze_architecture工具批量处理这些图表，提取关键元数据（如组件类型、技术栈关键词、创建者），存入一个简单的数据库或索引文件。
智能检索：当需要查找“所有使用了 Kafka 和 Redis 的架构”时，可以直接询问 Claude：“在我们的架构资产库中，找出所有包含 Kafka 和 Redis 组件的设计图。” Claude 可以通过调用工具查询索引，快速定位相关文件。
文档同步：当架构图更新后，可以自动触发流程，重新生成对应的 PlantUML 代码和 Markdown 文档，确保知识库的实时性。

这个场景将excalidraw-architect-mcp从一个单点工具，提升到了架构治理流水线的核心环节。它成为了连接可视化设计、机器可读架构描述和知识库的桥梁。

5. 高级技巧与自定义开发指南

当你熟悉了基本用法后，你可能会不满足于开箱即用的功能。好消息是，作为一个开源项目，excalidraw-architect-mcp具有很强的可扩展性。你可以根据自己的需求定制分析规则、增加新的转换器，甚至集成内部工具。

5.1 理解工具定义与扩展点

所有 MCP 工具都在src/tools/目录下定义。每个工具都是一个函数，接收参数，执行逻辑，返回结果。我们以analyze_architecture为例，看看如何修改。

打开src/tools/analyze.ts，你会看到类似的结构：

export const analyzeArchitectureTool: McpTool = { name: "analyze_architecture", description: "Analyzes an Excalidraw file for architectural insights...", inputSchema: { type: "object", properties: { filePath: { type: "string", description: "Path to the .excalidraw file" }, analysisType: { type: "string", enum: ["security", "cost", "performance", "general"], description: "Type of analysis to perform" } }, required: ["filePath"] }, handler: async (args: any) => { const { filePath, analysisType = "general" } = args; // 1. 读取并解析文件 const elements = await parseExcalidrawFile(filePath); // 2. 根据 analysisType 应用不同的分析规则 const insights = []; if (analysisType === "security") { insights.push(...checkSecurity(elements)); } else if (analysisType === "cost") { insights.push(...estimateCost(elements)); } // 3. 返回结果 return { content: [{ type: "text", text: `Analysis Results:\n${insights.join('\n')}` }] }; } };

自定义分析规则：如果你想增加一个“合规性”检查（比如检查是否包含了数据隐私声明组件），你可以：

在analysisType的enum中添加"compliance"。
在handler函数中添加对应的else if (analysisType === "compliance")分支。
实现一个checkCompliance(elements)函数，遍历图形元素，应用你的业务规则。

5.2 添加新的输出格式转换器

假设你的团队使用C4 Model进行架构设计，你需要将 Excalidraw 图转换成Structurizr DSL（一种用于 C4 模型的文本语言）。

创建新转换器：在src/converters/目录下新建一个文件structurizrConverter.ts。
实现转换逻辑：编写一个函数，接收解析后的 Excalidraw 元素数组，遍历它们，识别出人物、软件系统、容器、组件等 C4 元素（通常需要依赖约定的图形标签或颜色），然后生成对应的 Structurizr DSL 代码字符串。
暴露新工具：在src/tools/convert.ts中，导入你的新转换器，并在convertTool的handler函数中增加对新格式（如"structurizr"）的支持。
重建并重启：运行npm run build重新编译项目，然后重启 Claude Desktop 使新工具生效。

5.3 与企业内部系统集成

更强大的用法是将这个 MCP 服务器与你公司的内部系统打通。例如：

与 CMDB 集成：在analyze_architecture工具中，当识别出一个 AWS S3 图标时，不仅提示这是一个存储服务，还可以通过调用内部 CMDB 的 API，查询公司实际使用了多少个 S3 Bucket，并附上链接。
与成本中心集成：在成本分析中，识别出“EC2”和“RDS”组件后，可以调用云成本管理平台的 API，获取类似规格资源的月度预估费用，使分析报告更具实际指导意义。
自动生成工单：识别出安全风险后，工具可以自动调用 Jira 或 ServiceNow 的 API，创建一条“安全加固”待办事项，并分配给相应的运维团队。

实现这些集成的关键在于，你可以在工具的handler函数中自由地引入任何 Node.js 库，发起网络请求，处理返回数据，然后将丰富后的信息返回给 AI。这样，Claude 就成为了一个能够调用你整个技术栈能力的超级助手。

开发心得：在自定义开发时，务必做好错误处理。网络请求可能会失败，内部 API 的格式可能会变化。在handler函数中使用try...catch，并返回清晰的错误信息给 Claude，这样用户才能知道问题出在哪里。另外，考虑到 MCP 调用可能有超时限制，复杂的集成操作最好设计成异步或只返回关键摘要。

6. 常见问题、故障排查与优化建议

在实际使用和开发扩展的过程中，你肯定会遇到各种问题。下面我整理了一些典型问题及其解决方法，以及让工具更好用的优化建议。

6.1 安装与连接问题

问题现象	可能原因	解决方案
Claude 回复“我没有这个功能”或工具列表里没有`excalidraw-architect`。	1. Claude Desktop 配置未生效。 2. MCP 服务器路径错误。 3. 服务器启动失败。	1.彻底重启Claude Desktop（完全退出再打开）。 2. 检查`claude_desktop_config.json`中的`args`路径，必须为绝对路径。 3. 打开 Claude Desktop 的开发者工具（`Toggle Developer Tools`），查看`Console`标签页有无红色错误日志。根据日志排查。
开发者工具 Console 中出现`[MCP] Server startup failed`错误。	1. Node.js 版本不兼容。 2. 项目依赖未安装或损坏。 3. 入口文件不存在。	1. 确保 Node.js >= 18。使用`node -v`检查。 2. 进入项目目录，删除`node_modules`和`package-lock.json`，重新运行`npm install`。 3. 确认`build/index.js`或`dist/index.js`文件存在。如果不存在，运行`npm run build`。
工具调用超时或无响应。	1. 工具处理逻辑太复杂，耗时过长。 2. 文件路径不存在或权限不足。	1. 对于大型 Excalidraw 文件，分析可能需要时间。可以尝试优化代码，或先处理小文件测试。 2. 确保 Claude Desktop 有权限读取你指定的文件路径。

6.2 功能使用问题

问题现象	可能原因	解决方案
Claude 无法正确识别图中的组件（如把数据库说成普通方框）。	工具依赖文本标签或特定图形库进行语义识别。如果绘图时使用了自由绘制或非标准图标，识别率会下降。	1.建立绘图规范：团队约定使用 Excalidraw 内置的“Library”中的标准图标，如“Database”、“Cloud”、“Server”等。 2.善用文本标签：在图形内部或旁边添加明确的文字标签，如“MySQL DB”、“API Gateway”。工具主要靠文字理解意图。 3. 向项目提 Issue 或 PR，增加对更多图形样式的识别规则。
转换生成的 PlantUML/Mermaid 代码布局混乱，不符合原图。	Excalidraw 是自由画布，而 PlantUML/Mermaid 是自动布局引擎。转换器只能尽力映射关系，无法完美复现绝对位置。	1.接受自动布局：将生成的代码视为逻辑关系的准确描述，而非视觉复刻。对于演示文档，逻辑正确比布局一致更重要。 2.手动调整：以生成的代码为基础，在 PlantUML 编辑器中手动调整布局指令（如`together`，`-down->`等），这是最可控的方式。 3. 考虑使用 Excalidraw 的“框架”或“分组”功能，转换器可能会尝试将这些结构映射为子图或分组。
分析报告过于笼统或不准。	内置的分析规则相对通用，可能不符合你所在领域或公司的特定规范。	自定义规则：这是开源项目的优势。参考第5章，修改`src/tools/analyze.ts`，加入你们团队的检查清单，例如“所有外部服务调用必须经过服务网格图标”、“数据存储必须标注加密状态”等。

6.3 性能与使用优化建议

处理大型文件：如果架构图非常复杂（元素超过500个），解析和转换可能会变慢。建议：
- 将大图拆分成多个逻辑相关的子图。
- 在进行分析时，通过指令让 Claude 只关注特定部分，例如：“仅分析图中‘支付模块’区域的组件（该区域用蓝色框标出）。”
结合 AI 提示词工程：工具提供了原始数据，但最终回复的质量也取决于你如何提问。例如：
- 低效提问：“分析这个架构。”
- 高效提问：“从高可用性、故障隔离和成本优化三个维度，分析此架构图。对于每个发现的问题，请提供具体的 AWS 或 Azure 服务改进建议。” 后一种提问方式能引导 Claude 结合其庞大的知识库和工具提供的数据，给出更具洞察力的答案。
建立团队知识库：将常用的分析指令、转换模板保存下来。例如，可以创建一个文本文件，里面包含你们团队标准的架构评审问题列表。每次评审新图时，将这个列表粘贴给 Claude，让它依次执行，确保评审的全面性和一致性。
版本控制你的配置和自定义规则：如果你对项目进行了自定义开发（如新增转换器、分析规则），务必将这些更改用 Git 管理起来。这样可以在团队内部分享，并随着上游项目的更新而方便地合并。

这个项目的魅力在于，它打开了一扇门，让静态的架构图“活”了起来，成为了可查询、可分析、可演化的数字资产。它不能替代架构师的思考和决策，但它能极大地压缩从创意到文档、从设计到评审、从现状到优化的中间过程。