affine-mcp-server 1.7.1 → 1.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 A Model Context Protocol (MCP) server that integrates with AFFiNE (self‑hosted or cloud). It exposes AFFiNE workspaces and documents to AI assistants over stdio (default) or HTTP (`/mcp`).
 
-[![Version](https://img.shields.io/badge/version-1.7.1-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-1.8.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
 [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.17.2-green)](https://github.com/modelcontextprotocol/typescript-sdk)
 [![CI](https://github.com/dawncr0w/affine-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/dawncr0w/affine-mcp-server/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
@@ -16,16 +16,16 @@ A Model Context Protocol (MCP) server that integrates with AFFiNE (self‑hosted
 - Purpose: Manage AFFiNE workspaces and documents through MCP
 - Transport: stdio (default) and optional HTTP (`/mcp`) for remote MCP deployments
 - Auth: Token, Cookie, or Email/Password (priority order)
-- Tools: 43 focused tools with WebSocket-based document editing
+- Tools: 46 focused tools with WebSocket-based document editing
 - Status: Active
  
-> New in v1.7.1: Fixed MCP-created document structure parity with AFFiNE UI (`sys:parent` handling) and callout text rendering, plus regression coverage for UI visibility paths.
+> New in v1.8.0: Added database cell read/write tools, fixed Kanban row title persistence, and added CLI version commands.
 
 ## Features
 
 - Workspace: create (with initial doc), read, update, delete
 - Documents: list/get/read/publish/revoke + create/append/replace/delete + markdown import/export + tags (WebSocket‑based)
-- Database workflows: create database blocks, then add columns/rows via MCP tools
+- Database workflows: create database blocks, add columns and rows, and read or update cell values via MCP tools
 - Comments: full CRUD and resolve
 - Version History: list
 - Users & Tokens: current user, sign in, profile/settings, and personal access tokens
@@ -95,6 +95,7 @@ The MCP server will use these credentials automatically.
 Other CLI commands:
 - `affine-mcp status` — show current config and test connection
 - `affine-mcp logout` — remove stored credentials
+- `affine-mcp --version` / `-v` / `version` — print the installed CLI version and exit
 
 ### Environment variables
 
@@ -326,7 +327,10 @@ Endpoints currently available:
 - `append_paragraph` – append a paragraph block (WebSocket)
 - `append_block` – append canonical block types (text/list/code/media/embed/database/edgeless) with strict validation and placement control (`data_view` currently falls back to database)
 - `add_database_column` – add a column to a database block (`rich-text`, `select`, `multi-select`, `number`, `checkbox`, `link`, `date`)
-- `add_database_row` – add a row to a database block with values mapped by column name/ID
+- `add_database_row` – add a row to a database block with values mapped by column name/ID (`title` / `Title` updates the built-in row title)
+- `read_database_cells` – read row titles plus decoded database cell values with optional row / column filters
+- `update_database_cell` – update a single database cell or the built-in row title (`createOption` defaults to `true` for select fields)
+- `update_database_row` – batch update multiple cells on a database row (`createOption` defaults to `true` for select fields)
 - `append_markdown` – append markdown content to an existing document
 - `replace_doc_with_markdown` – replace the main note content with markdown content
 - `delete_doc` – delete a document (WebSocket)
@@ -374,7 +378,7 @@ npm run pack:check
 - CI validates that `registerTool(...)` declarations match the manifest exactly.
 - For full tool-surface verification, run `npm run test:comprehensive`.
 - For full environment verification, run `npm run test:e2e` (Docker + MCP + Playwright).
-- Additional focused runners: `npm run test:db-create`, `npm run test:bearer`, `npm run test:playwright`.
+- Additional focused runners: `npm run test:db-create`, `npm run test:db-cells`, `npm run test:bearer`, `npm run test:cli-version`, `npm run test:playwright`.
 
 ## Troubleshooting
 
@@ -409,6 +413,25 @@ Workspace visibility
 
 ## Version History
 
+### 1.8.0 (2026‑03‑09)
+- Added `read_database_cells`, `update_database_cell`, and `update_database_row` for database cell-level workflows
+- Fixed `add_database_row` so `title` / `Title` persists to the Kanban card header text
+- Added CLI version commands: `affine-mcp --version`, `affine-mcp -v`, and `affine-mcp version`
+- Added focused regression runners for database cells and CLI version support
+- Verified release gates with `npm run ci`, `npm run test:cli-version`, and live `npm run test:db-cells`
+
+### 1.7.2 (2026‑03‑04)
+- Fixed MCP tag persistence to use AFFiNE canonical tag option IDs so tags are visible in Web/App UI
+- Added backward-compatible tag normalization for legacy string tag entries
+- Added tag visibility regression coverage (`tests/test-tag-visibility.mjs`, `tests/playwright/verify-tag-visibility.pw.ts`)
+- Hardened E2E credential bootstrap with configurable health retries, retry attempts, and Docker diagnostics on failure
+- Verified CI gates (`validate`, `e2e`) for PR #46 and local `npm run ci`
+
+### 1.7.1 (2026‑03‑03)
+- Fixed MCP-created document structure parity with AFFiNE UI (`sys:parent` handling)
+- Fixed callout text rendering parity in AFFiNE UI for MCP-created blocks
+- Added regression assertions for visibility-sensitive document creation paths
+
 ### 1.7.0 (2026‑02‑27)
 - Added Streamable HTTP MCP support on `/mcp` for remote hosting while keeping legacy SSE compatibility paths (`/sse`, `/messages`)
 - Added HTTP deployment controls: `AFFINE_MCP_HTTP_HOST`, `AFFINE_MCP_HTTP_TOKEN`, `AFFINE_MCP_HTTP_ALLOWED_ORIGINS`, `AFFINE_MCP_HTTP_ALLOW_ALL_ORIGINS`

package/dist/index.js

@@ -15,8 +15,13 @@ import { loginWithPassword } from "./auth.js";
 import { registerAuthTools } from "./tools/auth.js";
 import { runCli } from "./cli.js";
 import { startHttpMcpServer } from "./sse.js";
-// CLI subcommands: affine-mcp login|status|logout
-const subcommand = process.argv[2];
+// CLI commands: affine-mcp login|status|logout|version
+const rawArgs = process.argv.slice(2);
+const subcommand = rawArgs[0] === "--" ? rawArgs[1] : rawArgs[0];
+if (subcommand === "--version" || subcommand === "-v" || subcommand === "version") {
+    console.log(VERSION);
+    process.exit(0);
+}
 if (subcommand && await runCli(subcommand)) {
     process.exit(0);
 }

package/dist/tools/docs.js

@@ -118,6 +118,11 @@ export function registerDocTools(server, gql, defaults) {
         }
         return normalized;
     }
+    const TAG_OPTION_COLORS = [
+        "var(--affine-tag-blue)", "var(--affine-tag-green)", "var(--affine-tag-red)",
+        "var(--affine-tag-orange)", "var(--affine-tag-purple)", "var(--affine-tag-yellow)",
+        "var(--affine-tag-teal)", "var(--affine-tag-pink)", "var(--affine-tag-gray)",
+    ];
     function getStringArray(value) {
         if (!(value instanceof Y.Array)) {
             return [];
@@ -146,23 +151,235 @@ export function registerDocTools(server, gql, defaults) {
         target.set(key, next);
         return next;
     }
-    function hasTag(tagValues, tag, ignoreCase) {
-        const normalizedTag = ignoreCase ? tag.toLocaleLowerCase() : tag;
-        return tagValues.some((entry) => (ignoreCase ? entry.toLocaleLowerCase() : entry) === normalizedTag);
+    function getYMap(target, key) {
+        const value = target.get(key);
+        if (!(value instanceof Y.Map)) {
+            return null;
+        }
+        return value;
     }
-    function findTagIndex(tags, tag, ignoreCase) {
-        const normalizedTag = ignoreCase ? tag.toLocaleLowerCase() : tag;
-        let index = -1;
-        tags.forEach((entry, i) => {
-            if (index >= 0 || typeof entry !== "string") {
+    function ensureYMap(target, key) {
+        const current = getYMap(target, key);
+        if (current) {
+            return current;
+        }
+        const next = new Y.Map();
+        target.set(key, next);
+        return next;
+    }
+    function getWorkspaceTagOptionsArray(meta) {
+        const properties = getYMap(meta, "properties");
+        if (!properties) {
+            return null;
+        }
+        const tags = getYMap(properties, "tags");
+        if (!tags) {
+            return null;
+        }
+        const options = tags.get("options");
+        if (!(options instanceof Y.Array)) {
+            return null;
+        }
+        return options;
+    }
+    function ensureWorkspaceTagOptionsArray(meta) {
+        const properties = ensureYMap(meta, "properties");
+        const tags = ensureYMap(properties, "tags");
+        const existing = tags.get("options");
+        if (existing instanceof Y.Array) {
+            return existing;
+        }
+        const next = new Y.Array();
+        tags.set("options", next);
+        return next;
+    }
+    function asNumberOrNull(value) {
+        return typeof value === "number" ? value : null;
+    }
+    function parseWorkspaceTagOption(raw) {
+        let id;
+        let value;
+        let color;
+        let createDate;
+        let updateDate;
+        if (raw instanceof Y.Map) {
+            id = raw.get("id");
+            value = raw.get("value");
+            color = raw.get("color");
+            createDate = raw.get("createDate");
+            updateDate = raw.get("updateDate");
+        }
+        else if (raw && typeof raw === "object") {
+            id = raw.id;
+            value = raw.value;
+            color = raw.color;
+            createDate = raw.createDate;
+            updateDate = raw.updateDate;
+        }
+        else {
+            return null;
+        }
+        if (typeof id !== "string" || id.trim().length === 0) {
+            return null;
+        }
+        if (typeof value !== "string" || value.trim().length === 0) {
+            return null;
+        }
+        return {
+            id,
+            value,
+            color: typeof color === "string" && color.trim().length > 0 ? color : TAG_OPTION_COLORS[0],
+            createDate: asNumberOrNull(createDate),
+            updateDate: asNumberOrNull(updateDate),
+        };
+    }
+    function getWorkspaceTagOptions(meta) {
+        const options = getWorkspaceTagOptionsArray(meta);
+        if (!options) {
+            return [];
+        }
+        const parsed = [];
+        options.forEach((raw) => {
+            const option = parseWorkspaceTagOption(raw);
+            if (option) {
+                parsed.push(option);
+            }
+        });
+        return parsed;
+    }
+    function getWorkspaceTagOptionMaps(meta) {
+        const options = getWorkspaceTagOptions(meta);
+        const byId = new Map();
+        const byValueLower = new Map();
+        for (const option of options) {
+            if (!byId.has(option.id)) {
+                byId.set(option.id, option);
+            }
+            const key = option.value.toLocaleLowerCase();
+            if (!byValueLower.has(key)) {
+                byValueLower.set(key, option);
+            }
+        }
+        return { options, byId, byValueLower };
+    }
+    function resolveTagLabels(tagEntries, byId) {
+        const deduped = new Set();
+        const resolved = [];
+        for (const entry of tagEntries) {
+            const raw = entry.trim();
+            if (!raw) {
+                continue;
+            }
+            const option = byId.get(raw);
+            const label = (option ? option.value : raw).trim();
+            if (!label) {
+                continue;
+            }
+            const dedupeKey = label.toLocaleLowerCase();
+            if (deduped.has(dedupeKey)) {
+                continue;
+            }
+            deduped.add(dedupeKey);
+            resolved.push(label);
+        }
+        return resolved;
+    }
+    function ensureWorkspaceTagOption(meta, tag) {
+        const normalizedTag = normalizeTag(tag);
+        const maps = getWorkspaceTagOptionMaps(meta);
+        const existing = maps.byValueLower.get(normalizedTag.toLocaleLowerCase());
+        if (existing) {
+            return { option: existing, created: false };
+        }
+        const optionsArray = ensureWorkspaceTagOptionsArray(meta);
+        const color = TAG_OPTION_COLORS[maps.options.length % TAG_OPTION_COLORS.length];
+        const now = Date.now();
+        const option = {
+            id: generateId(),
+            value: normalizedTag,
+            color,
+            createDate: now,
+            updateDate: now,
+        };
+        const optionMap = new Y.Map();
+        optionMap.set("id", option.id);
+        optionMap.set("value", option.value);
+        optionMap.set("color", option.color);
+        optionMap.set("createDate", now);
+        optionMap.set("updateDate", now);
+        optionsArray.push([optionMap]);
+        return { option, created: true };
+    }
+    function collectMatchingTagIndexes(tags, requestedTag, option, ignoreCase) {
+        const normalizedRequested = ignoreCase ? requestedTag.toLocaleLowerCase() : requestedTag;
+        const normalizedOptionId = option
+            ? (ignoreCase ? option.id.toLocaleLowerCase() : option.id)
+            : null;
+        const normalizedOptionValue = option
+            ? (ignoreCase ? option.value.toLocaleLowerCase() : option.value)
+            : null;
+        const indexes = [];
+        tags.forEach((entry, index) => {
+            if (typeof entry !== "string") {
                 return;
             }
             const current = ignoreCase ? entry.toLocaleLowerCase() : entry;
-            if (current === normalizedTag) {
-                index = i;
+            if (current === normalizedRequested ||
+                (normalizedOptionId && current === normalizedOptionId) ||
+                (normalizedOptionValue && current === normalizedOptionValue)) {
+                indexes.push(index);
             }
         });
-        return index;
+        return indexes;
+    }
+    function deleteArrayIndexes(arr, indexes) {
+        if (indexes.length === 0) {
+            return false;
+        }
+        const sorted = [...indexes].sort((a, b) => b - a);
+        for (const index of sorted) {
+            arr.delete(index, 1);
+        }
+        return true;
+    }
+    function syncTagArrayToOption(tags, requestedTag, option) {
+        const optionId = option.id.toLocaleLowerCase();
+        const optionValue = option.value.toLocaleLowerCase();
+        const requested = requestedTag.toLocaleLowerCase();
+        let existed = false;
+        let hasCanonicalId = false;
+        const removeIndexes = [];
+        tags.forEach((entry, index) => {
+            if (typeof entry !== "string") {
+                return;
+            }
+            const current = entry.toLocaleLowerCase();
+            const matched = current === optionId || current === optionValue || current === requested;
+            if (!matched) {
+                return;
+            }
+            existed = true;
+            if (current === optionId) {
+                if (hasCanonicalId) {
+                    removeIndexes.push(index);
+                }
+                else {
+                    hasCanonicalId = true;
+                }
+                return;
+            }
+            removeIndexes.push(index);
+        });
+        let changed = deleteArrayIndexes(tags, removeIndexes);
+        if (!hasCanonicalId) {
+            tags.push([option.id]);
+            changed = true;
+        }
+        return { existed, changed };
+    }
+    function hasTag(tagValues, tag, ignoreCase) {
+        const normalizedTag = ignoreCase ? tag.toLocaleLowerCase() : tag;
+        return tagValues.some((entry) => (ignoreCase ? entry.toLocaleLowerCase() : entry) === normalizedTag);
     }
     function getWorkspacePageEntries(meta) {
         const pages = meta.get("pages");
@@ -1373,9 +1590,9 @@ export function registerDocTools(server, gql, defaults) {
         }
         return tableData;
     }
-    function collectDocForMarkdown(doc) {
+    function collectDocForMarkdown(doc, tagOptionsById = new Map()) {
         const meta = doc.getMap("meta");
-        const tags = getStringArray(getTagArray(meta));
+        const tags = resolveTagLabels(getStringArray(getTagArray(meta)), tagOptionsById);
         const blocks = doc.getMap("blocks");
         const pageId = findBlockIdByFlavour(blocks, "affine:page");
         const noteId = findBlockIdByFlavour(blocks, "affine:note");
@@ -1640,8 +1857,10 @@ export function registerDocTools(server, gql, defaults) {
                     Y.applyUpdate(wsDoc, Buffer.from(snapshot.missing, "base64"));
                     const meta = wsDoc.getMap("meta");
                     const pages = getWorkspacePageEntries(meta);
+                    const { byId } = getWorkspaceTagOptionMaps(meta);
                     for (const page of pages) {
-                        tagsByDocId.set(page.id, getStringArray(page.tagsArray));
+                        const tagEntries = getStringArray(page.tagsArray);
+                        tagsByDocId.set(page.id, resolveTagLabels(tagEntries, byId));
                     }
                 }
             }
@@ -1700,9 +1919,10 @@ export function registerDocTools(server, gql, defaults) {
             Y.applyUpdate(wsDoc, Buffer.from(snapshot.missing, "base64"));
             const meta = wsDoc.getMap("meta");
             const pages = getWorkspacePageEntries(meta);
+            const { options, byId } = getWorkspaceTagOptionMaps(meta);
             const tagCounts = new Map();
-            for (const tag of getStringArray(getTagArray(meta))) {
-                const normalized = tag.trim();
+            for (const option of options) {
+                const normalized = option.value.trim();
                 if (!normalized || tagCounts.has(normalized)) {
                     continue;
                 }
@@ -1710,7 +1930,8 @@ export function registerDocTools(server, gql, defaults) {
             }
             for (const page of pages) {
                 const uniqueTags = new Set();
-                for (const tag of getStringArray(page.tagsArray)) {
+                const resolved = resolveTagLabels(getStringArray(page.tagsArray), byId);
+                for (const tag of resolved) {
                     const normalized = tag.trim();
                     if (!normalized) {
                         continue;
@@ -1761,18 +1982,22 @@ export function registerDocTools(server, gql, defaults) {
             Y.applyUpdate(wsDoc, Buffer.from(snapshot.missing, "base64"));
             const meta = wsDoc.getMap("meta");
             const pages = getWorkspacePageEntries(meta);
+            const { byId } = getWorkspaceTagOptionMaps(meta);
             const docs = pages
                 .map((page) => {
-                const tags = getStringArray(page.tagsArray);
+                const rawTags = getStringArray(page.tagsArray);
+                const tags = resolveTagLabels(rawTags, byId);
                 return {
                     id: page.id,
                     title: page.title,
                     createDate: page.createDate,
                     updatedDate: page.updatedDate,
                     tags,
+                    rawTags,
                 };
             })
-                .filter((page) => hasTag(page.tags, tag, ignoreCase));
+                .filter((page) => hasTag(page.tags, tag, ignoreCase) || hasTag(page.rawTags, tag, ignoreCase))
+                .map(({ rawTags: _rawTags, ...page }) => page);
             return text({
                 workspaceId,
                 tag,
@@ -1813,11 +2038,10 @@ export function registerDocTools(server, gql, defaults) {
             Y.applyUpdate(wsDoc, Buffer.from(snapshot.missing, "base64"));
             const prevSV = Y.encodeStateVector(wsDoc);
             const meta = wsDoc.getMap("meta");
-            const registry = ensureTagArray(meta);
-            if (findTagIndex(registry, tag, true) >= 0) {
+            const { created } = ensureWorkspaceTagOption(meta, tag);
+            if (!created) {
                 return text({ workspaceId, tag, created: false });
             }
-            registry.push([tag]);
             const delta = Y.encodeStateAsUpdate(wsDoc, prevSV);
             await pushDocUpdate(socket, workspaceId, workspaceId, Buffer.from(delta).toString("base64"));
             return text({ workspaceId, tag, created: true });
@@ -1857,17 +2081,11 @@ export function registerDocTools(server, gql, defaults) {
             if (!page) {
                 throw new Error(`docId ${parsed.docId} is not present in workspace ${workspaceId}`);
             }
+            const { option, created: optionCreated } = ensureWorkspaceTagOption(wsMeta, tag);
             const pageTags = ensureTagArray(page.entry);
-            const existedInDoc = findTagIndex(pageTags, tag, true) >= 0;
-            if (!existedInDoc) {
-                pageTags.push([tag]);
-            }
-            const registry = ensureTagArray(wsMeta);
-            const existedInRegistry = findTagIndex(registry, tag, true) >= 0;
-            if (!existedInRegistry) {
-                registry.push([tag]);
-            }
-            if (!existedInDoc || !existedInRegistry) {
+            const pageSync = syncTagArrayToOption(pageTags, tag, option);
+            const wsChanged = optionCreated || pageSync.changed;
+            if (wsChanged) {
                 const wsDelta = Y.encodeStateAsUpdate(wsDoc, wsPrevSV);
                 await pushDocUpdate(socket, workspaceId, workspaceId, Buffer.from(wsDelta).toString("base64"));
             }
@@ -1883,20 +2101,20 @@ export function registerDocTools(server, gql, defaults) {
                 const docPrevSV = Y.encodeStateVector(doc);
                 const docMeta = doc.getMap("meta");
                 const docTags = ensureTagArray(docMeta);
-                const existedInDocMeta = findTagIndex(docTags, tag, true) >= 0;
-                if (!existedInDocMeta) {
-                    docTags.push([tag]);
+                const docSync = syncTagArrayToOption(docTags, tag, option);
+                if (docSync.changed) {
                     const docDelta = Y.encodeStateAsUpdate(doc, docPrevSV);
                     await pushDocUpdate(socket, workspaceId, parsed.docId, Buffer.from(docDelta).toString("base64"));
                 }
                 docMetaSynced = true;
             }
+            const { byId } = getWorkspaceTagOptionMaps(wsMeta);
             return text({
                 workspaceId,
                 docId: parsed.docId,
                 tag,
-                added: !existedInDoc,
-                tags: getStringArray(pageTags),
+                added: !pageSync.existed,
+                tags: resolveTagLabels(getStringArray(pageTags), byId),
                 docMetaSynced,
                 warning,
             });
@@ -1937,10 +2155,11 @@ export function registerDocTools(server, gql, defaults) {
             if (!page) {
                 throw new Error(`docId ${parsed.docId} is not present in workspace ${workspaceId}`);
             }
+            const option = getWorkspaceTagOptionMaps(wsMeta).byValueLower.get(tag.toLocaleLowerCase()) || null;
             const pageTags = ensureTagArray(page.entry);
-            const pageTagIndex = findTagIndex(pageTags, tag, true);
-            if (pageTagIndex >= 0) {
-                pageTags.delete(pageTagIndex, 1);
+            const pageTagIndexes = collectMatchingTagIndexes(pageTags, tag, option, true);
+            const pageRemoved = deleteArrayIndexes(pageTags, pageTagIndexes);
+            if (pageRemoved) {
                 const wsDelta = Y.encodeStateAsUpdate(wsDoc, wsPrevSV);
                 await pushDocUpdate(socket, workspaceId, workspaceId, Buffer.from(wsDelta).toString("base64"));
             }
@@ -1956,20 +2175,20 @@ export function registerDocTools(server, gql, defaults) {
                 const docPrevSV = Y.encodeStateVector(doc);
                 const docMeta = doc.getMap("meta");
                 const docTags = ensureTagArray(docMeta);
-                const docTagIndex = findTagIndex(docTags, tag, true);
-                if (docTagIndex >= 0) {
-                    docTags.delete(docTagIndex, 1);
+                const docTagIndexes = collectMatchingTagIndexes(docTags, tag, option, true);
+                if (deleteArrayIndexes(docTags, docTagIndexes)) {
                     const docDelta = Y.encodeStateAsUpdate(doc, docPrevSV);
                     await pushDocUpdate(socket, workspaceId, parsed.docId, Buffer.from(docDelta).toString("base64"));
                 }
                 docMetaSynced = true;
             }
+            const { byId } = getWorkspaceTagOptionMaps(wsMeta);
             return text({
                 workspaceId,
                 docId: parsed.docId,
                 tag,
-                removed: pageTagIndex >= 0,
-                tags: getStringArray(pageTags),
+                removed: pageRemoved,
+                tags: resolveTagLabels(getStringArray(pageTags), byId),
                 docMetaSynced,
                 warning,
             });
@@ -2014,6 +2233,13 @@ export function registerDocTools(server, gql, defaults) {
         const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
         try {
             await joinWorkspace(socket, workspaceId);
+            let tagOptionsById = new Map();
+            const workspaceSnapshot = await loadDoc(socket, workspaceId, workspaceId);
+            if (workspaceSnapshot.missing) {
+                const workspaceDoc = new Y.Doc();
+                Y.applyUpdate(workspaceDoc, Buffer.from(workspaceSnapshot.missing, "base64"));
+                tagOptionsById = getWorkspaceTagOptionMaps(workspaceDoc.getMap("meta")).byId;
+            }
             const snapshot = await loadDoc(socket, workspaceId, parsed.docId);
             if (!snapshot.missing) {
                 return text({
@@ -2029,7 +2255,7 @@ export function registerDocTools(server, gql, defaults) {
             const doc = new Y.Doc();
             Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
             const meta = doc.getMap("meta");
-            const tags = getStringArray(getTagArray(meta));
+            const tags = resolveTagLabels(getStringArray(getTagArray(meta)), tagOptionsById);
             const blocks = doc.getMap("blocks");
             const pageId = findBlockIdByFlavour(blocks, "affine:page");
             const noteId = findBlockIdByFlavour(blocks, "affine:note");
@@ -2238,6 +2464,13 @@ export function registerDocTools(server, gql, defaults) {
         const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
         try {
             await joinWorkspace(socket, workspaceId);
+            let tagOptionsById = new Map();
+            const workspaceSnapshot = await loadDoc(socket, workspaceId, workspaceId);
+            if (workspaceSnapshot.missing) {
+                const wsDoc = new Y.Doc();
+                Y.applyUpdate(wsDoc, Buffer.from(workspaceSnapshot.missing, "base64"));
+                tagOptionsById = getWorkspaceTagOptionMaps(wsDoc.getMap("meta")).byId;
+            }
             const snapshot = await loadDoc(socket, workspaceId, parsed.docId);
             if (!snapshot.missing) {
                 return text({
@@ -2256,7 +2489,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             const doc = new Y.Doc();
             Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
-            const collected = collectDocForMarkdown(doc);
+            const collected = collectDocForMarkdown(doc, tagOptionsById);
             const rendered = renderBlocksToMarkdown({
                 rootBlockIds: collected.rootBlockIds,
                 blocksById: collected.blocksById,
@@ -2490,7 +2723,6 @@ export function registerDocTools(server, gql, defaults) {
         description: 'Delete a document and remove from workspace list',
         inputSchema: { workspaceId: z.string().optional(), docId: z.string() },
     }, deleteDocHandler);
-    // ── helpers for database select columns ──
     /** Read column definitions including select options from a database block */
     function readColumnDefs(dbBlock) {
         const columnsRaw = dbBlock.get("prop:columns");
@@ -2528,17 +2760,111 @@ export function registerDocTools(server, gql, defaults) {
         });
         return defs;
     }
+    function isTitleAliasKey(value) {
+        return value.trim().toLowerCase() === "title";
+    }
+    function buildDatabaseColumnLookup(columnDefs) {
+        const colById = new Map();
+        const colByName = new Map();
+        const colByNameLower = new Map();
+        let titleCol = null;
+        for (const col of columnDefs) {
+            colById.set(col.id, col);
+            if (col.name) {
+                colByName.set(col.name, col);
+                colByNameLower.set(col.name.trim().toLowerCase(), col);
+            }
+            if (!titleCol && col.type === "title") {
+                titleCol = col;
+            }
+        }
+        return { columnDefs, colById, colByName, colByNameLower, titleCol };
+    }
+    function findDatabaseColumn(key, lookup) {
+        return lookup.colByName.get(key)
+            || lookup.colById.get(key)
+            || lookup.colByNameLower.get(key.trim().toLowerCase())
+            || null;
+    }
+    function availableDatabaseColumns(lookup) {
+        return ["title", ...lookup.columnDefs.map(col => col.name || col.id)].join(", ");
+    }
+    function getDatabaseRowIds(dbBlock) {
+        return childIdsFrom(dbBlock.get("sys:children"));
+    }
+    function readDatabaseRowTitle(rowBlock) {
+        return asText(rowBlock.get("prop:text"));
+    }
+    function resolveDatabaseTitleValue(cells, lookup) {
+        if (lookup.titleCol) {
+            const value = cells[lookup.titleCol.name] ?? cells[lookup.titleCol.id];
+            if (value !== undefined) {
+                return String(value ?? "");
+            }
+        }
+        for (const [key, value] of Object.entries(cells)) {
+            if (isTitleAliasKey(key)) {
+                return String(value ?? "");
+            }
+        }
+        const namedTitleColumn = lookup.colByNameLower.get("title");
+        if (namedTitleColumn) {
+            const value = cells[namedTitleColumn.name] ?? cells[namedTitleColumn.id];
+            if (value !== undefined) {
+                return String(value ?? "");
+            }
+        }
+        return "";
+    }
+    function ensureDatabaseRowCells(cellsMap, rowBlockId) {
+        const existing = cellsMap.get(rowBlockId);
+        if (existing instanceof Y.Map) {
+            return existing;
+        }
+        const rowCells = new Y.Map();
+        cellsMap.set(rowBlockId, rowCells);
+        return rowCells;
+    }
+    function getDatabaseRowBlock(blocks, databaseBlockId, rowBlockId) {
+        const rowBlock = findBlockById(blocks, rowBlockId);
+        if (!rowBlock) {
+            throw new Error(`Row block '${rowBlockId}' not found`);
+        }
+        if (rowBlock.get("sys:parent") !== databaseBlockId) {
+            throw new Error(`Row block '${rowBlockId}' does not belong to database '${databaseBlockId}'`);
+        }
+        if (rowBlock.get("sys:flavour") !== "affine:paragraph") {
+            throw new Error(`Row block '${rowBlockId}' is not a database row paragraph`);
+        }
+        return rowBlock;
+    }
+    function databaseArrayValues(value) {
+        if (value instanceof Y.Array) {
+            const entries = [];
+            value.forEach(entry => {
+                entries.push(entry);
+            });
+            return entries;
+        }
+        if (Array.isArray(value)) {
+            return value;
+        }
+        return [];
+    }
     const SELECT_COLORS = [
         "var(--affine-tag-blue)", "var(--affine-tag-green)", "var(--affine-tag-red)",
         "var(--affine-tag-orange)", "var(--affine-tag-purple)", "var(--affine-tag-yellow)",
         "var(--affine-tag-teal)", "var(--affine-tag-pink)", "var(--affine-tag-gray)",
     ];
     /** Find or create a select option for a column, mutating the column's data in place */
-    function resolveSelectOptionId(col, valueText) {
+    function resolveSelectOptionId(col, valueText, createOption = true) {
         // Try exact match first
         const existing = col.options.find(o => o.value === valueText);
         if (existing)
             return existing.id;
+        if (!createOption) {
+            throw new Error(`Column "${col.name}": option "${valueText}" not found`);
+        }
         // Create new option
         const newId = generateId();
         const colorIdx = col.options.length % SELECT_COLORS.length;
@@ -2565,43 +2891,172 @@ export function registerDocTools(server, gql, defaults) {
         }
         return newId;
     }
+    function decodeDatabaseCellValue(col, cellEntry) {
+        const rawValue = cellEntry instanceof Y.Map ? cellEntry.get("value") : cellEntry?.value;
+        const base = {
+            columnId: col.id,
+            type: col.type,
+        };
+        switch (col.type) {
+            case "rich-text":
+            case "title":
+                return { ...base, value: richTextValueToString(rawValue) || null };
+            case "select": {
+                const optionId = asStringOrNull(rawValue);
+                const option = col.options.find(entry => entry.id === optionId) || null;
+                return {
+                    ...base,
+                    value: option?.value ?? optionId ?? null,
+                    optionId: optionId ?? null,
+                };
+            }
+            case "multi-select": {
+                const optionIds = databaseArrayValues(rawValue).map(entry => String(entry));
+                const values = optionIds.map(optionId => col.options.find(entry => entry.id === optionId)?.value ?? optionId);
+                return {
+                    ...base,
+                    value: values,
+                    optionIds,
+                };
+            }
+            case "number": {
+                const numericValue = typeof rawValue === "number" ? rawValue : Number(rawValue);
+                return {
+                    ...base,
+                    value: Number.isFinite(numericValue) ? numericValue : null,
+                };
+            }
+            case "checkbox":
+                return { ...base, value: typeof rawValue === "boolean" ? rawValue : !!rawValue };
+            case "date": {
+                const numericValue = typeof rawValue === "number" ? rawValue : Number(rawValue);
+                return {
+                    ...base,
+                    value: Number.isFinite(numericValue) ? numericValue : null,
+                };
+            }
+            case "link":
+                return { ...base, value: rawValue == null ? null : String(rawValue) };
+            default:
+                return {
+                    ...base,
+                    value: typeof rawValue === "string" || rawValue instanceof Y.Text || Array.isArray(rawValue)
+                        ? richTextValueToString(rawValue)
+                        : rawValue ?? null,
+                };
+        }
+    }
+    function writeDatabaseCellValue(rowCells, col, value, createOption) {
+        const cellValue = new Y.Map();
+        cellValue.set("columnId", col.id);
+        switch (col.type) {
+            case "rich-text":
+            case "title":
+                cellValue.set("value", makeText(String(value ?? "")));
+                break;
+            case "number": {
+                const num = Number(value);
+                if (Number.isNaN(num)) {
+                    throw new Error(`Column "${col.name}": expected a number, got ${JSON.stringify(value)}`);
+                }
+                cellValue.set("value", num);
+                break;
+            }
+            case "checkbox": {
+                let bool;
+                if (typeof value === "boolean") {
+                    bool = value;
+                }
+                else if (typeof value === "string") {
+                    const lower = value.toLowerCase().trim();
+                    bool = lower === "true" || lower === "1" || lower === "yes";
+                }
+                else {
+                    bool = !!value;
+                }
+                cellValue.set("value", bool);
+                break;
+            }
+            case "select":
+                cellValue.set("value", resolveSelectOptionId(col, String(value ?? ""), createOption));
+                break;
+            case "multi-select": {
+                const labels = Array.isArray(value) ? value.map(String) : [String(value ?? "")];
+                const optionIds = new Y.Array();
+                optionIds.push(labels.map(label => resolveSelectOptionId(col, label, createOption)));
+                cellValue.set("value", optionIds);
+                break;
+            }
+            case "date": {
+                const numericValue = typeof value === "number"
+                    ? value
+                    : Number.isNaN(Number(value)) ? Date.parse(String(value)) : Number(value);
+                if (!Number.isFinite(numericValue)) {
+                    throw new Error(`Column "${col.name}": expected a timestamp-compatible value, got ${JSON.stringify(value)}`);
+                }
+                cellValue.set("value", numericValue);
+                break;
+            }
+            case "link":
+                cellValue.set("value", String(value ?? ""));
+                break;
+            default:
+                if (typeof value === "string") {
+                    cellValue.set("value", makeText(value));
+                }
+                else {
+                    cellValue.set("value", value);
+                }
+        }
+        rowCells.set(col.id, cellValue);
+    }
+    async function loadDatabaseDocContext(workspaceId, docId, databaseBlockId) {
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        await joinWorkspace(socket, workspaceId);
+        const doc = new Y.Doc();
+        const snapshot = await loadDoc(socket, workspaceId, docId);
+        if (!snapshot.missing) {
+            socket.disconnect();
+            throw new Error("Document not found");
+        }
+        Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+        const prevSV = Y.encodeStateVector(doc);
+        const blocks = doc.getMap("blocks");
+        const dbBlock = findBlockById(blocks, databaseBlockId);
+        if (!dbBlock) {
+            socket.disconnect();
+            throw new Error(`Database block '${databaseBlockId}' not found`);
+        }
+        const dbFlavour = dbBlock.get("sys:flavour");
+        if (dbFlavour !== "affine:database") {
+            socket.disconnect();
+            throw new Error(`Block '${databaseBlockId}' is not a database (flavour: ${dbFlavour})`);
+        }
+        const cellsMap = dbBlock.get("prop:cells");
+        if (!(cellsMap instanceof Y.Map)) {
+            socket.disconnect();
+            throw new Error("Database block has no cells map");
+        }
+        const lookup = buildDatabaseColumnLookup(readColumnDefs(dbBlock));
+        return {
+            socket,
+            doc,
+            prevSV,
+            blocks,
+            dbBlock,
+            cellsMap,
+            ...lookup,
+        };
+    }
     // ADD DATABASE ROW
     const addDatabaseRowHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
         if (!workspaceId)
             throw new Error("workspaceId is required");
-        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
-        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
-        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        const ctx = await loadDatabaseDocContext(workspaceId, parsed.docId, parsed.databaseBlockId);
         try {
-            await joinWorkspace(socket, workspaceId);
-            const doc = new Y.Doc();
-            const snapshot = await loadDoc(socket, workspaceId, parsed.docId);
-            if (!snapshot.missing)
-                throw new Error("Document not found");
-            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
-            const prevSV = Y.encodeStateVector(doc);
-            const blocks = doc.getMap("blocks");
-            // Find the database block
-            const dbBlock = findBlockById(blocks, parsed.databaseBlockId);
-            if (!dbBlock)
-                throw new Error(`Database block '${parsed.databaseBlockId}' not found`);
-            const dbFlavour = dbBlock.get("sys:flavour");
-            if (dbFlavour !== "affine:database") {
-                throw new Error(`Block '${parsed.databaseBlockId}' is not a database (flavour: ${dbFlavour})`);
-            }
-            // Read column definitions with select options
-            const columnDefs = readColumnDefs(dbBlock);
-            // Build lookups
-            const colByName = new Map();
-            const colById = new Map();
-            for (const col of columnDefs) {
-                if (col.name)
-                    colByName.set(col.name, col);
-                colById.set(col.id, col);
-            }
-            // Identify the title column (first column, or type === "title")
-            const titleCol = columnDefs.find(c => c.type === "title") || null;
             // Create a new paragraph block as the row child of the database
             const rowBlockId = generateId();
             const rowBlock = new Y.Map();
@@ -2609,104 +3064,26 @@ export function registerDocTools(server, gql, defaults) {
             rowBlock.set("sys:parent", parsed.databaseBlockId);
             rowBlock.set("sys:children", new Y.Array());
             rowBlock.set("prop:type", "text");
-            // Title column value goes on the paragraph block's text
-            const titleValue = titleCol ? parsed.cells[titleCol.name] ?? parsed.cells[titleCol.id] ?? "" : "";
+            const titleValue = resolveDatabaseTitleValue(parsed.cells, ctx);
             rowBlock.set("prop:text", makeText(String(titleValue)));
-            blocks.set(rowBlockId, rowBlock);
+            ctx.blocks.set(rowBlockId, rowBlock);
             // Add row block to database's children
-            const dbChildren = ensureChildrenArray(dbBlock);
+            const dbChildren = ensureChildrenArray(ctx.dbBlock);
             dbChildren.push([rowBlockId]);
-            // Populate cells map on the database block
-            const cellsMap = dbBlock.get("prop:cells");
-            if (!(cellsMap instanceof Y.Map)) {
-                throw new Error("Database block has no cells map");
-            }
             // Create row cell map
-            const rowCells = new Y.Map();
+            const rowCells = ensureDatabaseRowCells(ctx.cellsMap, rowBlockId);
             for (const [key, value] of Object.entries(parsed.cells)) {
-                // Resolve column: try by name first, then by ID
-                const col = colByName.get(key) || colById.get(key);
+                const col = findDatabaseColumn(key, ctx);
                 if (!col) {
-                    throw new Error(`Column '${key}' not found. Available columns: ${columnDefs.map(c => c.name || c.id).join(", ")}`);
-                }
-                // Skip the title column — already stored on the paragraph block
-                if (titleCol && col.id === titleCol.id)
-                    continue;
-                // Create cell value based on column type
-                const cellValue = new Y.Map();
-                cellValue.set("columnId", col.id);
-                switch (col.type) {
-                    case "rich-text": {
-                        const yText = makeText(String(value ?? ""));
-                        cellValue.set("value", yText);
-                        break;
-                    }
-                    case "title": {
-                        // Handled above on the paragraph block; skip
+                    if (isTitleAliasKey(key)) {
                         continue;
                     }
-                    case "number": {
-                        const num = Number(value);
-                        if (Number.isNaN(num)) {
-                            throw new Error(`Column "${col.name}": expected a number, got ${JSON.stringify(value)}`);
-                        }
-                        cellValue.set("value", num);
-                        break;
-                    }
-                    case "checkbox": {
-                        let bool;
-                        if (typeof value === "boolean") {
-                            bool = value;
-                        }
-                        else if (typeof value === "string") {
-                            const lower = value.toLowerCase().trim();
-                            bool = lower === "true" || lower === "1" || lower === "yes";
-                        }
-                        else {
-                            bool = !!value;
-                        }
-                        cellValue.set("value", bool);
-                        break;
-                    }
-                    case "select": {
-                        // Resolve option ID by label text; auto-create if needed
-                        const optionId = resolveSelectOptionId(col, String(value ?? ""));
-                        cellValue.set("value", optionId);
-                        break;
-                    }
-                    case "multi-select": {
-                        const labels = Array.isArray(value) ? value.map(String) : [String(value ?? "")];
-                        const ids = labels.map(lbl => resolveSelectOptionId(col, lbl));
-                        cellValue.set("value", ids);
-                        break;
-                    }
-                    case "date": {
-                        const ts = Number(value);
-                        if (Number.isNaN(ts)) {
-                            throw new Error(`Column "${col.name}": expected a timestamp number, got ${JSON.stringify(value)}`);
-                        }
-                        cellValue.set("value", ts);
-                        break;
-                    }
-                    case "link": {
-                        cellValue.set("value", String(value ?? ""));
-                        break;
-                    }
-                    default: {
-                        // Fallback: store as rich-text
-                        if (typeof value === "string") {
-                            cellValue.set("value", makeText(value));
-                        }
-                        else {
-                            cellValue.set("value", value);
-                        }
-                    }
+                    throw new Error(`Column '${key}' not found. Available columns: ${availableDatabaseColumns(ctx)}`);
                 }
-                rowCells.set(col.id, cellValue);
+                writeDatabaseCellValue(rowCells, col, value, true);
             }
-            cellsMap.set(rowBlockId, rowCells);
-            const delta = Y.encodeStateAsUpdate(doc, prevSV);
-            await pushDocUpdate(socket, workspaceId, parsed.docId, Buffer.from(delta).toString("base64"));
+            const delta = Y.encodeStateAsUpdate(ctx.doc, ctx.prevSV);
+            await pushDocUpdate(ctx.socket, workspaceId, parsed.docId, Buffer.from(delta).toString("base64"));
             return text({
                 added: true,
                 rowBlockId,
@@ -2715,7 +3092,7 @@ export function registerDocTools(server, gql, defaults) {
             });
         }
         finally {
-            socket.disconnect();
+            ctx.socket.disconnect();
         }
     };
     server.registerTool("add_database_row", {
@@ -2728,6 +3105,164 @@ export function registerDocTools(server, gql, defaults) {
             cells: z.record(z.unknown()).describe("Map of column name (or column ID) to cell value. For select columns, pass the display label (option auto-created if new)."),
         },
     }, addDatabaseRowHandler);
+    const readDatabaseCellsHandler = async (parsed) => {
+        const workspaceId = parsed.workspaceId || defaults.workspaceId;
+        if (!workspaceId)
+            throw new Error("workspaceId is required");
+        const ctx = await loadDatabaseDocContext(workspaceId, parsed.docId, parsed.databaseBlockId);
+        try {
+            const requestedRows = parsed.rowBlockIds?.length
+                ? parsed.rowBlockIds
+                : getDatabaseRowIds(ctx.dbBlock);
+            const requestedColumns = parsed.columns?.length
+                ? parsed.columns.map(columnKey => {
+                    const col = findDatabaseColumn(columnKey, ctx);
+                    if (!col) {
+                        throw new Error(`Column '${columnKey}' not found. Available columns: ${availableDatabaseColumns(ctx)}`);
+                    }
+                    return col;
+                })
+                : ctx.columnDefs;
+            const requestedColumnIds = new Set(requestedColumns.map(col => col.id));
+            const rows = requestedRows.map(rowBlockId => {
+                const rowBlock = getDatabaseRowBlock(ctx.blocks, parsed.databaseBlockId, rowBlockId);
+                const title = readDatabaseRowTitle(rowBlock) || null;
+                const rowCells = ctx.cellsMap.get(rowBlockId);
+                const cells = {};
+                if (rowCells instanceof Y.Map) {
+                    for (const col of ctx.columnDefs) {
+                        if (ctx.titleCol && col.id === ctx.titleCol.id) {
+                            continue;
+                        }
+                        if (!requestedColumnIds.has(col.id)) {
+                            continue;
+                        }
+                        const cellEntry = rowCells.get(col.id);
+                        if (cellEntry === undefined) {
+                            continue;
+                        }
+                        cells[col.name || col.id] = decodeDatabaseCellValue(col, cellEntry);
+                    }
+                }
+                return {
+                    rowBlockId,
+                    title,
+                    cells,
+                };
+            });
+            return text({ rows });
+        }
+        finally {
+            ctx.socket.disconnect();
+        }
+    };
+    server.registerTool("read_database_cells", {
+        title: "Read Database Cells",
+        description: "Read row titles and database cell values from an AFFiNE database block.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID containing the database"),
+            databaseBlockId: z.string().min(1).describe("Block ID of the affine:database block"),
+            rowBlockIds: z.array(z.string().min(1)).optional().describe("Optional row block ID filter. Omit to return all rows."),
+            columns: z.array(z.string().min(1)).optional().describe("Optional column name or ID filter."),
+        },
+    }, readDatabaseCellsHandler);
+    const updateDatabaseCellHandler = async (parsed) => {
+        const workspaceId = parsed.workspaceId || defaults.workspaceId;
+        if (!workspaceId)
+            throw new Error("workspaceId is required");
+        const ctx = await loadDatabaseDocContext(workspaceId, parsed.docId, parsed.databaseBlockId);
+        try {
+            const rowBlock = getDatabaseRowBlock(ctx.blocks, parsed.databaseBlockId, parsed.rowBlockId);
+            const rowCells = ensureDatabaseRowCells(ctx.cellsMap, parsed.rowBlockId);
+            const col = findDatabaseColumn(parsed.column, ctx);
+            if (!col) {
+                if (!isTitleAliasKey(parsed.column)) {
+                    throw new Error(`Column '${parsed.column}' not found. Available columns: ${availableDatabaseColumns(ctx)}`);
+                }
+            }
+            else {
+                writeDatabaseCellValue(rowCells, col, parsed.value, parsed.createOption ?? true);
+            }
+            if (isTitleAliasKey(parsed.column) || (col && (col.type === "title" || isTitleAliasKey(col.name)))) {
+                rowBlock.set("prop:text", makeText(String(parsed.value ?? "")));
+            }
+            const delta = Y.encodeStateAsUpdate(ctx.doc, ctx.prevSV);
+            await pushDocUpdate(ctx.socket, workspaceId, parsed.docId, Buffer.from(delta).toString("base64"));
+            return text({
+                updated: true,
+                rowBlockId: parsed.rowBlockId,
+                column: parsed.column,
+                value: parsed.value ?? null,
+            });
+        }
+        finally {
+            ctx.socket.disconnect();
+        }
+    };
+    server.registerTool("update_database_cell", {
+        title: "Update Database Cell",
+        description: "Update a single cell on an existing AFFiNE database row. Use `title` to update the row title shown in Kanban card headers.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID containing the database"),
+            databaseBlockId: z.string().min(1).describe("Block ID of the affine:database block"),
+            rowBlockId: z.string().min(1).describe("Row paragraph block ID"),
+            column: z.string().min(1).describe("Column name or ID. Use `title` for the built-in row title."),
+            value: z.unknown().describe("New cell value"),
+            createOption: z.boolean().optional().describe("For select and multi-select columns, create the option label if it does not exist (default true)"),
+        },
+    }, updateDatabaseCellHandler);
+    const updateDatabaseRowHandler = async (parsed) => {
+        const workspaceId = parsed.workspaceId || defaults.workspaceId;
+        if (!workspaceId)
+            throw new Error("workspaceId is required");
+        const ctx = await loadDatabaseDocContext(workspaceId, parsed.docId, parsed.databaseBlockId);
+        try {
+            const rowBlock = getDatabaseRowBlock(ctx.blocks, parsed.databaseBlockId, parsed.rowBlockId);
+            const rowCells = ensureDatabaseRowCells(ctx.cellsMap, parsed.rowBlockId);
+            let titleValue = null;
+            for (const [key, value] of Object.entries(parsed.cells)) {
+                const col = findDatabaseColumn(key, ctx);
+                if (!col) {
+                    if (isTitleAliasKey(key)) {
+                        titleValue = String(value ?? "");
+                        continue;
+                    }
+                    throw new Error(`Column '${key}' not found. Available columns: ${availableDatabaseColumns(ctx)}`);
+                }
+                writeDatabaseCellValue(rowCells, col, value, parsed.createOption ?? true);
+                if (col.type === "title" || isTitleAliasKey(col.name)) {
+                    titleValue = String(value ?? "");
+                }
+            }
+            if (titleValue !== null) {
+                rowBlock.set("prop:text", makeText(titleValue));
+            }
+            const delta = Y.encodeStateAsUpdate(ctx.doc, ctx.prevSV);
+            await pushDocUpdate(ctx.socket, workspaceId, parsed.docId, Buffer.from(delta).toString("base64"));
+            return text({
+                updated: true,
+                rowBlockId: parsed.rowBlockId,
+                cellCount: Object.keys(parsed.cells).length,
+            });
+        }
+        finally {
+            ctx.socket.disconnect();
+        }
+    };
+    server.registerTool("update_database_row", {
+        title: "Update Database Row",
+        description: "Batch update multiple cells on an existing AFFiNE database row. Include `title` in the cells map to update the Kanban row title.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID containing the database"),
+            databaseBlockId: z.string().min(1).describe("Block ID of the affine:database block"),
+            rowBlockId: z.string().min(1).describe("Row paragraph block ID"),
+            cells: z.record(z.unknown()).describe("Map of column name (or column ID) to new cell value. Use `title` for the built-in row title."),
+            createOption: z.boolean().optional().describe("For select and multi-select columns, create the option label if it does not exist (default true)"),
+        },
+    }, updateDatabaseRowHandler);
     // ADD DATABASE COLUMN
     const addDatabaseColumnHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "affine-mcp-server",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "private": false,
   "type": "module",
   "description": "Model Context Protocol server for AFFiNE - enables AI assistants to interact with AFFiNE workspaces, documents, and collaboration features.",
@@ -33,11 +33,14 @@
     "start": "node dist/index.js",
     "start:http": "MCP_TRANSPORT=http node dist/index.js",
     "test": "npm run test:tool-manifest",
+    "test:cli-version": "node tests/test-cli-version.mjs",
     "test:tool-manifest": "node scripts/verify-tool-manifest.mjs",
     "test:comprehensive": "node test-comprehensive.mjs",
     "test:e2e": "bash tests/run-e2e.sh",
     "test:db-create": "node tests/test-database-creation.mjs",
+    "test:db-cells": "node tests/test-database-cells.mjs",
     "test:bearer": "node tests/test-bearer-auth.mjs",
+    "test:tag-visibility": "node tests/test-tag-visibility.mjs",
     "test:playwright": "npx playwright test --config tests/playwright/playwright.config.ts",
     "pack:check": "npm pack --dry-run",
     "ci": "npm run build && npm run test:tool-manifest && npm run pack:check",