@abraca/mcp 1.9.1 → 2.4.0

package/src/server.ts

@@ -1,13 +1,13 @@
 /**
  * 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.
+ * Space-aware: on connect, discovers Spaces (top-level docs with kind="space")
+ * by listing children of the server root. The first Space becomes the active
+ * one; use switchSpace(docId) to change.
  */
 import * as Y from 'yjs'
-import { AbracadabraProvider, AbracadabraClient } from '@abraca/dabra'
-import type { ServerInfo, SpaceMeta, DocumentMeta } from '@abraca/dabra'
+import { AbracadabraProvider, AbracadabraClient, Kind, SERVER_ROOT_ID } from '@abraca/dabra'
+import type { ServerInfo, DocumentMeta } 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'
@@ -52,7 +52,7 @@ export class AbracadabraMCPServer {
   readonly client: AbracadabraClient
   private _serverInfo: ServerInfo | null = null
   private _rootDocId: string | null = null
-  private _spaces: SpaceMeta[] = []
+  private _spaces: DocumentMeta[] = []
   private _activeConnection: SpaceConnection | null = null
   private _spaceConnections = new Map<string, SpaceConnection>()
   private childCache = new Map<string, CachedProvider>()
@@ -103,7 +103,11 @@ export class AbracadabraMCPServer {
     return this._rootDocId
   }
 
-  get spaces(): SpaceMeta[] {
+  /**
+   * Spaces visible to the caller — direct children of the server root with
+   * `kind === "space"`. Populated by {@link connect}.
+   */
+  get spaces(): DocumentMeta[] {
     return this._spaces
   }
 
@@ -131,9 +135,15 @@ export class AbracadabraMCPServer {
     try {
       await this.client.loginWithKey(keypair.publicKeyB64, signFn)
     } catch (err: any) {
-      // Key not registered — auto-register and retry
+      // Key not registered — auto-register and retry.
+      // Servers signal this with 404/422, or 401 + "public key not registered" / "user not found".
       const status = err?.status ?? err?.response?.status
-      if (status === 404 || status === 422) {
+      const msg = String(err?.message ?? '').toLowerCase()
+      const notRegistered =
+        status === 404 ||
+        status === 422 ||
+        (status === 401 && /not registered|user not found|no such user/.test(msg))
+      if (notRegistered) {
         console.error('[abracadabra-mcp] Key not registered, creating new account...')
         await this.client.registerWithKey({
           publicKey: keypair.publicKeyB64,
@@ -152,39 +162,23 @@ export class AbracadabraMCPServer {
     // Step 3: Discover server info
     this._serverInfo = await this.client.serverInfo()
 
-    // Step 4: Discover root documents (try new endpoint first, fall back to /spaces)
-    let initialDocId: string | null = this._serverInfo.index_doc_id ?? null
-    try {
-      const roots = await this.client.listRootDocuments()
-      // Map to SpaceMeta shape for backwards compat with list_spaces tool
-      this._spaces = roots.map(docToSpaceMeta)
-      const hub = roots.find(d => d.is_hub)
-      if (hub) {
-        initialDocId = hub.id
-        console.error(`[abracadabra-mcp] Root documents discovered. Hub: ${hub.label ?? hub.id} (${hub.id})`)
-      } else if (roots.length > 0) {
-        initialDocId = roots[0].id
-        console.error(`[abracadabra-mcp] No hub, using first root doc: ${roots[0].label ?? roots[0].id} (${roots[0].id})`)
-      }
-    } catch {
-      // Fall back to legacy /spaces endpoint for older servers
-      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] Neither /docs?root=true nor /spaces available, using index_doc_id')
-      }
+    // Step 4: Discover Spaces — top-level docs (children of the server root)
+    // tagged with kind="space". The first Space is the default landing doc;
+    // any other top-level doc serves as a fallback if no Spaces exist.
+    const roots = await this.client.listChildren()
+    this._spaces = roots.filter(d => d.kind === Kind.Space)
+    const first = this._spaces[0] ?? roots[0]
+    const initialDocId = first?.id ?? null
+    if (first) {
+      console.error(
+        `[abracadabra-mcp] Active space: ${first.label ?? first.id} (${first.id})`,
+      )
     }
 
     if (!initialDocId) {
-      throw new Error('No entry point found: server has neither spaces nor index_doc_id configured.')
+      throw new Error(
+        `No entry point found: server has no top-level documents under ${SERVER_ROOT_ID}. Create a Space first.`,
+      )
     }
 
     this._rootDocId = initialDocId
@@ -465,77 +459,65 @@ export class AbracadabraMCPServer {
     }
   }
 
-  /** Handle incoming stateless chat messages and dispatch as channel notifications. */
+  /** Handle incoming `messages:new_message` broadcasts and dispatch as channel notifications. */
   private async _handleStatelessChat(payload: string): Promise<void> {
     if (!this._serverRef) return
-    if (!payload.includes('"chat:message"')) return
+    if (!payload.includes('"messages:new_message"')) return
 
     try {
-      const data = JSON.parse(payload)
-      if (data.type !== 'chat:message') return
+      const env = JSON.parse(payload)
+      if (env.type !== 'messages:new_message') return
+      const data = env.record
+      if (!data) return
+      // Only react to actual messages — skip edit/tombstone records.
+      if (data.record_kind && data.record_kind !== '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) : ''
-      const isDM = channel?.startsWith('dm:') ?? false
-      const isGroup = channel?.startsWith('group:') ?? false
-
-      // Only process DMs where the agent is a participant
-      if (isDM) {
-        const parts = channel!.split(':')
-        if (parts.length === 3 && parts[1] !== this._userId && parts[2] !== this._userId) {
-          console.error(
-            `[abracadabra-mcp] Dropping DM: agent _userId=${this._userId} not in channel parts=[${parts[1]}, ${parts[2]}] — channel='${channel}'. ` +
-            `The dashboard's awareness likely points at a stale Claude identity.`,
-          )
-          return
-        }
-      }
+      const channelDocId = data.channel_doc_id as string | undefined
+      if (!channelDocId) return
+
+      // Look up the channel kind (channel vs dm) via the doc tree, since the
+      // new model has no synthetic channel string. Caller-side filtering of
+      // DMs (only dispatch when the agent is a participant) relies on the
+      // permissions on the dm doc — server enforces; nothing to check here.
+      const isDM = false // Without a kind lookup, treat all as group for trigger semantics.
+      const isGroup = !isDM
 
       // ── Trigger mode gate ─────────────────────────────────────────────
-      // DMs always dispatch (implicit summon). Groups obey the trigger mode.
       const mode = this.triggerMode
       const content = typeof data.content === 'string' ? data.content : ''
       let dispatchContent = content
 
       if (isGroup) {
         if (mode === 'task') {
-          // Chat never triggers in task-only mode
           return
         }
         if (mode === 'mention' || mode === 'mention+task') {
           const aliases = this.mentionAliases
           if (!containsMention(content, aliases)) {
-            console.error(`[abracadabra-mcp] skipped message on ${channel} — no @mention for ${aliases.join('|')}`)
+            console.error(`[abracadabra-mcp] skipped message on ${channelDocId} — no @mention for ${aliases.join('|')}`)
             return
           }
-          // Strip the mention so Claude sees a clean prompt
           dispatchContent = stripMention(content, aliases) || content
         }
         // mode === 'all' falls through unchanged
       }
       // ──────────────────────────────────────────────────────────────────
 
-      // Auto-mark channel as read so sender sees a read receipt
-      if (channel) {
-        const rootProvider = this._activeConnection?.provider
-        if (rootProvider) {
-          rootProvider.sendStateless(JSON.stringify({
-            type: 'chat:mark_read',
-            channel,
-            timestamp: Math.floor(Date.now() / 1000),
-          }))
-        }
-        // Remember the channel so setAutoStatus can scope statusContext to it.
-        // NOTE: no typing indicator here — "thinking" status + tool pills are
-        // the correct signal while Claude is working; typing is reserved for
-        // the actual send_chat_message burst below.
-        this._lastChatChannel = channel
+      // Auto-mark this message position read.
+      const rootProvider = this._activeConnection?.provider
+      if (rootProvider && data.id && data.period_id) {
+        rootProvider.sendStateless(JSON.stringify({
+          type: 'messages:mark_read',
+          channel_doc_id: channelDocId,
+          period_id: data.period_id,
+          message_id: data.id,
+          ts: Date.now(),
+        }))
       }
+      this._lastChatChannel = channelDocId
 
-      // Mint a fresh turn id so the dashboard ties its incantation + tool
-      // trace to THIS turn, and set status to "thinking".
       this._beginTurn()
       this.setAutoStatus('thinking')
 
@@ -543,18 +525,18 @@ export class AbracadabraMCPServer {
         method: 'notifications/claude/channel',
         params: {
           content: dispatchContent,
-          instructions: `You MUST use send_chat_message with channel="${channel ?? ''}" for ALL responses — both progress updates and final answers. The user CANNOT see plain text output; they only see messages sent via send_chat_message. When doing multi-step work, send brief status updates via send_chat_message (e.g. "Looking into that..." or "Found it, writing up results...") so the user knows you're working. Never output plain text as a substitute for send_chat_message.`,
+          instructions: `You MUST use send_chat_message with channel_doc_id="${channelDocId}" for ALL responses — both progress updates and final answers. The user CANNOT see plain text output; they only see messages sent via send_chat_message. When doing multi-step work, send brief status updates via send_chat_message (e.g. "Looking into that..." or "Found it, writing up results...") so the user knows you're working. Never output plain text as a substitute for send_chat_message.`,
           meta: {
             source: 'abracadabra',
             type: 'chat_message',
-            channel: channel ?? '',
+            channel_doc_id: channelDocId,
             sender: data.sender_name ?? 'Unknown',
             sender_id: data.sender_id ?? '',
-            doc_id: docId,
+            doc_id: channelDocId,
           },
         },
       })
-      console.error(`[abracadabra-mcp] Chat message from ${data.sender_name ?? 'unknown'} on ${channel}`)
+      console.error(`[abracadabra-mcp] Chat message from ${data.sender_name ?? 'unknown'} on ${channelDocId}`)
     } catch {
       // Ignore non-chat or malformed payloads
     }
@@ -669,15 +651,20 @@ export class AbracadabraMCPServer {
   }
 
   /**
-   * Send a typing indicator to a chat channel.
+   * Send a typing indicator to a chat channel. Pass the channel doc id
+   * (or for legacy callers, a `group:<docId>` string — we strip the prefix).
    */
   sendTypingIndicator(channel: string): void {
     const rootProvider = this._activeConnection?.provider
     if (!rootProvider) return
+    const channelDocId = channel.startsWith('group:')
+      ? channel.slice(6)
+      : channel.startsWith('dm:')
+        ? channel
+        : channel
     rootProvider.sendStateless(JSON.stringify({
-      type: 'chat:typing',
-      channel,
-      sender_name: this.agentName,
+      type: 'messages:typing',
+      channel_doc_id: channelDocId,
     }))
   }
 
@@ -714,23 +701,3 @@ export class AbracadabraMCPServer {
     console.error('[abracadabra-mcp] Shutdown complete')
   }
 }
-
-/** Map a DocumentMeta (from /docs?root=true) to the SpaceMeta shape for compat. */
-function docToSpaceMeta(doc: DocumentMeta): SpaceMeta {
-  const publicAccess = doc.public_access
-  let visibility: SpaceMeta['visibility'] = 'private'
-  if (publicAccess && publicAccess !== 'none') visibility = 'public'
-
-  return {
-    id: doc.id,
-    doc_id: doc.id,
-    name: doc.label ?? doc.id,
-    description: doc.description ?? null,
-    visibility,
-    is_hub: doc.is_hub ?? false,
-    owner_id: doc.owner_id ?? null,
-    created_at: 0,
-    updated_at: doc.updated_at ?? 0,
-    public_access: publicAccess ?? null,
-  }
-}

package/src/tools/channel.ts

@@ -65,12 +65,12 @@ export function registerChannelTools(mcp: McpServer, server: AbracadabraMCPServe
 
   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.',
+    'Send a chat message visible in the dashboard chat UI. Pass channel_doc_id — the UUID of a doc with kind "channel" (group chat under a Space) or "dm" (direct message). Use list_connected_users + the doc tree to discover channels.',
     {
-      channel: z.string().describe('Channel ID, e.g. "group:<docId>" or "dm:<key1>:<key2>"'),
+      channel_doc_id: z.string().describe('Channel doc UUID (kind = "channel" or "dm")'),
       text: z.string().describe('Message text'),
     },
-    async ({ channel, text }) => {
+    async ({ channel_doc_id, text }) => {
       try {
         const rootProvider = server.rootYProvider
         if (!rootProvider) {
@@ -90,18 +90,18 @@ export function registerChannelTools(mcp: McpServer, server: AbracadabraMCPServe
         // Order matters: clear status + tool pill FIRST so the dashboard's
         // typing-indicator filter (which hides typing while an activeToolCall
         // exists) doesn't swallow the burst. Then emit the typing frame, then
-        // the actual chat:send. The clear also flushes toolHistory + turnId.
+        // the actual messages:send. The clear also flushes toolHistory + turnId.
         server.setAutoStatus(null)
-        server.sendTypingIndicator(channel)
+        server.sendTypingIndicator(channel_doc_id)
 
         rootProvider.sendStateless(JSON.stringify({
-          type: 'chat:send',
-          channel,
+          type: 'messages:send',
+          channel_doc_id,
           content: normalized,
-          sender_name: server.agentName,
+          mentions: [],
         }))
 
-        return { content: [{ type: 'text' as const, text: `Sent to ${channel}` }] }
+        return { content: [{ type: 'text' as const, text: `Sent to ${channel_doc_id}` }] }
       } catch (error: any) {
         return {
           content: [{ type: 'text' as const, text: `Error: ${error.message}` }],

package/src/tools/meta.ts

@@ -4,8 +4,13 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { z } from 'zod'
 import type { AbracadabraMCPServer } from '../server.ts'
+import type { SchemaBundleValidator } from '../schema/validator.ts'
 
-export function registerMetaTools(mcp: McpServer, server: AbracadabraMCPServer) {
+export function registerMetaTools(
+  mcp: McpServer,
+  server: AbracadabraMCPServer,
+  validator: SchemaBundleValidator | null = null,
+) {
   mcp.tool(
     'get_metadata',
     'Read the metadata (PageMeta) of a document from the tree.',
@@ -59,9 +64,25 @@ export function registerMetaTools(mcp: McpServer, server: AbracadabraMCPServer)
         return { content: [{ type: 'text', text: `Document ${docId} not found` }] }
       }
 
+      const mergedMeta = { ...(entry.meta ?? {}), ...meta }
+
+      if (validator && entry.type) {
+        const result = validator.validateMeta(entry.type, mergedMeta)
+        if (!result.ok) {
+          const detail = result.errors.map((e) => `${e.path} ${e.message}`).join('; ')
+          return {
+            content: [{
+              type: 'text',
+              text: `Metadata validation failed for type "${entry.type}": ${detail}`,
+            }],
+            isError: true,
+          }
+        }
+      }
+
       treeMap.set(docId, {
         ...entry,
-        meta: { ...(entry.meta ?? {}), ...meta },
+        meta: mergedMeta,
         updatedAt: Date.now(),
       })
 

package/src/tools/tree.ts

@@ -7,6 +7,7 @@ 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'
+import type { SchemaBundleValidator } from '../schema/validator.ts'
 
 /**
  * Normalize a document ID so the hub/root doc ID is treated as the tree root (null).
@@ -80,7 +81,11 @@ function buildTree(entries: TreeEntry[], rootId: string | null, maxDepth: number
   })
 }
 
-export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer) {
+export function registerTreeTools(
+  mcp: McpServer,
+  server: AbracadabraMCPServer,
+  validator: SchemaBundleValidator | null = null,
+) {
   mcp.tool(
     'list_documents',
     'List direct children of a document (defaults to root). Returns id, label, type, meta, order. NOTE: Only returns ONE level. Use find_document to search by name across the full tree, or get_document_tree to see the complete hierarchy.',
@@ -196,6 +201,52 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
     }
   )
 
+  mcp.tool(
+    'query_documents',
+    'Find documents by structural predicate across every space the user can read (POST /docs/query, v1). v1 filters on type (kanban, doc, calendar, etc.), parent doc, and label substring. Meta-field predicates (priority >= 3, dateStart in range) arrive in v2. Use this instead of find_document when you want to scope by page-type rather than label, or list every doc of a given kind across the server.',
+    {
+      type: z.string().optional().describe('Match documents.kind exactly. Examples: "kanban", "doc", "calendar", "table", "gallery". Omit to range across kinds.'),
+      parentId: z.string().optional().describe('Narrow to direct children of this doc.'),
+      labelContains: z.string().optional().describe('Case-insensitive substring match on the document label.'),
+      limit: z.number().optional().describe('Maximum results returned. Default 50; hard cap 500 server-side.'),
+    },
+    async ({ type, parentId, labelContains, limit }) => {
+      server.setAutoStatus('searching')
+      server.setActiveToolCall({ name: 'query_documents', target: type ?? labelContains ?? parentId ?? 'query' })
+
+      if (type == null && parentId == null && labelContains == null) {
+        return {
+          content: [{
+            type: 'text',
+            text: 'At least one of `type`, `parentId`, or `labelContains` is required — the server refuses to scan the full document set. (Use list_documents for root-level listing, or find_document for full-tree label search.)',
+          }],
+        }
+      }
+
+      try {
+        const docs = await server.client.queryDocs({ type, parentId, labelContains, limit })
+        if (docs.length === 0) {
+          return {
+            content: [{
+              type: 'text',
+              text: `No documents matched (type=${type ?? '*'}, parentId=${parentId ?? '*'}, labelContains=${labelContains ?? '*'}). Try widening the predicate.`,
+            }],
+          }
+        }
+        return {
+          content: [{ type: 'text', text: JSON.stringify(docs, null, 2) }],
+        }
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text',
+            text: `query_documents failed: ${err instanceof Error ? err.message : String(err)}`,
+          }],
+        }
+      }
+    }
+  )
+
   mcp.tool(
     'create_document',
     'Create a new document in the tree. Returns the new document ID.',
@@ -215,6 +266,20 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
         return { content: [{ type: 'text', text: 'Not connected' }] }
       }
 
+      if (validator && type && meta) {
+        const result = validator.validateMeta(type, meta)
+        if (!result.ok) {
+          const detail = result.errors.map((e) => `${e.path} ${e.message}`).join('; ')
+          return {
+            content: [{
+              type: 'text',
+              text: `Metadata validation failed for type "${type}": ${detail}`,
+            }],
+            isError: true,
+          }
+        }
+      }
+
       const id = crypto.randomUUID()
       const normalizedParent = normalizeRootId(parentId, server)
       const now = Date.now()
@@ -368,27 +433,27 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
 
   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.',
+    'List all Spaces available on the server. Spaces are top-level documents (direct children of the server root) tagged with kind="space". Returns id, label, public_access, and active flag. Use switch_space to navigate.',
     {},
     async () => {
       const spaces = server.spaces
       if (!spaces.length) {
-        return { content: [{ type: 'text', text: 'No spaces available (spaces extension not loaded on this server)' }] }
+        return { content: [{ type: 'text', text: 'No spaces available — create one to get started.' }] }
       }
       const active = server.rootDocId
-      const annotated = spaces.map(s => ({ ...s, active: s.doc_id === active }))
+      const annotated = spaces.map(s => ({ ...s, active: s.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).') },
+    'Switch the active Space. All subsequent tree operations will target the new Space. Use list_spaces to discover available ids.',
+    { docId: z.string().describe('The 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
+      const space = server.spaces.find(s => s.id === docId)
+      const name = space?.label ?? docId
       return { content: [{ type: 'text', text: `Switched to space "${name}" (${docId})` }] }
     }
   )