excalidraw-editor-mcp

中文

An Excalidraw editor delivered as an MCP App for DeepSeek Harness (DSH). It uses the official @excalidraw/excalidraw component and stores standard .excalidraw files in the active DSH Workspace.

Features

• Managed multi-canvas projects and discovered standalone canvases.

• Semantic inspect and atomic revision-checked edits.

• Interactive inline/fullscreen editing with save, reload, conflict recovery, and Ask AI.

• Bounded local PNG, JPEG, GIF, and WebP assets. Network images are rejected.

• JSON, SVG, and PNG downloads through the MCP Host.

• Revision-bound Browser captures with a standard MCP PNG and text clipping diagnostics for AI verification.

• Self-contained App HTML, including all Excalidraw fonts; no runtime CDN is required.

Requirements

• Node.js >=22.19.0

• pnpm 10.25.0

• DSH Web with @creative-dswork/dsh-uni-editor

Build And Pack

pnpm install --frozen-lockfile
pnpm run release:check
pnpm pack --pack-destination .tmp

The package intentionally remains private: true at version 0.0.0. Before publishing, a maintainer must choose the release version, remove the private guard, inspect the tarball, and confirm third-party notices.

Configure DSH

Install the tarball into a directory and point DSH at its executable:

mkdir -p /absolute/path/to/excalidraw-mcp-install
cd /absolute/path/to/excalidraw-mcp-install
pnpm init
pnpm add /absolute/path/to/excalidraw-editor-mcp-0.0.0.tgz

Copy examples/dsh/cordis.patch.yml into the Web profile configuration and replace the placeholder paths. The essential server entry is:

- id: mcp-apps
  config:
    maxBodyBytes: 33554432
    servers:
      - serverName: excalidraw
        transport: stdio
        command: /absolute/path/to/excalidraw-mcp-install/node_modules/.bin/excalidraw-editor-mcp
        args: []
        cwd: /absolute/path/to/excalidraw-mcp-install
        forwardWorkspace: true

forwardWorkspace is required. The server accepts the Workspace only from trusted DSH request metadata. maxBodyBytes allows the Host to carry the self-contained App Resource and embedded fonts.

Validate and start the Web profile:

DSH_HOME="${DSH_HOME:-$HOME/.dsh}" pnpm dsh web --dump-config
DSH_HOME="${DSH_HOME:-$HOME/.dsh}" pnpm dsh web --host 127.0.0.1 --port 3080 --no-open

Open http://127.0.0.1:3080/, select a Workspace, and start a Session. Tools are exposed with the configured prefix, such as mcp__excalidraw__create_project.

AI Visual Verification

After an edit, keep the canvas View open and call capture_canvas with the exact saved revision. The View renders the canvas with Excalidraw's official exportToBlob API and returns:

• a standard MCP image/png content block;

• the image dimensions, SHA-256 digest, and capture time;

• bounded text diagnostics with stored width, measured width, overflow, and clipping state.

Image-capable models can inspect the PNG directly. If the selected model does not declare image input, DSH reports that limitation and the model can still use the text diagnostics. In that case, the result does not prove that the model inspected the pixels.

Safety Limits

• Asset source: regular file inside the active Workspace only; no URL, symlink, or hardlink.

• Asset types: PNG, JPEG, GIF, or WebP with a valid image header.

• Per asset: 1 MiB; decoded assets per canvas: 2 MiB.

• Dimensions: at most 8192 by 8192 and 32 million pixels.

• Canonical canvas document: 4 MiB.

• Model-visible tool result: 256 KiB.

• Harness capture: at most 1024 by 1024, 512 KiB of base64 image data, and 100 text diagnostics; one pending capture per Session connection with a 15-second timeout.

• All writes use revision checks; rejected mutations preserve the old file.

Development

pnpm typecheck
pnpm test
pnpm run release:check

Architecture and milestone details are in docs/DESIGN.md and docs/IMPLEMENTATION-PLAN.md.