feat(mcp): attach to live Yjs collaboration rooms (co-edit + attributed tracked changes)

[jacobjove]

Closes #3568.

Opened as a draft alongside #3568.

What this adds

A collaboration-attach path for apps/mcp, alongside the existing file-open path, so an MCP client can join a live Yjs room instead of only round-tripping a local .docx. The motivating use case is agent-assisted review: suggest tracked redlines into the document a human has open, attributed to a named reviewer, for accept/reject.

Capabilities, all kept in the MCP layer — no super-editor core edits:

1. superdoc_attach({ ws_url, document_id, token?, user? }) — connects to a Yjs room over WebSocket, awaits initial sync, returns a session_id usable with every existing tool. Like superdoc_open, it creates a session rather than consuming one.
2. Tracked-change attribution. user: { id?, name?, email? } is threaded into the headless Editor config. Without it, superdoc_mutations({ changeMode: "tracked" }) over an attach throws forceTrackChanges requires a user to be configured on the editor instance (the gate reads exactly this.options.user). The file-open path already defaulted a user; attach was the only path missing the seam. Caller-supplied so changes attribute to the real reviewer, not a hardcoded identity.
3. Presence. When user is supplied, the attach advertises it via provider.awareness.setLocalStateField('user', …), so collaborators see who is suggesting changes (SuperDoc surfaces this through awarenessStatesToArray → the participant list; the viewer assigns a color from its palette). Only the participant-list presence is published — see the design note below on why no cursor.
4. Collab-aware save export. A joiner editor is built with no docx source (content arrives via the Yjs fragment), so convertedXml lacks the base OOXML parts and exportDocx throws on the first unguarded deref. Fix: seed the blank-docx template (Editor.loadXmlData(blankDocxBytes, true)) so SuperConverter populates the standard parts. With a ydoc present, #createInitialState only uses the seeded content as export scaffolding — Yjs still drives the live body.

Sync-wait hardening + provider lifecycle

openRoom awaits sync via the codebase's onCollaborationProviderSynced helper (exported from superdoc/super-editor) instead of a bespoke on('sync') wait. The default WebsocketProvider was already safe — its sync(true) fires async from websocket.onmessage, after the handler is registered — but the createProvider seam admits alternate providers the bespoke wait would hang on until a spurious timeout: ones already synced when returned (pooled/reused), or ones that emit only the no-arg synced event. The helper pre-checks already-synced, listens to both sync(boolean) and synced, and re-checks after wiring to close the register-after-sync race.

Post-sync editor/adapter construction is wrapped so a throw there (e.g. buildAttachEditor's loadXmlData! assertion) destroys the provider before rethrowing, rather than orphaning a live socket plus its resync timers and a process.on('exit') handler. The attach error path also reports a non-Error throw as its string form instead of undefined.

Commit

Single squashed commit, rebased onto current main: feat(mcp): attach to live Yjs collaboration rooms with attributed tracked changes.

Dependencies added: yjs, y-websocket (via catalog:), ws + @types/ws. The lockfile delta is exactly the four apps/mcp importer entries — no transitive drift (pnpm install --frozen-lockfile clean on the repo-pinned pnpm@10.25.0, against current main).

Open design question — presence cursor (input wanted)

This PR publishes participant-list presence but not a cursor, deliberately. Two reasons, and I'd like your call on whether to take either further in this PR or a follow-up:

• Cursor. CollaborationCursor activates only when editor.options.collaborationProvider is set; the attach editor is built with ydoc only, so the cursor plugin is inert and the attach broadcasts no caret. That's intentional: a headless agent's ProseMirror selection jumps per superdoc_mutations call, so echoing it raw would teleport the caret rather than signal "the agent is reviewing §7." A useful "follow the agent" cursor needs curated/throttled position broadcasting (park at the region under review), which is a small design rather than a flag flip.
• Identity label. Presence currently reuses the attribution user. If that identity is a real person (e.g. the operating attorney, for the redline author record), the participant list would imply a human is present. You may want a distinct presence label (e.g. {name}'s AI) decoupled from the redline author. Happy to wire whichever you prefer.

(#3568 raised awareness as an open question — "whether you'd prefer user sourced from the Yjs awareness state rather than a tool param." Note that's the read direction; for an agent, awareness holds other participants' identities, so the agent must declare its own — hence the tool param. The presence above is the write direction.)

Testing

• apps/mcp/src/__tests__/collab-attach.test.ts — openRoom orchestration against a stubbed provider (following the repo's createProviderStub idiom — inert on/off, explicit emit, synced/isSynced fields): returns a registered room session on the sync edge, on an already-synced provider with no emit, and on a no-arg synced event with no sync edge; broadcasts awareness presence iff a user is supplied; rejects + tears down the provider on sync timeout; save() refuses a room session without an output path and writes a valid PK-zip with one.
• apps/mcp/src/__tests__/collab-export.test.ts — joiner-editor export → valid PK-zip with word/document.xml + word/styles.xml + word/_rels/document.xml.rels.
• apps/mcp/src/__tests__/collab-attach-user.test.ts — asserts editor.options.user is set with a user, null without.
• protocol.test.ts updated to include superdoc_attach in the tool-list / action-enum / session_id assertions (it's a session-creating lifecycle tool like superdoc_open).
• Full apps/mcp suite green: 46 pass / 0 fail (pnpm run build:superdoc then pnpm --prefix apps/mcp run test, matching ci-mcp.yml), run against current main after rebase.
• Verified end-to-end against a live collab server: attach with user → tracked mutation succeeds (no "requires a user") → superdoc_track_changes list shows the change attributed to the supplied author → save exports a valid OOXML file with the live-room body intact.

Left to the end-to-end check

The stubbed-provider tests cover the orchestration (sync resolution, timeout, presence wiring, save-guard, export scaffolding, user wiring). The only thing they don't exercise is the real WebSocket transport — actual connect/sync against a running y-websocket server — which is what the live-server check above covers.

Note for reviewers (latent, left untouched here)

Editor.exportDocx() wraps its whole body in try { … } catch (e) { this.emit('exception', …); console.error(e); } with no return in the catch, so on any export error it silently returns undefined and the real TypeError only reaches stderr. For a collab joiner the throw originates earlier (SuperConverter header/footer export with empty convertedXml). Seeding the template avoids the throw; I left the swallowing catch alone since it's on the shared export path and changing its contract is out of scope for this PR. Filed separately as #3579.

Checklist

• Changes focused (one feature)
• Tests added
• Suite passes locally (pnpm --prefix apps/mcp run test, after build:superdoc)
• Formatted (prettier --check clean on changed files)
• Conventional Commits
• PR links the related issue (MCP: attach to live Yjs collaboration rooms (co-edit + attributed tracked changes) #3568)

[cubic-dev-ai]

No issues found across 9 files

_{Re-trigger cubic}