@abraca/mcp 1.0.18 → 1.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/mcp",
-  "version": "1.0.18",
+  "version": "1.0.21",
   "description": "MCP server for Abracadabra — AI agent collaboration on CRDT documents",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -48,6 +48,13 @@ async function main() {
       capabilities: { experimental: { 'claude/channel': {} } },
       instructions: `Abracadabra is a CRDT collaboration platform where everything is a document in a tree.
 
+## CRITICAL: Responding to Channel Events
+The user CANNOT see your plain text output — they only see messages sent via MCP tools. When you receive a channel event:
+- **Chat messages**: Use send_chat_message with the SAME channel for ALL replies AND progress updates.
+- **AI tasks**: Use reply tool for the final response; use send_chat_message for progress updates.
+- For multi-step work, send brief status updates via send_chat_message so the user sees progress.
+- NEVER output plain text as a response or status update — it is invisible to the user.
+
 ## Quick Start Workflow
 1. list_spaces → note the active space's doc_id (this is the hub/root document)
 2. get_document_tree(rootId: hubDocId) → see the FULL hierarchy before doing anything
@@ -57,12 +64,12 @@ async function main() {
 ## Key Concepts
 - Documents form a tree. A kanban board's columns are child documents; cards are grandchildren.
 - A document's label IS its display name everywhere. Children ARE the content (not just the body text).
-- Page types (doc, kanban, table, calendar, timeline, checklist, outline, gallery, map, graph, dashboard, spatial, media, mindmap, etc.) are views over the SAME tree — switching types preserves data.
+- Page types are views over the SAME tree — switching types preserves data.
 - An empty markdown body does NOT mean empty content — always check the children array.
 - Use ![[docId]] in content to embed another document, or [[docId|label]] for inline links.
 
 ## Finding Documents
-- list_documents only shows ONE level of children. If you don't find what you need, use find_document to search the entire tree by name, or get_document_tree to see the full hierarchy.
+- list_documents only shows ONE level of children. Use find_document to search by name, or get_document_tree to see the full hierarchy.
 - NEVER conclude a document doesn't exist after only checking root-level documents.
 
 ## Rules
@@ -72,12 +79,6 @@ async function main() {
 - Never rename or write content to the hub document itself.
 - Use universal meta keys (color, icon, dateStart) — never prefix with page type names.
 
-## Channel Events
-Events from the abracadabra channel arrive as <channel source="abracadabra" ...>. They may be:
-- ai:task events from human users (includes sender, doc_id context)
-- chat messages from the platform chat system (includes channel, sender, sender_id)
-When you receive a channel event, read it, do the work using your tools, and reply using the reply tool (for document responses) or send_chat_message (for chat responses).
-
 ## Full Reference
 Read the resource at abracadabra://agent-guide for the complete guide covering page type schemas, metadata reference, awareness/presence, content structure, and detailed examples.`,
     },

package/src/server.ts

