@abraca/mcp 1.0.0

package/src/server.ts

@@ -0,0 +1,431 @@
+/**
+ * AbracadabraMCPServer — manages connection lifecycle, provider cache, and cleanup.
+ *
+ * Space-aware: on connect, discovers spaces via the spaces extension.
+ * If available, defaults to the hub space; otherwise falls back to index_doc_id.
+ * Use switchSpace(docId) to change the active space.
+ */
+import * as Y from 'yjs'
+import { AbracadabraProvider, AbracadabraClient } from '@abraca/dabra'
+import type { ServerInfo, SpaceMeta } from '@abraca/dabra'
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { waitForSync } from './utils.ts'
+
+export interface MCPServerConfig {
+  url: string
+  username: string
+  password: string
+  agentName?: string
+  agentColor?: string
+}
+
+interface SpaceConnection {
+  doc: Y.Doc
+  provider: AbracadabraProvider
+  docId: string
+}
+
+interface CachedProvider {
+  provider: AbracadabraProvider
+  lastAccessed: number
+}
+
+const IDLE_TIMEOUT_MS = 5 * 60 * 1000 // 5 minutes
+
+export class AbracadabraMCPServer {
+  readonly config: MCPServerConfig
+  readonly client: AbracadabraClient
+  private _serverInfo: ServerInfo | null = null
+  private _rootDocId: string | null = null
+  private _spaces: SpaceMeta[] = []
+  private _activeConnection: SpaceConnection | null = null
+  private _spaceConnections = new Map<string, SpaceConnection>()
+  private childCache = new Map<string, CachedProvider>()
+  private evictionTimer: ReturnType<typeof setInterval> | null = null
+  private _mcpServerRef: McpServer | null = null
+  private _serverRef: Server | null = null
+  private _handledTaskIds = new Set<string>()
+  private _userId: string | null = null
+
+  constructor(config: MCPServerConfig) {
+    this.config = config
+    this.client = new AbracadabraClient({
+      url: config.url,
+      persistAuth: false,
+    })
+  }
+
+  get agentName(): string {
+    return this.config.agentName || 'AI Assistant'
+  }
+
+  get agentColor(): string {
+    return this.config.agentColor || 'hsl(270, 80%, 60%)'
+  }
+
+  get serverInfo(): ServerInfo | null {
+    return this._serverInfo
+  }
+
+  get rootDocId(): string | null {
+    return this._rootDocId
+  }
+
+  get spaces(): SpaceMeta[] {
+    return this._spaces
+  }
+
+  get rootDocument(): Y.Doc | null {
+    return this._activeConnection?.doc ?? null
+  }
+
+  get rootYProvider(): AbracadabraProvider | null {
+    return this._activeConnection?.provider ?? null
+  }
+
+  get userId(): string | null {
+    return this._userId
+  }
+
+  /** Start the server: login, discover spaces/root doc, connect provider. */
+  async connect(): Promise<void> {
+    // Step 1: Login
+    await this.client.login({
+      username: this.config.username,
+      password: this.config.password,
+    })
+    console.error(`[abracadabra-mcp] Logged in as ${this.config.username}`)
+
+    // Step 1b: Get user profile for publicKey identity
+    try {
+      const me = await this.client.getMe()
+      this._userId = me.id
+      console.error(`[abracadabra-mcp] User ID: ${this._userId}`)
+    } catch {
+      console.error('[abracadabra-mcp] Could not fetch user profile, proceeding without userId')
+    }
+
+    // Step 2: Discover server info
+    this._serverInfo = await this.client.serverInfo()
+
+    // Step 3: Discover spaces (optional extension)
+    let initialDocId: string | null = this._serverInfo.index_doc_id ?? null
+    try {
+      this._spaces = await this.client.listSpaces()
+      const hub = this._spaces.find(s => s.is_hub)
+      if (hub) {
+        initialDocId = hub.doc_id
+        console.error(`[abracadabra-mcp] Spaces extension active. Hub space: ${hub.name} (${hub.doc_id})`)
+      } else if (this._spaces.length > 0) {
+        initialDocId = this._spaces[0].doc_id
+        console.error(`[abracadabra-mcp] Spaces active but no hub, using first space: ${this._spaces[0].name} (${this._spaces[0].doc_id})`)
+      }
+    } catch {
+      console.error('[abracadabra-mcp] Spaces extension not available, using index_doc_id')
+    }
+
+    if (!initialDocId) {
+      throw new Error('No entry point found: server has neither spaces nor index_doc_id configured.')
+    }
+
+    this._rootDocId = initialDocId
+    console.error(`[abracadabra-mcp] Active space doc: ${initialDocId}`)
+
+    // Step 4: Connect to initial space
+    await this._connectToSpace(initialDocId)
+    console.error('[abracadabra-mcp] Space doc synced')
+
+    // Step 5: Start eviction timer
+    this.evictionTimer = setInterval(() => this.evictIdle(), 60_000)
+  }
+
+  /** Connect to a space's root doc and cache it. Sets it as the active connection. */
+  private async _connectToSpace(docId: string): Promise<SpaceConnection> {
+    const existing = this._spaceConnections.get(docId)
+    if (existing) {
+      this._activeConnection = existing
+      this._rootDocId = docId
+      return existing
+    }
+
+    const doc = new Y.Doc({ guid: docId })
+    const provider = new AbracadabraProvider({
+      name: docId,
+      document: doc,
+      client: this.client,
+      disableOfflineStore: true,
+      subdocLoading: 'lazy',
+    })
+
+    await waitForSync(provider)
+
+    provider.awareness.setLocalStateField('user', {
+      name: this.agentName,
+      color: this.agentColor,
+      publicKey: this._userId,
+    })
+
+    const conn: SpaceConnection = { doc, provider, docId }
+    this._spaceConnections.set(docId, conn)
+    this._activeConnection = conn
+    this._rootDocId = docId
+
+    // Re-attach awareness + stateless listeners if messaging is active (handles space switches)
+    if (this._mcpServerRef) {
+      this._observeRootAwareness(provider)
+      provider.on('stateless', ({ payload }: { payload: string }) => {
+        this._handleStatelessChat(payload)
+      })
+    }
+
+    return conn
+  }
+
+  /**
+   * Switch the active space to the given doc ID.
+   * Clears the child provider cache (children belong to the previous space).
+   */
+  async switchSpace(docId: string): Promise<void> {
+    for (const [, cached] of this.childCache) {
+      cached.provider.destroy()
+    }
+    this.childCache.clear()
+    await this._connectToSpace(docId)
+    console.error(`[abracadabra-mcp] Switched active space to ${docId}`)
+  }
+
+  /** Get the root doc-tree Y.Map of the active space. */
+  getTreeMap(): Y.Map<any> | null {
+    return this._activeConnection?.doc.getMap('doc-tree') ?? null
+  }
+
+  /** Get the root doc-trash Y.Map of the active space. */
+  getTrashMap(): Y.Map<any> | null {
+    return this._activeConnection?.doc.getMap('doc-trash') ?? null
+  }
+
+  /**
+   * Get or create a child provider for a given document ID.
+   * Caches providers and waits for sync before returning.
+   */
+  async getChildProvider(docId: string): Promise<AbracadabraProvider> {
+    const cached = this.childCache.get(docId)
+    if (cached) {
+      cached.lastAccessed = Date.now()
+      return cached.provider
+    }
+
+    const activeProvider = this._activeConnection?.provider
+    if (!activeProvider) {
+      throw new Error('Not connected. Call connect() first.')
+    }
+
+    const childProvider = await activeProvider.loadChild(docId)
+    await waitForSync(childProvider)
+
+    childProvider.awareness.setLocalStateField('user', {
+      name: this.agentName,
+      color: this.agentColor,
+      publicKey: this._userId,
+    })
+
+    this.childCache.set(docId, {
+      provider: childProvider,
+      lastAccessed: Date.now(),
+    })
+
+    return childProvider
+  }
+
+  /** Update root awareness to reflect the currently focused document. */
+  setFocusedDoc(docId: string): void {
+    this.rootYProvider?.awareness.setLocalStateField('docId', docId)
+  }
+
+  /**
+   * Set a TipTap-compatible collapsed cursor (anchor === head) on a child doc's awareness.
+   * Only call after getChildProvider has cached the provider.
+   * @param index Character index in xmlFragment ('default'). Clamped to [0, length].
+   */
+  setDocCursor(docId: string, index: number): void {
+    const cached = this.childCache.get(docId)
+    if (!cached) return
+
+    const fragment = cached.provider.document.getXmlFragment('default')
+    const clampedIndex = Math.max(0, Math.min(index, fragment.length))
+    const relPos = Y.createRelativePositionFromTypeIndex(fragment, clampedIndex)
+    const relPosJson = Y.relativePositionToJSON(relPos)
+
+    cached.provider.awareness.setLocalStateField('anchor', relPosJson)
+    cached.provider.awareness.setLocalStateField('head', relPosJson)
+  }
+
+  /** Evict child providers that have been idle for too long. */
+  private evictIdle(): void {
+    const now = Date.now()
+    for (const [docId, cached] of this.childCache) {
+      if (now - cached.lastAccessed > IDLE_TIMEOUT_MS) {
+        // Clear cursor before destroying so TipTap removes the caret overlay
+        cached.provider.awareness.setLocalStateField('anchor', null)
+        cached.provider.awareness.setLocalStateField('head', null)
+        cached.provider.destroy()
+        this.childCache.delete(docId)
+        console.error(`[abracadabra-mcp] Evicted idle provider: ${docId}`)
+      }
+    }
+  }
+
+  /** Wire up real-time channel notifications via awareness observation and stateless chat. */
+  startChannelNotifications(mcpServer: McpServer): void {
+    this._mcpServerRef = mcpServer
+    this._serverRef = mcpServer.server
+    const provider = this._activeConnection?.provider
+    if (provider) {
+      this._observeRootAwareness(provider)
+      provider.on('stateless', ({ payload }: { payload: string }) => {
+        this._handleStatelessChat(payload)
+      })
+      console.error('[abracadabra-mcp] Stateless chat listener attached')
+    }
+  }
+
+  /** Attach awareness observer to detect `ai:task` fields from human users. */
+  private _observeRootAwareness(provider: AbracadabraProvider): void {
+    const selfId = provider.awareness.clientID
+    provider.awareness.on('change', () => {
+      const states = provider.awareness.getStates()
+      for (const [clientId, state] of states) {
+        if (clientId === selfId) continue
+        const task = (state as Record<string, any>)['ai:task']
+        if (!task || typeof task !== 'object') continue
+        const { id, text } = task as { id?: string; text?: string }
+        if (!id || !text) continue
+        if (this._handledTaskIds.has(id)) continue
+        this._handledTaskIds.add(id)
+
+        // Extract sender name from awareness state
+        const user = (state as Record<string, any>)['user']
+        const senderName = (user && typeof user === 'object' && typeof user.name === 'string')
+          ? user.name
+          : 'Unknown'
+
+        console.error(`[abracadabra-mcp] Handling ai:task id=${id} from ${senderName}: ${text.slice(0, 80)}`)
+        this._dispatchAiTask({
+          id,
+          text,
+          docId: (state as Record<string, any>)['docId'],
+          senderName,
+        })
+      }
+    })
+    console.error('[abracadabra-mcp] Root awareness observation started')
+  }
+
+  /** Dispatch an ai:task as a channel notification. */
+  private async _dispatchAiTask(task: { id: string; text: string; docId?: string; senderName: string }): Promise<void> {
+    if (!this._serverRef) return
+    try {
+      await this._serverRef.notification({
+        method: 'notifications/claude/channel',
+        params: {
+          content: task.text,
+          meta: {
+            source: 'abracadabra',
+            type: 'ai_task',
+            task_id: task.id,
+            sender: task.senderName,
+            doc_id: task.docId ?? '',
+          },
+        },
+      })
+      console.error(`[abracadabra-mcp] Channel notification sent for ai:task id=${task.id}`)
+    } catch (error: any) {
+      console.error(`[abracadabra-mcp] Channel notification failed: ${error.message}`)
+    }
+  }
+
+  /**
+   * Clear an ai:task from awareness to signal completion.
+   * Scans all awareness states for the given task ID and removes it.
+   */
+  clearAiTask(taskId: string): void {
+    const provider = this._activeConnection?.provider
+    if (!provider) return
+    const selfId = provider.awareness.clientID
+    const states = provider.awareness.getStates()
+    for (const [clientId, state] of states) {
+      if (clientId === selfId) continue
+      const task = (state as Record<string, any>)['ai:task']
+      if (task && typeof task === 'object' && (task as any).id === taskId) {
+        // We can't clear another client's awareness directly, but we can
+        // signal completion by setting our own awareness field
+        provider.awareness.setLocalStateField('ai:task:done', taskId)
+        break
+      }
+    }
+  }
+
+  /** Handle incoming stateless chat messages and dispatch as channel notifications. */
+  private async _handleStatelessChat(payload: string): Promise<void> {
+    if (!this._serverRef) return
+    if (!payload.includes('"chat:message"')) return
+
+    try {
+      const data = JSON.parse(payload)
+      if (data.type !== 'chat:message') return
+      // Skip own messages
+      if (data.sender_id && data.sender_id === this._userId) return
+
+      const channel = data.channel as string | undefined
+      const docId = channel?.startsWith('group:') ? channel.slice(6) : ''
+
+      // Only process DMs where the agent is a participant
+      if (channel?.startsWith('dm:')) {
+        const parts = channel.split(':')
+        if (parts.length === 3 && parts[1] !== this._userId && parts[2] !== this._userId) {
+          return
+        }
+      }
+
+      await this._serverRef.notification({
+        method: 'notifications/claude/channel',
+        params: {
+          content: data.content ?? '',
+          meta: {
+            source: 'abracadabra',
+            type: 'chat_message',
+            channel: channel ?? '',
+            sender: data.sender_name ?? 'Unknown',
+            sender_id: data.sender_id ?? '',
+            doc_id: docId,
+          },
+        },
+      })
+      console.error(`[abracadabra-mcp] Chat message from ${data.sender_name ?? 'unknown'} on ${channel}`)
+    } catch {
+      // Ignore non-chat or malformed payloads
+    }
+  }
+
+  /** Graceful shutdown. */
+  async destroy(): Promise<void> {
+    if (this.evictionTimer) {
+      clearInterval(this.evictionTimer)
+      this.evictionTimer = null
+    }
+
+    for (const [, cached] of this.childCache) {
+      cached.provider.destroy()
+    }
+    this.childCache.clear()
+
+    for (const [, conn] of this._spaceConnections) {
+      conn.provider.destroy()
+    }
+    this._spaceConnections.clear()
+    this._activeConnection = null
+
+    console.error('[abracadabra-mcp] Shutdown complete')
+  }
+}

