AFFiNE MCP Server

Instructions

Implementation Reference

• src/tools/workspaces.ts:209-342 (handler)

  Main handler function executing the create_workspace tool: generates initial Yjs workspace and document, sends GraphQL mutation via multipart form, and syncs document via WebSocket.

  const createWorkspaceHandler = async ({ name, avatar }: { name: string; avatar?: string }) => {
      try {
        // Get endpoint and headers from GraphQL client
        const endpoint = (gql as any).endpoint || process.env.AFFINE_BASE_URL + '/graphql';
        const headers = (gql as any).headers || {};
        const cookie = (gql as any).cookie || headers.Cookie || '';
        
        // Create initial workspace data
        const { workspaceUpdate, firstDocId, docUpdate } = createInitialWorkspaceData(name);
        
        // Only send workspace update - document will be created separately
        const initData = Buffer.from(workspaceUpdate);
        
        // Create multipart form
        const form = new FormData();
        
        // Add GraphQL operation
        form.append('operations', JSON.stringify({
          name: 'createWorkspace',
          query: `mutation createWorkspace($init: Upload!) {
            createWorkspace(init: $init) {
              id
              public
              createdAt
              enableAi
            }
          }`,
          variables: { init: null }
        }));
        
        // Map file to variable
        form.append('map', JSON.stringify({ '0': ['variables.init'] }));
        
        // Add workspace init data
        form.append('0', initData, {
          filename: 'init.yjs',
          contentType: 'application/octet-stream'
        });
        
        // Send request
        const response = await fetch(endpoint, {
          method: 'POST',
          headers: {
            ...headers,
            'Cookie': cookie,
            ...form.getHeaders()
          },
          body: form as any
        });
        
        const result = await response.json() as any;
        
        if (result.errors) {
          throw new Error(result.errors[0].message);
        }
        
        const workspace = result.data.createWorkspace;
        
        // Now create the actual document via WebSocket
        const wsUrl = endpoint.replace('https://', 'wss://').replace('http://', 'ws://').replace('/graphql', '');
        
        return new Promise((resolve) => {
          const socket = io(wsUrl, {
            transports: ['websocket'],
            path: '/socket.io/',
            extraHeaders: cookie ? { Cookie: cookie } : undefined
          });
          
          socket.on('connect', () => {
            // Join the workspace
            socket.emit('space:join', {
              spaceType: 'workspace',
              spaceId: workspace.id
            });
            
            // Send the document update
            setTimeout(() => {
              const docUpdateBase64 = Buffer.from(docUpdate).toString('base64');
              socket.emit('space:push-doc-update', {
                spaceType: 'workspace',
                spaceId: workspace.id,
                docId: firstDocId,
                update: docUpdateBase64
              });
              
              // Wait longer for sync and disconnect
              setTimeout(() => {
                socket.disconnect();
                resolve(text({
                  ...workspace,
                  name: name,
                  avatar: avatar,
                  firstDocId: firstDocId,
                  status: "success",
                  message: "Workspace created successfully",
                  url: `${process.env.AFFINE_BASE_URL}/workspace/${workspace.id}`
                }));
              }, 3000);
            }, 1000);
          });
          
          socket.on('error', () => {
            socket.disconnect();
            // Even if WebSocket fails, workspace was created
            resolve(text({
              ...workspace,
              name: name,
              avatar: avatar,
              firstDocId: firstDocId,
              status: "partial",
              message: "Workspace created (document sync may be pending)",
              url: `${process.env.AFFINE_BASE_URL}/workspace/${workspace.id}`
            }));
          });
          
          // Timeout
          setTimeout(() => {
            socket.disconnect();
            resolve(text({
              ...workspace,
              name: name,
              avatar: avatar,
              firstDocId: firstDocId,
              status: "success",
              message: "Workspace created",
              url: `${process.env.AFFINE_BASE_URL}/workspace/${workspace.id}`
            }));
          }, 10000);
        });
        
      } catch (error: any) {
        return text({ error: error.message, status: "failed" });
      }
    };

• src/tools/workspaces.ts:344-355 (registration)

  Registration of the 'create_workspace' MCP tool, including title, description, Zod input schema, and reference to the handler function.

  server.registerTool(
    "create_workspace",
    {
      title: "Create Workspace",
      description: "Create a new workspace with initial document (accessible in UI)",
      inputSchema: {
        name: z.string().describe("Workspace name"),
        avatar: z.string().optional().describe("Avatar emoji or URL")
      }
    },
    createWorkspaceHandler as any
  );

• src/tools/workspaces.ts:350-352 (schema)

  Zod input schema defining parameters for the create_workspace tool: required 'name' string and optional 'avatar' string.

    name: z.string().describe("Workspace name"),
    avatar: z.string().optional().describe("Avatar emoji or URL")
  }

