@abraca/mcp 1.5.0 → 1.8.0

package/src/resources/agent-guide.ts

@@ -1,7 +1,7 @@
 /**
  * Static resource: AI agent guide for working with Abracadabra documents.
  */
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 const AGENT_GUIDE = `# Abracadabra AI Agent Guide
 
@@ -47,24 +47,38 @@ If you are adding content to an existing space, call \`get_document_tree(rootId:
 
 ## Page Types Reference
 
+### Core Types (always available)
+
 | Type | Children Are | Grandchildren Are | Depth | Key Meta on Children |
 |------|-------------|-------------------|-------|---------------------|
 | **doc** | Sub-documents | Sub-sub-documents | ∞ | — |
 | **kanban** | Columns | Cards | 2 | color, icon on cards |
 | **table** | Columns | Cells (positional rows) | 2 | — |
-| **calendar** | Events | — | 1 | datetimeStart, datetimeEnd, allDay, color |
+| **calendar** | Events | — | 1 | datetimeStart, datetimeEnd, allDay, color, icon |
 | **timeline** | Epics | Tasks | 2 | dateStart, dateEnd, taskProgress, color |
 | **checklist** | Tasks | Sub-tasks | ∞ | checked, priority, dateEnd |
 | **outline** | Items | Sub-items | ∞ | — |
-| **mindmap** | Central nodes | Branches | ∞ | mmX, mmY |
 | **graph** | Nodes | — | 1 | graphX, graphY, graphPinned, color |
-| **gallery** | Items | — | 1 | geoLat, geoLng, datetimeStart, tags |
+| **gallery** | Items | — | 1 | geoLat, geoLng, datetimeStart, tags, rating, icon, color |
 | **map** | Markers/Lines | Points (for lines) | 2 | geoType, geoLat, geoLng, icon, color |
-| **dashboard** | Items | — | 1 | deskX, deskY, deskMode |
-| **spatial** | Objects | Sub-parts | ∞ | spShape, spX/Y/Z, spColor, spOpacity |
-| **media** | Tracks | — | 1 | tags |
-| **slides** | Slides | — | 1 | — |
-| **whiteboard** | Objects | — | 1 | wbX, wbY, wbW, wbH |
+| **slides** | Slides | Sub-slides | 2 | slidesTransition, color |
+| **dashboard** | Items | — | 1 | deskX, deskY, deskZ, deskMode |
+| **chart** | Data points | Data points | 2 | number (value), color, tags |
+| **sheets** | Columns | Cells | 2 | formula, bold, italic, textColor, bgColor, align |
+| **overview** | Pages | — | 1 | — |
+| **call** | — (no children) | — | 0 | — |
+
+Alias: \`desktop\` → \`dashboard\`.
+
+### Plugin Types (require plugin enabled on the server)
+
+| Type | Plugin | Children Are | Grandchildren Are | Depth | Key Meta on Children |
+|------|--------|-------------|-------------------|-------|---------------------|
+| **spatial** | spatial | Objects | Sub-parts | ∞ | spShape, spX/Y/Z, spRX/RY/RZ, spSX/SY/SZ, color, spOpacity |
+| **media** | media | Tracks | — | ∞ | tags |
+| **coder** | coder | Files/Folders | — | ∞ | fileType, entry |
+
+> Spatial uses the universal \`color\` key for object color — there is no \`spColor\`.
 
 ---
 
@@ -137,18 +151,65 @@ If you are adding content to an existing space, call \`get_document_tree(rootId:
 4. Modes: \`"icon"\` (small), \`"widget-sm"\` (240×180), \`"widget-lg"\` (400×320)
 5. Grid uses 80px cells
 
-**Spatial (3D scene):**
+**Spatial (3D scene)** *(requires spatial plugin):*
 1. \`create_document(parentId, "3D Scene", "spatial")\`
 2. Create objects: \`create_document(sceneId, "Red Cube")\`
-3. Set 3D properties: \`update_metadata(objId, { spShape: "box", spColor: "#ef4444", spX: 0, spY: 1, spZ: 0, spSX: 2, spSY: 2, spSZ: 2 })\`
-4. Shapes: \`"box"\`, \`"sphere"\`, \`"cylinder"\`, \`"cone"\`, \`"plane"\`, \`"torus"\`, \`"glb"\` (uploaded 3D model)
+3. Set 3D properties: \`update_metadata(objId, { spShape: "box", color: "#ef4444", spX: 0, spY: 1, spZ: 0, spSX: 2, spSY: 2, spSZ: 2 })\`
+4. Shapes: \`"box"\`, \`"sphere"\`, \`"cylinder"\`, \`"cone"\`, \`"plane"\`, \`"torus"\`, \`"glb"\` (uploaded 3D model — set \`spModelUploadId\` and \`spModelDocId\`)
 5. Rotation (degrees): \`spRX\`, \`spRY\`, \`spRZ\`. Scale: \`spSX\`, \`spSY\`, \`spSZ\` (default 1). Opacity: \`spOpacity\` (0–100)
+6. Use the universal \`color\` key — **never \`spColor\`**
 
 **Outline (nested items):**
 1. \`create_document(parentId, "Meeting Notes", "outline")\`
 2. Create items: \`create_document(outlineId, "Agenda Item 1")\`
 3. Create sub-items (unlimited depth): \`create_document(itemId, "Sub-point")\`
 
+**Slides (presentation with two-axis nav):**
+1. \`create_document(parentId, "Q1 Review", "slides")\`
+2. Create slides as direct children: \`create_document(deckId, "Intro")\`
+3. Create sub-slides (vertical navigation) as grandchildren: \`create_document(slideId, "Deep dive")\`
+4. Per-slide transition: \`update_metadata(slideId, { slidesTransition: "fade", color: "#6366f1" })\`
+5. Deck-level theme: \`update_metadata(deckId, { slidesTheme: "dark" })\`
+
+**Chart (data viz — manual or aggregation):**
+1. \`create_document(parentId, "Sales", "chart")\`
+2. Configure: \`update_metadata(chartId, { chartType: "bar", chartMetric: "value", chartShowLegend: true, chartLimit: 10 })\`
+3. Modes:
+   - **Manual data points**: create children with \`number\` (value) and optional \`tags\`/\`color\`
+     \`create_document(chartId, "Q1")\` then \`update_metadata(dpId, { number: 42500, color: "#6366f1" })\`
+   - **Aggregation**: set \`chartMetric\` to \`"type"\`/\`"tag"\`/\`"status"\`/\`"priority"\`/\`"activity"\`/\`"completion"\` and point the chart at a subtree — it aggregates the descendants' meta automatically
+4. Chart types: \`"bar"\`, \`"stacked bar"\`, \`"line"\`, \`"donut"\`, \`"treemap"\`
+5. Color schemes: \`"default"\`, \`"warm"\`, \`"cool"\`, \`"mono"\`
+
+**Sheets (spreadsheet with formulas):**
+1. \`create_document(parentId, "Budget", "sheets")\`
+2. Create columns: \`create_document(sheetId, "A")\`, \`create_document(sheetId, "B")\`
+3. Create cells under columns (positional rows, like \`table\`)
+4. Formulas on cells: \`update_metadata(cellId, { formula: "=A1+B1" })\`
+5. Cell formatting: \`update_metadata(cellId, { bold: true, bgColor: "#fef3c7", align: "right" })\`
+6. Deck config: \`update_metadata(sheetId, { sheetsDefaultColWidth: 120, sheetsDefaultRowHeight: 28, sheetsShowGridlines: true, sheetsFreezeRows: 1, sheetsFreezeCols: 1 })\`
+
+**Overview (space home):**
+1. \`create_document(parentId, "Home", "overview")\`
+2. No children required — renders activity, people, stats from the surrounding space
+3. Children (if any) show as linked pages
+
+**Call (video room):**
+1. \`create_document(parentId, "Daily Standup", "call")\`
+2. Video rooms have **no children** — do not add documents underneath
+
+**Coder (multi-file collaborative editor)** *(requires coder plugin):*
+1. \`create_document(parentId, "My App", "coder")\`
+2. Create files/folders: \`create_document(projectId, "App.vue")\`, \`create_document(projectId, "src")\`
+3. Set file type: \`update_metadata(fileId, { fileType: "vue", entry: true })\`
+4. \`fileType\` options: \`"vue"\`, \`"ts"\`, \`"js"\`, \`"css"\`, \`"json"\`, \`"folder"\`
+5. Mark the entry file with \`entry: true\` — the renderer uses it as the preview root
+
+**Media (audio/video playlist)** *(requires media plugin):*
+1. \`create_document(parentId, "Focus Mix", "media")\`
+2. Create tracks: \`create_document(playlistId, "Track 1")\` — attach audio/video file via upload tool
+3. Playlist config: \`update_metadata(playlistId, { mediaRepeat: "all", mediaShuffle: false })\`
+
 ---
 
 ## Document References
@@ -223,22 +284,55 @@ In the **graph** page type, document references (embeds and links) create visibl
 |-----|------|-----------|--------|
 | \`kanbanColumnWidth\` | string | kanban | "narrow", "default", "wide" |
 | \`galleryColumns\` | number | gallery | 1–6 |
-| \`galleryAspect\` | string | gallery | "square", "4:3", "16:9" |
+| \`galleryAspect\` | string | gallery | "square", "4:3", "3:2", "16:9", "free" |
+| \`galleryCardStyle\` | string | gallery | "default", "compact", "detailed" |
+| \`galleryShowLabels\` | boolean | gallery | show item labels |
+| \`gallerySortBy\` | string | gallery | "manual", "date", "name", "rating" |
 | \`calendarView\` | string | calendar | "month", "week", "day" |
 | \`calendarWeekStart\` | string | calendar | "sun", "mon" |
+| \`calendarShowWeekNumbers\` | boolean | calendar | — |
 | \`tableMode\` | string | table | "hierarchy", "flat" |
+| \`tableSortKey\` | string | table | meta key to sort by |
+| \`tableSortDir\` | string | table | "asc", "desc" |
+| \`timelineZoom\` | string | timeline | "week", "month", "quarter" |
+| \`timelinePixelsPerDay\` | number | timeline | zoom granularity |
+| \`timelineCenterDate\` | string | timeline | ISO date to center view |
+| \`checklistFilter\` | string | checklist | "all", "active", "completed" |
+| \`checklistSort\` | string | checklist | "manual", "priority", "due" |
+| \`mapShowLabels\` | boolean | map | — |
+| \`graphSpacing\` | string | graph | "compact", "default", "spacious" |
+| \`graphShowLabels\` | boolean | graph | — |
+| \`graphEdgeThickness\` | string | graph | "thin", "normal", "thick" |
 | \`showRefEdges\` | boolean | graph | show doc-reference edges |
-
-### Spatial 3D Keys (for spatial children)
+| \`mmSpacing\` | string | mindmap-layout | spacing between branches |
+| \`spatialGridVisible\` | boolean | spatial | show ground grid |
+| \`slidesTheme\` | string | slides | "dark", "light" |
+| \`chartType\` | string | chart | "bar", "stacked bar", "line", "donut", "treemap" |
+| \`chartMetric\` | string | chart | "value", "type", "tag", "status", "priority", "activity", "completion" |
+| \`chartColorScheme\` | string | chart | "default", "warm", "cool", "mono" |
+| \`chartLimit\` | number | chart | 3–30 (max items) |
+| \`chartShowLegend\` | boolean | chart | — |
+| \`chartShowValues\` | boolean | chart | — |
+| \`sheetsDefaultColWidth\` | number | sheets | 40–500 |
+| \`sheetsDefaultRowHeight\` | number | sheets | 20–100 |
+| \`sheetsShowGridlines\` | boolean | sheets | — |
+| \`sheetsFreezeRows\` | number | sheets | frozen rows count |
+| \`sheetsFreezeCols\` | number | sheets | frozen cols count |
+| \`mediaRepeat\` | string | media | "off", "all", "one" (plugin) |
+| \`mediaShuffle\` | boolean | media | plugin |
+
+### Spatial 3D Keys (for spatial children — requires spatial plugin)
 
 | Key | Type | Default | Meaning |
 |-----|------|---------|---------|
 | \`spShape\` | string | — | "box", "sphere", "cylinder", "cone", "plane", "torus", "glb" |
-| \`spColor\` | string | — | CSS color |
+| \`color\` | string | — | CSS color — universal key, **not** \`spColor\` |
 | \`spOpacity\` | number | 100 | 0–100 |
 | \`spX\`, \`spY\`, \`spZ\` | number | 0 | Position |
 | \`spRX\`, \`spRY\`, \`spRZ\` | number | 0 | Rotation (degrees) |
 | \`spSX\`, \`spSY\`, \`spSZ\` | number | 1 | Scale |
+| \`spModelUploadId\` | string | — | GLB upload ID (when \`spShape: "glb"\`) |
+| \`spModelDocId\` | string | — | Doc ID that owns the GLB upload |
 
 ### Dashboard Keys (for dashboard children)
 
@@ -248,6 +342,28 @@ In the **graph** page type, document references (embeds and links) create visibl
 | \`deskZ\` | number | Z-index (layering) |
 | \`deskMode\` | string | "icon", "widget-sm" (240×180), "widget-lg" (400×320) |
 
+### Sheets Cell Formatting (per-cell meta)
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| \`formula\` | string | Cell formula (e.g. "=A1+B1") |
+| \`bold\` | boolean | — |
+| \`italic\` | boolean | — |
+| \`textColor\` | string | CSS color |
+| \`bgColor\` | string | CSS color |
+| \`align\` | string | "left", "center", "right" |
+
+### Coder Keys (for coder children — plugin)
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| \`fileType\` | string | "vue", "ts", "js", "css", "json", "folder" |
+| \`entry\` | boolean | Mark this file as the preview entry point |
+
+### Discovering What Metadata Applies
+
+Use the \`list_page_types\` tool to enumerate all known page types and their declared \`metaSchema\` (fields that apply to children/descendants) and \`defaultMetaFields\` (renderer config fields on the page itself). It's the authoritative list of what meta keys make sense for any given page type.
+
 ---
 
 ## Content Structure
@@ -330,8 +446,11 @@ Always clear fields when done by setting them to \`null\`.
 | **Outline** | \`outline:editing\` | nodeId | Editing an outline node |
 | **Gallery** | \`gallery:focused\` | itemId | Item hovered/selected |
 | **Timeline** | \`timeline:focused\` | taskId | Task selected |
-| **Mindmap** | \`mindmap:focused\` | nodeId | Node selected/edited |
 | **Graph** | \`graph:focused\` | nodeId | Node hovered/selected |
+| **Slides** | \`slides:current\` | slideId | Slide being presented |
+| **Spatial** | \`spatial:selected\`, \`spatial:camera\` | objectId / camera state | plugin |
+| **Media** | \`media:playing\`, \`media:position\` | trackId / 0–1 | plugin |
+| **Coder** | \`coder:activeFile\` | fileId | plugin |
 | **Map** | \`map:focused\` | markerId | Marker hovered/selected |
 | **Doc** | \`doc:scroll\` | 0–1 number | Scroll position in document |
 
@@ -414,22 +533,25 @@ Always check and traverse the \`children\` array returned by \`read_document\`.*
 - Create top-level documents without first confirming the correct hub doc ID
 - Rename or write content to the space hub document itself
 - Set \`type\` on child items (cards, cells, events) — only set type on the parent page
-`
+`;
 
 export function registerAgentGuide(mcp: McpServer) {
   mcp.resource(
-    'agent-guide',
-    'abracadabra://agent-guide',
+    "agent-guide",
+    "abracadabra://agent-guide",
     {
-      description: 'Comprehensive guide for AI agents working with Abracadabra documents. Covers page types, tree operations, metadata, content structure, and best practices.',
-      mimeType: 'text/markdown',
+      description:
+        "Comprehensive guide for AI agents working with Abracadabra documents. Covers page types, tree operations, metadata, content structure, and best practices.",
+      mimeType: "text/markdown",
     },
     async () => ({
-      contents: [{
-        uri: 'abracadabra://agent-guide',
-        text: AGENT_GUIDE,
-        mimeType: 'text/markdown',
-      }],
-    })
-  )
+      contents: [
+        {
+          uri: "abracadabra://agent-guide",
+          text: AGENT_GUIDE,
+          mimeType: "text/markdown",
+        },
+      ],
+    }),
+  );
 }

package/src/server.ts

@@ -249,6 +249,19 @@ export class AbracadabraMCPServer {
     return this._activeConnection?.doc.getMap('doc-trash') ?? null
   }
 
+  /** Get plugin names enabled in the active space via space-plugins Y.Map. */
+  getEnabledPluginNames(): string[] {
+    const doc = this._activeConnection?.doc
+    if (!doc) return []
+    const pluginsMap = doc.getMap('space-plugins')
+    const names: string[] = []
+    pluginsMap.forEach((value: any, key: string) => {
+      const entry = value?.toJSON ? value.toJSON() : value
+      if (entry?.enabled) names.push(key)
+    })
+    return names
+  }
+
   /**
    * Get or create a child provider for a given document ID.
    * Caches providers and waits for sync before returning.

package/src/tools/meta.ts

@@ -47,7 +47,7 @@ export function registerMetaTools(mcp: McpServer, server: AbracadabraMCPServer)
     'Update metadata fields on a document. Merges the provided fields into existing metadata.',
     {
       docId: z.string().describe('Document ID.'),
-      meta: z.record(z.unknown()).describe('Metadata fields to update (merged with existing). Universal keys: color (hex), icon (Lucide kebab-case — NEVER emoji), dateStart/dateEnd, datetimeStart/datetimeEnd, allDay, tags (string[]), checked (bool), priority (0=none,1=low,2=med,3=high,4=urgent), status, rating (0-5), url, email, phone, number, unit, subtitle, note, taskProgress (0-100), members ({id,label}[]), coverUploadId. Geo/Map: geoType ("marker"|"line"|"measure"), geoLat, geoLng, geoDescription. Spatial 3D: spShape ("box"|"sphere"|"cylinder"|"cone"|"plane"|"torus"|"glb"), spX/spY/spZ, spRX/spRY/spRZ, spSX/spSY/spSZ, spColor, spOpacity (0-100). Dashboard: deskX, deskY, deskZ, deskMode ("icon"|"widget-sm"|"widget-lg"). Slides: slidesTransition ("none"|"fade"|"slide"), slidesTheme ("dark"|"light"). Chart: chartType ("bar"|"stacked bar"|"line"|"donut"|"treemap"), chartMetric, chartColorScheme, chartLimit, chartShowLegend, chartShowValues. Sheets: sheetsDefaultColWidth, sheetsDefaultRowHeight, sheetsShowGridlines, sheetsFreezeRows, sheetsFreezeCols. Cell formatting: bold, italic, textColor, bgColor, align, formula. Renderer config (on the page doc itself): kanbanColumnWidth, galleryColumns, galleryAspect, galleryCardStyle, galleryShowLabels, gallerySortBy, calendarView, calendarWeekStart, calendarShowWeekNumbers, tableMode, tableSortDir, checklistFilter, checklistSort, mapShowLabels, spatialGridVisible, showRefEdges, mediaRepeat, mediaShuffle. Set a key to null to clear it.'),
+      meta: z.record(z.unknown()).describe('Metadata fields to update (merged with existing). Universal keys: color (hex), icon (Lucide kebab-case — NEVER emoji), dateStart/dateEnd, datetimeStart/datetimeEnd, allDay, timeStart/timeEnd, tags (string[]), checked (bool), priority (0=none,1=low,2=med,3=high,4=urgent), status, rating (0-5), url, email, phone, number, unit, subtitle, note, taskProgress (0-100), members ({id,label}[]), coverUploadId, coverDocId, dateTaken. Geo/Map (children): geoType ("marker"|"line"|"measure"), geoLat, geoLng, geoDescription. Spatial 3D (children, plugin: spatial): spShape ("box"|"sphere"|"cylinder"|"cone"|"plane"|"torus"|"glb"), spX/spY/spZ, spRX/spRY/spRZ (deg), spSX/spSY/spSZ (scale), spOpacity (0-100), spModelUploadId, spModelDocId — spatial uses the universal `color` key, NOT spColor. Dashboard (children): deskX, deskY, deskZ, deskMode ("icon"|"widget-sm"|"widget-lg"). Mindmap-layout (children): mmX, mmY. Graph-layout (children): graphX, graphY, graphPinned. Slides (children): slidesTransition ("none"|"fade"|"slide"). Coder (children, plugin: coder): fileType ("vue"|"ts"|"js"|"css"|"json"|"folder"), entry (bool). Cell formatting (sheets cells): bold, italic, textColor, bgColor, align ("left"|"center"|"right"), formula. Renderer config (on the PAGE doc itself, not children): kanbanColumnWidth ("narrow"|"default"|"wide"), galleryColumns (1-6), galleryAspect ("square"|"4:3"|"3:2"|"16:9"|"free"), galleryCardStyle ("default"|"compact"|"detailed"), galleryShowLabels, gallerySortBy ("manual"|"date"|"name"|"rating"), calendarView ("month"|"week"|"day"), calendarWeekStart ("sun"|"mon"), calendarShowWeekNumbers, tableMode ("hierarchy"|"flat"), tableSortKey, tableSortDir ("asc"|"desc"), timelineZoom ("week"|"month"|"quarter"), timelinePixelsPerDay, timelineCenterDate (ISO date), checklistFilter ("all"|"active"|"completed"), checklistSort ("manual"|"priority"|"due"), mapShowLabels, graphSpacing ("compact"|"default"|"spacious"), graphShowLabels, graphEdgeThickness ("thin"|"normal"|"thick"), showRefEdges, mmSpacing, spatialGridVisible, slidesTheme ("dark"|"light"), chartType ("bar"|"stacked bar"|"line"|"donut"|"treemap"), chartMetric ("value"|"type"|"tag"|"status"|"priority"|"activity"|"completion"), chartColorScheme ("default"|"warm"|"cool"|"mono"), chartLimit (3-30), chartShowLegend, chartShowValues, sheetsDefaultColWidth (40-500), sheetsDefaultRowHeight (20-100), sheetsShowGridlines, sheetsFreezeRows, sheetsFreezeCols, mediaRepeat ("off"|"all"|"one"), mediaShuffle. Set a key to null to clear it.'),
     },
     async ({ docId, meta }) => {
       server.setAutoStatus('writing', docId)

package/src/tools/tree.ts

@@ -6,6 +6,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { z } from 'zod'
 import type { AbracadabraMCPServer } from '../server.ts'
 import type { TreeEntry, PageMeta } from '../converters/types.ts'
+import { PAGE_TYPES, TYPE_ALIASES, resolvePageType } from '../converters/page-types.ts'
 
 /**
  * Normalize a document ID so the hub/root doc ID is treated as the tree root (null).
@@ -207,7 +208,7 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
     {
       parentId: z.string().optional().describe('Parent document ID. Omit for top-level pages. Use a document ID for nested/child pages.'),
       label: z.string().describe('Display name / title for the document.'),
-      type: z.string().optional().describe('Page type — sets how this document renders. "doc" (rich text), "kanban" (columns → cards), "table" (columns → rows with custom fields), "calendar" (events with datetimeStart/End), "timeline" (epics → tasks with dateStart/End + taskProgress), "checklist" (tasks with checked/priority, unlimited nesting), "outline" (nested items, unlimited depth), "gallery" (visual grid with covers/ratings), "map" (markers/lines with geoLat/geoLng), "graph" (force-directed knowledge graph), "dashboard" (positioned widgets with deskX/deskY/deskMode), "spatial" (3D scene with spShape/spX/spY/spZ), "media" (audio/video player with playlists), "slides" (presentation with transitions), "chart" (bar/line/donut/treemap from data points or aggregation), "sheets" (spreadsheet with formulas and formatting), "overview" (space home — activity and stats), "call" (video call room, no children). Omit to inherit parent view. Only set on the parent page, NEVER on child items.'),
+      type: z.string().optional().describe('Page type — sets how this document renders. Core types (always available): "doc" (rich text), "kanban" (columns → cards), "table" (columns → rows, positional), "calendar" (events with datetimeStart/End), "timeline" (epics → tasks with dateStart/End + taskProgress), "checklist" (tasks with checked/priority, unlimited nesting), "outline" (nested items, unlimited depth), "gallery" (visual grid with covers/ratings), "map" (markers/lines with geoLat/geoLng), "graph" (force-directed knowledge graph), "dashboard" (positioned widgets with deskX/deskY/deskMode), "slides" (slides → sub-slides with transitions), "chart" (bar/stacked bar/line/donut/treemap from data points or aggregation), "sheets" (spreadsheet with formulas and formatting), "overview" (space home — activity and stats), "call" (video call room, no children). Plugin types (require plugin enabled on the server): "spatial" (3D scene with spShape/spX/spY/spZ + universal color, plugin: spatial), "media" (audio/video player with playlists, plugin: media), "coder" (collaborative multi-file coding env with fileType/entry, plugin: coder). Alias: "desktop" → "dashboard". Omit to inherit parent view. Only set on the parent page, NEVER on child items.'),
       meta: z.record(z.unknown()).optional().describe('Initial metadata (PageMeta fields: color as hex string, icon as Lucide kebab-case name like "star"/"code-2"/"users" — never emoji, dateStart, dateEnd, priority 0-4, tags array, etc). Omit icon entirely to use page type default.'),
     },
     async ({ parentId, label, type, meta }) => {
@@ -360,7 +361,7 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
     'Change the page type view of a document (data is preserved).',
     {
       id: z.string().describe('Document ID.'),
-      type: z.string().describe('New page type: "doc", "kanban", "table", "calendar", "timeline", "checklist", "outline", "gallery", "map", "graph", "dashboard", "spatial", "media", "slides", "chart", "sheets", "overview", "call".'),
+      type: z.string().describe('New page type. Core: "doc", "kanban", "table", "calendar", "timeline", "checklist", "outline", "gallery", "map", "graph", "dashboard", "slides", "chart", "sheets", "overview", "call". Plugin (require plugin enabled): "spatial", "media", "coder". Switching preserves the tree — children, labels, and meta are all retained; only the view changes.'),
     },
     async ({ id, type }) => {
       server.setAutoStatus('writing')
@@ -442,4 +443,28 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
       }
     }
   )
+
+  mcp.tool(
+    'list_page_types',
+    'Enumerate all known Abracadabra page types with their metadata schemas. Returns an array of { key, label, icon, description, core, plugin, supportsChildren, childLabel, grandchildLabel, defaultDepth, metaSchema, defaultMetaFields }. `metaSchema` describes fields that apply to DESCENDANTS (children, grandchildren, ...) of a page of this type. `defaultMetaFields` are view-config fields on the page doc itself. Plugin types (core: false) require the named plugin to be enabled on the server. Use this to discover what meta keys a given renderer supports instead of guessing.',
+    {
+      key: z.string().optional().describe('Filter to a single type by key (e.g. "kanban", "calendar"). Aliases are resolved (e.g. "desktop" → "dashboard"). Omit to list all types.'),
+    },
+    async ({ key }) => {
+      if (key) {
+        const resolved = resolvePageType(key)
+        if (!resolved) {
+          return { content: [{ type: 'text', text: `Unknown page type "${key}". Call list_page_types with no args to see all types.` }] }
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(resolved, null, 2) }] }
+      }
+      const all = Object.values(PAGE_TYPES)
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ types: all, aliases: TYPE_ALIASES }, null, 2),
+        }],
+      }
+    }
+  )
 }