synabun 1.3.0

package/mcp-server/src/tools/response.ts

@@ -0,0 +1,26 @@
+/**
+ * MCP response helpers — eliminates verbose response object boilerplate.
+ * Inspired by FastMCP's approach of letting tools return simple values.
+ *
+ * Before:  return { content: [{ type: 'text' as const, text: msg }] };
+ * After:   return text(msg);
+ */
+
+/**
+ * Strip unpaired Unicode surrogates (U+D800–U+DFFF) that produce
+ * invalid JSON ("no low surrogate in string" API errors).
+ * Common in browser-extracted content from Facebook, WhatsApp, etc.
+ */
+function sanitizeSurrogates(s: string): string {
+  return s.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, '\uFFFD');
+}
+
+/** Wrap a string in the MCP text response format. */
+export function text(msg: string) {
+  return { content: [{ type: 'text' as const, text: sanitizeSurrogates(msg) }] };
+}
+
+/** Wrap base64 image data in the MCP image response format. */
+export function image(data: string, mimeType: string) {
+  return { content: [{ type: 'image' as const, data, mimeType }] };
+}

package/mcp-server/src/tools/restore.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { restoreMemory, getMemory } from '../services/sqlite.js';
+import type { MemoryPayload } from '../types.js';
+import { text } from './response.js';
+
+export const restoreSchema = {
+  memory_id: z
+    .string()
+    .describe(
+      'The memory ID to restore from trash. Use the full UUID.'
+    ),
+};
+
+export const restoreDescription =
+  'Restore a trashed memory by ID. Use this to undo a forget operation.';
+
+export async function handleRestore(args: { memory_id: string }) {
+  const memoryId = args.memory_id;
+
+  const existing = await getMemory(memoryId);
+  if (!existing) {
+    return text(`Memory "${memoryId}" not found.`);
+  }
+
+  const payload = existing.payload as unknown as MemoryPayload;
+
+  if (!payload.trashed_at) {
+    return text(`Memory [${memoryId.slice(0, 8)}] is not in trash.`);
+  }
+
+  await restoreMemory(memoryId);
+
+  return text(`Restored [${memoryId.slice(0, 8)}]: "${payload.content.slice(0, 80)}..."`);
+}

