@abraca/mcp 1.0.2 → 1.0.10

package/dist/index.d.ts

@@ -8709,10 +8709,10 @@ type RegisteredPrompt = {
 //#region packages/mcp/src/server.d.ts
 interface MCPServerConfig {
   url: string;
-  username: string;
-  password: string;
   agentName?: string;
   agentColor?: string;
+  inviteCode?: string;
+  keyFile?: string;
 }
 declare class AbracadabraMCPServer {
   readonly config: MCPServerConfig;
@@ -8737,7 +8737,7 @@ declare class AbracadabraMCPServer {
   get rootDocument(): Y.Doc | null;
   get rootYProvider(): AbracadabraProvider | null;
   get userId(): string | null;
-  /** Start the server: login, discover spaces/root doc, connect provider. */
+  /** Start the server: authenticate with Ed25519 key, discover spaces/root doc, connect provider. */
   connect(): Promise<void>;
   /** Connect to a space's root doc and cache it. Sets it as the active connection. */
   private _connectToSpace;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/mcp",
-  "version": "1.0.2",
+  "version": "1.0.10",
   "description": "MCP server for Abracadabra — AI agent collaboration on CRDT documents",
   "license": "MIT",
   "type": "module",
@@ -29,6 +29,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@noble/hashes": "^1.8.0",
     "zod": "^3.25.0"
   },
   "peerDependencies": {

package/src/crypto.ts

@@ -0,0 +1,68 @@
+/**
+ * Ed25519 key generation, persistence, and challenge signing for MCP agent auth.
+ */
+import * as ed from '@noble/ed25519'
+import { sha512 } from '@noble/hashes/sha2'
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+
+// @noble/ed25519 v2+ requires explicit hash configuration
+ed.etc.sha512Sync = (...msgs) => sha512(ed.etc.concatBytes(...msgs))
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, dirname } from 'node:path'
+
+const DEFAULT_KEY_PATH = join(homedir(), '.abracadabra', 'agent.key')
+
+function toBase64url(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64url')
+}
+
+function fromBase64url(b64: string): Uint8Array {
+  return new Uint8Array(Buffer.from(b64, 'base64url'))
+}
+
+export interface AgentKeypair {
+  privateKey: Uint8Array
+  publicKeyB64: string
+}
+
+/**
+ * Load an existing Ed25519 keypair from disk, or generate and persist a new one.
+ * The file stores the raw 32-byte private key seed.
+ */
+export async function loadOrCreateKeypair(keyPath?: string): Promise<AgentKeypair> {
+  const path = keyPath || DEFAULT_KEY_PATH
+
+  if (existsSync(path)) {
+    const seed = await readFile(path)
+    if (seed.length !== 32) {
+      throw new Error(`Invalid key file at ${path}: expected 32 bytes, got ${seed.length}`)
+    }
+    const privateKey = new Uint8Array(seed)
+    const publicKey = ed.getPublicKey(privateKey)
+    return { privateKey, publicKeyB64: toBase64url(publicKey) }
+  }
+
+  // Generate new keypair
+  const privateKey = ed.utils.randomPrivateKey()
+  const publicKey = ed.getPublicKey(privateKey)
+
+  // Ensure directory exists and write seed with restricted permissions
+  const dir = dirname(path)
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true, mode: 0o700 })
+  }
+  await writeFile(path, Buffer.from(privateKey), { mode: 0o600 })
+
+  console.error(`[abracadabra-mcp] Generated new agent keypair at ${path}`)
+  console.error(`[abracadabra-mcp] Public key: ${toBase64url(publicKey)}`)
+
+  return { privateKey, publicKeyB64: toBase64url(publicKey) }
+}
+
+/** Sign a base64url challenge with the agent's private key; returns base64url signature. */
+export function signChallenge(challengeB64: string, privateKey: Uint8Array): string {
+  const challenge = fromBase64url(challengeB64)
+  const sig = ed.sign(challenge, privateKey)
+  return toBase64url(sig)
+}

package/src/index.ts

@@ -3,11 +3,11 @@
  * Abracadabra MCP Server — entry point.
  *
  * Environment variables:
