chore(release): v1.4.0

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>

.gitignore

@@ -15,6 +15,9 @@ public/dist/
 .cursor/
 .claude/
 
+# User preferences (only the example ships)
+skills/excalidraw-skill/preferences.json
+
 # Development artifacts
 *.excalidraw
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@sanjibdevnath/mcp-excalidraw-local",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@sanjibdevnath/mcp-excalidraw-local",
-      "version": "1.2.1",
+      "version": "1.4.0",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanjibdevnath/mcp-excalidraw-local",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Fully local MCP server for Excalidraw with SQLite persistence, multi-tenancy, auto-sync, real-time canvas, and 32 tools",
   "main": "dist/index.js",
   "type": "module",

skills/excalidraw-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: excalidraw-skill
-description: Programmatic canvas toolkit for creating, editing, and refining Excalidraw diagrams via MCP tools (32 tools) or REST API with real-time canvas sync, multi-tenant workspace isolation, SQLite persistence, project management, full-text search, and element version history. Use when an agent needs to draw or lay out diagrams on a live canvas, iteratively refine diagrams using screenshots, manage workspaces/tenants and projects, export/import .excalidraw files or PNG/SVG images, search elements, view change history, save/restore canvas snapshots, or perform element-level CRUD. Canvas server port is configurable via CANVAS_PORT env var (default 3000).
+description: MANDATORY prerequisite for ALL Excalidraw MCP tool usage. Read this skill BEFORE calling any Excalidraw tool (batch_create_elements, create_element, create_from_mermaid, update_element, etc.) — without this skill's sizing formulas, two-batch ordering (shapes first, arrows second), and write-check-review verification cycle, diagrams will have invisible arrows, truncated text, and overlapping elements. Use whenever the user asks to draw, create, visualize, sketch, or diagram anything — flowcharts, architecture diagrams, system designs, org charts, sequence flows, decision trees, network topologies, ER diagrams, mind maps, or any visual on Excalidraw canvas. Also covers diagram refinement, PNG/SVG export, project/workspace management, and all canvas interactions.
 ---
 
 # Excalidraw Skill
@@ -15,6 +15,79 @@ Run these checks **in order**:
 
 See `references/cheatsheet.md` for the full MCP-vs-REST mapping and REST API gotchas.
 
+## Step 1: Load User Preferences
+
+Before creating any elements, load the user's diagram preferences. These control default font, roughness, stroke width, etc.
+
+### Preference Resolution Order (most specific wins)
+
+| Priority | Scope | Location | Persists |
+|----------|-------|----------|----------|
+| 1 (highest) | Session | In-memory (set via prompt during this conversation) | No — current session only |
+| 2 | Folder | `.claude/excalidraw-preferences.json` in the current project root | Yes — per-project |
+| 3 | Global | `~/.claude/skills/excalidraw-skill/preferences.json` | Yes — all projects |
+| 4 (lowest) | Hardcoded | Server defaults (fontFamily: 1, roughness: 0, fontSize: 20, strokeWidth: 2) | — |
+
+### How to Load
+
+1. **Check folder-level first**: Read `.claude/excalidraw-preferences.json` from the current working directory (or project root). If it exists and has `defaults`, use those values.
+2. **Fall back to global**: Read `~/.claude/skills/excalidraw-skill/preferences.json`. If it exists and has `defaults`, use those values.
+3. **If neither exists** → run the **First-Time Setup** prompt below.
+4. **Merge**: Folder preferences override global; global overrides hardcoded. Only override fields that are explicitly set.
+
+### First-Time Setup (Interactive)
+
+If no preferences file exists at either location, **prompt the user before drawing anything**:
+
+> **Excalidraw Preferences Setup**
+>
+> I don't have any saved diagram preferences yet. Let me set up your defaults so every diagram looks the way you want.
+
+Ask these questions (use `AskUserQuestion` tool if available, otherwise ask inline):
+
+1. **Font family** — Which font for all text?
+   - Excalifont (hand-drawn) = 1
+   - Helvetica (sans-serif) = 2
+   - Cascadia (monospace) = 3
+   - Comic Shanns = 4
+   - Nunito = 6
+   - Lilita One = 7
+
+2. **Roughness** — Diagram style?
+   - Clean/professional (roughness: 0) — recommended
+   - Hand-drawn sketch (roughness: 1)
+   - Very rough (roughness: 2)
+
+3. **Scope** — Where to save?
+   - **This session only** — don't save to disk, just use for this conversation
+   - **This project** — save to `.claude/excalidraw-preferences.json` in project root
+   - **Global (all projects)** — save to `~/.claude/skills/excalidraw-skill/preferences.json`
+
+Then save the preferences JSON to the chosen location:
+
+```json
+{
+  "defaults": {
+    "fontFamily": <user_choice>,
+    "fontSize": 20,
+    "roughness": <user_choice>,
+    "strokeWidth": 2
+  }
+}
+```
+
+For session-only scope, just hold the values in memory and apply them to every element in this conversation.
+
+### Applying Preferences
+
+Once loaded, apply `defaults` to **every element** that supports the property:
+- `fontFamily` → all text-containing elements (text, rectangles with labels, diamonds, ellipses, arrows with labels)
+- `fontSize` → text elements and labels (unless the element explicitly overrides it)
+- `roughness` → all elements
+- `strokeWidth` → arrows and lines
+
+User-specified values in individual element calls always override preferences.
+
 ## Core Principles (Read Before Any Diagram)
 
 These principles were learned through extensive iterative use. Violating them produces bad diagrams.

