@mseep/affine-mcp-server 2.3.0

package/dist/tools/workspaces.js

@@ -0,0 +1,322 @@
+import { z } from "zod";
+import * as Y from "yjs";
+import FormData from "form-data";
+import fetch from "node-fetch";
+import { receipt, text } from "../util/mcp.js";
+import { connectWorkspaceSocket, joinWorkspace, pushDocUpdate, wsUrlFromGraphQLEndpoint } from "../ws.js";
+// Generate AFFiNE-style document ID
+function generateDocId() {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-';
+    let id = '';
+    for (let i = 0; i < 10; i++) {
+        id += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return id;
+}
+// Create initial workspace data with a document
+function createInitialWorkspaceData(workspaceName = 'New Workspace', avatar = '') {
+    // Create workspace root YDoc
+    const rootDoc = new Y.Doc();
+    // Set workspace metadata
+    const meta = rootDoc.getMap('meta');
+    meta.set('name', workspaceName);
+    meta.set('avatar', 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', null);
+    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', null);
+    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', null);
+    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
+    };
+}
+export function registerWorkspaceTools(server, gql) {
+    // LIST WORKSPACES
+    const listWorkspacesHandler = async () => {
+        try {
+            const query = `query { workspaces { id public enableAi createdAt } }`;
+            const data = await gql.request(query);
+            return text(data.workspaces || []);
+        }
+        catch (error) {
+            return text({ error: error.message });
+        }
+    };
+    server.registerTool("list_workspaces", {
+        title: "List Workspaces",
+        description: "List all available AFFiNE workspaces"
+    }, listWorkspacesHandler);
+    // GET WORKSPACE
+    const getWorkspaceHandler = async ({ id }) => {
+        try {
+            const query = `query GetWorkspace($id: String!) { 
+        workspace(id: $id) { 
+          id 
+          public 
+          enableAi 
+          createdAt
+          permissions { 
+            Workspace_Read 
+            Workspace_CreateDoc 
+          } 
+        } 
+      }`;
+            const data = await gql.request(query, { id });
+            return text(data.workspace);
+        }
+        catch (error) {
+            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);
+    // CREATE WORKSPACE
+    const createWorkspaceHandler = async ({ name, avatar }) => {
+        try {
+            // Get endpoint and headers from GraphQL client
+            const endpoint = gql.endpoint;
+            const headers = gql.headers;
+            const cookie = gql.cookie;
+            const bearer = gql.bearer;
+            // Create initial workspace data
+            const { workspaceUpdate, firstDocId, docUpdate } = createInitialWorkspaceData(name, avatar || '');
+            // 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
+            });
+            const result = await response.json();
+            if (result.errors) {
+                throw new Error(result.errors[0].message);
+            }
+            const workspace = result.data.createWorkspace;
+            const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+            const baseUrl = process.env.AFFINE_BASE_URL || endpoint.replace(/\/graphql\/?$/, '');
+            try {
+                const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+                try {
+                    await joinWorkspace(socket, workspace.id);
+                    const docUpdateBase64 = Buffer.from(docUpdate).toString('base64');
+                    await pushDocUpdate(socket, workspace.id, firstDocId, docUpdateBase64);
+                }
+                finally {
+                    socket.disconnect();
+                }
+            }
+            catch (_wsError) {
+                // Keep workspace creation successful even if initial websocket sync fails.
+                return receipt("workspace.create", {
+                    workspaceId: workspace.id,
+                    ...workspace,
+                    name,
+                    avatar,
+                    firstDocId,
+                    syncStatus: "partial",
+                    status: "partial",
+                    message: "Workspace created (document sync may be pending)",
+                    url: `${baseUrl}/workspace/${workspace.id}`
+                });
+            }
+            return receipt("workspace.create", {
+                workspaceId: workspace.id,
+                ...workspace,
+                name,
+                avatar,
+                firstDocId,
+                syncStatus: "success",
+                status: "success",
+                message: "Workspace created successfully",
+                url: `${baseUrl}/workspace/${workspace.id}`
+            });
+        }
+        catch (error) {
+            return text({
+                kind: "workspace.create",
+                ok: false,
+                status: "failed",
+                error: error.message,
+            });
+        }
+    };
+    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);
+    // UPDATE WORKSPACE
+    const updateWorkspaceHandler = async ({ id, public: isPublic, enableAi }) => {
+        try {
+            const mutation = `
+          mutation UpdateWorkspace($input: UpdateWorkspaceInput!) {
+            updateWorkspace(input: $input) {
+              id
+              public
+              enableAi
+            }
+          }
+        `;
+            const input = { id };
+            if (isPublic !== undefined)
+                input.public = isPublic;
+            if (enableAi !== undefined)
+                input.enableAi = enableAi;
+            const data = await gql.request(mutation, { input });
+            return receipt("workspace.update", {
+                workspaceId: id,
+                id,
+                ...data.updateWorkspace,
+            });
+        }
+        catch (error) {
+            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);
+    // DELETE WORKSPACE
+    const deleteWorkspaceHandler = async ({ id }) => {
+        try {
+            const mutation = `
+          mutation DeleteWorkspace($id: String!) {
+            deleteWorkspace(id: $id)
+          }
+        `;
+            const data = await gql.request(mutation, { id });
+            return receipt("workspace.delete", {
+                workspaceId: id,
+                id,
+                deleted: data.deleteWorkspace,
+                success: data.deleteWorkspace,
+                message: "Workspace deleted successfully",
+            });
+        }
+        catch (error) {
+            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);
+}

package/dist/util/explorerIcon.js

@@ -0,0 +1,95 @@
+import * as Y from "yjs";
+import { loadDoc, pushDocUpdate } from "../ws.js";
+/** Build the sub-document guid that holds a workspace's explorer icons. */
+export function explorerIconDocId(workspaceId) {
+    return `db$${workspaceId}$explorerIcon`;
+}
+/** Build the per-entity map key for a document. */
+export function docIconKey(docId) {
+    return `doc:${docId}`;
+}
+/** Build the per-entity map key for an organize folder. */
+export function folderIconKey(folderId) {
+    return `folder:${folderId}`;
+}
+/**
+ * Coerce user input into the stored icon shape (or null to clear).
+ *
+ * - A bare string is treated as an emoji shorthand → `{ type: "emoji", unicode }`.
+ * - A `{ type: "emoji", unicode }` or `{ type: "icon", name }` object is passed
+ *   through after validation. Named-icon `name` values are not validated against
+ *   AFFiNE's fixed icon set — they are written as-is.
+ * - `null` clears the icon.
+ */
+export function normalizeIconInput(input) {
+    if (input === null)
+        return null;
+    if (typeof input === "string") {
+        const unicode = input.trim();
+        if (!unicode)
+            throw new Error("icon emoji string must not be empty.");
+        return { type: "emoji", unicode };
+    }
+    if (input.type === "emoji") {
+        const unicode = input.unicode?.trim();
+        if (!unicode)
+            throw new Error("emoji icon requires a non-empty `unicode`.");
+        return { type: "emoji", unicode };
+    }
+    if (input.type === "icon") {
+        const name = input.name?.trim();
+        if (!name)
+            throw new Error("named icon requires a non-empty `name`.");
+        return { type: "icon", name };
+    }
+    throw new Error(`Unsupported icon type: ${JSON.stringify(input.type)}.`);
+}
+async function loadExplorerIconDoc(socket, workspaceId) {
+    const snap = await loadDoc(socket, workspaceId, explorerIconDocId(workspaceId));
+    const doc = new Y.Doc();
+    if (snap.missing)
+        Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
+    return doc;
+}
+function readIcon(doc, key) {
+    const map = doc.share.has(key) ? doc.getMap(key) : null;
+    if (!map || !map.has("icon"))
+        return null;
+    const raw = map.get("icon");
+    if (raw && typeof raw.toJSON === "function") {
+        return raw.toJSON();
+    }
+    return raw ?? null;
+}
+/**
+ * Set or clear the sidebar icon for a single explorer entity.
+ *
+ * Loads the workspace's `explorerIcon` sub-doc, mutates only the target entry,
+ * and pushes the minimal delta. Passing `icon = null` removes the `icon` field
+ * while preserving the entry's `id`.
+ */
+export async function setExplorerIcon(socket, workspaceId, key, icon) {
+    const doc = await loadExplorerIconDoc(socket, workspaceId);
+    const prevSV = Y.encodeStateVector(doc);
+    const map = doc.getMap(key);
+    if (!map.has("id"))
+        map.set("id", key);
+    if (icon === null) {
+        if (map.has("icon"))
+            map.delete("icon");
+    }
+    else {
+        map.set("icon", icon);
+    }
+    const delta = Y.encodeStateAsUpdate(doc, prevSV);
+    await pushDocUpdate(socket, workspaceId, explorerIconDocId(workspaceId), Buffer.from(delta).toString("base64"));
+    return { key, icon };
+}
+/**
+ * Read the current sidebar icon for a single explorer entity.
+ * Returns `null` when no icon is set (or the entry does not exist).
+ */
+export async function getExplorerIcon(socket, workspaceId, key) {
+    const doc = await loadExplorerIconDoc(socket, workspaceId);
+    return { key, icon: readIcon(doc, key) };
+}

package/dist/util/mcp.js

@@ -0,0 +1,28 @@
+function cloneJsonValue(data) {
+    if (data === undefined) {
+        return data;
+    }
+    return JSON.parse(JSON.stringify(data));
+}
+export function text(data) {
+    if (typeof data === "string") {
+        return { content: [{ type: "text", text: data }] };
+    }
+    if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+        const structuredContent = cloneJsonValue(data);
+        return {
+            content: [{ type: "text", text: JSON.stringify(structuredContent) }],
+            structuredContent,
+        };
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify(data) }],
+    };
+}
+export function receipt(kind, data) {
+    return text({
+        kind,
+        ok: true,
+        ...data,
+    });
+}

