AI导哈

Excalidraw程序化创作服务器

一个自托管的MCP服务器，用于程序化创建和优化Excalidraw场景，提供高级创作辅助工具和质量分析功能。

  • by duhman
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 duhman/excalidraw-mcp

使用说明

提取mcp

excalidraw-mcp 是一个用于编程Excalidraw创作的自托管MCP服务器。

目标不仅仅是改变场景JSON。服务器为代理提供了一个比Excalidraw更安全的抽象，这样他们就可以：

  • 创建和优化场景，而无需手动管理脆弱的内部
  • 为节点、流、泳道、框架、层和样式使用更高级的创作助手
  • 出口前分析质量
  • 在最终抛光之前进行确定性清理
  • 通过本地Excalidraw捆绑包离线导出
  • 可选择将场景导入经过身份验证的Excalidraw/Excalidraw+帐户

文档

服务器中有什么

  • 场景生命周期、补丁、应用状态、文件、库项、Mermaid转换和导出
  • 确定性布局助手：
    • elements_arrange
    • layout_flow
    • layout_swimlanes
    • layout_polish
  • 高级创作助手：
    • diagram_compose
    • elements_create_skeletons
    • nodes_create
    • nodes_compose
    • frames_create
    • frames_assign_elements
    • styles_apply_preset
    • layers_reorder
  • 质量和维修助手：
    • scene_validate
    • scene_normalize
    • scene_analyze
    • scene_quality_gate
  • 资源包括：
    • excalidraw://scenes
    • excalidraw://scene/{sceneId}/summary
    • excalidraw://scene/{sceneId}/analysis
    • excalidraw://scene/{sceneId}/json
    • excalidraw://docs （捆绑技能参考索引）
    • excalidraw://docs/{topic} （例如。 excalidraw-troubleshooting, excalidraw-install-and-integration)
  • 规划、改进、转换和审查提示

代理工作流

推荐的代理循环：

  1. scene_analyze
  2. 确定性助手： nodes_compose, layout_swimlanes, layout_flow, layout_polish, styles_apply_preset, frames_assign_elements
  3. scene_validate
  4. scene_quality_gate
  5. export_svg / export_png / export_webp

使用 scene_normalize 首先，每当分析显示结构问题，如绑定损坏、容器反向链接丢失、文件丢失或几何无效时。

如果客户端支持MCP提示，请从 agent-workflow-guide 以获取首选工具选择策略的带内摘要。

样例：语义节点

{
  "name": "nodes_compose",
  "arguments": {
    "sceneId": "system-map",
    "preset": "process",
    "nodes": [
      {
        "nodeId": "api",
        "x": 120,
        "y": 140,
        "width": 240,
        "minHeight": 132,
        "title": "API Gateway",
        "body": "Receives requests, validates auth, and routes traffic.",
        "iconText": "API"
      }
    ]
  }
}

示例：泳道

{
  "name": "layout_swimlanes",
  "arguments": {
    "sceneId": "system-map",
    "laneArrangement": "columns",
    "originX": 40,
    "originY": 80,
    "laneWidth": 320,
    "laneHeight": 260,
    "lanes": [
      { "laneId": "lane-intake", "label": "Intake", "elementIds": ["api"] },
      {
        "laneId": "lane-processing",
        "label": "Processing",
        "elementIds": ["worker"]
      }
    ]
  }
}

质量模型

scene_analyze 报告：

  • 场景边界和图形摘要
  • 重叠和密集集群
  • 画布外元素
  • 连接器交叉口
  • 排版不一致
  • 不可读文本
  • 缺少标题和传说
  • 容器/框架/文件完整性问题
  • recommendedActions 这指向了确定性的下一代工具

layout_polish 故意保守。它解决了确定性布局问题，如重叠、间距、连接器标签重新居中，并支持文本重新平衡，而无需发明新的语义内容。

预设

内置预设：

  • process
  • decision
  • note
  • title
  • legend
  • accent
  • swimlane
  • boundary
  • supporting_text

所有高级创作助手共享相同的间距和排版比例：

  • 间距： 8 / 16 / 24 / 32 / 48 / 72
  • 文本： 30 / 18 / 16 / 14
  • 节点填充： 20
  • 车架/车道衬垫： 24

运行时模型

  • 用于确定性场景操作和规范化的JSON引擎
  • 本地浏览器引擎（Playwright+Chromium）用于离线Excalidraw本地导出
  • 本地Excalidraw运行时包已签入仓库，用于导出/修复奇偶校验
  • 工作空间支持的存储 .excalidraw-mcp/

