@abraca/mcp 1.0.0

package/src/tools/content.ts

@@ -0,0 +1,133 @@
+/**
+ * Content tools — read/write document content via markdown ↔ Y.js conversion.
+ */
+import * as Y from 'yjs'
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import type { AbracadabraMCPServer } from '../server.ts'
+import { populateYDocFromMarkdown, parseFrontmatter } from '../converters/markdownToYjs.ts'
+import { yjsToMarkdown } from '../converters/yjsToMarkdown.ts'
+
+export function registerContentTools(mcp: McpServer, server: AbracadabraMCPServer) {
+  mcp.tool(
+    'read_document',
+    'Read a document\'s content as markdown, along with its immediate children. IMPORTANT: A document\'s full content is its body text PLUS all its children. An empty body does not mean empty content — the children ARE the content (sub-docs, kanban columns, table columns, calendar events, etc.). Always check the returned "children" array and read child documents too.',
+    {
+      docId: z.string().describe('Document ID to read.'),
+    },
+    async ({ docId }) => {
+      try {
+        const provider = await server.getChildProvider(docId)
+        const fragment = provider.document.getXmlFragment('default')
+
+        const { title, markdown } = yjsToMarkdown(fragment)
+
+        // Auto-update presence: mark this doc as focused and place cursor at start
+        server.setFocusedDoc(docId)
+        server.setDocCursor(docId, 0)
+
+        // Get tree metadata + immediate children
+        const treeMap = server.getTreeMap()
+        let label = title
+        let type: string | undefined
+        let meta: Record<string, unknown> | undefined
+        let children: Array<{ id: string; label: string; type?: string; meta?: unknown }> = []
+        if (treeMap) {
+          const entry = treeMap.get(docId)
+          if (entry) {
+            label = entry.label || title
+            type = entry.type
+            meta = entry.meta
+          }
+          // Collect immediate children sorted by order
+          treeMap.forEach((value: any, id: string) => {
+            if (value.parentId === docId) {
+              children.push({ id, label: value.label || 'Untitled', type: value.type, meta: value.meta })
+            }
+          })
+          children.sort((a: any, b: any) => ((treeMap.get(a.id)?.order ?? 0) - (treeMap.get(b.id)?.order ?? 0)))
+        }
+
+        const result: Record<string, unknown> = { label, type, meta, markdown, children }
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          }],
+        }
+      } catch (error: any) {
+        return {
+          content: [{ type: 'text', text: `Error reading document: ${error.message}` }],
+          isError: true,
+        }
+      }
+    }
+  )
+
+  mcp.tool(
+    'write_document',
+    'Write markdown content to a document. Parses the markdown and writes it to the Y.js CRDT document, which syncs in real-time to all connected clients. Supports optional YAML frontmatter for title and metadata.',
+    {
+      docId: z.string().describe('Document ID to write to.'),
+      markdown: z.string().describe('Markdown content to write. Can include YAML frontmatter with title and metadata fields.'),
+      mode: z.enum(['replace', 'append']).optional().describe('Write mode. "replace" clears existing content first (default). "append" adds to the end.'),
+    },
+    async ({ docId, markdown, mode }) => {
+      try {
+        const writeMode = mode ?? 'replace'
+        const provider = await server.getChildProvider(docId)
+        const doc = provider.document
+        const fragment = doc.getXmlFragment('default')
+
+        // Parse optional frontmatter
+        const { title, meta, body } = parseFrontmatter(markdown)
+
+        // Update tree metadata if frontmatter provided title or meta
+        if (title || Object.keys(meta).length > 0) {
+          const treeMap = server.getTreeMap()
+          const rootDoc = server.rootDocument
+          if (treeMap && rootDoc) {
+            const entry = treeMap.get(docId)
+            if (entry) {
+              rootDoc.transact(() => {
+                const updates: Record<string, unknown> = { ...entry, updatedAt: Date.now() }
+                if (title) updates.label = title
+                if (Object.keys(meta).length > 0) {
+                  updates.meta = { ...(entry.meta ?? {}), ...meta }
+                }
+                treeMap.set(docId, updates)
+              })
+            }
+          }
+        }
+
+        if (writeMode === 'replace') {
+          // Clear existing content
+          doc.transact(() => {
+            while (fragment.length > 0) {
+              fragment.delete(0)
+            }
+          })
+        }
+
+        // Write new content
+        const contentToWrite = body || markdown
+        const fallbackTitle = title || 'Untitled'
+        populateYDocFromMarkdown(fragment, contentToWrite, fallbackTitle)
+
+        // Auto-update presence: mark this doc as focused and place cursor at end
+        server.setFocusedDoc(docId)
+        server.setDocCursor(docId, fragment.length)
+
+        return {
+          content: [{ type: 'text', text: `Document ${docId} updated (${writeMode} mode)` }],
+        }
+      } catch (error: any) {
+        return {
+          content: [{ type: 'text', text: `Error writing document: ${error.message}` }],
+          isError: true,
+        }
+      }
+    }
+  )
+}

