@abraca/mcp 1.9.1 → 2.3.0

package/src/converters/page-types.ts

@@ -111,6 +111,16 @@ export const PAGE_TYPES: Record<string, PageTypeInfo> = {
     core: true,
     supportsChildren: true,
   },
+  prose: {
+    key: 'prose',
+    label: 'Prose',
+    icon: 'pen-tool',
+    description: 'Long-form prose with serif typography and a narrow readable measure',
+    core: true,
+    supportsChildren: true,
+    childLabel: 'Item',
+    defaultDepth: -1,
+  },
   kanban: {
     key: 'kanban',
     label: 'Kanban',

package/src/converters/yjsToMarkdown.ts

@@ -1,355 +1,12 @@
-/**
- * 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) {
-      // Inline nodes that carry meaning at the inline level.
-      if (child.nodeName === 'docLink') {
-        const docId = child.getAttribute('docId')
-        if (docId) parts.push(`[[${docId}]]`)
-        continue
-      }
-      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 'docEmbed': {
-      const docId = el.getAttribute('docId')
-      if (!docId) return ''
-      const seamlessAttr = el.getAttribute('seamless')
-      const seamless = seamlessAttr === true || seamlessAttr === 'true'
-      return seamless ? `![[${docId}]]{seamless}` : `![[${docId}]]`
-    }
-
-    case 'svgEmbed': {
-      const svg = el.getAttribute('svg') || ''
-      const svgTitle = el.getAttribute('title') || ''
-      if (!svg) return ''
-      return `\`\`\`svg${svgTitle ? ` ${svgTitle}` : ''}\n${svg}\n\`\`\``
-    }
-
-    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') }
-}
+// Thin re-export shim — Yjs → markdown conversion now lives in
+// @abraca/convert (extracted from cou-sh + abracadabra-nuxt + this
+// package). Existing imports inside the MCP server keep working
+// through this re-export.
+//
+// New code should import from @abraca/convert directly.
+
+export {
+  yjsToMarkdown,
+  yjsToHtml,
+  yjsToPlainText,
+} from '@abraca/convert'

package/src/crypto.ts

@@ -2,11 +2,12 @@
  * Ed25519 key generation, persistence, and challenge signing for MCP agent auth.
  */
 import * as ed from '@noble/ed25519'
-import { sha512 } from '@noble/hashes/sha2'
+import { sha512 } from '@noble/hashes/sha2.js'
 import { readFile, writeFile, mkdir } from 'node:fs/promises'
 
-// @noble/ed25519 v2+ requires explicit hash configuration
-ed.etc.sha512Sync = (...msgs) => sha512(ed.etc.concatBytes(...msgs))
+// @noble/ed25519 v3 hash hook
+ed.hashes.sha512 = sha512
+ed.hashes.sha512Async = (m: Uint8Array) => Promise.resolve(sha512(m))
 import { existsSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, dirname } from 'node:path'
@@ -44,7 +45,7 @@ export async function loadOrCreateKeypair(keyPath?: string): Promise<AgentKeypai
   }
 
   // Generate new keypair
-  const privateKey = ed.utils.randomPrivateKey()
+  const privateKey = ed.utils.randomSecretKey()
   const publicKey = ed.getPublicKey(privateKey)
 
   // Ensure directory exists and write seed with restricted permissions

package/src/index.ts

@@ -16,6 +16,13 @@
  *                                 DMs always trigger regardless of mode.
  *   ABRA_AGENT_MENTION_ALIASES  — Comma-separated aliases for @mentions
  *                                 (default: [ABRA_AGENT_NAME])
+ *   ABRA_MCP_SCHEMA_BUNDLE      — (optional) Path to a JSON Schema bundle
+ *                                 emitted by `@abraca/schema`. When set,
+ *                                 update_metadata + create_document
+ *                                 reject `meta` payloads that fail
+ *                                 validation against the resolved doc-type's
+ *                                 schema before forwarding to the server.
+ *                                 When unset, behaviour is unchanged.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
@@ -32,6 +39,8 @@ import { registerTreeResource } from './resources/tree-resource.ts'
 import { registerServerInfoResource } from './resources/server-info.ts'
 import { registerHookTools } from './tools/hooks.ts'
 import { HookBridge } from './hook-bridge.ts'