package/src/tools/awareness.ts

@@ -0,0 +1,156 @@
+/**
+ * Awareness tools — read/write presence state.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { awarenessStatesToArray } from '@abraca/dabra'
+import { yjsToMarkdown } from '../converters/yjsToMarkdown.ts'
+import type { AbracadabraMCPServer } from '../server.ts'
+
+export function registerAwarenessTools(mcp: McpServer, server: AbracadabraMCPServer) {
+  mcp.tool(
+    'set_presence',
+    'Set the AI agent\'s presence state. Use this to indicate which document you are viewing or your current status.',
+    {
+      docId: z.string().optional().describe('Document ID the agent is currently viewing. Sets docId in root awareness.'),
+      status: z.string().optional().describe('Status text (e.g. "writing", "reviewing", "thinking").'),
+    },
+    async ({ docId, status }) => {
+      const rootProvider = server.rootYProvider
+      if (!rootProvider) return { content: [{ type: 'text', text: 'Not connected' }] }
+
+      if (docId !== undefined) {
+        rootProvider.awareness.setLocalStateField('docId', docId)
+      }
+      if (status !== undefined) {
+        rootProvider.awareness.setLocalStateField('status', status)
+      }
+
+      return { content: [{ type: 'text', text: 'Presence updated' }] }
+    }
+  )
+
+  mcp.tool(
+    'set_doc_awareness',
+    'Set renderer-specific awareness fields on a child document. Use this to broadcast item-level presence (e.g. which kanban card, table cell, or slide you are interacting with). Setting a field to null clears it.',
+    {
+      docId: z.string().describe('Document ID to set awareness on.'),
+      fields: z.record(z.string(), z.unknown()).describe('Key-value pairs to set on the child document\'s awareness state. Use namespaced keys like "kanban:hovering", "table:editing", "slides:viewing", "outline:editing", "calendar:focused", "gallery:focused", "timeline:focused", "graph:focused", "map:focused", "doc:scroll". Set a key to null to clear it.'),
+    },
+    async ({ docId, fields }) => {
+      try {
+        const provider = await server.getChildProvider(docId)
+        for (const [key, value] of Object.entries(fields)) {
+          provider.awareness.setLocalStateField(key, value ?? null)
+        }
+        return { content: [{ type: 'text', text: 'Doc awareness updated' }] }
+      } catch (error: any) {
+        return {
+          content: [{ type: 'text', text: `Error: ${error.message}` }],
+          isError: true,
+        }
+      }
+    }
+  )
+
+  mcp.tool(
+    'poll_inbox',
+    'Check the "AI Inbox" document for pending instructions from humans. Returns the inbox content and any pending task sub-documents. Create the inbox as a doc called "AI Inbox" under the hub doc if it does not exist yet. Note: channel-based watching via watch_chat is preferred for real-time use.',
+    {},
+    async () => {
+      try {
+        const treeMap = server.getTreeMap()
+        const rootDocId = server.rootDocId
+        if (!treeMap || !rootDocId) {
+          return { content: [{ type: 'text', text: 'Not connected' }] }
+        }
+
+        // Find "AI Inbox" doc that is a direct child of the hub doc
+        let inboxId: string | null = null
+        treeMap.forEach((value: any, id: string) => {
+          if (
+            value.parentId === rootDocId &&
+            typeof value.label === 'string' &&
+            value.label.toLowerCase() === 'ai inbox'
+          ) {
+            inboxId = id
+          }
+        })
+
+        if (!inboxId) {
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                pending: [],
+                message: 'No AI Inbox document found. Create one under the hub doc with label "AI Inbox".',
+              }),
+            }],
+          }
+        }
+
+        const resolvedInboxId: string = inboxId
+        const provider = await server.getChildProvider(resolvedInboxId)
+        const fragment = provider.document.getXmlFragment('default')
+        const { markdown } = yjsToMarkdown(fragment)
+
+        // Collect direct children of inbox (pending task sub-docs)
+        const pendingTasks: Array<{ id: string; label: string }> = []
+        treeMap.forEach((value: any, id: string) => {
+          if (value.parentId === resolvedInboxId) {
+            pendingTasks.push({ id, label: value.label || 'Untitled' })
+          }
+        })
+
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({ inboxId: resolvedInboxId, content: markdown, pendingTasks }, null, 2),
+          }],
+        }
+      } catch (error: any) {
+        return {
+          content: [{ type: 'text', text: `Error: ${error.message}` }],
+          isError: true,
+        }
+      }
+    }
+  )
+
+  mcp.tool(
+    'list_connected_users',
+    'List all connected users and their awareness state. Shows who is online and what they are doing.',
+    {
+      docId: z.string().optional().describe('If provided, list users connected to this specific document. Otherwise lists users from root awareness.'),
+    },
+    async ({ docId }) => {
+      try {
+        let awareness
+        if (docId) {
+          const provider = await server.getChildProvider(docId)
+          awareness = provider.awareness
+        } else {
+          const rootProvider = server.rootYProvider
+          if (!rootProvider) return { content: [{ type: 'text', text: 'Not connected' }] }
+          awareness = rootProvider.awareness
+        }
+
+        const states = awarenessStatesToArray(awareness.getStates())
+        // Filter out empty states
+        const users = states.filter(s => s.user)
+
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(users, null, 2),
+          }],
+        }
+      } catch (error: any) {
+        return {
+          content: [{ type: 'text', text: `Error: ${error.message}` }],
+          isError: true,
+        }
+      }
+    }
+  )
+}

package/src/tools/channel.ts

@@ -0,0 +1,92 @@
+/**
+ * Channel tools — reply to channel events and send chat messages.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import type { AbracadabraMCPServer } from '../server.ts'
+import { populateYDocFromMarkdown } from '../converters/markdownToYjs.ts'
+
+export function registerChannelTools(mcp: McpServer, server: AbracadabraMCPServer) {
+  mcp.tool(
+    'reply',
+    'Create a document reply. Creates a child document under doc_id with the reply content as a rich-text document. Use this for structured, persistent responses. For conversational chat, use send_chat_message instead.',
+    {
+      doc_id: z.string().describe('Document ID to create the reply under.'),
+      text: z.string().describe('Markdown content for the reply.'),
+      task_id: z.string().optional().describe('If replying to an ai:task, the task ID to clear from awareness.'),
+    },
+    async ({ doc_id, text, task_id }) => {
+      try {
+        const treeMap = server.getTreeMap()
+        const rootDoc = server.rootDocument
+        if (!treeMap || !rootDoc) {
+          return { content: [{ type: 'text' as const, text: 'Not connected' }], isError: true }
+        }
+
+        const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19)
+        const snippet = text.slice(0, 40).replace(/\n/g, ' ')
+        const label = `AI Reply — ${timestamp}: ${snippet}`
+        const replyId = crypto.randomUUID()
+        const now = Date.now()
+
+        rootDoc.transact(() => {
+          treeMap.set(replyId, {
+            label,
+            parentId: doc_id,
+            order: now,
+            type: 'doc',
+            createdAt: now,
+            updatedAt: now,
+          })
+        })
+
+        const replyProvider = await server.getChildProvider(replyId)
+        populateYDocFromMarkdown(replyProvider.document, text)
+
+        if (task_id) {
+          server.clearAiTask(task_id)
+        }
+
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify({ replyDocId: replyId, parentId: doc_id }) }],
+        }
+      } catch (error: any) {
+        return {
+          content: [{ type: 'text' as const, text: `Error: ${error.message}` }],
+          isError: true,
+        }
+      }
+    }
+  )
+
+  mcp.tool(
+    'send_chat_message',
+    'Send a chat message visible in the dashboard chat UI. For document group chat use channel "group:<docId>". For DM use "dm:<key1>:<key2>" (keys sorted alphabetically). Use list_connected_users to find user publicKeys for DM channels.',
+    {
+      channel: z.string().describe('Channel ID, e.g. "group:<docId>" or "dm:<key1>:<key2>"'),
+      text: z.string().describe('Message text'),
+    },
+    async ({ channel, text }) => {
+      try {
+        const rootProvider = server.rootYProvider
+        if (!rootProvider) {
+          return { content: [{ type: 'text' as const, text: 'Not connected' }], isError: true }
+        }
+
+        rootProvider.sendStateless(JSON.stringify({
+          type: 'chat:send',
+          channel,
+          content: text,
+          sender_name: server.agentName,
+        }))
+
+        return { content: [{ type: 'text' as const, text: `Sent to ${channel}` }] }
+      } catch (error: any) {
+        return {
+          content: [{ type: 'text' as const, text: `Error: ${error.message}` }],
+          isError: true,
+        }
+      }
+    }
+  )
+}