package/mcp-server/src/tools/sync.ts

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+import { scrollMemories } from '../services/sqlite.js';
+import { hashFile } from '../services/file-checksums.js';
+import type { MemoryPayload } from '../types.js';
+import { coerceStringArray } from './utils.js';
+import { text } from './response.js';
+
+export const syncSchema = {
+  project: z
+    .string()
+    .optional()
+    .describe('Optional: only check memories for this project.'),
+  categories: coerceStringArray()
+    .optional()
+    .describe('Optional: filter results to memories in these categories only.'),
+  limit: z
+    .coerce.number()
+    .min(1)
+    .max(1000)
+    .optional()
+    .describe('Max stale memories to return (default 50). Keep low to avoid output overflow.'),
+};
+
+export const syncDescription =
+  'Check for stale memories whose related files have changed. Compares stored file checksums against current hashes. Returns compact output (ID + changed files only, no content). IMPORTANT: Always pass "categories" to scope the scan — calling without categories scans ALL memories and may produce output too large to return inline. For large memory sets, call iteratively per category rather than globally. Default limit is 50; increase only when using a narrow category filter.';
+
+export async function handleSync(args: { project?: string; categories?: string[]; limit?: number }) {
+  // Scroll all memories (paginated)
+  const allPoints: Array<{ id: string | number; payload: unknown }> = [];
+  let offset: string | undefined;
+
+  do {
+    const filter = args.project
+      ? { must: [{ key: 'project', match: { value: args.project } }] }
+      : undefined;
+    const result = await scrollMemories(filter, 100, offset);
+    for (const p of result.points) {
+      if (p.payload) allPoints.push({ id: p.id, payload: p.payload });
+    }
+    offset = (result.next_page_offset as string) ?? undefined;
+  } while (offset);
+
+  // Only evaluate memories with stored file_checksums — we need a baseline to compare against.
+  // Memories with related_files but no checksums are legacy; we can't determine staleness without a baseline.
+  const withChecksums = allPoints.filter(p => {
+    const payload = p.payload as unknown as MemoryPayload;
+    return payload.file_checksums && Object.keys(payload.file_checksums).length > 0;
+  });
+
+  const stale: Array<{
+    id: string | number;
+    category: string;
+    importance: number;
+    stale_files: string[];
+  }> = [];
+
+  for (const point of withChecksums) {
+    const payload = point.payload as unknown as MemoryPayload;
+    const storedChecksums = payload.file_checksums!;
+    const staleFiles: string[] = [];
+
+    for (const filePath of Object.keys(storedChecksums)) {
+      const currentHash = hashFile(filePath);
+      if (!currentHash) continue; // File not found — can't compare, skip
+
+      const storedHash = storedChecksums[filePath];
+      if (currentHash !== storedHash) {
+        staleFiles.push(filePath);
+      }
+    }
+
+    if (staleFiles.length > 0) {
+      stale.push({
+        id: point.id,
+        category: payload.category,
+        importance: payload.importance,
+        stale_files: staleFiles,
+      });
+    }
+  }
+
+  // Apply category filter if provided
+  const filtered = args.categories && args.categories.length > 0
+    ? stale.filter(m => args.categories!.includes(m.category))
+    : stale;
+
+  if (filtered.length === 0) {
+    const scopeMsg = args.categories ? ` in categories [${args.categories.join(', ')}]` : '';
+    return text(`All clear — checked ${withChecksums.length} memories with stored checksums${scopeMsg}, none are stale.`);
+  }
+
+  // Sort by importance descending
+  filtered.sort((a, b) => b.importance - a.importance);
+
+  // Apply limit
+  const maxResults = args.limit ?? 50;
+  const limited = filtered.slice(0, maxResults);
+  const truncated = filtered.length > maxResults;
+
+  // Compact output — IDs and changed files only, no full content
+  const scopeMsg = args.categories ? ` in [${args.categories.join(', ')}]` : '';
+  let msg = `Found ${filtered.length} stale memories${scopeMsg} (out of ${withChecksums.length} with checksums)`;
+  if (truncated) msg += ` — showing first ${maxResults}`;
+  msg += `:\n\n`;
+
+  for (const mem of limited) {
+    msg += `${mem.id} | ${mem.category} | imp:${mem.importance}\n`;
+    msg += `  Changed: ${mem.stale_files.join(', ')}\n`;
+  }
+
+  msg += `\nTo get full content: use recall with the memory ID, or memories with action "by-category".`;
+
+  return text(msg);
+}

