使用Excalidraw MCP生成FastAPI图

一个FastAPI应用程序，使用以下命令生成交互式图表 排除MCP（模型上下文协议） 服务器。该系统自动从自然语言描述中检测图表类型，使用AI生成Excalidraw元素，并返回可共享的Excalidraw.com URL。

🎯 什么是MCP？

MCP（模型上下文协议） 是一种标准化协议，允许AI代理通过API调用与外部工具和服务交互。使用 JSON-RPC 2.0 对于请求和 服务器发送事件（SSE） 用于流式响应。

排除MCP服务器

端点: https://excalidraw-mcp-app.vercel.app/mcp

目的：根据元素定义创建交互式手绘样式的Excalidraw图，并将其导出到Excalidraw.com。

可用的MCP工具:

read_me：返回Excalidraw格式参考和备忘单
create_view：验证并创建图表，返回检查点ID
export_to_excalidraw：将图表导出到Excalidraw.com并返回可共享的URL

🔄 完整流程：从用户请求到响应

高水位流量

User Request → API Route → Use Case → Excalidraw Adapter → MCP Tools → Excalidraw.com URL

详细的分步流程

1.用户发送请求

发布 /api/v1/diagrams

{
  "description": "Draw the mathematical function y = e^x on a 2D coordinate system"
}

2.API路由收到请求

路线： src/api/routes/diagram_routes.py
端点： POST /api/v1/diagrams
使用验证输入 DiagramCreateInput 数据传输对象
呼叫 DiagramUseCase.generate_diagram()

3.用例编排流程

用例： src/application/use_cases/diagram_use_case.py
呼叫 ExcalidrawAdapter.create_diagram()
商店导致 diagram_store
退货 DiagramResponse 使用Excalidraw URL

4.排除适配器初始化组件

位置: src/infrastructure/adapters/outbound/excalidraw/excalidraw_adapter.py

适配器初始化：

MCP客户端：处理与MCP服务器的JSON-RPC 2.0通信
FormatReferenceFetcher：获取并缓存Excalidraw格式引用
DiagramTypeDetector：使用AI检测图表类型
元素生成器：使用AI生成Excalidraw元素
出口退税出口商：将图表导出到Excalidraw.com
图表创建者：协调整个流程

5.图表类型检测（可选）

组件: DiagramTypeDetector

使用Azure OpenAI分析描述
退货： flowchart, architecture, er_diagram，或 sketch
提示： src/infrastructure/prompts/diagram_type_detection.txt

6.格式引用获取（缓存）

组件: FormatReferenceFetcher

调用MCP工具： read_me
获取Excalidraw元素格式引用
缓存后续请求的结果
用于改进AI元素生成

MCP呼叫:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "read_me",
    "arguments": {}
  }
}

响应：返回包含元素格式、颜色和示例的综合备忘单

7.使用AI生成元素

组件: ElementGenerator

使用带有格式参考的Azure OpenAI
提示： src/infrastructure/prompts/elements_generation.txt
生成Excalidraw元素JSON数组
在提示中包含格式参考，以获得更好的结果
返回：JSON元素字符串数组

示例元素:

[
  {"type": "cameraUpdate", "width": 800, "height": 600, "x": 0, "y": 0},
  {"type": "rectangle", "id": "box1", "x": 100, "y": 100, "width": 200, "height": 100},
  {"type": "arrow", "id": "arrow1", "x": 300, "y": 150, "width": 100, "height": 0}
]

8.MCP工具： `create_view`

组件: MCPClient

目的：验证元素并创建图表，返回检查点ID

MCP呼叫:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_view",
    "arguments": {
      "elements": "[{\"type\":\"cameraUpdate\",...}]"
    }
  }
}

HTTP请求:

POST https://excalidraw-mcp-app.vercel.app/mcp
Headers:
  Content-Type: application/json
  Accept: application/json, text/event-stream
Body: JSON-RPC 2.0 payload

MCP服务器处理:

接收JSON-RPC 2.0请求
验证JSON字符串元素
解析元素数组
验证结构（第一个元素必须是 cameraUpdate)
使用Excalidraw库渲染图表
应用手绘风格（rough.js）
生成唯一的检查点ID
通过SSE流式传输响应

SSE回应:

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"structuredContent":{"checkpointId":"abc123"},"content":[{"type":"text","text":"Diagram displayed! Checkpoint id: \"abc123\"."}]}}

响应解析:

提取物 checkpointId 从 result.structuredContent.checkpointId
在以下情况下处理错误 isError: true 作为回应

9.MCP工具： `export_to_excalidraw`

组件: ExcalidrawExporter

目的：将图表导出到Excalidraw.com并返回可共享的URL