安装

npm install

如果需要，请安装Playwright浏览器：

npx playwright install chromium

跑

工作室

npm run dev
# or
npm run start:stdio

超文本传输协议

npm run dev:http
# or
npm run start:http

可选环境变量：

  • MCP_HTTP_HOST 默认 127.0.0.1
  • MCP_HTTP_PORT 默认 8788
  • MCP_HTTP_PATH 默认 /mcp
  • MCP_WORKSPACE_ROOT 默认当前工作目录

克劳德客户

Claude Code和Claude Desktop都应该指向内置的stdio服务器：

node /Users/workboi/projects/excalidraw-mcp/dist/src/index.js --transport stdio

使用 MCP_WORKSPACE_ROOT=/Users/workboi/projects/excalidraw-mcp。完整的设置和验证命令位于 docs/CLAUDE_CLIENTS.md.

验证

主本地门：

npm test
npm run typecheck
npm run lint
npm run build

额外的烟雾路径：

npm run smoke:dist
npm run smoke:account:plus
npm run smoke:account:excalidraw

笔记：

  • smoke:dist 锻炼身体 dist 服务器通过stdio。
  • smoke:account:* 是选择加入手动检查，需要真正经过身份验证的浏览器会话。

视觉回归

该仓库包括结构夹具测试和已提交的规范化SVG goldens，用于：

  • 简单流程
  • 工艺板
  • 泳道板
  • 基于框架的体系结构

代理版本E2E覆盖范围还锻炼了MCP客户端的语义合成、手动修复、质量门和所有导出格式的工作流程。

仅故意刷新金币：

UPDATE_GOLDENS=1 npx vitest run test/integration/visual.goldens.test.ts

帐户链接快速入门

  1. 准备一个有头登录会话：
{
  "name": "account_login_session",
  "arguments": {
    "destination": "plus",
    "mode": "headed",
    "session": "main-profile",
    "timeoutSec": 300,
    "closeOnComplete": false
  }
}
  1. 导入场景：
{
  "name": "account_import_scene",
  "arguments": {
    "sceneId": "my-scene",
    "destination": "plus",
    "mode": "headed",
    "session": "main-profile",
    "allowInteractiveLogin": false
  }
}
  1. 检查最近的状态：
{
  "name": "account_link_status",
  "arguments": {
    "session": "main-profile"
  }
}

帐户结果现在包括显式 reasonCode 价值观如 READY, AUTH_NOT_READY, IMPORTED, IMPORT_STRATEGY_FAILED，以及 POST_IMPORT_VERIFICATION_FAILED.

演示

通过MCP服务器本身生成一个现实的销售流程板：

node scripts/demo-sales-process-board.mjs

文物被写在 tmp/generated/sales-process-overview/.

捆绑代理技能

这个仓库运送了一个Anthropic 代理技能 在 skills/excalidraw-agent/。它为代理客户提供了程序 在React/Next.js宿主应用程序中嵌入Excalidraw的指南，运行时故障排除 问题，并编排上述snake_case MCP工具。它的参考文件也是 由此MCP服务器作为 excalidraw://docs/{topic} 资源，因此仅MCP客户端可以 在没有文件系统访问权限的情况下读取它们。

通过符号链接目录安装到代理客户端：

ln -s "$PWD/skills/excalidraw-agent" ~/.claude/skills/excalidraw-agent      # Claude Code
ln -s "$PWD/skills/excalidraw-agent" ~/.codex/skills/excalidraw-agent       # Codex
ln -s "$PWD/skills/excalidraw-agent" ~/.cursor/skills/excalidraw-agent      # Cursor
ln -s "$PWD/skills/excalidraw-agent" ~/.config/zed/skills/excalidraw-agent  # Zed

验证技能元数据：

npx --yes skills-ref validate skills/excalidraw-agent

该技能不再发布自己的bash脚本——所有执行工作路线都通过MCP 此服务器中的工具。

对于代理作者

如果您要将此服务器连接到另一个代理堆栈，最佳的入职路径是：

  1. 读 docs/AGENT_PLAYBOOK.md
  2. 检查 docs/TOOL_REFERENCE.md
  3. 使用 agent-workflow-guide 提示
  4. 更喜欢 nodes_compose, layout_swimlanes, layout_flow, layout_polish，以及 styles_apply_preset 未经处理的修补
  5. 安装捆绑的 skills/excalidraw-agent 用于带内程序指导

相关 MCP