package/src/tools/files.ts

@@ -0,0 +1,110 @@
+/**
+ * File tools — upload/download/list/delete files via the REST API.
+ */
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import type { AbracadabraMCPServer } from '../server.ts'
+
+export function registerFileTools(mcp: McpServer, server: AbracadabraMCPServer) {
+  mcp.tool(
+    'list_uploads',
+    'List file attachments for a document.',
+    {
+      docId: z.string().describe('Document ID.'),
+    },
+    async ({ docId }) => {
+      try {
+        const uploads = await server.client.listUploads(docId)
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(uploads, null, 2),
+          }],
+        }
+      } catch (error: any) {
+        return {
+          content: [{ type: 'text', text: `Error listing uploads: ${error.message}` }],
+          isError: true,
+        }
+      }
+    }
+  )
+
+  mcp.tool(
+    'upload_file',
+    'Upload a local file to a document.',
+    {
+      docId: z.string().describe('Document ID to attach the file to.'),
+      filePath: z.string().describe('Absolute path to the local file to upload.'),
+      filename: z.string().optional().describe('Override filename (defaults to basename of filePath).'),
+    },
+    async ({ docId, filePath, filename }) => {
+      try {
+        const resolvedPath = path.resolve(filePath)
+        const data = fs.readFileSync(resolvedPath)
+        const name = filename ?? path.basename(resolvedPath)
+        const blob = new Blob([data])
+        const result = await server.client.upload(docId, blob, name)
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          }],
+        }
+      } catch (error: any) {
+        return {
+          content: [{ type: 'text', text: `Error uploading file: ${error.message}` }],
+          isError: true,
+        }
+      }
+    }
+  )
+
+  mcp.tool(
+    'download_file',
+    'Download a file attachment from a document to a local path.',
+    {
+      docId: z.string().describe('Document ID.'),
+      uploadId: z.string().describe('Upload ID to download.'),
+      saveTo: z.string().describe('Absolute local file path to save the download.'),
+    },
+    async ({ docId, uploadId, saveTo }) => {
+      try {
+        const blob = await server.client.getUpload(docId, uploadId)
+        const buffer = Buffer.from(await blob.arrayBuffer())
+        const resolvedPath = path.resolve(saveTo)
+        fs.writeFileSync(resolvedPath, buffer)
+        return {
+          content: [{ type: 'text', text: `Downloaded to ${resolvedPath} (${buffer.length} bytes)` }],
+        }
+      } catch (error: any) {
+        return {
+          content: [{ type: 'text', text: `Error downloading file: ${error.message}` }],
+          isError: true,
+        }
+      }
+    }
+  )
+
+  mcp.tool(
+    'delete_file',
+    'Delete a file attachment from a document.',
+    {
+      docId: z.string().describe('Document ID.'),
+      uploadId: z.string().describe('Upload ID to delete.'),
+    },
+    async ({ docId, uploadId }) => {
+      try {
+        await server.client.deleteUpload(docId, uploadId)
+        return { content: [{ type: 'text', text: `Deleted upload ${uploadId}` }] }
+      } catch (error: any) {
+        return {
+          content: [{ type: 'text', text: `Error deleting file: ${error.message}` }],
+          isError: true,
+        }
+      }
+    }
+  )
+}