package/mcp-server/src/tools/tictactoe-tools.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+import * as ni from '../services/neural-interface.js';
+import { text } from './response.js';
+
+// ═══════════════════════════════════════════
+// tictactoe — Dedicated TicTacToe MCP tool
+// ═══════════════════════════════════════════
+
+export const tictactoeSchema = {
+  action: z.enum(['start', 'move', 'state', 'end']).describe(
+    'Game action. "start" = set up board (optional piece: X or O). "move" = place piece (requires cell 1-9). "state" = get current board. "end" = tear down game.'
+  ),
+  cell: z.number().min(1).max(9).optional().describe(
+    'Cell number 1-9 (required for "move" action). Layout:\n  1 | 2 | 3\n  ---------\n  4 | 5 | 6\n  ---------\n  7 | 8 | 9'
+  ),
+  piece: z.enum(['X', 'O']).optional().describe(
+    'Which piece you play as (for "start" action). Default: X. X always goes first.'
+  ),
+};
+
+export const tictactoeDescription =
+  'Play Tic Tac Toe on the whiteboard. Actions: "start" sets up the board (piece defaults to X), "move" places the current turn\'s piece in cell 1-9, "state" shows the current board, "end" closes the game. The board renders visually on the whiteboard. X always goes first. Returns ASCII board + game status after each action.';
+
+export async function handleTictactoe(args: { action: string; cell?: number; piece?: string }) {
+  switch (args.action) {
+    case 'start':
+      return handleStart(args.piece);
+    case 'move':
+      return handleMove(args.cell);
+    case 'state':
+      return handleState();
+    case 'end':
+      return handleEnd();
+    default:
+      return text(`Unknown action: ${args.action}`);
+  }
+}
+
+async function handleStart(piece?: string) {
+  const result = await ni.tictactoeStart(piece);
+  if (result.error) {
+    return text(`Failed to start game: ${result.error}`);
+  }
+
+  const msg = `Game started! You are ${result.piece}.\n\n${result.ascii}\n\nTurn: ${result.turn} | Status: ${result.status}`;
+  return text(msg);
+}
+
+async function handleMove(cell?: number) {
+  if (cell === undefined) {
+    return text('cell is required for move action (1-9)');
+  }
+
+  const result = await ni.tictactoeMove(cell);
+  if (result.error) {
+    return text(`Move failed: ${result.error}`);
+  }
+
+  let statusLine = `Turn: ${result.turn} | Status: ${result.status}`;
+  if (result.winner) {
+    statusLine = `Status: ${result.winner} wins!`;
+  } else if (result.status === 'draw') {
+    statusLine = 'Status: draw';
+  }
+
+  const msg = `${result.ascii}\n\n${statusLine}`;
+  return text(msg);
+}
+
+async function handleState() {
+  const result = await ni.tictactoeState();
+  if (result.error) {
+    return text(`Failed to get state: ${result.error}`);
+  }
+
+  if (!result.active) {
+    return text('No active TicTacToe game. Use action "start" to begin.');
+  }
+
+  let statusLine = `Turn: ${result.turn} | Status: ${result.status} | You are: ${result.piece}`;
+  if (result.winner) {
+    statusLine = `Status: ${result.winner} wins! | You were: ${result.piece}`;
+  } else if (result.status === 'draw') {
+    statusLine = `Status: draw | You were: ${result.piece}`;
+  }
+
+  const msg = `${result.ascii}\n\n${statusLine}`;
+  return text(msg);
+}
+
+async function handleEnd() {
+  const result = await ni.tictactoeEnd();
+  if (result.error) {
+    return text(`Failed to end game: ${result.error}`);
+  }
+
+  return text('Game ended. Board cleared.');
+}

package/mcp-server/src/tools/tictactoe.ts

@@ -0,0 +1,13 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import {
+  tictactoeSchema, tictactoeDescription, handleTictactoe,
+} from './tictactoe-tools.js';
+
+/**
+ * Register the TicTacToe MCP tool on the given server instance.
+ * Single tool with action-based dispatch: start, move, state, end.
+ */
+export function registerTicTacToeTools(server: McpServer) {
+  server.tool('tictactoe', tictactoeDescription, tictactoeSchema, handleTictactoe);
+}

package/mcp-server/src/tools/utils.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema that accepts an array of strings OR a string representation of one.
+ *
+ * Claude Code's MCP client sometimes serializes array arguments as strings
+ * (e.g. `"[\"a\",\"b\"]"` or `"a, b"`) instead of real JSON arrays.
+ * This preprocessor coerces both forms into a proper string array.
+ */
+export function coerceStringArray() {
+  return z.preprocess((val) => {
+    if (Array.isArray(val)) return val;
+    if (typeof val === 'string') {
+      const trimmed = val.trim();
+      if (!trimmed) return [];
+      // Try JSON array first: ["a", "b"]
+      if (trimmed.startsWith('[')) {
+        try { return JSON.parse(trimmed); } catch { /* fall through */ }
+      }
+      // Comma-separated fallback: "a, b, c"
+      return trimmed.split(',').map(s => s.trim()).filter(Boolean);
+    }
+    return val;
+  }, z.array(z.string()));
+}

package/mcp-server/src/tools/whiteboard-tools.ts