skills/excalidraw-skill/preferences.example.json

@@ -0,0 +1,18 @@
+{
+  "_comment": "Excalidraw MCP user preferences. Copy to preferences.json to activate.",
+  "_fontReference": {
+    "1": "Excalifont (hand-drawn)",
+    "2": "Helvetica (sans-serif)",
+    "3": "Cascadia (monospace)",
+    "4": "Comic Shanns",
+    "5": "Liberation Sans",
+    "6": "Nunito",
+    "7": "Lilita One"
+  },
+  "defaults": {
+    "fontFamily": 1,
+    "fontSize": 20,
+    "roughness": 0,
+    "strokeWidth": 2
+  }
+}

skills/excalidraw-skill/references/cheatsheet.md

@@ -94,16 +94,15 @@
 |---------|----------------|-----------------|
 | Shape labels | `"text": "My Label"` (auto-converts) | `"label": {"text": "My Label"}` |
 | Arrow binding | `"startElementId": "id"` / `"endElementId": "id"` | `"start": {"id": "id"}` / `"end": {"id": "id"}` |
-| `fontFamily` | String `"1"` or omit | String `"1"` or omit (never a number) |
+| `fontFamily` | Number or string — use value from user preferences (see Step 1 in SKILL.md) | String — use value from user preferences |
 | Tenant scoping | Auto (uses active tenant) | Include `X-Tenant-Id` header on every request |
 
 ### Element Creation Best Practices
 
-- **Always set `roughness: 0`** for clean, professional diagrams (default is hand-drawn).
-- **Always set `strokeWidth: 2`** on arrows for visibility.
+- **Always apply user preferences** — load from Step 1 in SKILL.md and apply `fontFamily`, `roughness`, `fontSize`, `strokeWidth` to every element.
 - **Create shapes first, arrows second** (two separate `batch_create_elements` calls).
 - **Assign custom `id`** to every shape so arrows can reference it.
-- **Size shapes for their text** — Virgil font is ~30% wider than standard. Use sizing formulas from SKILL.md.
+- **Size shapes for their text** — use sizing formulas from SKILL.md.
 - `points` accepts both `[[x,y]]` tuples and `[{x,y}]` objects — normalized automatically.
 - **Curved arrows**: Use `"roundness": {"type": 2}` with 3+ points. **Elbowed arrows**: Use `"elbowed": true`.
 

src/index.ts

@@ -65,6 +65,47 @@ const CANVAS_PORT = process.env.CANVAS_PORT || process.env.PORT || '3000';
 const EXPRESS_SERVER_URL = process.env.EXPRESS_SERVER_URL || `http://localhost:${CANVAS_PORT}`;
 const ENABLE_CANVAS_SYNC = true;
 