• src/tools/workspaces.ts:21-132 (helper)

  Helper function to generate initial Yjs updates for new workspace root and first document with AFFiNE block structure.

  function createInitialWorkspaceData(workspaceName: string = 'New Workspace') {
    // Create workspace root YDoc
    const rootDoc = new Y.Doc();
    
    // Set workspace metadata
    const meta = rootDoc.getMap('meta');
    meta.set('name', workspaceName);
    meta.set('avatar', '');
    
    // Create pages array with initial document
    const pages = new Y.Array();
    const firstDocId = generateDocId();
    
    // Add first document metadata
    const pageMetadata = new Y.Map();
    pageMetadata.set('id', firstDocId);
    pageMetadata.set('title', 'Welcome to ' + workspaceName);
    pageMetadata.set('createDate', Date.now());
    pageMetadata.set('tags', new Y.Array());
    
    pages.push([pageMetadata]);
    meta.set('pages', pages);
    
    // Create settings
    const setting = rootDoc.getMap('setting');
    setting.set('collections', new Y.Array());
    
    // Encode workspace update
    const workspaceUpdate = Y.encodeStateAsUpdate(rootDoc);
    
    // Create the actual document
    const docYDoc = new Y.Doc();
    const blocks = docYDoc.getMap('blocks');
    
    // Create page block with proper structure
    const pageId = generateDocId();
    const pageBlock = new Y.Map();
    pageBlock.set('sys:id', pageId);
    pageBlock.set('sys:flavour', 'affine:page');
    
    // Title as Y.Text
    const titleText = new Y.Text();
    titleText.insert(0, 'Welcome to ' + workspaceName);
    pageBlock.set('prop:title', titleText);
    
    // Children
    const pageChildren = new Y.Array();
    pageBlock.set('sys:children', pageChildren);
    
    blocks.set(pageId, pageBlock);
    
    // Add surface block (required)
    const surfaceId = generateDocId();
    const surfaceBlock = new Y.Map();
    surfaceBlock.set('sys:id', surfaceId);
    surfaceBlock.set('sys:flavour', 'affine:surface');
    surfaceBlock.set('sys:parent', pageId);
    surfaceBlock.set('sys:children', new Y.Array());
    
    blocks.set(surfaceId, surfaceBlock);
    pageChildren.push([surfaceId]);
    
    // Add note block with xywh
    const noteId = generateDocId();
    const noteBlock = new Y.Map();
    noteBlock.set('sys:id', noteId);
    noteBlock.set('sys:flavour', 'affine:note');
    noteBlock.set('sys:parent', pageId);
    noteBlock.set('prop:displayMode', 'DocAndEdgeless');
    noteBlock.set('prop:xywh', '[0,0,800,600]');
    noteBlock.set('prop:index', 'a0');
    noteBlock.set('prop:lockedBySelf', false);
    
    const noteChildren = new Y.Array();
    noteBlock.set('sys:children', noteChildren);
    
    blocks.set(noteId, noteBlock);
    pageChildren.push([noteId]);
    
    // Add initial paragraph
    const paragraphId = generateDocId();
    const paragraphBlock = new Y.Map();
    paragraphBlock.set('sys:id', paragraphId);
    paragraphBlock.set('sys:flavour', 'affine:paragraph');
    paragraphBlock.set('sys:parent', noteId);
    paragraphBlock.set('sys:children', new Y.Array());
    paragraphBlock.set('prop:type', 'text');
    
    const paragraphText = new Y.Text();
    paragraphText.insert(0, 'This workspace was created by AFFiNE MCP Server');
    paragraphBlock.set('prop:text', paragraphText);
    
    blocks.set(paragraphId, paragraphBlock);
    noteChildren.push([paragraphId]);
    
    // Set document metadata
    const docMeta = docYDoc.getMap('meta');
    docMeta.set('id', firstDocId);
    docMeta.set('title', 'Welcome to ' + workspaceName);
    docMeta.set('createDate', Date.now());
    docMeta.set('tags', new Y.Array());
    docMeta.set('version', 1);
    
    // Encode document update
    const docUpdate = Y.encodeStateAsUpdate(docYDoc);
    
    return {
      workspaceUpdate,
      firstDocId,
      docUpdate
    };
  }

• src/tools/workspaces.ts:11-18 (helper)

  Utility function to generate AFFiNE-style 10-char document IDs used in workspace creation.

  function generateDocId(): string {
    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-';
    let id = '';
    for (let i = 0; i < 10; i++) {
      id += chars.charAt(Math.floor(Math.random() * chars.length));
    }
    return id;
  }