@abraca/mcp 1.0.0

package/src/converters/types.ts

@@ -0,0 +1,75 @@
+export interface UserMetaField {
+  id: string
+  type: string
+  label?: string
+  key?: string
+  latKey?: string
+  lngKey?: string
+  startKey?: string
+  endKey?: string
+  allDayKey?: string
+  presets?: string[]
+  options?: string[]
+  min?: number
+  max?: number
+  step?: number
+  unit?: string
+}
+
+export interface PageMeta extends Record<string, unknown> {
+  color?: string
+  icon?: string
+  datetimeStart?: string
+  datetimeEnd?: string
+  allDay?: boolean
+  dateStart?: string
+  dateEnd?: string
+  timeStart?: string
+  timeEnd?: string
+  taskProgress?: number
+  tags?: string[]
+  checked?: boolean
+  priority?: number
+  status?: string
+  rating?: number
+  url?: string
+  email?: string
+  phone?: string
+  number?: number
+  unit?: string
+  subtitle?: string
+  note?: string
+  coverUploadId?: string
+  coverDocId?: string
+  coverMimeType?: string
+  geoType?: 'marker' | 'line' | 'measure'
+  geoLat?: number
+  geoLng?: number
+  geoDescription?: string
+  wbX?: number
+  wbY?: number
+  wbW?: number
+  wbH?: number
+  wbBg?: string
+  deskX?: number
+  deskY?: number
+  deskMode?: string
+  mmX?: number
+  mmY?: number
+  graphX?: number
+  graphY?: number
+  graphPinned?: boolean
+  _metaFields?: UserMetaField[]
+  _metaInitialized?: boolean
+}
+
+export interface TreeEntry {
+  id: string
+  label: string
+  parentId: string | null
+  order: number
+  type?: string
+  meta?: PageMeta
+  createdAt?: number
+  updatedAt?: number
+}

package/src/converters/yjsToMarkdown.ts