+// User preferences for element defaults (font, roughness, etc.)
+// Resolution: folder-level .claude/excalidraw-preferences.json > global ~/.claude/skills/excalidraw-skill/preferences.json > hardcoded
+interface ExcalidrawPreferences {
+  fontFamily: number;
+  fontSize: number;
+  roughness: number;
+  strokeWidth: number;
+}
+
+const HARDCODED_DEFAULTS: ExcalidrawPreferences = {
+  fontFamily: 1,
+  fontSize: 20,
+  roughness: 0,
+  strokeWidth: 2,
+};
+
+function loadPreferences(): ExcalidrawPreferences {
+  const locations = [
+    path.join(process.cwd(), '.claude', 'excalidraw-preferences.json'),
+    path.join(process.env.HOME || '~', '.claude', 'skills', 'excalidraw-skill', 'preferences.json'),
+  ];
+
+  for (const loc of locations) {
+    try {
+      if (fs.existsSync(loc)) {
+        const raw = JSON.parse(fs.readFileSync(loc, 'utf-8'));
+        if (raw?.defaults) {
+          logger.info(`Loaded user preferences from ${loc}`);
+          return { ...HARDCODED_DEFAULTS, ...raw.defaults };
+        }
+      }
+    } catch (e) {
+      logger.warn(`Failed to read preferences from ${loc}: ${e}`);
+    }
+  }
+
+  return HARDCODED_DEFAULTS;
+}
+
+const USER_PREFS = loadPreferences();
+
 // One-time tokens for clear_canvas confirmation (token → expiry timestamp)
 const pendingClearTokens = new Map<string, { expiresAt: number; elementCount: number }>();
 const CLEAR_TOKEN_TTL_MS = 120_000; // 2 minutes
@@ -2199,8 +2240,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request: CallToolRequest)
           if (el.type === 'text') {
             base.text = text ?? '';
             base.originalText = text ?? '';
-            base.fontSize = rest.fontSize ?? 20;
-            base.fontFamily = rest.fontFamily ?? 1;
+            base.fontSize = rest.fontSize ?? USER_PREFS.fontSize;
+            base.fontFamily = rest.fontFamily ?? USER_PREFS.fontFamily;
             base.textAlign = rest.textAlign ?? 'center';
             base.verticalAlign = rest.verticalAlign ?? 'middle';
             base.autoResize = rest.autoResize ?? true;
@@ -2294,8 +2335,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request: CallToolRequest)
               locked: false,
               text: labelText,
               originalText: labelText,
-              fontSize: isArrow ? 14 : (rest.fontSize ?? 16),
-              fontFamily: rest.fontFamily ?? 1,
+              fontSize: isArrow ? 14 : (rest.fontSize ?? USER_PREFS.fontSize),
+              fontFamily: rest.fontFamily ?? USER_PREFS.fontFamily,
               textAlign: 'center',
               verticalAlign: 'middle',
               autoResize: true,

src/setup.ts