@@ -352,6 +352,7 @@ export class AbracadabraMCPServer {
         method: 'notifications/claude/channel',
         params: {
           content: task.text,
+          instructions: `You MUST use the reply tool with doc_id="${task.docId ?? ''}" and task_id="${task.id}" for your final response. The user CANNOT see plain text output; they only see replies sent via MCP tools. For progress updates during multi-step work, use send_chat_message with channel="group:${task.docId ?? ''}" (e.g. "Looking into that..." or "Found it, writing up results..."). Never output plain text as a substitute for MCP tools.`,
           meta: {
             source: 'abracadabra',
             type: 'ai_task',
@@ -433,6 +434,7 @@ export class AbracadabraMCPServer {
         method: 'notifications/claude/channel',
         params: {
           content: data.content ?? '',
+          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.`,
           meta: {
             source: 'abracadabra',
             type: 'chat_message',

package/src/tools/meta.ts

@@ -13,12 +13,21 @@ export function registerMetaTools(mcp: McpServer, server: AbracadabraMCPServer)
       docId: z.string().describe('Document ID.'),
     },
     async ({ docId }) => {
+      server.setAutoStatus('reading', docId)
+      server.setActiveToolCall({ name: 'get_metadata', target: docId })
       const treeMap = server.getTreeMap()
-      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+      if (!treeMap) {
+        server.setActiveToolCall(null)
+        return { content: [{ type: 'text', text: 'Not connected' }] }
+      }
 
       const entry = treeMap.get(docId)
-      if (!entry) return { content: [{ type: 'text', text: `Document ${docId} not found` }] }
+      if (!entry) {
+        server.setActiveToolCall(null)
+        return { content: [{ type: 'text', text: `Document ${docId} not found` }] }
+      }
 
+      server.setActiveToolCall(null)
       return {
         content: [{
           type: 'text',
@@ -41,11 +50,19 @@ export function registerMetaTools(mcp: McpServer, server: AbracadabraMCPServer)
       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"). Renderer config (on the page doc itself): kanbanColumnWidth, galleryColumns, galleryAspect, calendarView, calendarWeekStart, tableMode, showRefEdges. Set a key to null to clear it.'),
     },
     async ({ docId, meta }) => {
+      server.setAutoStatus('writing', docId)
+      server.setActiveToolCall({ name: 'update_metadata', target: docId })
       const treeMap = server.getTreeMap()
-      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+      if (!treeMap) {
+        server.setActiveToolCall(null)
+        return { content: [{ type: 'text', text: 'Not connected' }] }
+      }
 
       const entry = treeMap.get(docId)
-      if (!entry) return { content: [{ type: 'text', text: `Document ${docId} not found` }] }
+      if (!entry) {
+        server.setActiveToolCall(null)
+        return { content: [{ type: 'text', text: `Document ${docId} not found` }] }
+      }
 
       treeMap.set(docId, {
         ...entry,
@@ -53,6 +70,7 @@ export function registerMetaTools(mcp: McpServer, server: AbracadabraMCPServer)
         updatedAt: Date.now(),
       })
 
+      server.setActiveToolCall(null)
       return { content: [{ type: 'text', text: `Metadata updated for ${docId}` }] }
     }
   )

package/src/tools/tree.ts

@@ -78,13 +78,19 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
     '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.',
     { parentId: z.string().optional().describe('Parent document ID. Omit for root-level documents.') },
     async ({ parentId }) => {
+      server.setAutoStatus('reading')
+      server.setActiveToolCall({ name: 'list_documents' })
       const treeMap = server.getTreeMap()
-      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+      if (!treeMap) {
+        server.setActiveToolCall(null)
+        return { content: [{ type: 'text', text: 'Not connected' }] }
+      }
 
       const targetId = normalizeRootId(parentId, server)
       const entries = readEntries(treeMap)
       const children = childrenOf(entries, targetId)
 
+      server.setActiveToolCall(null)
       return {
         content: [{
           type: 'text',
@@ -102,14 +108,20 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
       depth: z.number().optional().describe('Maximum depth to traverse. Default 3. Use -1 for unlimited.'),
     },
     async ({ rootId, depth }) => {
+      server.setAutoStatus('reading')
+      server.setActiveToolCall({ name: 'get_document_tree' })
       const treeMap = server.getTreeMap()
-      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+      if (!treeMap) {
+        server.setActiveToolCall(null)
+        return { content: [{ type: 'text', text: 'Not connected' }] }
+      }
 
       const targetId = normalizeRootId(rootId, server)
       const maxDepth = depth ?? 3
       const entries = readEntries(treeMap)
       const tree = buildTree(entries, targetId, maxDepth)
 
+      server.setActiveToolCall(null)
       return {
         content: [{
           type: 'text',
@@ -127,8 +139,13 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
       rootId: z.string().optional().describe('Restrict search to descendants of this document. Omit to search the entire tree.'),
     },
     async ({ query, rootId }) => {
+      server.setAutoStatus('searching')
+      server.setActiveToolCall({ name: 'find_document', target: query })
       const treeMap = server.getTreeMap()
-      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+      if (!treeMap) {
+        server.setActiveToolCall(null)
+        return { content: [{ type: 'text', text: 'Not connected' }] }
+      }
 
       const entries = readEntries(treeMap)
       const lowerQuery = query.toLowerCase()
@@ -164,6 +181,7 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
         }
       })
 
+      server.setActiveToolCall(null)
       if (results.length === 0) {
         return {
           content: [{ type: 'text', text: `No documents found matching "${query}". Try get_document_tree to see the full hierarchy.` }],
@@ -231,13 +249,22 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
       label: z.string().describe('New display name.'),
     },
     async ({ id, label }) => {
+      server.setAutoStatus('writing')
+      server.setActiveToolCall({ name: 'rename_document', target: id })
       const treeMap = server.getTreeMap()
-      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+      if (!treeMap) {
+        server.setActiveToolCall(null)
+        return { content: [{ type: 'text', text: 'Not connected' }] }
+      }
 
       const entry = treeMap.get(id)
-      if (!entry) return { content: [{ type: 'text', text: `Document ${id} not found` }] }
+      if (!entry) {
+        server.setActiveToolCall(null)
+        return { content: [{ type: 'text', text: `Document ${id} not found` }] }
+      }
 
       treeMap.set(id, { ...entry, label, updatedAt: Date.now() })
+      server.setActiveToolCall(null)
       return { content: [{ type: 'text', text: `Renamed to "${label}"` }] }
     }
   )
@@ -251,11 +278,19 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
       order: z.number().optional().describe('New sort order. Defaults to Date.now() (append to end).'),
     },
     async ({ id, newParentId, order }) => {
+      server.setAutoStatus('writing')
+      server.setActiveToolCall({ name: 'move_document', target: id })
       const treeMap = server.getTreeMap()
-      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+      if (!treeMap) {
+        server.setActiveToolCall(null)
+        return { content: [{ type: 'text', text: 'Not connected' }] }
+      }
 
       const entry = treeMap.get(id)
-      if (!entry) return { content: [{ type: 'text', text: `Document ${id} not found` }] }
+      if (!entry) {
+        server.setActiveToolCall(null)
+        return { content: [{ type: 'text', text: `Document ${id} not found` }] }
+      }
 
       treeMap.set(id, {
         ...entry,
@@ -263,6 +298,7 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
         order: order ?? Date.now(),
         updatedAt: Date.now(),
       })
+      server.setActiveToolCall(null)
       return { content: [{ type: 'text', text: `Moved ${id} to parent ${newParentId}` }] }
     }
   )
@@ -274,10 +310,15 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
       id: z.string().describe('Document ID to delete.'),
     },
     async ({ id }) => {
+      server.setAutoStatus('writing')
+      server.setActiveToolCall({ name: 'delete_document', target: id })
       const treeMap = server.getTreeMap()
       const trashMap = server.getTrashMap()
       const rootDoc = server.rootDocument
-      if (!treeMap || !trashMap || !rootDoc) return { content: [{ type: 'text', text: 'Not connected' }] }
+      if (!treeMap || !trashMap || !rootDoc) {
+        server.setActiveToolCall(null)
+        return { content: [{ type: 'text', text: 'Not connected' }] }
+      }
 
       const entries = readEntries(treeMap)
       const toDelete = [id, ...descendantsOf(entries, id).map(e => e.id)]
@@ -299,6 +340,7 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
         }
       })
 
+      server.setActiveToolCall(null)
       return { content: [{ type: 'text', text: `Deleted ${toDelete.length} document(s)` }] }
     }
   )
@@ -311,13 +353,22 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
       type: z.string().describe('New page type (e.g. "doc", "kanban", "table", "calendar", "outline", "gallery", "slides", "timeline", "whiteboard", "map", "dashboard", "mindmap", "graph").'),
     },
     async ({ id, type }) => {
+      server.setAutoStatus('writing')
+      server.setActiveToolCall({ name: 'change_document_type', target: id })
       const treeMap = server.getTreeMap()
-      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+      if (!treeMap) {
+        server.setActiveToolCall(null)
+        return { content: [{ type: 'text', text: 'Not connected' }] }
+      }
 
       const entry = treeMap.get(id)
-      if (!entry) return { content: [{ type: 'text', text: `Document ${id} not found` }] }
+      if (!entry) {
+        server.setActiveToolCall(null)
+        return { content: [{ type: 'text', text: `Document ${id} not found` }] }
+      }
 
       treeMap.set(id, { ...entry, type, updatedAt: Date.now() })
+      server.setActiveToolCall(null)
       return { content: [{ type: 'text', text: `Changed type to "${type}"` }] }
     }
   )