@@ -0,0 +1,334 @@
+/**
+ * Y.XmlFragment → Markdown serializer.
+ * Walks the TipTap document structure and produces markdown text.
+ */
+import * as Y from 'yjs'
+
+// ── Inline text serialization ────────────────────────────────────────────────
+
+function deltaToMarkdown(delta: { insert: string; attributes?: Record<string, any> }[]): string {
+  return delta.map(op => {
+    let text = op.insert as string
+    if (!op.attributes) return text
+
+    const a = op.attributes
+
+    if (a.code) text = `\`${text}\``
+    if (a.bold) text = `**${text}**`
+    if (a.italic) text = `*${text}*`
+    if (a.strike) text = `~~${text}~~`
+    if (a.link?.href) text = `[${text}](${a.link.href})`
+    if (a.badge) text = `:badge[${a.badge.label || text}]`
+    if (a.kbd) text = `:kbd{value="${a.kbd.value || text}"}`
+    if (a.proseIcon) text = `:icon{name="${a.proseIcon.name}"}`
+
+    return text
+  }).join('')
+}
+
+function xmlTextToMarkdown(xmlText: Y.XmlText): string {
+  const delta = xmlText.toDelta()
+  return deltaToMarkdown(delta)
+}
+
+function elementTextContent(el: Y.XmlElement | Y.XmlFragment): string {
+  const parts: string[] = []
+  for (let i = 0; i < el.length; i++) {
+    const child = el.get(i)
+    if (child instanceof Y.XmlText) {
+      parts.push(xmlTextToMarkdown(child))
+    } else if (child instanceof Y.XmlElement) {
+      parts.push(elementTextContent(child))
+    }
+  }
+  return parts.join('')
+}
+
+// ── Block serialization ──────────────────────────────────────────────────────
+
+function serializeElement(el: Y.XmlElement, indent = ''): string {
+  const name = el.nodeName
+
+  switch (name) {
+    case 'documentHeader':
+    case 'documentMeta':
+      return ''
+
+    case 'heading': {
+      const level = Number(el.getAttribute('level')) || 1
+      const prefix = '#'.repeat(level)
+      return `${prefix} ${elementTextContent(el)}`
+    }
+
+    case 'paragraph':
+      return elementTextContent(el)
+
+    case 'bulletList':
+      return serializeList(el, 'bullet', indent)
+
+    case 'orderedList':
+      return serializeList(el, 'ordered', indent)
+
+    case 'taskList':
+      return serializeTaskList(el, indent)
+
+    case 'codeBlock': {
+      const lang = el.getAttribute('language') || ''
+      const code = elementTextContent(el)
+      return `\`\`\`${lang}\n${code}\n\`\`\``
+    }
+
+    case 'blockquote': {
+      const lines: string[] = []
+      for (let i = 0; i < el.length; i++) {
+        const child = el.get(i)
+        if (child instanceof Y.XmlElement) {
+          lines.push(serializeElement(child, indent))
+        }
+      }
+      return lines.map(l => `> ${l}`).join('\n')
+    }
+
+    case 'horizontalRule':
+      return '---'
+
+    case 'table':
+      return serializeTable(el)
+
+    case 'image': {
+      const src = el.getAttribute('src') || ''
+      const alt = el.getAttribute('alt') || ''
+      const w = el.getAttribute('width')
+      const h = el.getAttribute('height')
+      let attrs = ''
+      if (w || h) {
+        const parts: string[] = []
+        if (w) parts.push(`width="${w}"`)
+        if (h) parts.push(`height="${h}"`)
+        attrs = `{${parts.join(' ')}}`
+      }
+      return `![${alt}](${src})${attrs}`
+    }
+
+    case 'callout': {
+      const type = el.getAttribute('type') || 'note'
+      const inner = serializeChildren(el, indent)
+      return `::${type}\n${inner}\n::`
+    }
+
+    case 'collapsible': {
+      const label = el.getAttribute('label') || 'Details'
+      const open = el.getAttribute('open')
+      const props: string[] = [`label="${label}"`]
+      if (open === true || open === 'true') props.push('open="true"')
+      const inner = serializeChildren(el, indent)
+      return `::collapsible{${props.join(' ')}}\n${inner}\n::`
+    }
+
+    case 'steps': {
+      const inner = serializeChildren(el, indent)
+      return `::steps\n${inner}\n::`
+    }
+
+    case 'card': {
+      const title = el.getAttribute('title') || ''
+      const icon = el.getAttribute('icon') || ''
+      const to = el.getAttribute('to') || ''
+      const props: string[] = []
+      if (title) props.push(`title="${title}"`)
+      if (icon) props.push(`icon="${icon}"`)
+      if (to) props.push(`to="${to}"`)
+      const inner = serializeChildren(el, indent)
+      return `::card{${props.join(' ')}}\n${inner}\n::`
+    }
+
+    case 'cardGroup': {
+      const inner = serializeChildren(el, indent)
+      return `::card-group\n${inner}\n::`
+    }
+
+    case 'codeCollapse': {
+      const inner = serializeChildren(el, indent)
+      return `::code-collapse\n${inner}\n::`
+    }
+
+    case 'codeGroup': {
+      const inner = serializeChildren(el, indent)
+      return `::code-group\n${inner}\n::`
+    }
+
+    case 'codePreview': {
+      const inner = serializeChildren(el, indent)
+      return `::code-preview\n${inner}\n::`
+    }
+
+    case 'codeTree': {
+      const files = el.getAttribute('files') || '[]'
+      return `::code-tree{files="${files}"}\n::`
+    }
+
+    case 'accordion':
+      return serializeSlottedComponent(el, 'accordion', 'accordionItem', 'item')
+
+    case 'tabs':
+      return serializeSlottedComponent(el, 'tabs', 'tabsItem', 'tab')
+
+    case 'field': {
+      const fieldName = el.getAttribute('name') || ''
+      const fieldType = el.getAttribute('type') || 'string'
+      const required = el.getAttribute('required')
+      const props: string[] = []
+      if (fieldName) props.push(`name="${fieldName}"`)
+      props.push(`type="${fieldType}"`)
+      if (required === true || required === 'true') props.push('required="true"')
+      const inner = serializeChildren(el, indent)
+      return `::field{${props.join(' ')}}\n${inner}\n::`
+    }
+
+    case 'fieldGroup': {
+      const inner = serializeChildren(el, indent)
+      return `::field-group\n${inner}\n::`
+    }
+
+    default: {
+      // Unknown node — try to serialize children
+      return serializeChildren(el, indent)
+    }
+  }
+}
+
+function serializeList(el: Y.XmlElement, type: 'bullet' | 'ordered', indent: string): string {
+  const lines: string[] = []
+  for (let i = 0; i < el.length; i++) {
+    const item = el.get(i)
+    if (item instanceof Y.XmlElement && item.nodeName === 'listItem') {
+      const prefix = type === 'bullet' ? '- ' : `${i + 1}. `
+      const content = elementTextContent(item)
+      lines.push(`${indent}${prefix}${content}`)
+    }
+  }
+  return lines.join('\n')
+}
+
+function serializeTaskList(el: Y.XmlElement, indent: string): string {
+  const lines: string[] = []
+  for (let i = 0; i < el.length; i++) {
+    const item = el.get(i)
+    if (item instanceof Y.XmlElement && item.nodeName === 'taskItem') {
+      const checked = item.getAttribute('checked')
+      const marker = (checked === true || checked === 'true') ? '[x]' : '[ ]'
+      const content = elementTextContent(item)
+      lines.push(`${indent}- ${marker} ${content}`)
+    }
+  }
+  return lines.join('\n')
+}
+
+function serializeTable(el: Y.XmlElement): string {
+  const rows: string[][] = []
+  let isHeader = true
+
+  for (let i = 0; i < el.length; i++) {
+    const row = el.get(i)
+    if (!(row instanceof Y.XmlElement) || row.nodeName !== 'tableRow') continue
+
+    const cells: string[] = []
+    for (let j = 0; j < row.length; j++) {
+      const cell = row.get(j)
+      if (cell instanceof Y.XmlElement) {
+        cells.push(elementTextContent(cell))
+      }
+    }
+    rows.push(cells)
+  }
+
+  if (!rows.length) return ''
+
+  const headerRow = rows[0]!
+  const lines = [`| ${headerRow.join(' | ')} |`]
+
+  // Separator
+  lines.push(`| ${headerRow.map(() => '---').join(' | ')} |`)
+
+  // Data rows
+  for (let i = 1; i < rows.length; i++) {
+    lines.push(`| ${rows[i]!.join(' | ')} |`)
+  }
+
+  return lines.join('\n')
+}
+
+function serializeSlottedComponent(
+  el: Y.XmlElement,
+  componentName: string,
+  childNodeName: string,
+  slotName: string
+): string {
+  const parts: string[] = [`::${componentName}`]
+
+  for (let i = 0; i < el.length; i++) {
+    const child = el.get(i)
+    if (!(child instanceof Y.XmlElement) || child.nodeName !== childNodeName) continue
+
+    const label = child.getAttribute('label') || `Item ${i + 1}`
+    const icon = child.getAttribute('icon') || ''
+    const props: string[] = [`label="${label}"`]
+    if (icon) props.push(`icon="${icon}"`)
+    parts.push(`#${slotName}{${props.join(' ')}}`)
+
+    const inner = serializeChildren(child, '')
+    if (inner) parts.push(inner)
+  }
+
+  parts.push('::')
+  return parts.join('\n')
+}
+
+function serializeChildren(el: Y.XmlElement | Y.XmlFragment, indent: string): string {
+  const parts: string[] = []
+  for (let i = 0; i < el.length; i++) {
+    const child = el.get(i)
+    if (child instanceof Y.XmlElement) {
+      const serialized = serializeElement(child, indent)
+      if (serialized) parts.push(serialized)
+    } else if (child instanceof Y.XmlText) {
+      const text = xmlTextToMarkdown(child)
+      if (text) parts.push(text)
+    }
+  }
+  return parts.join('\n\n')
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Converts a Y.XmlFragment (TipTap document) to markdown.
+ * Extracts the title from the documentHeader element.
+ *
+ * @returns `{ title, markdown }` where title is the H1/header text
+ */
+export function yjsToMarkdown(fragment: Y.XmlFragment): { title: string; markdown: string } {
+  let title = 'Untitled'
+  const bodyParts: string[] = []
+
+  for (let i = 0; i < fragment.length; i++) {
+    const child = fragment.get(i)
+    if (!(child instanceof Y.XmlElement)) continue
+
+    if (child.nodeName === 'documentHeader') {
+      title = elementTextContent(child) || 'Untitled'
+      continue
+    }
+
+    if (child.nodeName === 'documentMeta') {
+      continue
+    }
+
+    const serialized = serializeElement(child)
+    if (serialized !== '') {
+      bodyParts.push(serialized)
+    }
+  }
+
+  return { title, markdown: bodyParts.join('\n\n') }
+}

package/src/index.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * 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%)")
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { AbracadabraMCPServer } from './server.ts'
+import { registerTreeTools } from './tools/tree.ts'
+import { registerContentTools } from './tools/content.ts'
+import { registerMetaTools } from './tools/meta.ts'
+import { registerFileTools } from './tools/files.ts'
+import { registerAwarenessTools } from './tools/awareness.ts'
+import { registerChannelTools } from './tools/channel.ts'
+import { registerAgentGuide } from './resources/agent-guide.ts'
+import { registerTreeResource } from './resources/tree-resource.ts'
+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')
+    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,
+  })
+
+  // Create MCP server with channel capability
+  const mcp = new McpServer(
+    { name: 'abracadabra', version: '1.0.0' },
+    {
+      capabilities: { experimental: { 'claude/channel': {} } },
+      instructions: `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.`,
+    },
+  )
+
+  // Register tools
+  registerTreeTools(mcp, server)
+  registerContentTools(mcp, server)
+  registerMetaTools(mcp, server)
+  registerFileTools(mcp, server)
+  registerAwarenessTools(mcp, server)
+  registerChannelTools(mcp, server)
+
+  // Register resources
+  registerAgentGuide(mcp)
+  registerTreeResource(mcp, server)
+  registerServerInfoResource(mcp, server)
+
+  // Connect to Abracadabra server
+  try {
+    await server.connect()
+  } catch (error: any) {
+    console.error(`[abracadabra-mcp] Failed to connect: ${error.message}`)
+    process.exit(1)
+  }
+
+  // Start MCP stdio transport
+  const transport = new StdioServerTransport()
+  await mcp.connect(transport)
+
+  // Wire up real-time channel notifications (awareness → channel dispatch)
+  server.startChannelNotifications(mcp)
+  console.error('[abracadabra-mcp] MCP server running on stdio')
+
+  // Graceful shutdown
+  const shutdown = async () => {
+    console.error('[abracadabra-mcp] Shutting down...')
+    await server.destroy()
+    process.exit(0)
+  }
+
+  process.on('SIGINT', shutdown)
+  process.on('SIGTERM', shutdown)
+}
+
+main().catch((error) => {
+  console.error('[abracadabra-mcp] Fatal error:', error)
+  process.exit(1)
+})
+
+// Re-export for library usage
+export { AbracadabraMCPServer } from './server.ts'
+export type { MCPServerConfig } from './server.ts'