+import { loadSchemaBundle, SchemaBundleLoadError } from './schema/loader.ts'
+import type { SchemaBundleValidator } from './schema/validator.ts'
 
 async function main() {
   const url = process.env.ABRA_URL
@@ -69,6 +78,24 @@ async function main() {
 
   console.error(`[abracadabra-mcp] Trigger mode: ${triggerMode}; aliases: ${server.mentionAliases.join(', ')}`)
 
+  // Optional schema bundle. When set, update_metadata + create_document validate
+  // `meta` against the resolved doc-type's schema before forwarding. When unset,
+  // behaviour is identical to today (Rules 2 + 4 in feedback_schema_free_core.md).
+  let schemaValidator: SchemaBundleValidator | null = null
+  const schemaBundlePath = process.env.ABRA_MCP_SCHEMA_BUNDLE
+  if (schemaBundlePath && schemaBundlePath.trim().length > 0) {
+    try {
+      schemaValidator = loadSchemaBundle(schemaBundlePath)
+      console.error(
+        `[abracadabra-mcp] Loaded schema bundle from ${schemaBundlePath}; known doc-types: ${schemaValidator.knownTypes.join(', ')}`,
+      )
+    } catch (err) {
+      const msg = err instanceof SchemaBundleLoadError ? err.message : String(err)
+      console.error(`[abracadabra-mcp] ${msg}`)
+      process.exit(1)
+    }
+  }
+
   // Create MCP server with channel capability
   const mcp = new McpServer(
     { name: 'abracadabra', version: '1.0.0' },
@@ -113,9 +140,9 @@ Read the resource at abracadabra://agent-guide for the complete guide covering p
   )
 
   // Register tools
-  registerTreeTools(mcp, server)
+  registerTreeTools(mcp, server, schemaValidator)
   registerContentTools(mcp, server)
-  registerMetaTools(mcp, server)
+  registerMetaTools(mcp, server, schemaValidator)
   registerFileTools(mcp, server)
   registerAwarenessTools(mcp, server)
   registerChannelTools(mcp, server)

package/src/resources/server-info.ts

@@ -21,7 +21,7 @@ export function registerServerInfoResource(mcp: McpServer, server: AbracadabraMC
       }
 
       const spaces = server.spaces
-      const activeSpace = spaces.find(s => s.doc_id === server.rootDocId) ?? null
+      const activeSpace = spaces.find(s => s.id === server.rootDocId) ?? null
 
       const info = {
         serverInfo: server.serverInfo,

package/src/schema/loader.ts

@@ -0,0 +1,139 @@
+/**
+ * Schema bundle loader for the MCP runtime hook.
+ *
+ * Reads a JSON Schema bundle produced by `@abraca/schema` codegen, compiles
+ * one Ajv validator per declared doc-type, and returns a
+ * {@link SchemaBundleValidator} that the MCP tool handlers consult before
+ * forwarding `meta` writes to the server.
+ *
+ * Bundle format (see abracadabra-ts/packages/schema/scripts/codegen-json-schema.ts):
+ *
+ * ```jsonc
+ * { "schemaVersion": 1,
+ *   "label": "...",
+ *   "types": {
+ *     "<doc-type>": {
+ *       "version": 1,
+ *       "meta":     { ...JSON Schema 2020-12... },
+ *       "body":     "ytext" | "yarray" | "ymap" | "none",
+ *       "children": ["..."]
+ *     } } }
+ * ```
+ *
+ * Loader errors at boot are *fatal* — caller is expected to abort startup
+ * with a clear message. We do not silently fall back to "no validation".
+ */
+
+import { readFileSync } from 'node:fs'
+import Ajv2020 from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import type { ValidateFunction } from 'ajv/dist/2020.js'
+import type {
+	MetaValidationIssue,
+	MetaValidationResult,
+	SchemaBundleValidator,
+} from './validator.ts'
+
+interface BundleDoc {
+	version: number
+	meta: Record<string, unknown>
+	body: 'ytext' | 'yarray' | 'ymap' | 'none'
+	children: ReadonlyArray<string>
+}
+
+interface Bundle {
+	schemaVersion: number
+	label?: string
+	types: Record<string, BundleDoc>
+}
+
+const SUPPORTED_BUNDLE_VERSION = 1
+
+export class SchemaBundleLoadError extends Error {
+	constructor(message: string, readonly cause?: unknown) {
+		super(message)
+		this.name = 'SchemaBundleLoadError'
+	}
+}
+
+/**
+ * Read, parse, and compile a JSON Schema bundle into a runtime validator.
+ *
+ * @throws {SchemaBundleLoadError} if the file is missing, malformed, has
+ *   an unsupported `schemaVersion`, or any per-type schema fails to compile.
+ */
+export function loadSchemaBundle(path: string): SchemaBundleValidator {
+	let raw: string
+	try {
+		raw = readFileSync(path, 'utf8')
+	} catch (err) {
+		throw new SchemaBundleLoadError(
+			`Failed to read schema bundle from ${path}: ${(err as Error).message}`,
+			err,
+		)
+	}
+
+	let bundle: Bundle
+	try {
+		bundle = JSON.parse(raw) as Bundle
+	} catch (err) {
+		throw new SchemaBundleLoadError(
+			`Schema bundle at ${path} is not valid JSON: ${(err as Error).message}`,
+			err,
+		)
+	}
+
+	if (bundle.schemaVersion !== SUPPORTED_BUNDLE_VERSION) {
+		throw new SchemaBundleLoadError(
+			`Schema bundle at ${path} has schemaVersion ${bundle.schemaVersion}; this MCP server supports ${SUPPORTED_BUNDLE_VERSION}`,
+		)
+	}
+	if (!bundle.types || typeof bundle.types !== 'object') {
+		throw new SchemaBundleLoadError(
+			`Schema bundle at ${path} is missing the "types" object`,
+		)
+	}
+
+	const ajv = new Ajv2020({
+		strict: false,
+		allErrors: true,
+		// JSON Schema bundles include their own $schema URI; we don't need Ajv to add another.
+		validateSchema: false,
+	})
+	addFormats(ajv)
+
+	const validators = new Map<string, ValidateFunction>()
+	for (const [docType, decl] of Object.entries(bundle.types)) {
+		try {
+			const fn = ajv.compile(decl.meta)
+			validators.set(docType, fn)
+		} catch (err) {
+			throw new SchemaBundleLoadError(
+				`Schema bundle at ${path} has an invalid meta schema for "${docType}": ${(err as Error).message}`,
+				err,
+			)
+		}
+	}
+
+	const knownTypes = Array.from(validators.keys()).sort()
+
+	return {
+		knownTypes,
+		validateMeta(docType: string, meta: unknown): MetaValidationResult {
+			const fn = validators.get(docType)
+			if (!fn) {
+				// Unknown doc-type → unconstrained (Rule 4). Existing-app traffic
+				// for non-canary types is never rejected by this validator.
+				return { ok: true }
+			}
+			const ok = fn(meta)
+			if (ok) return { ok: true }
+			const errors: MetaValidationIssue[] = (fn.errors ?? []).map((e) => ({
+				path: e.instancePath || '/',
+				message: e.message ?? 'validation failed',
+				keyword: e.keyword,
+			}))
+			return { ok: false, errors }
+		},
+	}
+}

package/src/schema/validator.ts

@@ -0,0 +1,31 @@
+/**
+ * Validator types for the MCP schema runtime hook.
+ *
+ * The MCP server stays schema-agnostic at the type level: it loads
+ * JSON Schema bundles (data) at boot, never imports a live Zod registry.
+ * This file declares only the shape of the validator, not how it's built.
+ */
+
+export interface MetaValidationIssue {
+	/** JSON-pointer-ish path to the offending field, e.g. "/priority". */
+	readonly path: string;
+	/** Human-readable error message. */
+	readonly message: string;
+	/** Ajv keyword that failed (e.g. "enum", "required", "pattern"). */
+	readonly keyword?: string;
+}
+
+export type MetaValidationResult =
+	| { ok: true }
+	| { ok: false; errors: ReadonlyArray<MetaValidationIssue> };
+
+export interface SchemaBundleValidator {
+	/** Doc-types known to this bundle. */
+	readonly knownTypes: ReadonlyArray<string>;
+	/**
+	 * Validate `meta` against the schema for `docType`. If `docType` is not
+	 * in this bundle, returns `{ ok: true }` — unknown doc-types are
+	 * unconstrained (Rule 4: never reject existing-app traffic).
+	 */
+	validateMeta(docType: string, meta: unknown): MetaValidationResult;
+}