MCP呼叫:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "export_to_excalidraw",
    "arguments": {
      "json": "{\"type\":\"excalidraw\",\"version\":2,\"elements\":[...],\"appState\":{...}}"
    }
  }
}

完整的Excalidraw JSON文档:

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw-mcp-app.vercel.app",
  "elements": [...],
  "appState": {
    "gridSize": null,
    "viewBackgroundColor": "#ffffff"
  },
  "files": {}
}

响应：返回Excalidraw.com可共享URL

https://excalidraw.com/#json=,

备注：此工具可能只是小部件，但我们尝试调用它。如果失败，图表仍然会成功创建，只是没有可共享的URL。

10.储存和退货响应

存储: diagram_store.save(checkpoint_id, diagram_data)

响应:

{
  "status": "success",
  "diagram_type": "sketch",
  "message": "Diagram created successfully using MCP create_view tool. Shareable URL: https://excalidraw.com/#json=...",
  "view_url": "https://excalidraw.com/#json=...",
  "diagram_data": {
    "agent_summary": "Created sketch diagram using MCP create_view with 5 elements (checkpoint: abc123)",
    "diagram_type": "sketch",
    "excalidraw": {
      "type": "excalidraw",
      "version": 2,
      "elements": [...],
      "checkpointId": "abc123"
    },
    "excalidraw_url": "https://excalidraw.com/#json=..."
  }
}

🏗️ 建筑

组件组织

src/infrastructure/adapters/outbound/excalidraw/
├── excalidraw_adapter.py      # Main adapter (implements IDiagramService)
├── mcp_client.py              # MCP tool client (JSON-RPC 2.0)
├── format_reference.py        # Format reference fetcher
├── diagram_type_detector.py   # Diagram type detection (AI)
├── element_generator.py       # Element generation (AI)
├── excalidraw_exporter.py     # Export to Excalidraw.com
├── diagram_creator.py         # Flow orchestrator
└── json_utils.py              # JSON parsing utilities

组件责任

Excalidraw适配器：主要入口点，实现服务接口
MCP客户端：通过JSON-RPC 2.0处理所有MCP工具调用
FormatReferenceFetcher：从中获取和缓存格式引用 read_me
DiagramTypeDetector：使用AI从描述中检测图表类型
元素生成器：使用带有格式参考的AI生成元素
出口退税出口商：将图表导出到Excalidraw.com
图表创建者：协调整个流程

📡 MCP协议详细信息

协议：JSON-RPC 2.0

MCP对所有请求都使用JSON-RPC 2.0。这是一个无状态、轻量级的RPC协议。

请求格式

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "key": "value"
    }
  }
}

领域:

jsonrpc：协议版本（始终为“2.0”）
id：请求标识符（用于匹配响应）
method：MCP工具调用始终为“工具/调用”
params.name：工具名称（例如，“create_view”、“read_me”、“export_to_excalidraw”）
params.arguments：特定于工具的参数

响应格式：服务器发送事件（SSE）

MCP使用服务器发送事件格式进行响应：

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"structuredContent":{"checkpointId":"abc123"}}}

SSE格式规则:

每个事件都始于 event:
数据如下： data:
用空行分隔的事件(\n\n)
JSON必须正确转义

所需的HTTP标头

请求头:

Content-Type: application/json
Accept: application/json, text/event-stream

响应头 （来自MCP服务器）：

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

🛠️ MCP工具参考

1. `read_me` -获取格式参考

目的：返回全面的Excalidraw格式参考和备忘单

参数：无（空对象 {})

响应：包含元素格式、颜色、示例和提示的文本内容

用法：调用一次并缓存以用于后续请求

2. `create_view` -创建/验证图表

目的：验证元素并创建Excalidraw图

参数:

{
  "elements": "[{\"type\":\"cameraUpdate\",...}]"
}

关键要求:

elements 必须是JSON字符串，而不是对象
第一个元素必须是 cameraUpdate
必须是有效的JSON（无注释，无尾随逗号）

响应:

{
  "result": {
    "structuredContent": {
      "checkpointId": "abc123"
    },
    "content": [
      {
        "type": "text",
        "text": "Diagram displayed! Checkpoint id: \"abc123\"."
      }
    ]
  }
}

3. `export_to_excalidraw` -导出到Excalidraw.com

目的：将图表上传到Excalidraw.com并返回可共享的URL

参数:

{
  "json": "{\"type\":\"excalidraw\",\"version\":2,\"elements\":[...],\"appState\":{...}}"
}

响应：返回Excalidraw.com URL

https://excalidraw.com/#json=,

备注：此工具可能只是小部件，但我们无论如何都会尝试调用它。

📡 API终点

1.创建图表（标准）

发布 /api/v1/diagrams

请求:

{
  "description": "Draw the mathematical function y = e^x on a 2D coordinate system"
}

响应:

