@elixpo/lixsketch 5.6.1 → 5.6.2

package/src/mcp/scene.js

@@ -0,0 +1,275 @@
+const FORMAT = 'lixsketch';
+const VERSION = 1;
+const MAX_SHAPES = 5000;
+const MAX_OPERATIONS = 500;
+const SCENE_TYPES = new Set(['rectangle', 'circle', 'line', 'arrow', 'freehandStroke', 'frame', 'text', 'code', 'image', 'icon']);
+const WRITABLE_TYPES = new Set(['rectangle', 'circle', 'line', 'arrow', 'freehandStroke', 'frame', 'text']);
+
+const clone = (value) => JSON.parse(JSON.stringify(value));
+const finite = (value, fallback = 0) => Number.isFinite(Number(value)) ? Number(value) : fallback;
+const positive = (value, fallback = 1) => Math.max(1, finite(value, fallback));
+
+export function createEmptyScene(name = 'MCP Canvas') {
+  return {
+    format: FORMAT,
+    version: VERSION,
+    sessionID: `mcp-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+    name: String(name || 'MCP Canvas').trim().slice(0, 72),
+    createdAt: new Date().toISOString(),
+    viewport: { x: 0, y: 0, width: 1280, height: 720 },
+    zoom: 1,
+    mcpRevision: 0,
+    shapes: [],
+  };
+}
+
+export function validateScene(scene) {
+  const errors = [];
+  if (!scene || typeof scene !== 'object') return { valid: false, errors: ['Scene must be an object'] };
+  if (scene.format !== FORMAT) errors.push(`Scene format must be "${FORMAT}"`);
+  if (scene.version !== VERSION) errors.push(`Scene version must be ${VERSION}`);
+  if (!Array.isArray(scene.shapes)) errors.push('Scene shapes must be an array');
+  if (Array.isArray(scene.shapes) && scene.shapes.length > MAX_SHAPES) errors.push(`Scene exceeds ${MAX_SHAPES} shapes`);
+  const ids = new Set();
+  for (const [index, shape] of (scene.shapes || []).entries()) {
+    if (!shape || typeof shape !== 'object') { errors.push(`Shape ${index} must be an object`); continue; }
+    if (!SCENE_TYPES.has(shape.type)) errors.push(`Shape ${index} has unsupported type "${shape.type}"`);
+    if (!shape.shapeID || typeof shape.shapeID !== 'string') errors.push(`Shape ${index} is missing shapeID`);
+    else if (ids.has(shape.shapeID)) errors.push(`Duplicate shapeID "${shape.shapeID}"`);
+    else ids.add(shape.shapeID);
+    validateShapeGeometry(shape, index, errors);
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function escapeXml(value) {
+  return String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+}
+
+function normalizeOptions(value = {}) {
+  return {
+    roughness: Math.max(0, Math.min(3, finite(value.roughness, 1.2))),
+    stroke: typeof value.stroke === 'string' ? value.stroke : '#8b76d6',
+    strokeWidth: Math.max(0.5, Math.min(20, finite(value.strokeWidth, 2))),
+    fill: typeof value.fill === 'string' ? value.fill : 'transparent',
+    fillStyle: typeof value.fillStyle === 'string' ? value.fillStyle : 'solid',
+    opacity: Math.max(0, Math.min(1, finite(value.opacity, 1))),
+  };
+}
+
+function createTextShape(input, shapeID) {
+  const x = finite(input.x), y = finite(input.y), rotation = finite(input.rotation);
+  const text = String(input.text || '').slice(0, 10000);
+  const fontSize = Math.max(8, Math.min(160, finite(input.fontSize, 20)));
+  const color = typeof input.color === 'string' ? input.color : '#e8e3f3';
+  const family = typeof input.fontFamily === 'string' ? input.fontFamily.slice(0, 80) : 'lixFont';
+  const transform = `translate(${x}, ${y})${rotation ? ` rotate(${rotation}, 0, 0)` : ''}`;
+  const lines = text.split('\n').map((line, index) => `<tspan x="0" dy="${index === 0 ? 0 : '1.2em'}">${escapeXml(line || ' ')}</tspan>`).join('');
+  return {
+    shapeID, type: 'text', x, y, rotation,
+    mcpText: text, mcpFontSize: fontSize, mcpColor: color, mcpFontFamily: family,
+    groupHTML: `<g id="${escapeXml(shapeID)}" data-type="text-group" data-x="${x}" data-y="${y}" transform="${transform}"><text id="${escapeXml(shapeID)}-text" x="0" y="0" fill="${escapeXml(color)}" font-size="${fontSize}" font-family="${escapeXml(family)}" dominant-baseline="hanging" white-space="pre" pointer-events="painted" data-type="text" data-initial-size="${fontSize}" data-initial-font="${escapeXml(family)}" data-initial-color="${escapeXml(color)}">${lines}</text></g>`,
+  };
+}
+
+export function normalizeShape(input, existingIds = new Set()) {
+  if (!input || typeof input !== 'object') throw new Error('Shape must be an object');
+  if (!WRITABLE_TYPES.has(input.type)) throw new Error(`Shape type "${input.type}" is read-only through MCP`);
+  let shapeID = String(input.shapeID || `${input.type}-${crypto.randomUUID()}`).slice(0, 120);
+  while (existingIds.has(shapeID)) shapeID = `${input.type}-${crypto.randomUUID()}`;
+  const base = { shapeID, type: input.type, rotation: finite(input.rotation), options: normalizeOptions(input.options), groupId: input.groupId || null, parentFrame: input.parentFrame || null, docBlockIds: [] };
+  switch (input.type) {
+    case 'rectangle': return { ...base, x: finite(input.x), y: finite(input.y), width: positive(input.width, 160), height: positive(input.height, 90) };
+    case 'circle': return { ...base, x: finite(input.x), y: finite(input.y), rx: positive(input.rx, 60), ry: positive(input.ry, 60) };
+    case 'line': return { ...base, startPoint: point(input.startPoint), endPoint: point(input.endPoint, 120), isCurved: Boolean(input.isCurved), controlPoint: input.controlPoint ? point(input.controlPoint) : null };
+    case 'arrow': return { ...base, startPoint: point(input.startPoint), endPoint: point(input.endPoint, 120), arrowHeadStyle: input.arrowHeadStyle || 'triangle', arrowOutlineStyle: input.arrowOutlineStyle || 'solid', arrowCurved: Boolean(input.arrowCurved), arrowCurveAmount: finite(input.arrowCurveAmount, 0.2) };
+    case 'freehandStroke': {
+      const points = (Array.isArray(input.points) ? input.points : []).slice(0, 4096).map((entry) => [finite(entry?.[0]), finite(entry?.[1]), finite(entry?.[2], 0.5)]);
+      if (points.length < 2) throw new Error('freehandStroke requires at least two points');
+      return { ...base, points };
+    }
+    case 'frame': return { ...base, x: finite(input.x), y: finite(input.y), width: positive(input.width, 640), height: positive(input.height, 360), frameName: String(input.frameName || 'Frame').slice(0, 80), fillStyle: input.fillStyle || 'transparent', fillColor: input.fillColor || '#1e1e28', gridSize: positive(input.gridSize, 20), containedShapeIDs: [] };
+    case 'text': return { ...base, ...createTextShape(input, shapeID) };
+    default: throw new Error(`Unsupported shape type "${input.type}"`);
+  }
+}
+
+function point(value, fallbackX = 0) {
+  return { x: finite(value?.x, fallbackX), y: finite(value?.y) };
+}
+
+function translateShape(shape, dx, dy) {
+  const moved = clone(shape);
+  if (moved.startPoint) { moved.startPoint.x += dx; moved.startPoint.y += dy; }
+  if (moved.endPoint) { moved.endPoint.x += dx; moved.endPoint.y += dy; }
+  if (moved.controlPoint) { moved.controlPoint.x += dx; moved.controlPoint.y += dy; }
+  if (moved.controlPoint1) { moved.controlPoint1.x += dx; moved.controlPoint1.y += dy; }
+  if (moved.controlPoint2) { moved.controlPoint2.x += dx; moved.controlPoint2.y += dy; }
+  if (Array.isArray(moved.points)) moved.points = moved.points.map((p) => [p[0] + dx, p[1] + dy, ...p.slice(2)]);
+  if (Number.isFinite(moved.x)) moved.x += dx;
+  if (Number.isFinite(moved.y)) moved.y += dy;
+  if (moved.type === 'text' && moved.groupHTML) {
+    moved.groupHTML = moved.groupHTML
+      .replace(/data-x="[^"]*"/, `data-x="${moved.x}"`)
+      .replace(/data-y="[^"]*"/, `data-y="${moved.y}"`)
+      .replace(/transform="translate\([^)]*\)/, `transform="translate(${moved.x}, ${moved.y})`);
+  }
+  if (moved.type === 'code' && moved.groupHTML) {
+    moved.groupHTML = moved.groupHTML
+      .replace(/data-x="[^"]*"/, `data-x="${moved.x}"`)
+      .replace(/data-y="[^"]*"/, `data-y="${moved.y}"`)
+      .replace(/transform="translate\([^)]*\)/, `transform="translate(${moved.x}, ${moved.y})`);
+  }
+  if (moved.type === 'icon' && moved.elementHTML) {
+    moved.elementHTML = moved.elementHTML
+      .replace(/\bx="[^"]*"/, `x="${moved.x}"`)
+      .replace(/\by="[^"]*"/, `y="${moved.y}"`);
+  }
+  return moved;
+}
+
+export function applyScenePatch(sceneInput, operations, { expectedRevision, dryRun = false } = {}) {
+  const scene = clone(sceneInput);
+  const check = validateScene(scene);
+  if (!check.valid) throw new Error(`Invalid scene: ${check.errors.join('; ')}`);
+  if (!Array.isArray(operations) || operations.length === 0) throw new Error('At least one operation is required');
+  if (operations.length > MAX_OPERATIONS) throw new Error(`Patch exceeds ${MAX_OPERATIONS} operations`);
+  const revision = Number(scene.mcpRevision || 0);
+  if (expectedRevision !== undefined && Number(expectedRevision) !== revision) throw new Error(`Revision conflict: expected ${expectedRevision}, current ${revision}`);
+  const changedIds = new Set();
+  for (const operation of operations) {
+    if (!operation || typeof operation !== 'object') throw new Error('Each operation must be an object');
+    if (operation.op === 'add') {
+      if (scene.shapes.length >= MAX_SHAPES) throw new Error(`Scene exceeds ${MAX_SHAPES} shapes`);
+      const ids = new Set(scene.shapes.map((shape) => shape.shapeID));
+      const shape = normalizeShape(operation.shape, ids);
+      scene.shapes.push(shape); changedIds.add(shape.shapeID);
+    } else if (operation.op === 'update') {
+      const index = scene.shapes.findIndex((shape) => shape.shapeID === operation.shapeID);
+      if (index < 0) throw new Error(`Shape "${operation.shapeID}" was not found`);
+      const immutable = scene.shapes[index];
+      scene.shapes[index] = applyShapeChanges(immutable, operation.changes || {}); changedIds.add(immutable.shapeID);
+    } else if (operation.op === 'delete') {
+      const ids = new Set(Array.isArray(operation.shapeIDs) ? operation.shapeIDs : [operation.shapeID]);
+      const before = scene.shapes.length;
+      scene.shapes = scene.shapes.filter((shape) => !ids.has(shape.shapeID));
+      if (scene.shapes.length === before) throw new Error('No requested shapes were found');
+      scene.shapes.forEach((shape) => {
+        if (ids.has(shape.parentFrame)) shape.parentFrame = null;
+        if (Array.isArray(shape.containedShapeIDs)) shape.containedShapeIDs = shape.containedShapeIDs.filter((id) => !ids.has(id));
+      });
+      ids.forEach((id) => changedIds.add(id));
+    } else if (operation.op === 'translate') {
+      const ids = new Set(operation.shapeIDs || []), dx = finite(operation.dx), dy = finite(operation.dy);
+      if (!ids.size) throw new Error('translate requires shapeIDs');
+      scene.shapes = scene.shapes.map((shape) => ids.has(shape.shapeID) ? translateShape(shape, dx, dy) : shape);
+      ids.forEach((id) => changedIds.add(id));
+    } else if (operation.op === 'rename_canvas') {
+      scene.name = String(operation.name || '').trim().slice(0, 72) || scene.name;
+    } else throw new Error(`Unsupported operation "${operation.op}"`);
+  }
+  scene.mcpRevision = revision + 1;
+  scene.updatedAt = new Date().toISOString();
+  const result = validateScene(scene);
+  if (!result.valid) throw new Error(`Patch produced an invalid scene: ${result.errors.join('; ')}`);
+  return { scene, revision: scene.mcpRevision, dryRun: Boolean(dryRun), changedShapeIDs: [...changedIds] };
+}
+
+function applyShapeChanges(shape, changes) {
+  if (!changes || typeof changes !== 'object' || Array.isArray(changes)) throw new Error('Shape changes must be an object');
+  const allowed = {
+    rectangle: ['x', 'y', 'width', 'height', 'rotation', 'options', 'groupId', 'parentFrame'],
+    circle: ['x', 'y', 'rx', 'ry', 'rotation', 'options', 'groupId', 'parentFrame'],
+    line: ['startPoint', 'endPoint', 'controlPoint', 'isCurved', 'options', 'groupId', 'parentFrame'],
+    arrow: ['startPoint', 'endPoint', 'controlPoint1', 'controlPoint2', 'arrowHeadStyle', 'arrowOutlineStyle', 'arrowCurved', 'arrowCurveAmount', 'options', 'groupId', 'parentFrame'],
+    freehandStroke: ['points', 'rotation', 'options', 'groupId', 'parentFrame'],
+    frame: ['x', 'y', 'width', 'height', 'rotation', 'frameName', 'fillStyle', 'fillColor', 'gridSize', 'options', 'groupId', 'parentFrame'],
+    text: ['x', 'y', 'rotation', 'text', 'fontSize', 'color', 'fontFamily', 'groupId', 'parentFrame'],
+  }[shape.type] || [];
+  const rejected = Object.keys(changes).filter((key) => !allowed.includes(key));
+  if (rejected.length) throw new Error(`Cannot update ${shape.type} fields: ${rejected.join(', ')}`);
+  if (shape.type === 'text') {
+    const text = changes.text ?? shape.mcpText ?? extractText(shape.groupHTML);
+    return { ...shape, ...createTextShape({ x: changes.x ?? shape.x, y: changes.y ?? shape.y, rotation: changes.rotation ?? shape.rotation, text, fontSize: changes.fontSize ?? shape.mcpFontSize, color: changes.color ?? shape.mcpColor, fontFamily: changes.fontFamily ?? shape.mcpFontFamily }, shape.shapeID), groupId: changes.groupId ?? shape.groupId, parentFrame: changes.parentFrame ?? shape.parentFrame };
+  }
+  const copy = { ...clone(shape), ...clone(changes), shapeID: shape.shapeID, type: shape.type };
+  if (changes.options) copy.options = { ...(shape.options || {}), ...normalizeOptions({ ...(shape.options || {}), ...changes.options }) };
+  return copy;
+}
+
+function extractText(groupHTML = '') {
+  return String(groupHTML).replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+function validateShapeGeometry(shape, index, errors) {
+  const numbers = [];
+  if (['rectangle', 'frame', 'text', 'code', 'image', 'icon'].includes(shape.type)) numbers.push(['x', shape.x], ['y', shape.y]);
+  if (['rectangle', 'frame', 'image', 'icon'].includes(shape.type)) numbers.push(['width', shape.width], ['height', shape.height]);
+  if (shape.type === 'circle') numbers.push(['x', shape.x], ['y', shape.y], ['rx', shape.rx], ['ry', shape.ry]);
+  if (shape.startPoint) numbers.push(['startPoint.x', shape.startPoint.x], ['startPoint.y', shape.startPoint.y]);
+  if (shape.endPoint) numbers.push(['endPoint.x', shape.endPoint.x], ['endPoint.y', shape.endPoint.y]);
+  for (const [field, value] of numbers) if (!Number.isFinite(Number(value))) errors.push(`Shape ${index} has invalid ${field}`);
+  if (['rectangle', 'frame', 'image', 'icon'].includes(shape.type) && (Number(shape.width) <= 0 || Number(shape.height) <= 0)) errors.push(`Shape ${index} must have positive dimensions`);
+  if (shape.type === 'circle' && (Number(shape.rx) <= 0 || Number(shape.ry) <= 0)) errors.push(`Shape ${index} must have positive radii`);
+  if (shape.type === 'freehandStroke' && (!Array.isArray(shape.points) || shape.points.length < 2 || shape.points.length > 4096)) errors.push(`Shape ${index} has invalid freehand points`);
+  if (shape.type === 'text' && typeof shape.groupHTML !== 'string') errors.push(`Shape ${index} is missing text markup`);
+  if (shape.type === 'code' && typeof shape.groupHTML !== 'string') errors.push(`Shape ${index} is missing code markup`);
+  if (shape.type === 'image' && typeof shape.href !== 'string') errors.push(`Shape ${index} is missing image href`);
+  if (shape.type === 'icon' && typeof shape.elementHTML !== 'string') errors.push(`Shape ${index} is missing icon markup`);
+}
+
+export function getSceneSummary(scene) {
+  const counts = {};
+  for (const shape of scene.shapes || []) counts[shape.type] = (counts[shape.type] || 0) + 1;
+  return { name: scene.name, format: scene.format, version: scene.version, revision: Number(scene.mcpRevision || 0), shapeCount: scene.shapes?.length || 0, counts, bounds: getSceneBounds(scene) };
+}
+
+export function getSceneBounds(scene) {
+  const boxes = (scene.shapes || []).map(shapeBounds).filter(Boolean);
+  if (!boxes.length) return null;
+  const minX = Math.min(...boxes.map((b) => b.x)), minY = Math.min(...boxes.map((b) => b.y));
+  const maxX = Math.max(...boxes.map((b) => b.x + b.width)), maxY = Math.max(...boxes.map((b) => b.y + b.height));
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+
+export function shapeBounds(shape) {
+  if (shape.type === 'circle') return { x: shape.x - shape.rx, y: shape.y - shape.ry, width: shape.rx * 2, height: shape.ry * 2 };
+  if (shape.startPoint && shape.endPoint) {
+    const x = Math.min(shape.startPoint.x, shape.endPoint.x), y = Math.min(shape.startPoint.y, shape.endPoint.y);
+    return { x, y, width: Math.abs(shape.endPoint.x - shape.startPoint.x), height: Math.abs(shape.endPoint.y - shape.startPoint.y) };
+  }
+  if (Array.isArray(shape.points) && shape.points.length) {
+    const xs = shape.points.map((p) => p[0]), ys = shape.points.map((p) => p[1]);
+    return { x: Math.min(...xs), y: Math.min(...ys), width: Math.max(...xs) - Math.min(...xs), height: Math.max(...ys) - Math.min(...ys) };
+  }
+  if (shape.type === 'text') return { x: finite(shape.x), y: finite(shape.y), width: 160, height: 32 };
+  return { x: finite(shape.x), y: finite(shape.y), width: positive(shape.width), height: positive(shape.height) };
+}
+
+export function mergeTemplateScene(sceneInput, templateInput, { x, y } = {}) {
+  const scene = clone(sceneInput), template = clone(templateInput);
+  const validation = validateScene(template);
+  if (!validation.valid) throw new Error(`Template scene is invalid: ${validation.errors.join('; ')}`);
+  if (scene.shapes.length + template.shapes.length > MAX_SHAPES) throw new Error(`Imported template would exceed ${MAX_SHAPES} shapes`);
+  const bounds = getSceneBounds(template) || { x: 0, y: 0 };
+  const targetX = finite(x, scene.viewport?.x || 0), targetY = finite(y, scene.viewport?.y || 0);
+  const dx = targetX - bounds.x, dy = targetY - bounds.y;
+  const idMap = new Map(template.shapes.map((shape) => [shape.shapeID, `${shape.type}-${crypto.randomUUID()}`]));
+  const imported = template.shapes.map((shape) => {
+    const moved = translateShape(shape, dx, dy);
+    moved.shapeID = idMap.get(shape.shapeID);
+    if (moved.parentFrame) moved.parentFrame = idMap.get(moved.parentFrame) || null;
+    if (Array.isArray(moved.containedShapeIDs)) moved.containedShapeIDs = moved.containedShapeIDs.map((id) => idMap.get(id)).filter(Boolean);
+    if (moved.startAttachmentID) moved.startAttachmentID = idMap.get(moved.startAttachmentID) || null;
+    if (moved.endAttachmentID) moved.endAttachmentID = idMap.get(moved.endAttachmentID) || null;
+    if (moved.groupHTML) moved.groupHTML = moved.groupHTML.split(shape.shapeID).join(moved.shapeID);
+    if (moved.elementHTML) moved.elementHTML = moved.elementHTML.split(shape.shapeID).join(moved.shapeID);
+    return moved;
+  });
+  scene.shapes.push(...imported);
+  scene.mcpRevision = Number(scene.mcpRevision || 0) + 1;
+  scene.updatedAt = new Date().toISOString();
+  return { scene, revision: scene.mcpRevision, importedShapeIDs: imported.map((shape) => shape.shapeID) };
+}
+
+export const MCP_LIMITS = Object.freeze({ maxShapes: MAX_SHAPES, maxOperations: MAX_OPERATIONS });

package/src/mcp/server.js

@@ -0,0 +1,195 @@
+import { applyScenePatch, createEmptyScene, getSceneSummary, mergeTemplateScene, validateScene, MCP_LIMITS } from './scene.js';
+import { MarketplaceTemplateProvider } from './templates.js';
+import { renderSceneSvg } from './preview.js';
+
+const SERVER_NAME = 'lixsketch';
+const SERVER_VERSION = '1.0.0';
+const PROTOCOL_VERSION = '2025-11-25';
+const SUPPORTED_PROTOCOL_VERSIONS = new Set([PROTOCOL_VERSION, '2025-06-18', '2024-11-05']);
+
+const PATCH_OPERATION_SCHEMA = {
+  oneOf: [
+    { type: 'object', required: ['op', 'shape'], properties: { op: { const: 'add' }, shape: { type: 'object', description: 'A rectangle, circle, line, arrow, frame, freehandStroke, or text shape.' } } },
+    { type: 'object', required: ['op', 'shapeID', 'changes'], properties: { op: { const: 'update' }, shapeID: { type: 'string' }, changes: { type: 'object' } } },
+    { type: 'object', required: ['op'], properties: { op: { const: 'delete' }, shapeID: { type: 'string' }, shapeIDs: { type: 'array', items: { type: 'string' } } } },
+    { type: 'object', required: ['op', 'shapeIDs', 'dx', 'dy'], properties: { op: { const: 'translate' }, shapeIDs: { type: 'array', items: { type: 'string' } }, dx: { type: 'number' }, dy: { type: 'number' } } },
+    { type: 'object', required: ['op', 'name'], properties: { op: { const: 'rename_canvas' }, name: { type: 'string', maxLength: 72 } } },
+  ],
+};
+
+export const LIXSKETCH_MCP_TOOLS = Object.freeze([
+  {
+    name: 'canvas_get',
+    title: 'Read LixSketch canvas',
+    description: 'Return the canvas summary and optionally its editable scene shapes. Read this before mutation to obtain the current revision.',
+    inputSchema: { type: 'object', properties: { includeShapes: { type: 'boolean', default: false }, shapeIDs: { type: 'array', maxItems: 500, items: { type: 'string' } } }, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+  },
+  {
+    name: 'canvas_apply_patch',
+    title: 'Apply atomic canvas patch',
+    description: `Atomically add, update, translate, or delete shapes. Supports ${MCP_LIMITS.maxOperations} operations per call, optimistic revision checks, and dry runs.`,
+    inputSchema: { type: 'object', required: ['operations'], properties: { expectedRevision: { type: 'integer', minimum: 0 }, dryRun: { type: 'boolean', default: false }, operations: { type: 'array', minItems: 1, maxItems: MCP_LIMITS.maxOperations, items: PATCH_OPERATION_SCHEMA } }, additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+  },
+  {
+    name: 'canvas_validate',
+    title: 'Validate LixSketch canvas',
+    description: 'Validate the current scene format, supported shapes, unique IDs, and package limits.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+  },
+  {
+    name: 'canvas_preview',
+    title: 'Render canvas preview',
+    description: 'Render a lightweight SVG preview of the current scene for visual inspection before or after edits.',
+    inputSchema: { type: 'object', properties: { background: { type: 'string', pattern: '^#[0-9a-fA-F]{3,8}$' }, padding: { type: 'number', minimum: 0, maximum: 200, default: 40 } }, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+  },
+  {
+    name: 'canvas_new',
+    title: 'Create blank LixSketch canvas',
+    description: 'Replace the current scene with a blank canvas. Requires explicit confirmation.',
+    inputSchema: { type: 'object', required: ['confirm'], properties: { name: { type: 'string', maxLength: 72 }, confirm: { const: true } }, additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+  },
+  {
+    name: 'templates_search',
+    title: 'Search LixSketch templates',
+    description: 'Search published workspace and component templates in the LixSketch marketplace.',
+    inputSchema: { type: 'object', properties: { query: { type: 'string', maxLength: 80 }, tag: { type: 'string', maxLength: 24 }, limit: { type: 'integer', minimum: 1, maximum: 24, default: 12 } }, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+  },
+  {
+    name: 'template_insert',
+    title: 'Insert LixSketch template',
+    description: 'Insert a published template into the current canvas, remapping every shape and relationship ID. The operation is atomic and supports a dry run.',
+    inputSchema: { type: 'object', required: ['slug'], properties: { slug: { type: 'string', pattern: '^[a-z0-9-]{1,80}$' }, x: { type: 'number' }, y: { type: 'number' }, expectedRevision: { type: 'integer', minimum: 0 }, dryRun: { type: 'boolean', default: false } }, additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  },
+]);
+
+function toolResult(value, message) {
+  return {
+    content: [{ type: 'text', text: message || JSON.stringify(value, null, 2) }],
+    structuredContent: value,
+  };
+}
+
+function toolError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return { isError: true, content: [{ type: 'text', text: message }], structuredContent: { error: message } };
+}
+
+export class LixSketchMcpServer {
+  constructor({ store, templateProvider = new MarketplaceTemplateProvider(), serverInfo = {} } = {}) {
+    if (!store?.read || !store?.write) throw new Error('createLixSketchMcpServer requires a scene store with read() and write()');
+    this.store = store;
+    this.templateProvider = templateProvider;
+    this.serverInfo = { name: SERVER_NAME, version: SERVER_VERSION, ...serverInfo };
+    this.mutationChain = Promise.resolve();
+  }
+
+  listTools() {
+    return LIXSKETCH_MCP_TOOLS;
+  }
+
+  async callTool(name, args = {}) {
+    try {
+      switch (name) {
+        case 'canvas_get': {
+          const scene = await this.store.read();
+          let shapes;
+          if (args.includeShapes) {
+            const ids = new Set(args.shapeIDs || []);
+            shapes = ids.size ? scene.shapes.filter((shape) => ids.has(shape.shapeID)) : scene.shapes;
+          }
+          return toolResult({ summary: getSceneSummary(scene), ...(shapes ? { shapes } : {}) });
+        }
+        case 'canvas_validate': {
+          const scene = await this.store.read();
+          const validation = validateScene(scene);
+          return toolResult({ ...validation, summary: getSceneSummary(scene), limits: MCP_LIMITS });
+        }
+        case 'canvas_preview': {
+          const scene = await this.store.read();
+          const svg = renderSceneSvg(scene, args);
+          return toolResult({ svg, dataUrl: `data:image/svg+xml;base64,${encodeBase64(svg)}`, summary: getSceneSummary(scene) }, svg);
+        }
+        case 'templates_search': {
+          const templates = await this.templateProvider.search(args);
+          return toolResult({ templates: templates.map(safeTemplateMetadata) });
+        }
+        case 'canvas_apply_patch':
+          return await this.enqueueMutation(async () => {
+            const scene = await this.store.read();
+            const result = applyScenePatch(scene, args.operations, args);
+            if (!args.dryRun) await this.store.write(result.scene);
+            return toolResult({ revision: result.revision, dryRun: result.dryRun, changedShapeIDs: result.changedShapeIDs, summary: getSceneSummary(result.scene) }, args.dryRun ? 'Canvas patch is valid. No changes were saved.' : `Canvas patch saved at revision ${result.revision}.`);
+          });
+        case 'canvas_new':
+          if (args.confirm !== true) throw new Error('canvas_new requires confirm=true');
+          return await this.enqueueMutation(async () => {
+            const scene = createEmptyScene(args.name);
+            await this.store.write(scene);
+            return toolResult({ summary: getSceneSummary(scene) }, 'Blank canvas created.');
+          });
+        case 'template_insert':
+          return await this.enqueueMutation(async () => {
+            const scene = await this.store.read();
+            const revision = Number(scene.mcpRevision || 0);
+            if (args.expectedRevision !== undefined && Number(args.expectedRevision) !== revision) throw new Error(`Revision conflict: expected ${args.expectedRevision}, current ${revision}`);
+            const template = await this.templateProvider.load(args.slug);
+            const result = mergeTemplateScene(scene, template.scene, args);
+            if (!args.dryRun) await this.store.write(result.scene);
+            return toolResult({ template: safeTemplateMetadata(template.metadata), revision: result.revision, dryRun: Boolean(args.dryRun), importedShapeIDs: result.importedShapeIDs, summary: getSceneSummary(result.scene) }, args.dryRun ? 'Template import is valid. No changes were saved.' : `Template inserted with ${result.importedShapeIDs.length} shapes.`);
+          });
+        default: throw new Error(`Unknown tool "${name}"`);
+      }
+    } catch (error) {
+      return toolError(error);
+    }
+  }
+
+  enqueueMutation(operation) {
+    const pending = this.mutationChain.then(operation, operation);
+    this.mutationChain = pending.catch(() => {});
+    return pending;
+  }
+
+  async handleRequest(request) {
+    const method = request?.method;
+    if (method === 'initialize') {
+      const requested = request.params?.protocolVersion;
+      const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.has(requested) ? requested : PROTOCOL_VERSION;
+      return { protocolVersion, capabilities: { tools: { listChanged: false }, resources: { subscribe: false, listChanged: false } }, serverInfo: this.serverInfo, instructions: 'Read canvas_get before mutations. Use expectedRevision and dryRun for safe edits. Prefer template_insert for reusable component packs.' };
+    }
+    if (method === 'ping') return {};
+    if (method === 'tools/list') return { tools: this.listTools() };
+    if (method === 'tools/call') return this.callTool(request.params?.name, request.params?.arguments || {});
+    if (method === 'resources/list') return { resources: [{ uri: 'lixsketch://canvas', name: 'Current LixSketch canvas', description: 'The active editable .lixjson scene', mimeType: 'application/vnd.lixsketch+json' }, { uri: 'lixsketch://canvas/preview.svg', name: 'Current canvas preview', description: 'A lightweight SVG preview of the current scene', mimeType: 'image/svg+xml' }] };
+    if (method === 'resources/read') {
+      const scene = await this.store.read();
+      if (request.params?.uri === 'lixsketch://canvas') return { contents: [{ uri: 'lixsketch://canvas', mimeType: 'application/vnd.lixsketch+json', text: JSON.stringify(scene) }] };
+      if (request.params?.uri === 'lixsketch://canvas/preview.svg') return { contents: [{ uri: 'lixsketch://canvas/preview.svg', mimeType: 'image/svg+xml', text: renderSceneSvg(scene) }] };
+      throw Object.assign(new Error('Resource not found'), { code: -32002 });
+    }
+    if (method?.startsWith('notifications/')) return undefined;
+    throw Object.assign(new Error(`Method not found: ${method}`), { code: -32601 });
+  }
+}
+
+function safeTemplateMetadata(template = {}) {
+  return { id: template.id, slug: template.slug, title: template.title, description: template.description || '', tags: template.tags || [], publisher: template.publisher, views: template.views, forks: template.forks, clones: template.clones, publishedAt: template.publishedAt, updatedAt: template.updatedAt };
+}
+
+function encodeBase64(value) {
+  if (typeof btoa === 'function') return btoa(unescape(encodeURIComponent(value)));
+  return Buffer.from(value, 'utf8').toString('base64');
+}
+
+export function createLixSketchMcpServer(options) {
+  return new LixSketchMcpServer(options);
+}
+
+export { PROTOCOL_VERSION as LIXSKETCH_MCP_PROTOCOL_VERSION };

package/src/mcp/stdio.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { createLixSketchMcpServer } from './server.js';
+import { FileSceneStore } from './fileStore.js';
+import { MarketplaceTemplateProvider } from './templates.js';
+import { serveLixSketchStdio } from './stdioTransport.js';
+
+function parseArguments(argv) {
+  const options = { scene: process.env.LIXSKETCH_SCENE_FILE || './lixsketch-mcp.lixjson', marketplaceUrl: process.env.LIXSKETCH_MARKETPLACE_URL || 'https://sketch.elixpo.com' };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--scene') options.scene = argv[++index];
+    else if (argument === '--marketplace-url') options.marketplaceUrl = argv[++index];
+    else if (argument === '--help' || argument === '-h') options.help = true;
+    else throw new Error(`Unknown argument: ${argument}`);
+  }
+  if (!options.scene) throw new Error('--scene requires a file path');
+  return options;
+}
+
+function printHelp() {
+  process.stderr.write(`LixSketch MCP server\n\nUsage:\n  lixsketch-mcp --scene ./diagram.lixjson\n\nOptions:\n  --scene <path>             Atomic .lixjson scene file (default: ./lixsketch-mcp.lixjson)\n  --marketplace-url <url>    Template marketplace origin\n  -h, --help                 Show this help\n\nEnvironment:\n  LIXSKETCH_SCENE_FILE\n  LIXSKETCH_MARKETPLACE_URL\n`);
+}
+
+async function main() {
+  const options = parseArguments(process.argv.slice(2));
+  if (options.help) { printHelp(); return; }
+  const store = new FileSceneStore(options.scene);
+  const server = createLixSketchMcpServer({ store, templateProvider: new MarketplaceTemplateProvider({ baseUrl: options.marketplaceUrl }) });
+  const transport = serveLixSketchStdio(server);
+  const close = () => { void transport.close().finally(() => process.exit(0)); };
+  process.once('SIGINT', close);
+  process.once('SIGTERM', close);
+  process.stderr.write(`LixSketch MCP ready: ${store.filePath}\n`);
+  await transport.closed;
+}
+
+main().catch((error) => {
+  process.stderr.write(`LixSketch MCP failed: ${error?.message || error}\n`);
+  process.exitCode = 1;
+});

package/src/mcp/stdioTransport.js

@@ -0,0 +1,46 @@
+import { createInterface } from 'node:readline';
+
+const MAX_MESSAGE_BYTES = 10 * 1024 * 1024;
+
+export function serveLixSketchStdio(server, { input = process.stdin, output = process.stdout } = {}) {
+  if (!server?.handleRequest) throw new Error('A LixSketch MCP server is required');
+  const lines = createInterface({ input, crlfDelay: Infinity, terminal: false });
+  let processing = Promise.resolve();
+  let resolveClosed;
+  const closed = new Promise((resolve) => { resolveClosed = resolve; });
+  const send = (message) => output.write(`${JSON.stringify(message)}\n`);
+
+  lines.on('line', (line) => {
+    processing = processing.then(async () => {
+      if (!line.trim()) return;
+      if (Buffer.byteLength(line, 'utf8') > MAX_MESSAGE_BYTES) {
+        send({ jsonrpc: '2.0', id: null, error: { code: -32600, message: 'MCP request exceeds the 10 MB limit' } });
+        return;
+      }
+      let request;
+      try { request = JSON.parse(line); }
+      catch { send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }); return; }
+      if (request.jsonrpc !== '2.0' || typeof request.method !== 'string') {
+        if (request.id !== undefined) send({ jsonrpc: '2.0', id: request.id ?? null, error: { code: -32600, message: 'Invalid Request' } });
+        return;
+      }
+      try {
+        const result = await server.handleRequest(request);
+        if (request.id !== undefined && result !== undefined) send({ jsonrpc: '2.0', id: request.id, result });
+      } catch (error) {
+        if (request.id !== undefined) send({ jsonrpc: '2.0', id: request.id, error: { code: Number(error?.code) || -32603, message: error?.message || 'Internal error' } });
+      }
+    }).catch((error) => {
+      process.stderr.write(`LixSketch MCP transport error: ${error?.message || error}\n`);
+    });
+  });
+  lines.once('close', () => processing.finally(resolveClosed));
+
+  return {
+    closed,
+    close: async () => {
+      lines.close();
+      await processing;
+    },
+  };
+}

package/src/mcp/store.js

@@ -0,0 +1,23 @@
+import { createEmptyScene, validateScene } from './scene.js';
+
+export class MemorySceneStore {
+  #scene;
+
+  constructor(scene = createEmptyScene()) {
+    const validation = validateScene(scene);
+    if (!validation.valid) throw new Error(`Invalid initial scene: ${validation.errors.join('; ')}`);
+    this.#scene = structuredClone(scene);
+  }
+
+  async read() {
+    return structuredClone(this.#scene);
+  }
+
+  async write(scene) {
+    const validation = validateScene(scene);
+    if (!validation.valid) throw new Error(`Refusing to store invalid scene: ${validation.errors.join('; ')}`);
+    this.#scene = structuredClone(scene);
+    return this.read();
+  }
+}
+

package/src/mcp/templates.js

@@ -0,0 +1,51 @@
+const DEFAULT_MARKETPLACE_URL = 'https://sketch.elixpo.com';
+
+function decodeBase64Url(value) {
+  const base64 = String(value).replaceAll('-', '+').replaceAll('_', '/');
+  const padded = base64 + '='.repeat((4 - base64.length % 4) % 4);
+  const binary = atob(padded);
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+
+export async function decryptPublicTemplate(ciphertext, keyValue) {
+  const keyBytes = decodeBase64Url(keyValue);
+  if (keyBytes.byteLength !== 32) throw new Error('Template key is not AES-256');
+  const combined = decodeBase64Url(ciphertext);
+  if (combined.byteLength < 28) throw new Error('Template ciphertext is invalid');
+  const key = await crypto.subtle.importKey('raw', keyBytes, { name: 'AES-GCM', length: 256 }, false, ['decrypt']);
+  const plaintext = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: combined.slice(0, 12) }, key, combined.slice(12));
+  return JSON.parse(new TextDecoder().decode(plaintext));
+}
+
+export class MarketplaceTemplateProvider {
+  constructor({ baseUrl = DEFAULT_MARKETPLACE_URL, fetchImpl = globalThis.fetch } = {}) {
+    if (typeof fetchImpl !== 'function') throw new Error('MarketplaceTemplateProvider requires fetch');
+    this.baseUrl = String(baseUrl).replace(/\/$/, '');
+    this.fetch = fetchImpl;
+  }
+
+  async search({ query = '', tag = '', limit = 12 } = {}) {
+    const url = new URL('/api/templates', this.baseUrl);
+    if (query) url.searchParams.set('q', String(query).slice(0, 80));
+    if (tag) url.searchParams.set('tag', String(tag).slice(0, 24));
+    url.searchParams.set('limit', String(Math.min(24, Math.max(1, Number(limit) || 12))));
+    const response = await this.fetch(url, { headers: { accept: 'application/json' } });
+    const body = await response.json();
+    if (!response.ok) throw new Error(body.error || `Marketplace request failed (${response.status})`);
+    return body.templates || [];
+  }
+
+  async load(slug) {
+    const safeSlug = String(slug || '').trim();
+    if (!/^[a-z0-9-]{1,80}$/.test(safeSlug)) throw new Error('Template slug is invalid');
+    const url = new URL(`/api/templates/${encodeURIComponent(safeSlug)}`, this.baseUrl);
+    url.searchParams.set('snapshot', '1');
+    const response = await this.fetch(url, { headers: { accept: 'application/json' } });
+    const body = await response.json();
+    if (!response.ok) throw new Error(body.error || `Template request failed (${response.status})`);
+    const template = body.template;
+    if (!template?.encryptedData || !template?.publicKey) throw new Error('Template snapshot is unavailable');
+    return { metadata: { ...template, encryptedData: undefined, publicKey: undefined, encryptedDocData: undefined }, scene: await decryptPublicTemplate(template.encryptedData, template.publicKey) };
+  }
+}
+