package/dist/ws.js

@@ -0,0 +1,113 @@
+import { io } from "socket.io-client";
+const DEFAULT_WS_CLIENT_VERSION = process.env.AFFINE_WS_CLIENT_VERSION || '0.26.0';
+const WS_CONNECT_TIMEOUT_MS = Number(process.env.AFFINE_WS_CONNECT_TIMEOUT_MS || 10000);
+const WS_ACK_TIMEOUT_MS = Number(process.env.AFFINE_WS_ACK_TIMEOUT_MS || 10000);
+function ackErrorMessage(ack, fallback) {
+    const message = ack?.error?.message;
+    if (typeof message === "string" && message.trim())
+        return message;
+    return ack?.error ? fallback : null;
+}
+function emitWithAck(socket, event, payload, onAck) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error(`${event} timeout after ${WS_ACK_TIMEOUT_MS}ms`));
+        }, WS_ACK_TIMEOUT_MS);
+        socket.emit(event, payload, (ack) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            try {
+                resolve(onAck(ack));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    });
+}
+export function wsUrlFromGraphQLEndpoint(endpoint) {
+    return endpoint
+        .replace('https://', 'wss://')
+        .replace('http://', 'ws://')
+        .replace(/\/graphql\/?$/, '');
+}
+export async function connectWorkspaceSocket(wsUrl, cookie, bearer) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const extraHeaders = {};
+        if (cookie)
+            extraHeaders['Cookie'] = cookie;
+        if (bearer)
+            extraHeaders['Authorization'] = `Bearer ${bearer}`;
+        const socket = io(wsUrl, {
+            transports: ['websocket'],
+            path: '/socket.io/',
+            extraHeaders: Object.keys(extraHeaders).length ? extraHeaders : undefined,
+            autoConnect: true
+        });
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            socket.disconnect();
+            reject(new Error(`socket connect timeout after ${WS_CONNECT_TIMEOUT_MS}ms`));
+        }, WS_CONNECT_TIMEOUT_MS);
+        const onError = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            socket.disconnect();
+            reject(err);
+        };
+        const onConnect = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(socket);
+        };
+        const cleanup = () => {
+            clearTimeout(timeout);
+            socket.off('connect', onConnect);
+            socket.off('connect_error', onError);
+        };
+        socket.on('connect', onConnect);
+        socket.on('connect_error', onError);
+    });
+}
+export async function joinWorkspace(socket, workspaceId, clientVersion = DEFAULT_WS_CLIENT_VERSION) {
+    return emitWithAck(socket, 'space:join', { spaceType: 'workspace', spaceId: workspaceId, clientVersion }, (ack) => {
+        const message = ackErrorMessage(ack, "join failed");
+        if (message)
+            throw new Error(message);
+    });
+}
+export async function loadDoc(socket, workspaceId, docId) {
+    return emitWithAck(socket, 'space:load-doc', { spaceType: 'workspace', spaceId: workspaceId, docId }, (ack) => {
+        if (ack?.error) {
+            if (ack.error.name === 'DOC_NOT_FOUND')
+                return {};
+            throw new Error(ackErrorMessage(ack, "load-doc failed") || "load-doc failed");
+        }
+        return ack?.data || {};
+    });
+}
+export async function pushDocUpdate(socket, workspaceId, docId, updateBase64) {
+    return emitWithAck(socket, 'space:push-doc-update', { spaceType: 'workspace', spaceId: workspaceId, docId, update: updateBase64 }, (ack) => {
+        const message = ackErrorMessage(ack, "push-doc-update failed");
+        if (message)
+            throw new Error(message);
+        return ack?.data?.timestamp || Date.now();
+    });
+}
+export function deleteDoc(socket, workspaceId, docId) {
+    socket.emit('space:delete-doc', { spaceType: 'workspace', spaceId: workspaceId, docId });
+}