@@ -0,0 +1,260 @@
+import { z } from 'zod';
+import * as ni from '../services/neural-interface.js';
+import { text, image } from './response.js';
+
+// ═══════════════════════════════════════════
+// whiteboard_read
+// ═══════════════════════════════════════════
+
+export const whiteboardReadSchema = {};
+
+export const whiteboardReadDescription =
+  'Read the current whiteboard state. Returns element descriptions with IDs, positions, and properties, plus the usable viewport dimensions (width x height in pixels, excluding navbar and terminal). ALWAYS call this before placing elements — the viewport tells you the exact canvas boundaries. All elements must fit within these dimensions.';
+
+interface WhiteboardElement {
+  id: string;
+  type: string;
+  x: number;
+  y: number;
+  width?: number;
+  height?: number;
+  content?: string;
+  items?: string[];
+  ordered?: boolean;
+  shape?: string;
+  color?: string;
+  fontSize?: number;
+  bold?: boolean;
+  italic?: boolean;
+  points?: number[][];
+  startAnchor?: string | null;
+  endAnchor?: string | null;
+  strokeWidth?: number;
+  rotation?: number;
+  zIndex?: number;
+  dataUrl?: string;
+  sectionType?: string;
+  label?: string;
+}
+
+function describeElement(el: WhiteboardElement): string {
+  const pos = `at (${Math.round(el.x)}, ${Math.round(el.y)})`;
+
+  switch (el.type) {
+    case 'text': {
+      const style = [
+        el.bold && 'bold',
+        el.italic && 'italic',
+        el.fontSize && `${el.fontSize}px`,
+        el.color && `color:${el.color}`,
+      ].filter(Boolean).join(', ');
+      const content = el.content || '(empty)';
+      const preview = content.length > 80 ? content.slice(0, 80) + '...' : content;
+      return `[${el.id}] TEXT ${pos}: "${preview}"${style ? ` (${style})` : ''}`;
+    }
+    case 'shape': {
+      const dims = `${Math.round(el.width || 160)}x${Math.round(el.height || 100)}`;
+      return `[${el.id}] SHAPE:${el.shape || 'rect'} ${pos} ${dims}${el.color ? ` color:${el.color}` : ''}`;
+    }
+    case 'arrow': {
+      const pts = (el.points || []).map(p => `(${Math.round(p[0])},${Math.round(p[1])})`).join(' → ');
+      const anchors = [];
+      if (el.startAnchor) anchors.push(`from:${el.startAnchor}`);
+      if (el.endAnchor) anchors.push(`to:${el.endAnchor}`);
+      return `[${el.id}] ARROW: ${pts}${anchors.length ? ` anchored ${anchors.join(', ')}` : ''}`;
+    }
+    case 'pen': {
+      const ptCount = el.points?.length || 0;
+      return `[${el.id}] PEN ${pos} (${ptCount} points, stroke:${el.strokeWidth || 3})${el.color ? ` color:${el.color}` : ''}`;
+    }
+    case 'list': {
+      const items = el.items || [];
+      const preview = items.slice(0, 5).map((it, i) => `  ${i + 1}. ${it}`).join('\n');
+      const more = items.length > 5 ? `\n  ... +${items.length - 5} more` : '';
+      return `[${el.id}] LIST ${pos} (${items.length} item${items.length !== 1 ? 's' : ''}):\n${preview}${more}`;
+    }
+    case 'image': {
+      const dims = `${Math.round(el.width || 0)}x${Math.round(el.height || 0)}`;
+      return `[${el.id}] IMAGE ${pos} ${dims}`;
+    }
+    case 'section': {
+      const dims = `${Math.round(el.width || 0)}x${Math.round(el.height || 0)}`;
+      const sType = el.sectionType || 'unknown';
+      const label = el.label || sType;
+      return `[${el.id}] SECTION:${sType} ${pos} ${dims} "${label}"`;
+    }
+    default:
+      return `[${el.id}] ${el.type.toUpperCase()} ${pos}`;
+  }
+}
+
+export async function handleWhiteboardRead() {
+  const result = await ni.getWhiteboard();
+  if (result.error) {
+    return text(`Failed to read whiteboard: ${result.error}`);
+  }
+
+  const elements = (result.elements || []) as WhiteboardElement[];
+  const viewport = result.viewport as { width: number; height: number; yOffset?: number; xOffset?: number } | null;
+
+  if (elements.length === 0) {
+    let emptyText = 'Whiteboard is empty. No elements present.';
+    if (viewport) emptyText += `\nUsable viewport: ${viewport.width}x${viewport.height} (origin offset: x=${viewport.xOffset || 0}, y=${viewport.yOffset || 0})\n⚠️ Design compact layouts centered in the viewport. Do NOT fill the entire width — use ~70-80% of viewport width, centered. All sections must fit vertically within the viewport height. Scale section heights proportionally to fit.`;
+    return text(emptyText);
+  }
+
+  let msg = `Whiteboard: ${elements.length} element(s)`;
+  if (viewport) msg += ` | Usable viewport: ${viewport.width}x${viewport.height} (origin: x=${viewport.xOffset || 0}, y=${viewport.yOffset || 0})`;
+  msg += '\n\n';
+  msg += elements.map(describeElement).join('\n');
+
+  // Spatial bounds summary
+  const positioned = elements.filter(e => e.x != null && e.y != null);
+  if (positioned.length > 0) {
+    const xs = positioned.map(e => e.x);
+    const ys = positioned.map(e => e.y);
+    msg += `\n\nBounds: x=[${Math.round(Math.min(...xs))}, ${Math.round(Math.max(...xs))}], y=[${Math.round(Math.min(...ys))}, ${Math.round(Math.max(...ys))}]`;
+  }
+
+  return text(msg);
+}
+
+
+// ═══════════════════════════════════════════
+// whiteboard_add
+// ═══════════════════════════════════════════
+
+export const whiteboardAddSchema = {
+  coordMode: z.enum(['px', 'pct']).optional().describe('Coordinate mode. "px" (default) = absolute pixels. "pct" = percentage of viewport (0-100). x:50 y:50 = exact center.'),
+  layout: z.enum(['row', 'column', 'grid', 'center']).optional().describe('Auto-layout (overrides x/y). "row" = horizontal centered. "column" = vertical centered. "grid" = auto columns. "center" = stacked center.'),
+  elements: z.array(z.object({
+    type: z.enum(['text', 'list', 'shape', 'arrow', 'pen', 'image', 'section']).describe('Element type'),
+    x: z.number().optional().describe('X position (pixels from left). Required for text, list, shape.'),
+    y: z.number().optional().describe('Y position (pixels from top). Required for text, list, shape.'),
+    width: z.number().optional().describe('Width in pixels (shapes). Default: 160'),
+    height: z.number().optional().describe('Height in pixels (shapes). Default: 100'),
+    content: z.string().optional().describe('Text content (for text elements). Use \\n for line breaks.'),
+    items: z.array(z.string()).optional().describe('List items array (for list elements). Each string is one bullet point.'),
+    ordered: z.boolean().optional().describe('Use numbered list instead of bullets (list elements). Default: false'),
+    fontSize: z.number().optional().describe('Font size in px (text: default 22, list: default 18)'),
+    color: z.string().optional().describe('Color as CSS value. Default: rgba(255,255,255,0.85). Options: #ef4444 (red), #f97316 (orange), #eab308 (yellow), #22c55e (green), #3b82f6 (blue), #a855f7 (purple), #ec4899 (pink), #06b6d4 (cyan)'),
+    bold: z.boolean().optional().describe('Bold text (text elements)'),
+    italic: z.boolean().optional().describe('Italic text (text elements)'),
+    shape: z.enum(['rect', 'pill', 'circle', 'drawn-circle']).optional().describe('Shape subtype (for shape elements). Default: rect'),
+    points: z.array(z.array(z.number()).length(2)).optional().describe('Array of [x,y] waypoints (for arrow and pen elements). Arrows need 2+ points.'),
+    startAnchor: z.string().optional().describe('Element ID to anchor arrow start to'),
+    endAnchor: z.string().optional().describe('Element ID to anchor arrow end to'),
+    strokeWidth: z.number().optional().describe('Stroke width for pen elements (default 3)'),
+    rotation: z.number().optional().describe('Rotation in degrees'),
+    url: z.string().optional().describe('URL path for image elements (e.g., "/games/TicTacToe/Cross.svg"). Server resolves to base64 dataUrl.'),
+    sectionType: z.enum(['navbar', 'hero', 'sidebar', 'content', 'footer', 'card', 'form', 'image-placeholder', 'button', 'text-block', 'grid', 'modal']).optional().describe('Section type for wireframe elements (type=section). Determines default size, color, and semantic meaning.'),
+    label: z.string().optional().describe('Display label for section elements. Defaults to section type name.'),
+  })).describe('Array of elements to add to the whiteboard'),
+};
+
+export const whiteboardAddDescription =
+  'Add elements to the whiteboard. ALWAYS call whiteboard_read first to get the usable viewport size.\n\n⚠️ LAYOUT RULES (MANDATORY):\n1. COMPACT DESIGN — Do NOT fill the entire viewport. Use ~70-80% of viewport width, centered horizontally. This creates a clean, contained wireframe.\n2. VERTICAL FIT — ALL elements MUST fit within the viewport height. Scale section heights proportionally if the total exceeds the available space. Leave ~20px padding from top and bottom edges.\n3. NO OVERFLOW — No element should extend beyond viewport edges. The viewport already excludes the navbar, toolbar, and terminal. Coordinates are auto-offset to the usable area.\n4. PROPORTIONAL SCALING — Section default sizes are for manual use. When building full-page wireframes via MCP, calculate heights as fractions of viewport height (e.g. navbar=6%, hero=30%, content=40%, footer=10%).\n\nCoordinate modes (coordMode): "px" (default) = absolute pixels. "pct" = percentage of usable viewport (0-100), e.g. x:10 y:5 = near top-left of usable area. Coordinates are automatically offset past the navbar and toolbar.\n\nAuto-layout (layout): overrides individual x/y. "row" = horizontal row centered vertically. "column" = vertical stack centered horizontally. "grid" = auto-grid (2-4 columns based on count). "center" = stacked in center. Layouts auto-fit within viewport.\n\nSupports: text (\\n for line breaks), list (items array), shape (rect/pill/circle/drawn-circle), arrow (points + optional anchoring), pen, image (server URL), section (wireframe blocks). Returns assigned IDs. Good defaults: text fontSize 22, list fontSize 18, shapes 160x100.\n\nWireframe sections (type "section"): Semantic website layout blocks. Set sectionType (navbar/hero/sidebar/content/footer/card/form/image-placeholder/button/text-block/grid/modal) and optional label. When using "pct" coordMode, set widths as % of viewport (e.g. 70 for 70%) and heights as % too. Center horizontally with x: 15 for a 70%-width element.';
+
+export async function handleWhiteboardAdd(args: { elements: Record<string, unknown>[]; coordMode?: string; layout?: string }) {
+  const result = await ni.addWhiteboardElements(args.elements, args.coordMode, args.layout);
+  if (result.error) {
+    return text(`Failed to add elements: ${result.error}`);
+  }
+
+  const added = result.added as { id: string; type: string; zIndex: number }[];
+  const summary = added.map(a => `  ${a.id} (${a.type}, z:${a.zIndex})`).join('\n');
+  return text(`Added ${added.length} element(s):\n${summary}`);
+}
+
+
+// ═══════════════════════════════════════════
+// whiteboard_update
+// ═══════════════════════════════════════════
+
+export const whiteboardUpdateSchema = {
+  coordMode: z.enum(['px', 'pct']).optional().describe('Coordinate mode for position/size values. "pct" = percentage of viewport.'),
+  id: z.string().describe('The element ID to update (from whiteboard_read results)'),
+  updates: z.object({
+    x: z.number().optional().describe('New X position'),
+    y: z.number().optional().describe('New Y position'),
+    width: z.number().optional().describe('New width'),
+    height: z.number().optional().describe('New height'),
+    content: z.string().optional().describe('New text content (text elements). Use \\n for line breaks.'),
+    items: z.array(z.string()).optional().describe('New list items array (list elements)'),
+    ordered: z.boolean().optional().describe('Switch between bullet/numbered list (list elements)'),
+    fontSize: z.number().optional().describe('New font size'),
+    color: z.string().optional().describe('New color'),
+    bold: z.boolean().optional().describe('Bold text'),
+    italic: z.boolean().optional().describe('Italic text'),
+    shape: z.enum(['rect', 'pill', 'circle', 'drawn-circle']).optional().describe('Change shape type'),
+    points: z.array(z.array(z.number()).length(2)).optional().describe('New points array'),
+    startAnchor: z.string().nullable().optional().describe('New start anchor ID (null to detach)'),
+    endAnchor: z.string().nullable().optional().describe('New end anchor ID (null to detach)'),
+    rotation: z.number().optional().describe('New rotation in degrees'),
+    strokeWidth: z.number().optional().describe('New stroke width'),
+    sectionType: z.enum(['navbar', 'hero', 'sidebar', 'content', 'footer', 'card', 'form', 'image-placeholder', 'button', 'text-block', 'grid', 'modal']).optional().describe('Change section type'),
+    label: z.string().optional().describe('Change section label'),
+  }).describe('Fields to update. Only specified fields are changed; others remain untouched.'),
+};
+
+export const whiteboardUpdateDescription =
+  'Update properties of an existing whiteboard element. Use whiteboard_read first to get element IDs. Only the specified fields are changed; others remain untouched. Set coordMode to "pct" to use percentage-based positioning. Changes appear in real-time.';
+
+export async function handleWhiteboardUpdate(args: { id: string; updates: Record<string, unknown>; coordMode?: string }) {
+  const result = await ni.updateWhiteboardElement(args.id, args.updates, args.coordMode);
+  if (result.error) {
+    return text(`Failed to update element: ${result.error}`);
+  }
+
+  const el = result.element as WhiteboardElement;
+  return text(`Updated: ${describeElement(el)}`);
+}
+
+
+// ═══════════════════════════════════════════
+// whiteboard_remove
+// ═══════════════════════════════════════════
+
+export const whiteboardRemoveSchema = {
+  id: z.string().optional().describe('Element ID to remove. Omit to clear the entire whiteboard.'),
+};
+
+export const whiteboardRemoveDescription =
+  'Remove a specific element from the whiteboard by ID, or clear the entire whiteboard if no ID is provided. Use whiteboard_read first to see element IDs. Arrows anchored to a removed element will be detached.';
+
+export async function handleWhiteboardRemove(args: { id?: string }) {
+  if (!args.id) {
+    const result = await ni.clearWhiteboard();
+    if (result.error) {
+      return text(`Failed to clear whiteboard: ${result.error}`);
+    }
+    return text('Whiteboard cleared.');
+  }
+
+  const result = await ni.removeWhiteboardElement(args.id);
+  if (result.error) {
+    return text(`Failed to remove element: ${result.error}`);
+  }
+
+  const removed = result.removed as { id: string; type: string };
+  return text(`Removed ${removed.type} element ${removed.id}`);
+}
+
+
+// ═══════════════════════════════════════════
+// whiteboard_screenshot
+// ═══════════════════════════════════════════
+
+export const whiteboardScreenshotSchema = {};
+
+export const whiteboardScreenshotDescription =
+  'Take a visual screenshot of the whiteboard. Returns a JPEG image showing all current elements. Requires the Neural Interface to be open in a browser with Focus mode active. After receiving the screenshot, spawn a Haiku Task agent to interpret the visual contents if needed.';
+
+export async function handleWhiteboardScreenshot() {
+  const result = await ni.whiteboardScreenshot();
+  if (result.error) {
+    return text(`Screenshot failed: ${result.error}`);
+  }
+
+  return image(result.data as string, 'image/jpeg');
+}

