AI导哈

Excalidraw MCP 服务器

一个强大的模型上下文协议（MCP）服务器，使AI代理能够以编程方式创建高质量的Excalidraw图表。

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

使用说明

排除MCP服务器

一个强大的模型上下文协议（MCP）服务器，使AI代理能够以编程方式创建高质量的Excalidraw图。

特性

第1阶段（当前）✅

  • ✅ 核心HTTP和WebSocket服务器
  • ✅ MCP SDK与stdio传输的集成
  • ✅ 基本元素创建工具（矩形、文本、椭圆、菱形、箭头、直线）
  • ✅ 具有版本控制的内存状态管理
  • ✅ 并发修改的乐观锁定
  • ✅ 对所有输入进行Zod模式验证
  • ✅ 实时WebSocket广播
  • ✅ 基本集成测试

安装

先决条件

  • Node.js>=18.0.0
  • npm>=9.0.0

再进行

npm install

构建

npm run build

用法

在HTTP/WebSocket模式下运行

启动服务器以进行基于web的访问：

npm start

或者在自动重新加载的开发模式下：

npm run dev

服务器将于启动 http://localhost:3000 默认情况下。

在MCP模式下运行

⚠️ 备注：由于MCP SDK API的变化，MCP stdio模式目前正在开发中。HTTP/WebSocket模式功能齐全。

用于MCP客户端（Claude Desktop、Cursor等）：

npm run dev -- --mcp

这将以stdio模式启动服务器，用于MCP协议通信（当前正在调试）。

API终点

HTTP端点

健康检查

GET /health

返回服务器状态和元素计数。

获取所有元素

GET /api/elements

返回所有图表元素。

获取单个元素

GET /api/elements/:id

按ID返回特定元素。

透明画布

DELETE /api/elements

从画布中删除所有元素。

WebSocket事件

服务器向所有连接的客户端广播以下事件：

  • sync：完全状态同步（在连接时发送）
  • element_created：添加了新元素
  • element_updated：元素已修改
  • element_deleted：元素已移除

MCP工具

创建矩形

在画布上创建一个矩形元素。

参数：

  • id （字符串，必填）：唯一标识符
  • x （数字，必填）：X坐标
  • y （数字，必填）：Y坐标
  • width （数字，必填）：宽度
  • height （数字，必填）：高度
  • strokeColor （字符串，可选）：笔划颜色（十六进制）
  • backgroundColor （字符串，可选）：背景颜色（十六进制）
  • fillStyle （字符串，可选）：填充样式（八字形、十字图案、实心）
  • strokeWidth （数字，可选）：笔划宽度
  • strokeStyle （字符串，可选）：笔划样式（实线、虚线、虚线）

createText

在画布上创建一个文本元素。

参数：

  • id （字符串，必填）：唯一标识符
  • x （数字，必填）：X坐标
  • y （数字，必填）：Y坐标
  • text （字符串，必填）：文本内容
  • fontSize （数字，可选）：字体大小
  • fontFamily （数字，可选）：字体系列（1-4）
  • textAlign （字符串，可选）：文本对齐方式（左、中、右）

获取所有元素

从画布中获取所有元素。

参数： 无

发展

运行测试

npm test

运行覆盖率测试

npm run test:coverage

Lint代码

npm run lint

格式码

npm run format

建筑

核心组件

  • DiagramStore：具有版本控制和乐观锁定的内存存储
  • MCP服务器：通过stdio处理MCP协议通信
  • HTTP/WebSocket服务器：提供REST API和实时更新
  • Zod模式：所有操作的输入验证

元素版本控制

所有元素均包含 version 随着每次更新而递增的字段。这启用了乐观锁定以防止并发修改冲突（FR-006、FR-007、FR-008）。

批量操作

可以在单个操作中创建多个元素。如果批次中的任何元素无效，则整个批次将被拒收（FR-005a）。

配置

环境变量（可选）：

  • PORT：服务器端口（默认值：3000）
  • HOST：服务器主机（默认：localhost）

测试

该项目包括以下集成测试：

  • 元素创建和存储
  • 版本管理和乐观锁定
  • 具有回滚功能的批处理操作
  • 错误处理和验证

许可证

国际学生委员会

贡献

本项目遵循 specs/001-excalidraw-mcp-server/spec.md.

路线图

看 specs/001-excalidraw-mcp-server/plan.md 完整的实施计划。

即将到来的阶段

  • 第2阶段：实时同步增强和前端
  • 阶段3：使用SQLite实现图表持久化
  • 第四阶段：高级功能（智能定位、用户偏好）
  • 第5阶段：部署、测试和文件编制

相关 MCP