AFFiNE MCP Server

Instructions

Implementation Reference

• src/tools/workspaces.ts:136-144 (handler)

  The core handler function that implements the list_workspaces tool logic by querying the GraphQL endpoint for available workspaces and returning the list or an error.
  const listWorkspacesHandler = async () => { try { const query = `query { workspaces { id public enableAi createdAt } }`; const data = await gql.request<{ workspaces: any[] }>(query); return text(data.workspaces || []); } catch (error: any) { return text({ error: error.message }); } };
• src/tools/workspaces.ts:146-153 (registration)

  Direct registration of the 'list_workspaces' tool with the MCP server, including metadata and handler reference.
  server.registerTool( "list_workspaces", { title: "List Workspaces", description: "List all available AFFiNE workspaces" }, listWorkspacesHandler as any );
• src/tools/workspaces.ts:154-161 (registration)

  Additional registration of an alias 'affine_list_workspaces' using the same handler.
  server.registerTool( "affine_list_workspaces", { title: "List Workspaces", description: "List all available AFFiNE workspaces" }, listWorkspacesHandler );
• src/index.ts:65-65 (registration)

  Top-level call to register all workspace-related tools, including list_workspaces, during server initialization.
  registerWorkspaceTools(server, gql);
• src/tools/workspaces.ts:134-468 (helper)

  Helper function that defines and registers all workspace tools, including the listWorkspacesHandler and its registrations.
  export function registerWorkspaceTools(server: McpServer, gql: GraphQLClient) { // LIST WORKSPACES const listWorkspacesHandler = async () => { try { const query = `query { workspaces { id public enableAi createdAt } }`; const data = await gql.request<{ workspaces: any[] }>(query); return text(data.workspaces || []); } catch (error: any) { return text({ error: error.message }); } }; server.registerTool( "list_workspaces", { title: "List Workspaces", description: "List all available AFFiNE workspaces" }, listWorkspacesHandler as any ); server.registerTool( "affine_list_workspaces", { title: "List Workspaces", description: "List all available AFFiNE workspaces" }, listWorkspacesHandler ); // GET WORKSPACE const getWorkspaceHandler = async ({ id }: { id: string }) => { try { const query = `query GetWorkspace($id: String!) { workspace(id: $id) { id public enableAi createdAt permissions { Workspace_Read Workspace_CreateDoc } } }`; const data = await gql.request<{ workspace: any }>(query, { id }); return text(data.workspace); } catch (error: any) { return text({ error: error.message }); } }; server.registerTool( "get_workspace", { title: "Get Workspace", description: "Get details of a specific workspace", inputSchema: { id: z.string().describe("Workspace ID") } }, getWorkspaceHandler as any ); server.registerTool( "affine_get_workspace", { title: "Get Workspace", description: "Get details of a specific workspace", inputSchema: { id: z.string().describe("Workspace ID") } }, getWorkspaceHandler as any ); // CREATE WORKSPACE 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" }); } }; 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 ); server.registerTool( "affine_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 ); server.registerTool( "affine_create_workspace_fixed", { title: "Create Workspace (Fixed)", description: "Create a new workspace with initial document (backward compatible alias)", inputSchema: { name: z.string().describe("Workspace name"), avatar: z.string().optional().describe("Avatar emoji or URL") } }, createWorkspaceHandler as any ); // UPDATE WORKSPACE const updateWorkspaceHandler = async ({ id, public: isPublic, enableAi }: { id: string; public?: boolean; enableAi?: boolean }) => { try { const mutation = ` mutation UpdateWorkspace($input: UpdateWorkspaceInput!) { updateWorkspace(input: $input) { id public } } `; const input: any = { id }; if (isPublic !== undefined) input.public = isPublic; const data = await gql.request<{ updateWorkspace: any }>(mutation, { input }); return text(data.updateWorkspace); } catch (error: any) { return text({ error: error.message }); } }; server.registerTool( "update_workspace", { title: "Update Workspace", description: "Update workspace settings", inputSchema: { id: z.string().describe("Workspace ID"), public: z.boolean().optional().describe("Make workspace public"), enableAi: z.boolean().optional().describe("Enable AI features") } }, updateWorkspaceHandler as any ); server.registerTool( "affine_update_workspace", { title: "Update Workspace", description: "Update workspace settings", inputSchema: { id: z.string().describe("Workspace ID"), public: z.boolean().optional().describe("Make workspace public"), enableAi: z.boolean().optional().describe("Enable AI features") } }, updateWorkspaceHandler as any ); // DELETE WORKSPACE const deleteWorkspaceHandler = async ({ id }: { id: string }) => { try { const mutation = ` mutation DeleteWorkspace($id: String!) { deleteWorkspace(id: $id) } `; const data = await gql.request<{ deleteWorkspace: boolean }>(mutation, { id }); return text({ success: data.deleteWorkspace, message: "Workspace deleted successfully" }); } catch (error: any) { return text({ error: error.message }); } }; server.registerTool( "delete_workspace", { title: "Delete Workspace", description: "Delete a workspace permanently", inputSchema: { id: z.string().describe("Workspace ID") } }, deleteWorkspaceHandler as any ); server.registerTool( "affine_delete_workspace", { title: "Delete Workspace", description: "Delete a workspace permanently", inputSchema: { id: z.string().describe("Workspace ID") } }, deleteWorkspaceHandler as any ); }