feat(mcp): attach to live Yjs collaboration rooms with attributed tracked changes

Add `superdoc_attach` so an MCP client can join a live SuperDoc Yjs
collaboration room over WebSocket (openRoom + WebsocketProvider, awaiting
initial sync) instead of only round-tripping a local .docx. The returned
session_id works with every existing tool. The motivating use case is
agent-assisted review: suggesting tracked redlines into a document a human has
open, attributed to a named reviewer, for accept/reject.

Tracked-change attribution: `superdoc_attach` accepts an optional
user ({ id, name, email }) threaded through openRoom into buildAttachEditor's
headless Editor config. Without a configured user, forceTrackChanges rejects
tracked edits, so suggested edits over an attach could not be attributed. The
file-open path already sets a default user; this brings the attach path to
parity, scoped to a caller-supplied identity.

Collab-aware save export: a joiner editor is built with no docx source, so
converter.convertedXml carried none of the base OOXML parts that
Editor.exportDocx dereferences. The deref threw and (via exportDocx's catch)
surfaced as "not binary (got undefined)". buildAttachEditor now seeds the
blank-docx template via Editor.loadXmlData so export has valid scaffolding;
Yjs still drives the body (the initial ProseMirror doc is seeded from `content`
only when no ydoc is present). save() rejects room saves without an explicit
output path.

Tests: protocol.test.ts now covers superdoc_attach in the tool-list,
action-enum, and session_id assertions (like superdoc_open, it creates a
session rather than consuming one). New collab-export.test.ts asserts a binary
PK-zip round-trip (word/document.xml + styles.xml + document.xml.rels) from a
collab-joiner editor, and collab-attach-user.test.ts asserts the tracked-change
user is configured when supplied and left unset otherwise.

Adds yjs, y-websocket, and ws dependencies.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: 2 people

apps/mcp/package.json

@@ -19,6 +19,9 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
+    "ws": "^8.18.3",
+    "y-websocket": "catalog:",
+    "yjs": "catalog:",
     "zod": "^4.3.6"
   },
   "devDependencies": {
@@ -27,6 +30,7 @@
     "superdoc": "workspace:*",
     "@types/bun": "catalog:",
     "@types/node": "catalog:",
+    "@types/ws": "catalog:",
     "typescript": "catalog:"
   },
   "publishConfig": {

apps/mcp/src/__tests__/collab-attach-user.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'bun:test';
+import { Doc as YDoc } from 'yjs';
+import { buildAttachEditor } from '../session-manager.js';
+
+/**
+ * Tracked-change authoring over a collab attach requires a configured user.
+ * Without one, `forceTrackChanges` rejects the edit ("forceTrackChanges requires
+ * a user to be configured on the editor instance") because the gate reads
+ * `editor.options.user`, which is null on a bare attach.
+ *
+ * `buildAttachEditor` accepts an optional user and wires it into the headless
+ * Editor config so suggested edits can be attributed to a reviewer.
+ */
+describe('collab attach user identity (tracked-change user wiring)', () => {
+  // Scope: this asserts buildAttachEditor wires `user` into the Editor config —
+  // the input the forceTrackChanges gate reads. The gate's own behavior (rejecting
+  // tracked edits when no user is set) belongs to super-editor and is tested there.
+  it('configures the tracked-change user on the attach editor when supplied', async () => {
+    const ydoc = new YDoc({ gc: false });
+    const user = { id: 'reviewer-1', name: 'Reviewer', email: 'reviewer@example.com' };
+
+    const editor = await buildAttachEditor(ydoc, 'test-room', user);
+
+    // This is the exact value the forceTrackChanges gate reads.
+    expect(editor.options.user).toEqual(user);
+
+    editor.destroy();
+  });
+
+  it('leaves the user unset when none is supplied (default preserved)', async () => {
+    const ydoc = new YDoc({ gc: false });
+
+    const editor = await buildAttachEditor(ydoc, 'test-room');
+
+    // Editor default for `user` is null; the no-arg attach path must not invent one.
+    expect(editor.options.user ?? null).toBeNull();
+
+    editor.destroy();
+  });
+});

apps/mcp/src/__tests__/collab-export.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'bun:test';
+import { Doc as YDoc } from 'yjs';
+import { Editor } from 'superdoc/super-editor';
+import { buildAttachEditor } from '../session-manager.js';
+
+/**
+ * Regression: `superdoc_save` over a collab attach reported
+ * "Exported document data is not binary (got undefined)".
+ *
+ * Root cause: the attach editor was built with no docx source, so
+ * `converter.convertedXml` carried none of the base OOXML parts that
+ * `Editor.exportDocx` unguarded-derefs (docProps/custom.xml, word/styles.xml,
+ * word/_rels/document.xml.rels). The deref threw; the swallowing catch in
+ * exportDocx returned `undefined`.
+ *
+ * A collab-joiner editor must export a valid .docx even with an empty Yjs doc.
+ */
+describe('collab attach export (superdoc_save over a room)', () => {
+  it('exports binary .docx bytes from a collab-joiner editor with no docx source', async () => {
+    const ydoc = new YDoc({ gc: false });
+    const editor = await buildAttachEditor(ydoc, 'test-room');
+
+    const exported = await editor.exportDocument();
+
+    // The pre-fix failure mode: exportDocx throws on the missing parts and the
+    // catch swallows to undefined.
+    expect(exported).toBeDefined();
+
+    const bytes = exported instanceof Uint8Array ? exported : new Uint8Array(await (exported as Blob).arrayBuffer());
+
+    expect(bytes.byteLength).toBeGreaterThan(0);
+    // Valid .docx is a ZIP — "PK" local-file-header magic.
+    expect(bytes[0]).toBe(0x50); // 'P'
+    expect(bytes[1]).toBe(0x4b); // 'K'
+
+    // Round-trip: the exported bytes must re-open as a structurally valid docx
+    // carrying the base OOXML parts that were previously missing.
+    const [parts] = (await Editor.loadXmlData(Buffer.from(bytes), true))!;
+    const names = new Set(parts.map((p: { name: string }) => p.name));
+    expect(names.has('word/document.xml')).toBe(true);
+    expect(names.has('word/styles.xml')).toBe(true);
+    expect(names.has('word/_rels/document.xml.rels')).toBe(true);
+
+    editor.destroy();
+  });
+});

apps/mcp/src/__tests__/protocol.test.ts

@@ -6,10 +6,11 @@ import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
 const BLANK_DOCX = resolve(import.meta.dir, '../../../../shared/common/data/blank.docx');
 const SERVER_ENTRY = resolve(import.meta.dir, '../index.ts');
 
-// 3 lifecycle + 10 intent tools from the generated catalog
+// 4 lifecycle + 10 intent tools from the generated catalog
 const EXPECTED_TOOLS = [
   // Lifecycle
   'superdoc_open',
+  'superdoc_attach',
   'superdoc_save',
   'superdoc_close',
   // Intent tools (from catalog.json)
@@ -77,8 +78,10 @@ describe('MCP protocol integration', () => {
     const { tools } = await client.listTools();
 
     // Multi-action intent tools should have an "action" property with an enum
+    // superdoc_attach, like superdoc_open, is a session-creating lifecycle tool — no action enum.
     const multiActionTools = tools.filter(
-      (t) => !['superdoc_open', 'superdoc_save', 'superdoc_close', 'superdoc_search'].includes(t.name),
+      (t) =>
+        !['superdoc_open', 'superdoc_attach', 'superdoc_save', 'superdoc_close', 'superdoc_search'].includes(t.name),
     );
 
     for (const tool of multiActionTools) {
@@ -93,8 +96,11 @@ describe('MCP protocol integration', () => {
     await ready;
     const { tools } = await client.listTools();
 
-    // All intent tools (not lifecycle open) should require session_id
-    const intentTools = tools.filter((t) => !['superdoc_open', 'superdoc_save', 'superdoc_close'].includes(t.name));
+    // All intent tools (not session-creating lifecycle tools) should require session_id.
+    // superdoc_open and superdoc_attach both produce a session_id rather than consuming one.
+    const intentTools = tools.filter(
+      (t) => !['superdoc_open', 'superdoc_attach', 'superdoc_save', 'superdoc_close'].includes(t.name),
+    );
 
     for (const tool of intentTools) {
       const schema = tool.inputSchema as { properties?: Record<string, unknown>; required?: string[] };

apps/mcp/src/session-manager.ts

@@ -1,17 +1,20 @@
 import { access, readFile, writeFile } from 'node:fs/promises';
 import { randomBytes } from 'node:crypto';
 import { resolve, basename } from 'node:path';
-import { Editor } from 'superdoc/super-editor';
+import { Editor, getStarterExtensions } from 'superdoc/super-editor';
 import { getDocumentApiAdapters } from '@superdoc/super-editor/document-api-adapters';
 import { createDocumentApi, type DocumentApi } from '@superdoc/document-api';
 import { BLANK_DOCX_BASE64 } from '@superdoc/super-editor/blank-docx';
+import { Doc as YDoc } from 'yjs';
+import { WebsocketProvider } from 'y-websocket';
 
 export interface Session {
   id: string;
-  filePath: string;
+  filePath: string | null;
   editor: Editor;
   api: DocumentApi;
   openedAt: number;
+  provider?: WebsocketProvider;
 }
 
 export class SessionManager {
@@ -65,12 +68,59 @@ export class SessionManager {
     return session;
   }
 
+  async openRoom(wsUrl: string, documentId: string, token?: string, user?: AttachUser): Promise<Session> {
+    const ydoc = new YDoc({ gc: false });
+
+    // y-websocket needs a WebSocket constructor; Node has no global one, so supply `ws`.
+    const { default: WebSocket } = await import('ws');
+    const provider = new WebsocketProvider(wsUrl, documentId, ydoc, {
+      WebSocketPolyfill: WebSocket as unknown as typeof globalThis.WebSocket,
+      params: token ? { token } : {},
+    });
+
+    // Await initial sync before editor construction so the fragment is populated
+    await new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        provider.destroy();
+        reject(new Error('sync timeout (10s)'));
+      }, 10_000);
+      provider.once('sync', (synced: boolean) => {
+        if (synced) {
+          clearTimeout(timeout);
+          resolve();
+        }
+      });
+    });
+
+    const editor = await buildAttachEditor(ydoc, documentId, user);
+
+    const adapters = getDocumentApiAdapters(editor);
+    const api = createDocumentApi(adapters);
+
+    const id = generateRoomSessionId(documentId);
+
+    const session: Session = {
+      id,
+      filePath: null,
+      editor,
+      api,
+      openedAt: Date.now(),
+      provider,
+    };
+
+    this.sessions.set(id, session);
+    return session;
+  }
+
   async save(sessionId: string, outputPath?: string): Promise<{ path: string; byteLength: number }> {
     const session = this.get(sessionId);
-    const targetPath = outputPath ? resolve(outputPath) : session.filePath;
+    if (!outputPath && !session.filePath) {
+      throw new Error('Cannot save a room session without specifying an output path.');
+    }
+    const targetPath = outputPath ? resolve(outputPath) : resolve(session.filePath!);
 
     const exported = await session.editor.exportDocument();
-    const bytes = toUint8Array(exported);
+    const bytes = await toBytes(exported);
 
     await writeFile(targetPath, bytes);
 
@@ -81,18 +131,20 @@ export class SessionManager {
     const session = this.sessions.get(sessionId);
     if (!session) return;
 
+    session.provider?.destroy();
     session.editor.destroy();
     this.sessions.delete(sessionId);
   }
 
   async closeAll(): Promise<void> {
     for (const session of this.sessions.values()) {
+      session.provider?.destroy();
       session.editor.destroy();
     }
     this.sessions.clear();
   }
 
-  list(): Array<{ id: string; filePath: string; openedAt: number }> {
+  list(): Array<{ id: string; filePath: string | null; openedAt: number }> {
     return Array.from(this.sessions.values()).map((s) => ({
       id: s.id,
       filePath: s.filePath,
@@ -101,6 +153,60 @@ export class SessionManager {
   }
 }
 
+/** Identity for attributing tracked changes authored over a collab attach. */
+export interface AttachUser {
+  id?: string;
+  name?: string;
+  email?: string;
+}
+
+/**
+ * Build the headless Editor for a collaborative attach session.
+ *
+ * The document body arrives via the Yjs fragment (`ydoc`); `content` only seeds
+ * the base OOXML parts (`converter.convertedXml`) that `Editor.exportDocx` derefs
+ * on save. A bare `content: []` leaves those parts empty, so export throws and the
+ * swallowing catch returns `undefined` ("not binary (got undefined)"). Seeding the
+ * blank-docx template gives export valid scaffolding while Yjs still drives the body
+ * (Editor only seeds the initial PM doc from `content` when no `ydoc` is present).
+ *
+ * An optional `user` configures the tracked-change author so an MCP client can
+ * author attributable tracked (suggested) edits over the attach; without it,
+ * `forceTrackChanges` rejects tracked edits. The file-open path (`open`) already
+ * sets a default user; this brings the attach path to parity.
+ */
+export async function buildAttachEditor(ydoc: YDoc, documentId: string, user?: AttachUser): Promise<Editor> {
+  const blankBytes = Buffer.from(BLANK_DOCX_BASE64, 'base64');
+  const [content, , mediaFiles, fonts] = (await Editor.loadXmlData(blankBytes, true))!;
+
+  return new Editor({
+    isHeadless: true,
+    mode: 'docx',
+    documentId,
+    extensions: getStarterExtensions(),
+    ydoc,
+    content,
+    mediaFiles,
+    fonts,
+    fileSource: blankBytes,
+    // Without a user, `forceTrackChanges` rejects tracked edits. Supplying one
+    // lets the caller author attributable tracked changes over the attach.
+    ...(user ? { user } : {}),
+  });
+}
+
+function generateRoomSessionId(documentId: string): string {
+  const stem = documentId.replace(/\//g, '-').replace(/[^a-zA-Z0-9._-]+/g, '-') || 'room';
+  const normalized =
+    stem
+      .toLowerCase()
+      .replace(/[^a-z0-9._-]+/g, '-')
+      .replace(/-{2,}/g, '-')
+      .replace(/^[._-]+|[._-]+$/g, '') || 'room';
+  const suffix = randomBytes(4).toString('hex').slice(0, 6);
+  return `room-${normalized.slice(0, 50)}-${suffix}`;
+}
+
 function generateSessionId(filePath: string): string {
   const stem = basename(filePath).replace(/\.[^.]+$/, '');
   const normalized =
@@ -113,11 +219,17 @@ function generateSessionId(filePath: string): string {
   return `${normalized.slice(0, 57)}-${suffix}`;
 }
 
-function toUint8Array(data: unknown): Uint8Array {
+async function toBytes(data: unknown): Promise<Uint8Array> {
   if (data instanceof Uint8Array) return data;
   if (data instanceof ArrayBuffer) return new Uint8Array(data);
   if (ArrayBuffer.isView(data)) {
     return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
   }
-  throw new Error('Exported document data is not binary.');
+  // Blob (incl. cross-realm/polyfilled instances where `instanceof Blob` is false): duck-type
+  // on arrayBuffer(). Headless/collab exportDocument() returns a Blob.
+  if (data && typeof (data as { arrayBuffer?: unknown }).arrayBuffer === 'function') {
+    return new Uint8Array(await (data as Blob).arrayBuffer());
+  }
+  const desc = data == null ? String(data) : `${typeof data}/${(data as object).constructor?.name ?? 'unknown'}`;
+  throw new Error(`Exported document data is not binary (got ${desc}).`);
 }

apps/mcp/src/tools/collab.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { SessionManager } from '../session-manager.js';
+
+export function registerCollabTools(server: McpServer, sessions: SessionManager): void {
+  server.registerTool(
+    'superdoc_attach',
+    {
+      title: 'Attach to Collaboration Room',
+      description:
+        'Attach to a live SuperDoc Yjs collaboration room via WebSocket and return a session_id for use with all other superdoc tools. Awaits initial sync before returning.',
+      inputSchema: {
+        ws_url: z.string().describe('WebSocket URL base, e.g. ws://localhost:4444/doc'),
+        document_id: z.string().describe('Document/room identifier'),
+        token: z.string().optional().describe('Optional auth token passed as query param'),
+        user: z
+          .object({
+            id: z.string().optional(),
+            name: z.string().optional(),
+            email: z.string().optional(),
+          })
+          .optional()
+          .describe(
+            'Optional identity for attributing tracked changes. Required to author tracked (suggested) edits over the attach; direct edits work without it.',
+          ),
+      },
+      annotations: { readOnlyHint: false },
+    },
+    async ({ ws_url, document_id, token, user }) => {
+      try {
+        const session = await sessions.openRoom(ws_url, document_id, token, user);
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({ session_id: session.id }),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text' as const, text: `Failed to attach to room: ${(err as Error).message}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

apps/mcp/src/tools/index.ts

@@ -2,8 +2,10 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { SessionManager } from '../session-manager.js';
 import { registerLifecycleTools } from './lifecycle.js';
 import { registerIntentTools } from './intent.js';
+import { registerCollabTools } from './collab.js';
 
 export function registerAllTools(server: McpServer, sessions: SessionManager): void {
   registerLifecycleTools(server, sessions);
   registerIntentTools(server, sessions);
+  registerCollabTools(server, sessions);
 }