@@ -57,6 +57,11 @@ interface AgentDef {
   mcpConfigPath?: string;
   mcpCliRemove?: string;
   mcpCliCommand?: string;
+  instructionConfig?: {
+    global: string;
+    local: string;
+    format: 'claude-md' | 'cursor-mdc';
+  };
 }
 
 function getAgents(): AgentDef[] {
@@ -71,6 +76,11 @@ function getAgents(): AgentDef[] {
       },
       mcpConfigType: 'json-file',
       mcpConfigPath: path.join(home, '.cursor', 'mcp.json'),
+      instructionConfig: {
+        global: path.join(home, '.cursor', 'rules', 'excalidraw.mdc'),
+        local: path.join(process.cwd(), '.cursor', 'rules', 'excalidraw.mdc'),
+        format: 'cursor-mdc',
+      },
     },
     {
       name: 'Claude Code',
@@ -82,6 +92,11 @@ function getAgents(): AgentDef[] {
       mcpConfigType: 'cli-command',
       mcpCliRemove: 'claude mcp remove excalidraw-canvas --scope user',
       mcpCliCommand: 'claude mcp add excalidraw-canvas --scope user -e CANVAS_PORT=3000 -- npx -y @sanjibdevnath/mcp-excalidraw-local@latest',
+      instructionConfig: {
+        global: path.join(home, '.claude', 'CLAUDE.md'),
+        local: path.join(process.cwd(), 'CLAUDE.md'),
+        format: 'claude-md',
+      },
     },
     {
       name: 'Codex CLI',
@@ -226,6 +241,17 @@ async function phaseSkillInstall(rl: readline.Interface): Promise<void> {
       fs.mkdirSync(destDir, { recursive: true });
       copyDirSync(skillSource, destDir);
       ok(`Installed to ${destDir}`);
+
+      // Write instruction directive to ensure skill auto-triggers
+      if (agent.instructionConfig) {
+        const instrPath = agent.instructionConfig[scope];
+        try {
+          writeInstructionDirective(instrPath, agent.instructionConfig.format);
+          ok(`Skill directive added to ${instrPath}`);
+        } catch (instrErr) {
+          warn(`Could not write directive to ${instrPath}: ${(instrErr as Error).message}`);
+        }
+      }
     } catch (err) {
       fail(`Failed to install to ${destDir}: ${(err as Error).message}`);
     }
@@ -245,6 +271,79 @@ function copyDirSync(src: string, dest: string): void {
   }
 }
 
+// ── Instruction Directives ──────────────────────────────────
+
+const DIRECTIVE_MARKER_START = '<!-- excalidraw-mcp:start -->';
+const DIRECTIVE_MARKER_END = '<!-- excalidraw-mcp:end -->';
+
+const EXCALIDRAW_DIRECTIVE_BODY =
+  'When Excalidraw MCP tools are available (batch_create_elements, create_element, ' +
+  'create_from_mermaid, etc.), ALWAYS invoke the `/excalidraw-skill` skill FIRST ' +
+  'before calling any Excalidraw tool. The skill contains essential sizing formulas, ' +
+  'batch ordering rules (shapes first, arrows second), and a mandatory ' +
+  'write-check-review verification cycle. Using Excalidraw tools without consulting ' +
+  'this skill produces broken diagrams — invisible arrows, truncated text, ' +
+  'overlapping elements.';
+
+function buildClaudeMdSection(): string {
+  return [
+    DIRECTIVE_MARKER_START,
+    '## Excalidraw Canvas — Skill Directive',
+    '',
+    EXCALIDRAW_DIRECTIVE_BODY,
+    DIRECTIVE_MARKER_END,
+  ].join('\n');
+}
+
+function buildCursorMdc(): string {
+  return [
+    '---',
+    'description: Always consult excalidraw-skill before using Excalidraw MCP tools',
+    'globs:',
+    'alwaysApply: true',
+    '---',
+    '',
+    '## Excalidraw Canvas — Skill Directive',
+    '',
+    EXCALIDRAW_DIRECTIVE_BODY,
+    '',
+  ].join('\n');
+}
+
+function writeInstructionDirective(filePath: string, format: 'claude-md' | 'cursor-mdc'): void {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  if (format === 'cursor-mdc') {
+    // Cursor .mdc files are standalone — write/overwrite the whole file
+    fs.writeFileSync(filePath, buildCursorMdc(), 'utf-8');
+    return;
+  }
+
+  // For claude-md: append or replace the marked section
+  let content = '';
+  if (fs.existsSync(filePath)) {
+    content = fs.readFileSync(filePath, 'utf-8');
+  }
+
+  const section = buildClaudeMdSection();
+  const startIdx = content.indexOf(DIRECTIVE_MARKER_START);
+  const endIdx = content.indexOf(DIRECTIVE_MARKER_END);
+
+  if (startIdx !== -1 && endIdx !== -1) {
+    // Replace existing section
+    content = content.slice(0, startIdx) + section + content.slice(endIdx + DIRECTIVE_MARKER_END.length);
+  } else {
+    // Append with spacing
+    const trimmed = content.trimEnd();
+    content = trimmed + (trimmed ? '\n\n' : '') + section + '\n';
+  }
+
+  fs.writeFileSync(filePath, content, 'utf-8');
+}
+
 // ── Phase 3: MCP Configuration ──────────────────────────────
 
 async function phaseMcpConfig(rl: readline.Interface): Promise<void> {
@@ -450,6 +549,17 @@ export async function runUpdate(): Promise<void> {
             copyDirSync(skillSource, inst.path);
             ok(`Updated ${inst.agent.name} (${inst.scope}) — ${inst.path}`);
             updated++;
+
+            // Update instruction directive
+            if (inst.agent.instructionConfig) {
+              const instrPath = inst.agent.instructionConfig[inst.scope];
+              try {
+                writeInstructionDirective(instrPath, inst.agent.instructionConfig.format);
+                ok(`Skill directive updated in ${instrPath}`);
+              } catch (instrErr) {
+                warn(`Could not update directive in ${instrPath}: ${(instrErr as Error).message}`);
+              }
+            }
           } catch (err) {
             fail(`Failed to update ${inst.path}: ${(err as Error).message}`);
           }
@@ -484,6 +594,17 @@ export async function runUpdate(): Promise<void> {
             fs.mkdirSync(destDir, { recursive: true });
             copyDirSync(skillSource, destDir);
             ok(`Installed to ${destDir}`);
+
+            // Write instruction directive
+            if (agent.instructionConfig) {
+              const instrPath = agent.instructionConfig[scope];
+              try {
+                writeInstructionDirective(instrPath, agent.instructionConfig.format);
+                ok(`Skill directive added to ${instrPath}`);
+              } catch (instrErr) {
+                warn(`Could not write directive to ${instrPath}: ${(instrErr as Error).message}`);
+              }
+            }
           } catch (err) {
             fail(`Failed to install to ${destDir}: ${(err as Error).message}`);
           }