@abraca/mcp 1.0.0

package/src/resources/agent-guide.ts

@@ -0,0 +1,324 @@
+/**
+ * Static resource: AI agent guide for working with Abracadabra documents.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+
+const AGENT_GUIDE = `# Abracadabra AI Agent Guide
+
+## Core Principle: "Everything is a Document"
+
+Every piece of visible data in Abracadabra — a calendar event, a kanban card, a table cell, a map marker — is a **document** in the tree. The document's **label** (name) IS the displayed value. Always.
+
+- A column's name IS the column header
+- A card's name IS the card title
+- A cell's name IS the cell content
+- An event's name IS the event title
+
+**Page types are views over the same document hierarchy**, not isolated data stores. Switching a page from Kanban to Table to Outline works without migration — the tree doesn't change, only the rendering.
+
+---
+
+## Getting Oriented in a Space
+
+Before creating any documents, always call \`list_spaces\` to understand the current workspace. Each space has a \`doc_id\` — this is the **hub document** (the space root). All user-created documents must be direct or indirect children of this hub doc.
+
+\`\`\`
+list_spaces → pick the active space → note its doc_id (= hub doc ID)
+create_document(parentId: hubDocId, ...)   ← top-level pages go here
+\`\`\`
+
+The hub doc itself is a system document — do not rename, move, or write content to it. It is just a container.
+
+If you are adding content to an existing space, call \`get_document_tree(rootId: hubDocId)\` first to understand what already exists before creating anything.
+
+---
+
+## Page Types Reference
+
+| Type | Children Are | Grandchildren Are | Depth Limit |
+|------|-------------|-------------------|-------------|
+| **doc** | Sub-documents | Sub-sub-documents | Unlimited |
+| **kanban** | Columns | Cards | 2 |
+| **table** | Columns | Cells (positional rows) | 2 |
+| **calendar** | Events | — | 1 |
+| **timeline** | Epics | Tasks | 2 |
+| **outline** | Items | Sub-items | Unlimited |
+| **mindmap** | Central nodes | Branches | Unlimited |
+| **graph** | Nodes | — | 1 |
+| **gallery** | Items | — | 1 |
+| **slides** | Slides | — | 1 |
+| **whiteboard** | Objects | — | 1 |
+| **map** | Markers/Lines | Points (for lines) | 2 |
+| **desktop** | Items | — | 1 |
+| **call** | — | — | 0 |
+| **game** | — | — | 0 |
+
+---
+
+## Document Tree Operations
+
+### Creating Well-Structured Hierarchies
+
+**Kanban board:**
+1. Create the kanban document: \`create_document(parentId, "Project Board", "kanban")\`
+2. Create columns: \`create_document(boardId, "To Do")\`, \`create_document(boardId, "In Progress")\`, \`create_document(boardId, "Done")\`
+3. Create cards under columns: \`create_document(toDoColumnId, "Fix bug #123")\`
+
+**Calendar with events:**
+1. Create calendar: \`create_document(parentId, "Team Calendar", "calendar")\`
+2. Create events: \`create_document(calendarId, "Sprint Planning")\`
+3. Set event times: \`update_metadata(eventId, { datetimeStart: "2026-03-20T10:00:00Z", datetimeEnd: "2026-03-20T11:00:00Z" })\`
+
+**Timeline with tasks:**
+1. Create timeline: \`create_document(parentId, "Q1 Roadmap", "timeline")\`
+2. Create epics: \`create_document(timelineId, "Auth Rewrite")\`
+3. Create tasks: \`create_document(epicId, "Implement JWT refresh")\`
+4. Set dates/progress: \`update_metadata(taskId, { dateStart: "2026-03-01", dateEnd: "2026-03-15", taskProgress: 50 })\`
+
+**Table with data:**
+1. Create table: \`create_document(parentId, "Contacts", "table")\`
+2. Create columns: \`create_document(tableId, "Name")\`, \`create_document(tableId, "Email")\`, \`create_document(tableId, "Phone")\`
+3. Create cells (children of columns): \`create_document(nameColId, "Alice")\`, \`create_document(emailColId, "alice@example.com")\`
+4. Rows are positional — the Nth child of each column forms row N
+
+---
+
+## Metadata Reference
+
+### Universal Keys (use these — never invent prefixed variants)
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| \`color\` | string | Hex/CSS color (e.g. "#6366f1") |
+| \`icon\` | string | Lucide icon name in kebab-case (e.g. "star", "code-2", "users", "calendar-days", "book-open"). **Never emoji.** Omit to use the page type's default icon. |
+| \`datetimeStart\` / \`datetimeEnd\` | string | ISO datetime with time |
+| \`allDay\` | boolean | Whether datetime is all-day |
+| \`dateStart\` / \`dateEnd\` | string | ISO date-only (e.g. "2026-03-20") |
+| \`timeStart\` / \`timeEnd\` | string | HH:MM time |
+| \`tags\` | string[] | Tag labels |
+| \`checked\` | boolean | Done/checked state |
+| \`priority\` | number | 0=none, 1=low, 2=medium, 3=high, 4=urgent |
+| \`status\` | string | Status string |
+| \`rating\` | number | 0–5 stars |
+| \`url\` | string | URL |
+| \`email\` | string | Email address |
+| \`phone\` | string | Phone number |
+| \`number\` | number | Generic numeric value |
+| \`unit\` | string | Unit label for \`number\` |
+| \`subtitle\` | string | Secondary text |
+| \`note\` | string | Free-text note |
+| \`taskProgress\` | number | 0–100 progress (timeline tasks) |
+
+### Type-Specific Meta Schemas
+
+**Calendar events** require: \`datetimeStart\`, \`datetimeEnd\`, optionally \`allDay\`, \`color\`
+
+**Timeline tasks** require: \`dateStart\`, \`dateEnd\`, optionally \`taskProgress\` (0–100), \`color\`
+
+**Map markers** require: \`geoLat\`, \`geoLng\`, \`geoType\` ("marker"|"line"|"measure"), optionally \`icon\`, \`color\`
+
+---
+
+## Content Structure
+
+Documents use a TipTap editor schema with these top-level elements:
+- **documentHeader** — The document title (H1)
+- **documentMeta** — Metadata display block (skip when reading/writing)
+- **Body blocks** — paragraphs, headings (H2-H6), lists, code blocks, tables, images, and custom components
+
+### Supported Markdown Elements
+- Headings (# through ######)
+- Paragraphs with **bold**, *italic*, ~~strikethrough~~, \`code\`, [links](url)
+- Bullet lists, ordered lists, task lists
+- Code blocks with language
+- Blockquotes
+- Tables (pipe syntax)
+- Horizontal rules
+- Images
+- MDC components: callout, collapsible, steps, card, accordion, tabs, code-group, etc.
+
+### Writing Content with Frontmatter
+
+You can set document title and metadata via YAML frontmatter:
+
+\`\`\`markdown
+---
+title: My Document
+tags: [important, review]
+color: "#6366f1"
+priority: high
+---
+
+Content goes here...
+\`\`\`
+
+---
+
+## Awareness / Presence
+
+When you connect, you appear in the awareness system alongside human users. Presence runs at two levels:
+- **Root awareness**: your name, color, and which document you're currently viewing (\`docId\`)
+- **Child doc awareness**: per-document presence including TipTap cursor position and renderer-specific state
+
+### What happens automatically
+
+You do **not** need to call \`set_presence\` after reading or writing content — it's done for you:
+
+| Action | Automatic effect |
+|---|---|
+| \`read_document\` | Root \`docId\` updated; TipTap cursor placed at start of document |
+| \`write_document\` | Root \`docId\` updated; TipTap cursor placed at end of written content |
+
+The TipTap cursor (\`anchor\`/\`head\` as \`Y.RelativePosition\`) makes your colored caret with name label appear inline in the document editor for human collaborators.
+
+### set_presence — manual overrides only
+
+Use \`set_presence\` when you want to:
+- Override \`status\` to communicate intent ("thinking", "reviewing", "writing")
+- Explicitly update \`docId\` when browsing the document tree without reading content
+
+### set_doc_awareness — renderer-specific item presence
+
+For structured renderers (kanban, table, calendar, etc.), use \`set_doc_awareness(docId, fields)\` to broadcast which item you are interacting with. This is visible as highlighted cards, cells, events, etc. in the dashboard.
+
+Always clear fields when done by setting them to \`null\`.
+
+| Renderer | Key | Value | When to set |
+|---|---|---|---|
+| **Kanban** | \`kanban:hovering\` | cardId | Inspecting or about to edit a card |
+| **Kanban** | \`kanban:dragging\` | \`{ cardId, toColumnId }\` | Moving a card between columns |
+| **Table** | \`table:editing\` | \`{ rowIdx, fieldId }\` | Editing a cell |
+| **Calendar** | \`calendar:focused\` | eventId | Interacting with an event |
+| **Calendar** | \`calendar:viewing\` | "YYYY-MM" | The month/week you're looking at |
+| **Outline** | \`outline:editing\` | nodeId | Editing an outline node |
+| **Outline** | \`outline:selected\` | nodeId | Node selected/hovered |
+| **Slides** | \`slides:viewing\` | slideId | The slide you're currently on |
+| **Gallery** | \`gallery:focused\` | itemId | Item hovered/selected |
+| **Timeline** | \`timeline:focused\` | taskId | Task selected |
+| **Mindmap** | \`mindmap:focused\` | nodeId | Node selected/edited |
+| **Graph** | \`graph:focused\` | nodeId | Node hovered/selected |
+| **Map** | \`map:focused\` | markerId | Marker hovered/selected |
+| **Doc** | \`doc:scroll\` | 0–1 number | Scroll position in document |
+
+Example — mark a kanban card as being inspected, then clear on completion:
+\`\`\`
+set_doc_awareness(boardDocId, { "kanban:hovering": cardId })
+// ... do work ...
+set_doc_awareness(boardDocId, { "kanban:hovering": null })
+\`\`\`
+
+---
+
+## Receiving Instructions from Humans
+
+Three ways humans can send you tasks:
+
+**Channel events (preferred):** When running in channel mode, \`ai:task\` events from
+human users arrive as \`<channel source="abracadabra" ...>\` notifications directly in
+your session. These include the sender name, task ID, and document context. Use the
+\`reply\` tool to send your response back — it creates a reply document and signals
+task completion.
+
+**Chat document watching:** Use \`watch_chat\` to observe a document for new messages.
+Changes are pushed as channel notifications in real time. Reply using the \`reply\` tool
+with the chat document's ID.
+
+**Polling (fallback):** Call \`poll_inbox\` to read the "AI Inbox" document.
+Act on any pending tasks you find there. Write your response back with \`write_document\`
+or \`create_document\` under the inbox.
+
+### Channel Tools
+
+| Tool | Purpose |
+|------|---------|
+| \`reply\` | Send a reply to Abracadabra — creates a child doc with your response. Pass \`task_id\` to signal ai:task completion. |
+| \`watch_chat\` | Start/stop watching a document for chat messages. New content arrives as channel notifications. |
+
+When you complete a task, always use \`reply\` (in channel mode) or write a response
+document (in polling mode) so the human knows the work is done.
+
+---
+
+## Common Patterns
+
+### Populate a kanban board from a list
+\`\`\`
+1. create_document → kanban parent
+2. For each column: create_document under kanban
+3. For each card: create_document under the appropriate column
+4. Optionally set metadata (color, tags, priority) on cards
+\`\`\`
+
+### Explore a document fully (the correct way)
+\`\`\`
+User: "Check out the Marketing doc"
+
+1. read_document(marketingId)
+   → returns { markdown, children: [...] }
+2. The body may be empty — that does NOT mean the doc is empty.
+   Children ARE the content. Read every child:
+   read_document(childId1), read_document(childId2), ...
+3. Each child's response also includes ITS children.
+   Continue recursively until no children remain.
+\`\`\`
+
+**Never conclude a document is "empty" just because its markdown body is empty.
+Always check and traverse the \`children\` array returned by \`read_document\`.**
+
+### Write rich content to a document
+\`\`\`
+1. read_document to see current content (and children)
+2. write_document with markdown (mode: "replace" to overwrite, "append" to add)
+3. Include frontmatter for title/metadata if needed
+\`\`\`
+
+### Organize documents into a hierarchy
+\`\`\`
+1. get_document_tree to understand current structure
+2. create_document to add new nodes
+3. move_document to reorganize
+4. change_document_type to switch views
+\`\`\`
+
+---
+
+## Rules
+
+### MUST:
+- Call \`list_spaces\` first to find the hub doc ID before creating any documents
+- Use document \`label\` as the display value — renaming a document renames it everywhere
+- Create child documents for every visible item (columns, cards, events, etc.)
+- Use universal meta keys (color, icon, dateStart) — never prefix with page type
+- Set meaningful labels on every document you create
+- Use \`get_document_tree\` to understand existing structure before adding to a space
+- Traverse the full \`children\` tree when asked to "check out", "explore", or "summarize" a document
+
+### MUST NOT:
+- Conclude a document is empty because its markdown body is empty — check children first
+- Stop at the top-level doc when exploring — children and grandchildren are part of the content
+- Store display values in metadata — the label IS the display value
+- Use special metadata to distinguish document roles — the hierarchy does that
+- Create documents just for metadata — metadata lives ON documents
+- Break interchangeability — switching page types must not lose data
+- Use emoji as \`icon\` values — only lowercase kebab-case Lucide icon names are valid
+- Create top-level documents without first confirming the correct hub doc ID
+- Rename or write content to the space hub document itself
+`
+
+export function registerAgentGuide(mcp: McpServer) {
+  mcp.resource(
+    'agent-guide',
+    'abracadabra://agent-guide',
+    {
+      description: 'Comprehensive guide for AI agents working with Abracadabra documents. Covers page types, tree operations, metadata, content structure, and best practices.',
+      mimeType: 'text/markdown',
+    },
+    async () => ({
+      contents: [{
+        uri: 'abracadabra://agent-guide',
+        text: AGENT_GUIDE,
+        mimeType: 'text/markdown',
+      }],
+    })
+  )
+}

package/src/resources/server-info.ts

@@ -0,0 +1,47 @@
+/**
+ * Dynamic resource: server health + info.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { AbracadabraMCPServer } from '../server.ts'
+
+export function registerServerInfoResource(mcp: McpServer, server: AbracadabraMCPServer) {
+  mcp.resource(
+    'server-info',
+    'abracadabra://server-info',
+    {
+      description: 'Abracadabra server info: name, version, root document ID, and health status.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      let health = null
+      try {
+        health = await server.client.health()
+      } catch {
+        // health endpoint unavailable
+      }
+
+      const spaces = server.spaces
+      const activeSpace = spaces.find(s => s.doc_id === server.rootDocId) ?? null
+
+      const info = {
+        serverInfo: server.serverInfo,
+        activeSpaceDocId: server.rootDocId,
+        activeSpace,
+        spaces: spaces.length > 0 ? spaces : undefined,
+        health,
+        agent: {
+          name: server.agentName,
+          color: server.agentColor,
+        },
+      }
+
+      return {
+        contents: [{
+          uri: 'abracadabra://server-info',
+          text: JSON.stringify(info, null, 2),
+          mimeType: 'application/json',
+        }],
+      }
+    }
+  )
+}

package/src/resources/tree-resource.ts

@@ -0,0 +1,71 @@
+/**
+ * Dynamic resource: document tree as navigable JSON.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { AbracadabraMCPServer } from '../server.ts'
+import type { TreeEntry } from '../converters/types.ts'
+
+function readEntries(treeMap: 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,
+    })
+  })
+  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 buildTree(entries: TreeEntry[], rootId: string | null, maxDepth: number, depth = 0): any[] {
+  if (maxDepth >= 0 && depth >= maxDepth) return []
+  return childrenOf(entries, rootId).map(e => ({
+    id: e.id,
+    label: e.label,
+    type: e.type,
+    children: buildTree(entries, e.id, maxDepth, depth + 1),
+  }))
+}
+
+export function registerTreeResource(mcp: McpServer, server: AbracadabraMCPServer) {
+  mcp.resource(
+    'tree',
+    'abracadabra://tree',
+    {
+      description: 'Full document tree as nested JSON. Shows the complete hierarchy of all documents.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const treeMap = server.getTreeMap()
+      if (!treeMap) {
+        return {
+          contents: [{
+            uri: 'abracadabra://tree',
+            text: '{"error": "Not connected"}',
+            mimeType: 'application/json',
+          }],
+        }
+      }
+
+      const entries = readEntries(treeMap)
+      const tree = buildTree(entries, null, 10)
+
+      return {
+        contents: [{
+          uri: 'abracadabra://tree',
+          text: JSON.stringify(tree, null, 2),
+          mimeType: 'application/json',
+        }],
+      }
+    }
+  )
+}