{
  "status": "success",
  "diagram_type": "sketch",
  "message": "Diagram created successfully using MCP create_view tool. Shareable URL: https://excalidraw.com/#json=...",
  "view_url": "https://excalidraw.com/#json=...",
  "diagram_data": {
    "agent_summary": "Created sketch diagram using MCP create_view with 5 elements (checkpoint: abc123)",
    "diagram_type": "sketch",
    "excalidraw": {
      "type": "excalidraw",
      "version": 2,
      "elements": [...],
      "checkpointId": "abc123"
    },
    "excalidraw_url": "https://excalidraw.com/#json=..."
  }
}

2.创建图表（SSE流）

发布 /api/v1/diagrams/stream

请求：与上述相同

响应：服务器已发送事件流，其中包含事件：

type_detected: {"diagram_type": "sketch"}
generating: {"status": "Generating diagram elements..."}
elements_ready: {"element_count": 5}
mcp_call: {"status": "Calling MCP create_view..."}
exporting: {"status": "Exporting to Excalidraw.com..."}
message: {"result": {"structuredContent": {"checkpointId": "...", "excalidraw_url": "..."}}}
error: {"error": "Error message"}

📝 使用示例

创建数学图

curl -X POST "http://localhost:8000/api/v1/diagrams" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Draw the mathematical function y = e^x on a 2D coordinate system. Show the X and Y axes and draw the curve in a hand-drawn Excalidraw style."
  }'

创建ER图

curl -X POST "http://localhost:8000/api/v1/diagrams" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "ER diagram: users table (id, name, email), products table (id, name, price), orders table (id, user_id, product_id, quantity). Users have many orders, products have many orders."
  }'

流图创建

curl -X POST "http://localhost:8000/api/v1/diagrams/stream" \
  -H "Content-Type: application/json" \
  -d '{"description": "Create a flowchart showing user login process"}' \
  --no-buffer

🚀 运行应用程序

# With Docker
docker compose up --build

# Local development
uvicorn src.main:app --reload

API网站： http://localhost:8000

📚 API 文档

Swagger用户界面: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

🔑 关键文件

适配器: src/infrastructure/adapters/outbound/excalidraw/excalidraw_adapter.py
MCP客户端: src/infrastructure/adapters/outbound/excalidraw/mcp_client.py
路线: src/api/routes/diagram_routes.py
提示: src/infrastructure/prompts/

- diagram_type_detection.txt - elements_generation.txt

配置: src/infrastructure/config/settings.py

- excalidraw_mcp_url：MCP服务器端点

📖 参考文献

MCP服务器: https://excalidraw-mcp-app.vercel.app
白板绘图: https://excalidraw.com
JSON-RPC 2.0: https://www.jsonrpc.org/specification
服务器发送的事件: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events

🎯 摘要

此应用程序与Excalidraw MCP服务器集成，以：

接受自然语言图描述
检测自动图表类型（流程图、架构、ER图、草图）
获取从MCP中删除格式参考 read_me 工具
生成使用具有格式参考的AI排除元素
验证使用MCP的元素 create_view 工具（返回检查点ID）
出口使用MCP将图表发送到Excalidraw.com export_to_excalidraw 工具
返回用户可共享的Excalidraw.com网址

MCP服务器处理所有复杂的图表渲染，确保手绘风格的图表一致，可以在Excalidraw.com上直接查看和编辑。

Excalidraw MCP Integration

快速接入

详细介绍

使用Excalidraw MCP生成FastAPI图

🎯 什么是MCP？

排除MCP服务器

🔄 完整流程：从用户请求到响应

高水位流量

详细的分步流程

1.用户发送请求

2.API路由收到请求

3.用例编排流程

4.排除适配器初始化组件

5.图表类型检测（可选）

6.格式引用获取（缓存）

7.使用AI生成元素

8.MCP工具： create_view

9.MCP工具： export_to_excalidraw

10.储存和退货响应

🏗️ 建筑

组件组织

组件责任

📡 MCP协议详细信息

协议：JSON-RPC 2.0

请求格式

响应格式：服务器发送事件（SSE）

所需的HTTP标头

🛠️ MCP工具参考

1. read_me -获取格式参考

2. create_view -创建/验证图表

3. export_to_excalidraw -导出到Excalidraw.com

📡 API终点

1.创建图表（标准）

2.创建图表（SSE流）

📝 使用示例

创建数学图

创建ER图

流图创建

🚀 运行应用程序

📚 API 文档

🔑 关键文件

📖 参考文献

🎯 摘要

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

8.MCP工具： `create_view`

9.MCP工具： `export_to_excalidraw`

1. `read_me` -获取格式参考

2. `create_view` -创建/验证图表

3. `export_to_excalidraw` -导出到Excalidraw.com