- *   ABRA_URL       (required) — Server URL (e.g. http://localhost:1234)
- *   ABRA_USERNAME  (required) — Service account username
- *   ABRA_PASSWORD  (required) — Service account password
- *   ABRA_AGENT_NAME           — Display name (default: "AI Assistant")
- *   ABRA_AGENT_COLOR          — HSL color for presence (default: "hsl(270, 80%, 60%)")
+ *   ABRA_URL         (required) — Server URL (e.g. http://localhost:1234)
+ *   ABRA_AGENT_NAME             — Display name (default: "AI Assistant")
+ *   ABRA_AGENT_COLOR            — HSL color for presence (default: "hsl(270, 80%, 60%)")
+ *   ABRA_INVITE_CODE            — Invite code for first-run registration (grants role)
+ *   ABRA_KEY_FILE               — Path to Ed25519 key file (default: ~/.abracadabra/agent.key)
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
@@ -24,21 +24,19 @@ import { registerServerInfoResource } from './resources/server-info.ts'
 
 async function main() {
   const url = process.env.ABRA_URL
-  const username = process.env.ABRA_USERNAME
-  const password = process.env.ABRA_PASSWORD
 
-  if (!url || !username || !password) {
-    console.error('Missing required environment variables: ABRA_URL, ABRA_USERNAME, ABRA_PASSWORD')
+  if (!url) {
+    console.error('Missing required environment variable: ABRA_URL')
     process.exit(1)
   }
 
   // Create the Abracadabra connection manager
   const server = new AbracadabraMCPServer({
     url,
-    username,
-    password,
     agentName: process.env.ABRA_AGENT_NAME,
     agentColor: process.env.ABRA_AGENT_COLOR,
+    inviteCode: process.env.ABRA_INVITE_CODE,
+    keyFile: process.env.ABRA_KEY_FILE,
   })
 
   // Create MCP server with channel capability
@@ -46,10 +44,39 @@ async function main() {
     { name: 'abracadabra', version: '1.0.0' },
     {
       capabilities: { experimental: { 'claude/channel': {} } },
-      instructions: `Events from the abracadabra channel arrive as <channel source="abracadabra" ...>. They may be:
+      instructions: `Abracadabra is a CRDT collaboration platform where everything is a document in a tree.
+
+## 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
+3. find_document(query) → search for a document by name if you know what you're looking for
+4. read_document / write_document / create_document → operate on specific documents
+
+## 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, outline, etc.) are views over the SAME tree — switching types preserves data.
+- An empty markdown body does NOT mean empty content — always check the children array.
+
+## 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.
+- NEVER conclude a document doesn't exist after only checking root-level documents.
+
+## Rules
+- Always call list_spaces first to get the hub doc ID before creating documents.
+- Always call get_document_tree to understand existing structure before creating documents.
+- Use Lucide icon names in kebab-case (e.g. "star", "code-2") for meta.icon — NEVER emoji.
+- 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) with the appropriate context.`,
+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

@@ -11,13 +11,14 @@ 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'
+import { loadOrCreateKeypair, signChallenge } from './crypto.ts'
 
 export interface MCPServerConfig {
   url: string
-  username: string
-  password: string
   agentName?: string
   agentColor?: string
+  inviteCode?: string
+  keyFile?: string
 }
 
 interface SpaceConnection {
@@ -88,28 +89,39 @@ export class AbracadabraMCPServer {
     return this._userId
   }
 
-  /** Start the server: login, discover spaces/root doc, connect provider. */
+  /** Start the server: authenticate with Ed25519 key, 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 1: Load or generate Ed25519 keypair
+    const keypair = await loadOrCreateKeypair(this.config.keyFile)
+    this._userId = keypair.publicKeyB64
+    const signFn = (challenge: string) => Promise.resolve(signChallenge(challenge, keypair.privateKey))
 
-    // Step 1b: Get user profile for publicKey identity
+    // Step 2: Authenticate via challenge-response (register on first run)
     try {
-      const me = await this.client.getMe()
-      this._userId = me.publicKey ?? me.id
-      console.error(`[abracadabra-mcp] User ID (pubkey): ${this._userId}`)
-    } catch {
-      console.error('[abracadabra-mcp] Could not fetch user profile, proceeding without userId')
+      await this.client.loginWithKey(keypair.publicKeyB64, signFn)
+    } catch (err: any) {
+      // Key not registered — auto-register and retry
+      const status = err?.status ?? err?.response?.status
+      if (status === 404 || status === 422) {
+        console.error('[abracadabra-mcp] Key not registered, creating new account...')
+        await this.client.registerWithKey({
+          publicKey: keypair.publicKeyB64,
+          username: this.agentName.replace(/\s+/g, '-').toLowerCase(),
+          displayName: this.agentName,
+          deviceName: 'MCP Agent',
+          inviteCode: this.config.inviteCode,
+        })
+        await this.client.loginWithKey(keypair.publicKeyB64, signFn)
+      } else {
+        throw err
+      }
     }
+    console.error(`[abracadabra-mcp] Authenticated as ${this.agentName} (${keypair.publicKeyB64.slice(0, 12)}...)`)
 
-    // Step 2: Discover server info
+    // Step 3: Discover server info
     this._serverInfo = await this.client.serverInfo()
 
-    // Step 3: Discover spaces (optional extension)
+    // Step 4: Discover spaces (optional extension)
     let initialDocId: string | null = this._serverInfo.index_doc_id ?? null
     try {
       this._spaces = await this.client.listSpaces()
@@ -132,11 +144,11 @@ export class AbracadabraMCPServer {
     this._rootDocId = initialDocId
     console.error(`[abracadabra-mcp] Active space doc: ${initialDocId}`)
 
-    // Step 4: Connect to initial space
+    // Step 5: Connect to initial space
     await this._connectToSpace(initialDocId)
     console.error('[abracadabra-mcp] Space doc synced')
 
-    // Step 5: Start eviction timer
+    // Step 6: Start eviction timer
     this.evictionTimer = setInterval(() => this.evictIdle(), 60_000)
   }
 

package/src/tools/tree.ts

@@ -7,6 +7,16 @@ import { z } from 'zod'
 import type { AbracadabraMCPServer } from '../server.ts'
 import type { TreeEntry, PageMeta } from '../converters/types.ts'
 
+/**
+ * Normalize a document ID so the hub/root doc ID is treated as the tree root (null).
+ * This lets callers pass the hub doc_id from list_spaces as parentId/rootId
+ * and get the expected root-level results instead of an empty set.
+ */
+function normalizeRootId(id: string | null | undefined, server: AbracadabraMCPServer): string | null {
+  if (id == null) return null
+  return id === server.rootDocId ? null : id
+}
+
 function readEntries(treeMap: Y.Map<any>): TreeEntry[] {
   const entries: TreeEntry[] = []
   treeMap.forEach((value: any, id: string) => {
@@ -32,7 +42,10 @@ function childrenOf(entries: TreeEntry[], parentId: string | null): TreeEntry[]
 
 function descendantsOf(entries: TreeEntry[], id: string | null): TreeEntry[] {
   const result: TreeEntry[] = []
+  const visited = new Set<string>()
   function collect(pid: string) {
+    if (visited.has(pid)) return
+    visited.add(pid)
     for (const child of childrenOf(entries, pid)) {
       result.push(child)
       collect(child.id)
@@ -42,29 +55,33 @@ function descendantsOf(entries: TreeEntry[], id: string | null): TreeEntry[] {
   return result
 }
 
-function buildTree(entries: TreeEntry[], rootId: string | null, maxDepth: number, currentDepth = 0): any[] {
+function buildTree(entries: TreeEntry[], rootId: string | null, maxDepth: number, currentDepth = 0, visited = new Set<string>()): 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),
-  }))
+  return children.filter(e => !visited.has(e.id)).map(entry => {
+    const next = new Set(visited)
+    next.add(entry.id)
+    return {
+      id: entry.id,
+      label: entry.label,
+      type: entry.type,
+      meta: entry.meta,
+      order: entry.order,
+      children: buildTree(entries, entry.id, maxDepth, currentDepth + 1, next),
+    }
+  })
 }
 
 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.',
+    '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 }) => {
       const treeMap = server.getTreeMap()
       if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
 
-      const targetId = parentId ?? null
+      const targetId = normalizeRootId(parentId, server)
       const entries = readEntries(treeMap)
       const children = childrenOf(entries, targetId)
 
@@ -79,7 +96,7 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
 
   mcp.tool(
     'get_document_tree',
-    'Get the full document tree as nested JSON. Useful for understanding the document structure.',
+    'Get the full document tree as nested JSON. Call this FIRST when exploring a space or looking for documents — it shows the complete hierarchy including all nested documents. Use rootId to scope to a subtree.',
     {
       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.'),
@@ -88,7 +105,7 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
       const treeMap = server.getTreeMap()
       if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
 
-      const targetId = rootId ?? null
+      const targetId = normalizeRootId(rootId, server)
       const maxDepth = depth ?? 3
       const entries = readEntries(treeMap)
       const tree = buildTree(entries, targetId, maxDepth)
@@ -102,13 +119,70 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
     }
   )
 
+  mcp.tool(
+    'find_document',
+    'Search for documents by name across the entire tree. Returns matching documents with their full ancestor path. Use this when you\'re looking for a specific document and don\'t know where it is in the hierarchy.',
+    {
+      query: z.string().describe('Search query — matched case-insensitively against document labels (substring match).'),
+      rootId: z.string().optional().describe('Restrict search to descendants of this document. Omit to search the entire tree.'),
+    },
+    async ({ query, rootId }) => {
+      const treeMap = server.getTreeMap()
+      if (!treeMap) return { content: [{ type: 'text', text: 'Not connected' }] }
+
+      const entries = readEntries(treeMap)
+      const lowerQuery = query.toLowerCase()
+
+      // If rootId specified, restrict to descendants only
+      const normalizedRoot = normalizeRootId(rootId, server)
+      const searchSet = normalizedRoot ? descendantsOf(entries, normalizedRoot) : entries
+
+      // Find matches
+      const matches = searchSet.filter(e =>
+        e.label.toLowerCase().includes(lowerQuery)
+      )
+
+      // Build ancestor path for each match
+      const byId = new Map(entries.map(e => [e.id, e]))
+      const results = matches.map(entry => {
+        const path: string[] = []
+        let current = entry.parentId
+        const visited = new Set<string>()
+        while (current && !visited.has(current)) {
+          visited.add(current)
+          const parent = byId.get(current)
+          if (!parent) break
+          path.unshift(parent.label)
+          current = parent.parentId
+        }
+        return {
+          id: entry.id,
+          label: entry.label,
+          type: entry.type,
+          meta: entry.meta,
+          path,
+        }
+      })
+
+      if (results.length === 0) {
+        return {
+          content: [{ type: 'text', text: `No documents found matching "${query}". Try get_document_tree to see the full hierarchy.` }],
+        }
+      }
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(results, 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.'),
+      type: z.string().optional().describe('Page type: "doc", "kanban", "calendar", "table", "outline", "gallery", "slides", "timeline", "whiteboard", "map", "dashboard", "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 }) => {
@@ -117,11 +191,12 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
       if (!treeMap || !rootDoc) return { content: [{ type: 'text', text: 'Not connected' }] }
 
       const id = crypto.randomUUID()
+      const normalizedParent = normalizeRootId(parentId, server)
       const now = Date.now()
       rootDoc.transact(() => {
         treeMap.set(id, {
           label,
-          parentId: parentId ?? null,
+          parentId: normalizedParent,
           order: now,
           type,
           meta: meta as PageMeta,
@@ -175,7 +250,7 @@ export function registerTreeTools(mcp: McpServer, server: AbracadabraMCPServer)
 
       treeMap.set(id, {
         ...entry,
-        parentId: newParentId ?? null,
+        parentId: normalizeRootId(newParentId, server),
         order: order ?? Date.now(),
         updatedAt: Date.now(),
       })
@@ -224,7 +299,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 (e.g. "doc", "kanban", "table", "calendar", "outline", "gallery", "slides", "timeline", "whiteboard", "map", "desktop", "mindmap", "graph").'),
+      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 }) => {
       const treeMap = server.getTreeMap()