package/src/tools/meta.ts

@@ -0,0 +1,59 @@
+/**
+ * Metadata tools — read/update PageMeta on tree entries.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import type { AbracadabraMCPServer } from '../server.ts'
+
+export function registerMetaTools(mcp: McpServer, server: AbracadabraMCPServer) {
+  mcp.tool(
+    'get_metadata',
+    'Read the metadata (PageMeta) of a document from the tree.',
+    {
+      docId: z.string().describe('Document ID.'),
+    },
+    async ({ docId }) => {
+      const treeMap = server.getTreeMap()
+      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+
+      const entry = treeMap.get(docId)
+      if (!entry) return { content: [{ type: 'text', text: `Document ${docId} not found` }] }
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            id: docId,
+            label: entry.label,
+            type: entry.type,
+            meta: entry.meta ?? {},
+          }, null, 2),
+        }],
+      }
+    }
+  )
+
+  mcp.tool(
+    'update_metadata',
+    '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). Standard PageMeta keys: color (hex string), icon (Lucide kebab-case name like "star"/"code-2"/"users" — NEVER emoji), dateStart, dateEnd, datetimeStart, datetimeEnd, allDay, tags, checked, priority (0-4), status, rating, url, taskProgress (0-100), subtitle, note. Set a key to null to clear it.'),
+    },
+    async ({ docId, meta }) => {
+      const treeMap = server.getTreeMap()
+      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+
+      const entry = treeMap.get(docId)
+      if (!entry) return { content: [{ type: 'text', text: `Document ${docId} not found` }] }
+
+      treeMap.set(docId, {
+        ...entry,
+        meta: { ...(entry.meta ?? {}), ...meta },
+        updatedAt: Date.now(),
+      })
+
+      return { content: [{ type: 'text', text: `Metadata updated for ${docId}` }] }
+    }
+  )
+}

package/src/tools/tree.ts

@@ -0,0 +1,296 @@
+/**
+ * Document tree tools — operate on the root Y.Doc's "doc-tree" Y.Map.
+ */
+import type * as Y from 'yjs'
+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'
+
+function readEntries(treeMap: Y.Map<any>): TreeEntry[] {
+  const entries: TreeEntry[] = []
+  treeMap.forEach((value: any, id: string) => {
+    entries.push({
+      id,
+      label: value.label || 'Untitled',
+      parentId: value.parentId ?? null,
+      order: value.order ?? 0,
+      type: value.type,
+      meta: value.meta,
+      createdAt: value.createdAt,
+      updatedAt: value.updatedAt,
+    })
+  })
+  return entries
+}
+
+function childrenOf(entries: TreeEntry[], parentId: string | null): TreeEntry[] {
+  return entries
+    .filter(e => e.parentId === parentId)
+    .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+}
+
+function descendantsOf(entries: TreeEntry[], id: string | null): TreeEntry[] {
+  const result: TreeEntry[] = []
+  function collect(pid: string) {
+    for (const child of childrenOf(entries, pid)) {
+      result.push(child)
+      collect(child.id)
+    }
+  }
+  collect(id)
+  return result
+}
+
+function buildTree(entries: TreeEntry[], rootId: string | null, maxDepth: number, currentDepth = 0): any[] {
+  if (maxDepth >= 0 && currentDepth >= maxDepth) return []
+  const children = childrenOf(entries, rootId)
+  return children.map(entry => ({
+    id: entry.id,
+    label: entry.label,
+    type: entry.type,
+    meta: entry.meta,
+    order: entry.order,
+    children: buildTree(entries, entry.id, maxDepth, currentDepth + 1),
+  }))
+}
+
+export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer) {
+  mcp.tool(
+    'list_documents',
+    'List direct children of a document (defaults to root). Returns id, label, type, meta, order.',
+    { parentId: z.string().optional().describe('Parent document ID. Omit for root-level documents.') },
+    async ({ parentId }) => {
+      const treeMap = server.getTreeMap()
+      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+
+      const targetId = parentId ?? null
+      const entries = readEntries(treeMap)
+      const children = childrenOf(entries, targetId)
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(children, null, 2),
+        }],
+      }
+    }
+  )
+
+  mcp.tool(
+    'get_document_tree',
+    'Get the full document tree as nested JSON. Useful for understanding the document structure.',
+    {
+      rootId: z.string().optional().describe('Root document ID to start from. Omit for the entire tree.'),
+      depth: z.number().optional().describe('Maximum depth to traverse. Default 3. Use -1 for unlimited.'),
+    },
+    async ({ rootId, depth }) => {
+      const treeMap = server.getTreeMap()
+      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+
+      const targetId = rootId ?? null
+      const maxDepth = depth ?? 3
+      const entries = readEntries(treeMap)
+      const tree = buildTree(entries, targetId, maxDepth)
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(tree, null, 2),
+        }],
+      }
+    }
+  )
+
+  mcp.tool(
+    'create_document',
+    'Create a new document in the tree. Returns the new document ID.',
+    {
+      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: "doc", "kanban", "calendar", "table", "outline", "gallery", "slides", "timeline", "whiteboard", "map", "desktop", "mindmap", "graph". Omit to inherit parent view.'),
+      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 }) => {
+      const treeMap = server.getTreeMap()
+      const rootDoc = server.rootDocument
+      if (!treeMap || !rootDoc) return { content: [{ type: 'text', text: 'Not connected' }] }
+
+      const id = crypto.randomUUID()
+      const now = Date.now()
+      rootDoc.transact(() => {
+        treeMap.set(id, {
+          label,
+          parentId: parentId ?? null,
+          order: now,
+          type,
+          meta: meta as PageMeta,
+          createdAt: now,
+          updatedAt: now,
+        })
+      })
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ id, label, parentId, type }, null, 2),
+        }],
+      }
+    }
+  )
+
+  mcp.tool(
+    'rename_document',
+    'Rename a document (updates its display label everywhere).',
+    {
+      id: z.string().describe('Document ID to rename.'),
+      label: z.string().describe('New display name.'),
+    },
+    async ({ id, label }) => {
+      const treeMap = server.getTreeMap()
+      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+
+      const entry = treeMap.get(id)
+      if (!entry) return { content: [{ type: 'text', text: `Document ${id} not found` }] }
+
+      treeMap.set(id, { ...entry, label, updatedAt: Date.now() })
+      return { content: [{ type: 'text', text: `Renamed to "${label}"` }] }
+    }
+  )
+
+  mcp.tool(
+    'move_document',
+    'Move a document to a new parent and/or reorder it.',
+    {
+      id: z.string().describe('Document ID to move.'),
+      newParentId: z.string().optional().describe('New parent document ID. Omit to move to top level.'),
+      order: z.number().optional().describe('New sort order. Defaults to Date.now() (append to end).'),
+    },
+    async ({ id, newParentId, order }) => {
+      const treeMap = server.getTreeMap()
+      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+
+      const entry = treeMap.get(id)
+      if (!entry) return { content: [{ type: 'text', text: `Document ${id} not found` }] }
+
+      treeMap.set(id, {
+        ...entry,
+        parentId: newParentId ?? null,
+        order: order ?? Date.now(),
+        updatedAt: Date.now(),
+      })
+      return { content: [{ type: 'text', text: `Moved ${id} to parent ${newParentId}` }] }
+    }
+  )
+
+  mcp.tool(
+    'delete_document',
+    'Soft-delete a document and its descendants (moves to trash).',
+    {
+      id: z.string().describe('Document ID to delete.'),
+    },
+    async ({ id }) => {
+      const treeMap = server.getTreeMap()
+      const trashMap = server.getTrashMap()
+      const rootDoc = server.rootDocument
+      if (!treeMap || !trashMap || !rootDoc) return { content: [{ type: 'text', text: 'Not connected' }] }
+
+      const entries = readEntries(treeMap)
+      const toDelete = [id, ...descendantsOf(entries, id).map(e => e.id)]
+
+      const now = Date.now()
+      rootDoc.transact(() => {
+        for (const nid of toDelete) {
+          const entry = treeMap.get(nid)
+          if (!entry) continue
+          trashMap.set(nid, {
+            label: entry.label || 'Untitled',
+            parentId: entry.parentId ?? null,
+            order: entry.order ?? 0,
+            type: entry.type,
+            meta: entry.meta,
+            deletedAt: now,
+          })
+          treeMap.delete(nid)
+        }
+      })
+
+      return { content: [{ type: 'text', text: `Deleted ${toDelete.length} document(s)` }] }
+    }
+  )
+
+  mcp.tool(
+    'change_document_type',
+    'Change the page type view of a document (data is preserved).',
+    {
+      id: z.string().describe('Document ID.'),
+      type: z.string().describe('New page type (e.g. "doc", "kanban", "table", "calendar", "outline", "gallery", "slides", "timeline", "whiteboard", "map", "desktop", "mindmap", "graph").'),
+    },
+    async ({ id, type }) => {
+      const treeMap = server.getTreeMap()
+      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+
+      const entry = treeMap.get(id)
+      if (!entry) return { content: [{ type: 'text', text: `Document ${id} not found` }] }
+
+      treeMap.set(id, { ...entry, type, updatedAt: Date.now() })
+      return { content: [{ type: 'text', text: `Changed type to "${type}"` }] }
+    }
+  )
+
+  mcp.tool(
+    'list_spaces',
+    'List all spaces available on the server. Returns id, name, doc_id, is_hub, and visibility. Use switch_space to navigate to a space.',
+    {},
+    async () => {
+      const spaces = server.spaces
+      if (!spaces.length) {
+        return { content: [{ type: 'text', text: 'No spaces available (spaces extension not loaded on this server)' }] }
+      }
+      const active = server.rootDocId
+      const annotated = spaces.map(s => ({ ...s, active: s.doc_id === active }))
+      return { content: [{ type: 'text', text: JSON.stringify(annotated, null, 2) }] }
+    }
+  )
+
+  mcp.tool(
+    'switch_space',
+    'Switch the active space. All subsequent tree operations will target the new space. Use list_spaces to discover available doc_ids.',
+    { docId: z.string().describe('The doc_id of the space to switch to (from list_spaces).') },
+    async ({ docId }) => {
+      await server.switchSpace(docId)
+      const space = server.spaces.find(s => s.doc_id === docId)
+      const name = space?.name ?? docId
+      return { content: [{ type: 'text', text: `Switched to space "${name}" (${docId})` }] }
+    }
+  )
+
+  mcp.tool(
+    'duplicate_document',
+    'Shallow-clone a document with " (copy)" suffix. Returns new document ID.',
+    {
+      id: z.string().describe('Document ID to duplicate.'),
+    },
+    async ({ id }) => {
+      const treeMap = server.getTreeMap()
+      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+
+      const entry = treeMap.get(id)
+      if (!entry) return { content: [{ type: 'text', text: `Document ${id} not found` }] }
+
+      const newId = crypto.randomUUID()
+      treeMap.set(newId, {
+        ...entry,
+        label: (entry.label || 'Untitled') + ' (copy)',
+        order: Date.now(),
+      })
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ id: newId, label: entry.label + ' (copy)' }, null, 2),
+        }],
+      }
+    }
+  )
+}

package/src/utils.ts

@@ -0,0 +1,37 @@
+/**
+ * Wait for a provider's `synced` event with a timeout.
+ */
+export function waitForSync(
+  provider: { on(event: string, cb: () => void): void; off(event: string, cb: () => void): void },
+  timeoutMs = 15000
+): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      provider.off('synced', handler)
+      reject(new Error(`Sync timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+
+    function handler() {
+      clearTimeout(timer)
+      resolve()
+    }
+
+    provider.on('synced', handler)
+  })
+}
+
+/**
+ * Wraps a promise with a timeout.
+ */
+export function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message?: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(message ?? `Operation timed out after ${timeoutMs}ms`)),
+      timeoutMs
+    )
+    promise.then(
+      (val) => { clearTimeout(timer); resolve(val) },
+      (err) => { clearTimeout(timer); reject(err) }
+    )
+  })
+}