package/mcp-server/src/tools/whiteboard.ts

@@ -0,0 +1,22 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import {
+  whiteboardReadSchema, whiteboardReadDescription, handleWhiteboardRead,
+  whiteboardAddSchema, whiteboardAddDescription, handleWhiteboardAdd,
+  whiteboardUpdateSchema, whiteboardUpdateDescription, handleWhiteboardUpdate,
+  whiteboardRemoveSchema, whiteboardRemoveDescription, handleWhiteboardRemove,
+  whiteboardScreenshotSchema, whiteboardScreenshotDescription, handleWhiteboardScreenshot,
+} from './whiteboard-tools.js';
+
+/**
+ * Register all 5 whiteboard MCP tools on the given server instance.
+ * These tools let Claude read, create, modify, remove, and screenshot
+ * the whiteboard in the Neural Interface Focus mode.
+ */
+export function registerWhiteboardTools(server: McpServer) {
+  server.tool('whiteboard_read', whiteboardReadDescription, whiteboardReadSchema, handleWhiteboardRead);
+  server.tool('whiteboard_add', whiteboardAddDescription, whiteboardAddSchema, handleWhiteboardAdd);
+  server.tool('whiteboard_update', whiteboardUpdateDescription, whiteboardUpdateSchema, handleWhiteboardUpdate);
+  server.tool('whiteboard_remove', whiteboardRemoveDescription, whiteboardRemoveSchema, handleWhiteboardRemove);
+  server.tool('whiteboard_screenshot', whiteboardScreenshotDescription, whiteboardScreenshotSchema, handleWhiteboardScreenshot);
+}