Users are now prompted to choose their preferred font family and roughness
style during both `setup` and `update`. Preferences are saved to
~/.claude/skills/excalidraw-skill/preferences.json, which the MCP server
already reads at startup via loadPreferences(). This ensures third-party
users who install via npx get preferences configured before first use.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a preference system that lets users configure default font, roughness,
fontSize, and strokeWidth — with three scopes (session/folder/global).
Skill layer (Step 1 in SKILL.md):
- Reads .claude/excalidraw-preferences.json (folder) then
~/.claude/skills/excalidraw-skill/preferences.json (global)
- If neither exists, prompts user interactively on first use
- Session-only scope keeps preferences in-memory without saving
Server layer (index.ts):
- loadPreferences() reads the same files at startup
- Replaces hardcoded fontFamily ?? 1 with USER_PREFS.fontFamily
- Folder-level preferences override global; user values override both
Also ships preferences.example.json as a template (preferences.json
is gitignored).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The excalidraw-skill was not being auto-invoked when users prompted
Claude to draw diagrams, despite being installed. Claude would call
Excalidraw MCP tools directly, bypassing the skill's critical sizing
formulas and verification workflow — producing broken diagrams with
invisible arrows, truncated text, and overlapping elements. The root
cause is that Claude Code's skill system is advisory: when direct MCP
tools or built-in Bash instructions are available, Claude skips skill
consultation entirely.
🔧 Skill description rewrite:
- Lead with "MANDATORY prerequisite" to assert priority over raw MCP tools
- Add user-intent trigger keywords (draw, visualize, sketch, diagram)
- Name specific consequences of skipping the skill
- List common diagram types for semantic matching
🏗️ Setup/update auto-directives:
- Write marked CLAUDE.md sections during skill install and update
- Write Cursor .mdc rules with alwaysApply for Cursor users
- Use HTML comment markers for idempotent append-or-replace on updates
- Non-fatal directive writing — skill installs even if directive fails
🎯 Two-layer defense ensures reliable skill triggering: the description
catches semantic matching, while the CLAUDE.md directive provides an
authoritative instruction that Claude cannot deprioritize in favor of
raw tool access.
The `claude mcp add` command fails with "already exists" when the server
is already registered. Additionally, configs written by setup/update used
a bare package name without @latest, causing npx to serve stale cached
versions indefinitely.
🔧 CLI registration:
- Remove existing entry before re-adding for Claude Code (both setup and update flows)
- Silently ignore removal errors when entry doesn't exist yet
⚡ Auto-update via @latest:
- Write @latest suffix in JSON configs, CLI commands, and manual instructions
- Smart detection in update flow: skip if config already has @latest,
offer migration if pinned, offer creation if missing
🎯 Users who run setup or update now get configs that always fetch the
newest version on MCP client restart, eliminating the stale-cache problem
without requiring manual npm cache clearing.
Existing users who update the npm package often forget to update the agent
skill files, leaving their AI agent working with stale workflow guidance
(sizing rules, color palettes, anti-patterns). The new `update` subcommand
solves this by detecting and updating all skill installations automatically.
🔧 Interactive update wizard:
- Scan all agent directories (Cursor, Claude Code, Codex CLI) across global
and local scopes for existing excalidraw-skill installations
- Batch-update found installations with a single Y/n confirmation
- Offer to install the skill for detected agents that don't have it yet
- Optionally re-apply MCP config (defaults to no for non-breaking updates)
📝 Documentation:
- Rewrite README "Updating" section to lead with the interactive command
- Add collapsible example session showing the update flow
- Retain manual update methods as fallback for each installation path
🎯 Ensures skill files stay in sync with MCP tools across releases,
preventing the subtle drift where new tool capabilities exist but the
agent's workflow guidance doesn't reference them.
Excalidraw skill lacked guidance on building complex visual shapes from
basic primitives, leading to flat single-shape attempts for structures
like roofs and walls. Adds coordinate geometry foundations so agents
produce realistic illustrative diagrams alongside technical ones.
🔧 Core geometric principles:
- Compose complex shapes from many small primitives with tessellation
- Eliminate gaps using interleaving offset rows at half-width spacing
- Parametric positioning formulas for centering, circular, triangular, and isometric layouts
- Scale primitive dimensions proportionally to container size
📦 Technique catalog reference:
- Illustrative elements (roofs, walls, clouds, trees, fences, windows)
- Sugiyama-inspired flow diagram layout algorithm
- Zone-grid architecture diagram layout
- Isometric 2.5D projection formulas
- Repeating pattern formulas with brick-pattern offsets
🧹 Consolidate tenants/projects/search into single compact table to
keep SKILL.md under the 500-line skill guideline
The postinstall ran prebuild-install and node-gyp in the wrong context
(our package instead of better-sqlite3), always failing with "binding.gyp
not found". better-sqlite3 handles its own native compilation via its
install script — the package-level postinstall was redundant.
Co-authored-by: sanjibdevnathlabs <devnath.sanjib@gmail.com>
- Use fs.realpathSync for entry point detection to fix npx symlink failures
- Add --help and --version CLI flags with explicit process.exit(0)
- Add TTY detection in setup wizard to prevent non-interactive hangs
- Wrap JSON.parse in mergeJsonConfig with try/catch for malformed configs
- Update engines.node to >=20.0.0 to match better-sqlite3 requirements
- Update Dockerfiles from node:18-slim to node:20-slim
- Remove error-swallowing || true from postinstall script
- Replace deprecated windows-build-tools with VS Build Tools link
The release workflow pushes version bump commits directly to main, but
branch protection rules block the default GITHUB_TOKEN from bypassing
required status checks and PR requirements. Using a dedicated GitHub
App (sanjibdevnathlabs-release-bot) generates installation tokens that
are permitted through the ruleset bypass list, and keeps the bot
identity on release commits instead of a personal account.
The Docker Build workflow previously used a paths filter, causing it to
not trigger at all for non-Docker PRs — leaving the required
github/docker-build-check status permanently pending. Now the workflow
always triggers but checks for Docker-related file changes first,
skipping builds when unnecessary while still reporting the status check
as passed.
Establish comprehensive quality infrastructure for a project that previously
had zero tests, enabling confident refactoring and community contributions
with automated guardrails. Port upstream enhancements for font normalization,
image element support, and arrow binding preservation.
🏗️ Testing infrastructure:
- Unit tests for SQLite persistence layer and element validation helpers
- Integration tests for REST API, WebSocket broadcast, and arrow binding
- E2E tests with Playwright for canvas rendering and real-time sync
- Vitest + Playwright configuration with proper isolation
👷 CI/CD pipeline:
- Auto-versioning from conventional commits on push to main
- Auto-publish to NPM and Docker Hub on GitHub release
- Matrix testing across Node 18/20/22 with pinned dependencies
- Docker health check with diagnostic logging on failure
- Preserve rollup status checks for branch protection gates
📦 Developer experience:
- Interactive setup wizard for first-time configuration
- Canvas clear confirmation and scene description tools
- Frontend helpers extracted for testability
🔧 Upstream feature ports:
- Font family normalization (string names to numeric IDs)
- Image element support with file management API
- Arrow binding preservation through server round-trips
- Vite config fix for font subsetting worker chunk names
- Idempotent database initialization for standalone Docker mode
🐛 Docker fixes:
- Set EXCALIDRAW_DB_PATH in both Dockerfiles to writable /app/data/
- Make initDb() idempotent and closeDb() reset-safe for test isolation
🎯 Provides the safety net needed for rapid iteration — every PR is
validated across 120 test cases before merge, and releases are fully
automated from commit to published package.
Co-authored-by: sanjibdevnathlabs <devnath.sanjib@gmail.com>
The npm-publish workflow needs write access to upload tarballs to
GitHub releases. Read-only caused "Resource not accessible by integration".
Co-authored-by: Cursor <cursoragent@cursor.com>
* 🔧 chore: reset version to 1.0.0 for independent NPM package
This is a new scoped package (@sanjibdevnath/mcp-excalidraw-local),
so versioning starts fresh at 1.0.0 rather than continuing upstream's
numbering.
Co-authored-by: Cursor <cursoragent@cursor.com>
* chore: trigger PR
Co-authored-by: Cursor <cursoragent@cursor.com>
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
Dogfood our own tool — the architecture diagram is now drawn in
Excalidraw and exported as PNG, replacing the ASCII art block.
Co-authored-by: Cursor <cursoragent@cursor.com>
Replace in-memory storage with SQLite (WAL mode), add workspace-based
multi-tenancy with auto-detection via server.listRoots(), and embed the
canvas server into the MCP process for single-process operation.
🔧 Core enhancements:
- SQLite persistence with versioning, element history, and search
- Multi-tenancy: isolated canvases per workspace (SHA-256 tenant IDs)
- Embedded canvas lifecycle (single node process starts MCP + canvas)
- Auto-sync with 3s debounce and manual override toggle
- Configurable canvas port via CANVAS_PORT env var
- 6 new MCP tools (search, history, tenants, projects)
- Workspace switcher UI with dropdown search
- Sync normalization to prevent bound-text breakage on reload
🐳 Docker & CI improvements:
- BuildKit cache mounts for faster npm installs across builds
- Skip native compilation in frontend-builder stage (--ignore-scripts)
- Build only linux/amd64 on PRs, multi-arch on push to main
- Docker Hub registry with proper build tools for better-sqlite3
- CI and Docker status check gates (github/ci-status-check, github/docker-build-check)
📦 Package & publishing:
- Renamed to @sanjibdevnath/mcp-excalidraw-local (v3.0.0)
- Updated npm-publish workflow for scoped package
- Updated bin entry, keywords, and files list
📝 Documentation:
- README with UI screenshots, architecture diagram, and full feature docs
- Updated agent skill with 32-tool cheatsheet and workflow playbooks
- Fork attribution and upstream comparison table
Co-authored-by: Cursor <cursoragent@cursor.com>
* feat: enhance Excalidraw MCP with advanced canvas toolkit features
- Rename skill to `excalidraw-skill` with expanded playbook and cheatsheet.
- Add new MCP tools for iterative refinement: `describe_scene` and `get_canvas_screenshot`.
- Implement layout tools (`align_elements`, `distribute_elements`) and `duplicate_elements`.
- Add file I/O support for `.excalidraw` JSON and image export (PNG/SVG).
- Introduce named snapshots for canvas state management.
- Add server-side element CRUD and WebSocket handlers for real-time sync.
- Normalize `points` format for arrows and lines.
* docs: update README with v2.0 features and official MCP comparison
* feat: implement arrow binding and edge-to-edge routing
* fix: enhance security with path sanitization and improve export error handling
* feat: add viewport control, design guide, and excalidraw.com URL export
* feat: enhance excalidraw.com export with proper scene formatting and labels
* feat(skill): add excalidraw-mcp skill with export/import helpers
* fix(skill): correct url trailing-slash normalization in scripts
* feat(skill): add create/update/delete helpers and document CRUD test
* docs: restructure README and document skill usage
* docs: make README skill guidance tool-agnostic and SEO-friendly
* docs: add Claude Code skill installation instructions
* feat: Introduce skill creation tools and an agent-browser skill with templates and reference documentation.
* fix(frontend): keep server element ids for WS updates
Ensure WS delete/update events match scene element IDs by disabling ID regeneration when converting server payloads.
* feat: Add Zod library and OpenCode AI SDK dependencies, and introduce new Excalidraw skill scripts for element deletion and health checks.
* chore: Install project dependencies including Zod and OpenCode AI SDK, and add an Excalidraw reference cheatsheet.
---------
Co-authored-by: YC Lin <yclin@YCdeMacBook-Air.local>
The batch creation endpoint was always generating new IDs, ignoring IDs
passed from the MCP server. This caused sync issues where the MCP server
would think elements were created with specific IDs, but the canvas had
different IDs.
This fix makes the batch endpoint behave like the single element endpoint:
it now respects passed IDs (for MCP sync) or generates new ones if not provided.
Fixes the 'MCP tool registration issues' mentioned in the roadmap.
- Replace all `any` types with proper Excalidraw types
- Add proper type imports from @excalidraw/excalidraw
- Improve MermaidConversionResult interface with ExcalidrawElement[] and BinaryFiles
- Add mermaidDiagram and config fields to WebSocketMessage interface
- Remove unused ElementBinding interface
- Remove all `as any` type casts throughout App.tsx
- Fix Vite security vulnerability (1 of 6 moderate vulns)
Changes:
- frontend/src/App.tsx: Restored proper TypeScript types, removed 12+ `as any` casts
- frontend/src/utils/mermaidConverter.ts: Added proper return types
- package-lock.json: Updated vite to fix security issue
Remaining security issues:
- 5 moderate vulnerabilities from @excalidraw/mermaid-to-excalidraw dependencies
- These are upstream issues in dompurify, nanoid, and mermaid packages
- No fixes available without major version upgrades
- Risk is acceptable for this use case (diagram rendering)
- Add WebSocket message handler for mermaid_convert type
- Make handleWebSocketMessage async to support conversion
- Add automatic backend sync after diagram generation
- Integrate convertMermaidToExcalidraw utility
- Remove test button and handleMermaidTest function
- Fix: Add missing Excalidraw CSS import for proper UI rendering
- Enhance server endpoint with WebSocket broadcast support
- Add mermaid_convert to WebSocketMessageType union
sanjibdevnathlabs-release-bot[bot]