affine-mcp-server 1.8.0 → 1.9.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.8.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-1.9.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: 46 focused tools with WebSocket-based document editing
+- Tools: 47 focused tools with WebSocket-based document editing
 - Status: Active
  
-> New in v1.8.0: Added database cell read/write tools, fixed Kanban row title persistence, and added CLI version commands.
+> New in v1.9.0: Added database schema discovery, preset-backed data views, self-bootstrapping comprehensive regression, focused supporting-tools coverage, and markdown callout round-trips.
 
 ## 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, add columns and rows, and read or update cell values via MCP tools
+- Database workflows: create database blocks, inspect schema, 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
@@ -325,9 +325,10 @@ Endpoints currently available:
 - `add_tag_to_doc` – attach a tag to a document
 - `remove_tag_from_doc` – detach a tag from a document
 - `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)
+- `append_block` – append canonical block types (text/list/code/media/embed/database/edgeless) with strict validation and placement control (`viewMode=kanban` enables preset-backed data views; `data_view` defaults to kanban)
 - `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 (`title` / `Title` updates the built-in row title)
+- `read_database_columns` – read database schema metadata including column IDs/types, select options, and table view column mappings
 - `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)
@@ -376,9 +377,10 @@ npm run pack:check
 
 - `tool-manifest.json` is the source of truth for publicly exposed tool names.
 - CI validates that `registerTool(...)` declarations match the manifest exactly.
-- For full tool-surface verification, run `npm run test:comprehensive`.
+- For full tool-surface verification, run `npm run test:comprehensive` (self-bootstraps a local Docker AFFiNE stack).
+- For pre-provisioned environments, use `npm run test:comprehensive:raw`.
 - For full environment verification, run `npm run test:e2e` (Docker + MCP + 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`.
+- Additional focused runners: `npm run test:db-create`, `npm run test:db-cells`, `npm run test:db-schema`, `npm run test:supporting-tools`, `npm run test:bearer`, `npm run test:cli-version`, `npm run test:playwright`.
 
 ## Troubleshooting
 
@@ -411,83 +413,11 @@ Workspace visibility
 - Use HTTPS
 - Store credentials in a secrets manager
 
-## 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`
-- Added `npm run start:http` for one-command HTTP mode startup
-- Hardened HTTP request handling with explicit 50MB parser application and case-insensitive Bearer auth parsing
-- Expanded docs with remote deployment/security presets (Docker, Render, Railway, VPS)
-- Verified full release checks with `npm run ci`, `npm run test:e2e`, and `npm run test:comprehensive`
-
-### 1.6.0 (2026‑02‑24)
-- Added 11 document workflow tools: tags (`list_tags`, `list_docs_by_tag`, `create_tag`, `add_tag_to_doc`, `remove_tag_from_doc`), markdown roundtrip (`export_doc_markdown`, `create_doc_from_markdown`, `append_markdown`, `replace_doc_with_markdown`), and database operations (`add_database_column`, `add_database_row`)
-- Added interactive CLI commands: `affine-mcp login`, `affine-mcp status`, `affine-mcp logout`
-- Added Docker + Playwright E2E pipeline and CI workflow for auth/database regression checks
-- Tool surface increased from 32 to 43 canonical tools
-- Added release test commands (`test:e2e`, `test:db-create`, `test:bearer`, `test:playwright`) and package dependencies for markdown conversion + Playwright
-
-### 1.5.0 (2026‑02‑13)
-- Expanded `append_block` from Step1 to Step4 profiles: canonical text/list/code/divider/callout/latex/table/bookmark/media/embed plus `database`, `data_view`, `surface_ref`, `frame`, `edgeless_text`, `note` (`data_view` currently mapped to database for stability)
-- Added strict field validation and canonical parent enforcement for page/note/surface containers
-- Added local integration runner coverage for all 30 append_block cases against a live AFFINE server
-
-### 1.4.0 (2026‑02‑13)
-- Added `read_doc` for reading document block snapshot + plain text
-- Added Cursor setup examples and troubleshooting notes for JSON-RPC method usage
-- Added explicit local-storage workspace limitation notes
-
-### 1.3.0 (2026‑02‑13)
-- Added `append_block` for slash-command style editing (`heading/list/todo/code/divider/quote`)
-- Tool surface simplified to 31 canonical tools (duplicate aliases removed)
-- Added CI + manifest parity verification (`npm run test:tool-manifest`, `npm run ci`)
-- Added open-source community health docs and issue/PR templates
-
-### 1.2.2 (2025‑09‑18)
-- CLI wrapper added to ensure Node runs ESM entry (`bin/affine-mcp`), preventing shell mis-execution
-- Docs cleaned: use env vars via shell/app config; `.env` file no longer recommended
-- MCP startup behavior unchanged from 1.2.1 (async login by default)
-
-### 1.2.1 (2025‑09‑17)
-- Default to asynchronous email/password login after MCP stdio handshake
-- `AFFINE_LOGIN_AT_START` supports `sync` when you need blocking startup (default is non-blocking)
-- Expanded docs for Codex/Claude using npm, npx, and local clone
-
-### 1.2.0 (2025‑09‑16)
-- WebSocket-based document tools: `create_doc`, `append_paragraph`, `delete_doc` (create/edit/delete now supported)
-- Tool aliases introduced at the time (`affine_*` + non-prefixed names). They were removed later to reduce duplication.
-- ESM resolution: NodeNext; improved build stability
-- CLI binary: `affine-mcp` for easy `npm i -g` usage
-
-### 1.1.0 (2025‑08‑12)
-- Fixed workspace creation with initial documents (UI accessible)
-- 30+ tools, simplified tool names
-- Improved error handling and authentication
-
-### 1.0.0 (2025‑08‑12)
-- Initial stable release
-- Basic workspace and document operations
-- Full authentication support
+## Release Notes
+
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+- Release notes: [RELEASE_NOTES.md](RELEASE_NOTES.md)
+- GitHub Releases: [Releases](https://github.com/dawncr0w/affine-mcp-server/releases)
 
 ## Contributing
 

package/dist/markdown/parse.js

@@ -231,6 +231,14 @@ function collectQuoteText(tokens, start, end) {
     }
     return lines.join("\n");
 }
+function parseCalloutAdmonition(text) {
+    const lines = text.split("\n");
+    const marker = lines[0]?.trim() ?? "";
+    if (!/^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]$/i.test(marker)) {
+        return null;
+    }
+    return lines.slice(1).join("\n").trim();
+}
 function parseList(tokens, start, end, defaultStyle, state, depth) {
     const operations = [];
     let i = start;
@@ -382,7 +390,11 @@ function parseTokens(tokens, start, end, state) {
                     break;
                 }
                 const quoteText = collectQuoteText(tokens, i + 1, close).trim();
-                if (quoteText.length > 0) {
+                const calloutText = parseCalloutAdmonition(quoteText);
+                if (calloutText !== null) {
+                    state.operations.push({ type: "callout", text: calloutText });
+                }
+                else if (quoteText.length > 0) {
                     state.operations.push({ type: "quote", text: quoteText });
                 }
                 i = close + 1;

package/dist/markdown/render.js

@@ -8,6 +8,12 @@ function formatQuote(text) {
     const lines = text.split("\n");
     return lines.map(line => `> ${line}`);
 }
+function formatCallout(lines) {
+    return [
+        "> [!NOTE]",
+        ...lines.map(line => line.length > 0 ? `> ${line}` : ">"),
+    ];
+}
 function escapePipe(value) {
     return value.replace(/\|/g, "\\|");
 }
@@ -138,6 +144,25 @@ function renderBlock(blockId, listDepth, state) {
                 isList: false,
             };
         }
+        case "affine:callout": {
+            const contentLines = [];
+            for (const childId of children) {
+                const child = renderBlock(childId, listDepth, state);
+                if (child.lines.length > 0) {
+                    if (contentLines.length > 0 && !child.isList) {
+                        contentLines.push("");
+                    }
+                    contentLines.push(...child.lines);
+                }
+            }
+            if (contentLines.length === 0 && text.length > 0) {
+                contentLines.push(text);
+            }
+            return {
+                lines: formatCallout(contentLines),
+                isList: false,
+            };
+        }
         case "affine:note":
         case "affine:page":
         case "affine:surface": {

package/dist/tools/docs.js

@@ -53,6 +53,8 @@ const APPEND_BLOCK_BOOKMARK_STYLE_VALUES = [
     "citation",
 ];
 const AppendBlockBookmarkStyle = z.enum(APPEND_BLOCK_BOOKMARK_STYLE_VALUES);
+const APPEND_BLOCK_DATA_VIEW_MODE_VALUES = ["table", "kanban"];
+const AppendBlockDataViewMode = z.enum(APPEND_BLOCK_DATA_VIEW_MODE_VALUES);
 function blockVersion(flavour) {
     switch (flavour) {
         case "affine:page":
@@ -78,6 +80,11 @@ export function registerDocTools(server, gql, defaults) {
         const bearer = gql.bearer;
         return { endpoint, cookie, bearer };
     }
+    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)",
+    ];
     function makeText(content) {
         const yText = new Y.Text();
         if (content.length > 0) {
@@ -717,6 +724,9 @@ export function registerDocTools(server, gql, defaults) {
         else if (raw.tableData !== undefined && normalized.strict) {
             throw new Error("The 'tableData' field can only be used with type='table'.");
         }
+        if (normalized.type !== "database" && normalized.type !== "data_view" && raw.viewMode !== undefined && normalized.strict) {
+            throw new Error("The 'viewMode' field can only be used with type='database' or type='data_view'.");
+        }
     }
     function normalizeAppendBlockInput(parsed) {
         const strict = parsed.strict !== false;
@@ -726,6 +736,7 @@ export function registerDocTools(server, gql, defaults) {
         const headingLevel = Math.max(1, Math.min(6, headingLevelNumber));
         const listStyle = typeInfo.listStyleFromAlias ?? parsed.style ?? "bulleted";
         const bookmarkStyle = parsed.bookmarkStyle ?? "horizontal";
+        const dataViewMode = parsed.viewMode ?? (typeInfo.type === "data_view" ? "kanban" : "table");
         const language = (parsed.language ?? "txt").trim().toLowerCase() || "txt";
         const placement = normalizePlacement(parsed.placement);
         const url = (parsed.url ?? "").trim();
@@ -774,6 +785,7 @@ export function registerDocTools(server, gql, defaults) {
             headingLevel,
             listStyle,
             bookmarkStyle,
+            dataViewMode,
             checked: Boolean(parsed.checked),
             language,
             caption: parsed.caption,
@@ -929,6 +941,102 @@ export function registerDocTools(server, gql, defaults) {
         }
         return { parentId, parentBlock, children, insertIndex };
     }
+    function createDatabaseViewColumn(columnId, width = 200, hide = false) {
+        const column = new Y.Map();
+        column.set("id", columnId);
+        column.set("width", width);
+        column.set("hide", hide);
+        return column;
+    }
+    function createDatabaseColumnDefinition(input) {
+        const column = new Y.Map();
+        column.set("id", input.id);
+        column.set("name", input.name);
+        column.set("type", input.type);
+        column.set("width", input.width ?? 200);
+        if ((input.type === "select" || input.type === "multi-select") && input.options?.length) {
+            const data = new Y.Map();
+            const options = new Y.Array();
+            input.options.forEach((value, index) => {
+                const option = new Y.Map();
+                option.set("id", generateId());
+                option.set("value", value);
+                option.set("color", SELECT_COLORS[index % SELECT_COLORS.length]);
+                options.push([option]);
+            });
+            data.set("options", options);
+            column.set("data", data);
+        }
+        return column;
+    }
+    function createPresetBackedDataViewBlock(blockId, titleText, viewMode, blockType) {
+        const block = new Y.Map();
+        setSysFields(block, blockId, "affine:database");
+        block.set("sys:parent", null);
+        block.set("sys:children", new Y.Array());
+        block.set("prop:title", makeText(titleText));
+        block.set("prop:cells", new Y.Map());
+        block.set("prop:comments", undefined);
+        const titleColumnId = generateId();
+        const columns = new Y.Array();
+        columns.push([createDatabaseColumnDefinition({
+                id: titleColumnId,
+                name: "Title",
+                type: "title",
+                width: 320,
+            })]);
+        const viewColumns = new Y.Array();
+        viewColumns.push([createDatabaseViewColumn(titleColumnId, 320, false)]);
+        const header = {
+            titleColumn: titleColumnId,
+            iconColumn: "type",
+        };
+        let groupBy = null;
+        let groupProperties = null;
+        if (viewMode === "kanban") {
+            const statusColumnId = generateId();
+            columns.push([createDatabaseColumnDefinition({
+                    id: statusColumnId,
+                    name: "Status",
+                    type: "select",
+                    options: ["Todo", "In Progress", "Done"],
+                })]);
+            viewColumns.push([createDatabaseViewColumn(statusColumnId, 200, false)]);
+            groupBy = {
+                columnId: statusColumnId,
+                name: "select",
+                type: "groupBy",
+            };
+            groupProperties = [];
+        }
+        const view = new Y.Map();
+        view.set("id", generateId());
+        view.set("name", viewMode === "kanban" ? "Kanban View" : "Table View");
+        view.set("mode", viewMode);
+        view.set("columns", viewColumns);
+        view.set("filter", { type: "group", op: "and", conditions: [] });
+        if (groupBy) {
+            view.set("groupBy", groupBy);
+        }
+        else {
+            view.set("groupBy", null);
+        }
+        if (groupProperties) {
+            view.set("groupProperties", groupProperties);
+        }
+        view.set("sort", null);
+        view.set("header", header);
+        const views = new Y.Array();
+        views.push([view]);
+        block.set("prop:columns", columns);
+        block.set("prop:views", views);
+        return {
+            blockId,
+            block,
+            flavour: "affine:database",
+            blockType,
+        };
+    }
     function createBlock(normalized) {
         const blockId = generateId();
         const block = new Y.Map();
@@ -1237,6 +1345,9 @@ export function registerDocTools(server, gql, defaults) {
                 return { blockId, block, flavour: "affine:embed-iframe" };
             }
             case "database": {
+                if (normalized.dataViewMode === "kanban") {
+                    return createPresetBackedDataViewBlock(blockId, normalized.text, "kanban", "database_kanban");
+                }
                 setSysFields(block, blockId, "affine:database");
                 block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
@@ -1260,28 +1371,7 @@ export function registerDocTools(server, gql, defaults) {
                 return { blockId, block, flavour: "affine:database" };
             }
             case "data_view": {
-                // AFFiNE 0.26.x currently crashes on raw affine:data-view render path.
-                // Keep API compatibility for type="data_view" by mapping it to the stable database block.
-                setSysFields(block, blockId, "affine:database");
-                block.set("sys:parent", null);
-                block.set("sys:children", new Y.Array());
-                const dvDefaultView = new Y.Map();
-                dvDefaultView.set("id", generateId());
-                dvDefaultView.set("name", "Table View");
-                dvDefaultView.set("mode", "table");
-                dvDefaultView.set("columns", new Y.Array());
-                dvDefaultView.set("filter", { type: "group", op: "and", conditions: [] });
-                dvDefaultView.set("groupBy", null);
-                dvDefaultView.set("sort", null);
-                dvDefaultView.set("header", { titleColumn: null, iconColumn: null });
-                const dvViews = new Y.Array();
-                dvViews.push([dvDefaultView]);
-                block.set("prop:views", dvViews);
-                block.set("prop:title", makeText(content));
-                block.set("prop:cells", new Y.Map());
-                block.set("prop:columns", new Y.Array());
-                block.set("prop:comments", undefined);
-                return { blockId, block, flavour: "affine:database", blockType: "data_view_fallback" };
+                return createPresetBackedDataViewBlock(blockId, normalized.text, normalized.dataViewMode, `data_view_${normalized.dataViewMode}`);
             }
             case "surface_ref": {
                 setSysFields(block, blockId, "affine:surface-ref");
@@ -1425,6 +1515,15 @@ export function registerDocTools(server, gql, defaults) {
                     strict,
                     placement,
                 };
+            case "callout":
+                return {
+                    workspaceId,
+                    docId,
+                    type: "callout",
+                    text: operation.text,
+                    strict,
+                    placement,
+                };
             case "list":
                 return {
                     workspaceId,
@@ -2439,6 +2538,7 @@ export function registerDocTools(server, gql, defaults) {
             level: z.number().int().min(1).max(6).optional().describe("Heading level for type=heading"),
             style: AppendBlockListStyle.optional().describe("List style for type=list"),
             bookmarkStyle: AppendBlockBookmarkStyle.optional().describe("Bookmark card style"),
+            viewMode: AppendBlockDataViewMode.optional().describe("Initial data view preset for type=database or type=data_view. Defaults: database=table, data_view=kanban"),
             checked: z.boolean().optional().describe("Todo state when type is todo"),
             language: z.string().optional().describe("Code language when type is code"),
             caption: z.string().optional().describe("Code caption when type is code"),
@@ -2760,6 +2860,58 @@ export function registerDocTools(server, gql, defaults) {
         });
         return defs;
     }
+    function readDatabaseViewDefs(dbBlock, lookup) {
+        const viewsRaw = dbBlock.get("prop:views");
+        const views = [];
+        if (!(viewsRaw instanceof Y.Array)) {
+            return views;
+        }
+        viewsRaw.forEach((view) => {
+            const id = view instanceof Y.Map ? view.get("id") : view?.id;
+            if (!id) {
+                return;
+            }
+            const columnsRaw = view instanceof Y.Map ? view.get("columns") : view?.columns;
+            const headerRaw = view instanceof Y.Map ? view.get("header") : view?.header;
+            const groupByRaw = view instanceof Y.Map ? view.get("groupBy") : view?.groupBy;
+            const columns = databaseArrayValues(columnsRaw)
+                .map((entry) => {
+                const columnId = entry instanceof Y.Map ? entry.get("id") : entry?.id;
+                if (!columnId || typeof columnId !== "string") {
+                    return null;
+                }
+                const columnDef = lookup.colById.get(columnId) || null;
+                const hidden = entry instanceof Y.Map ? entry.get("hide") : entry?.hide;
+                const width = entry instanceof Y.Map ? entry.get("width") : entry?.width;
+                return {
+                    id: columnId,
+                    name: columnDef?.name || null,
+                    hidden: hidden === true,
+                    width: typeof width === "number" ? width : null,
+                };
+            })
+                .filter((entry) => entry !== null);
+            views.push({
+                id: String(id),
+                name: String((view instanceof Y.Map ? view.get("name") : view?.name) || ""),
+                mode: String((view instanceof Y.Map ? view.get("mode") : view?.mode) || ""),
+                columns,
+                columnIds: columns.map(column => column.id),
+                groupBy: groupByRaw
+                    ? {
+                        columnId: typeof groupByRaw?.columnId === "string" ? groupByRaw.columnId : null,
+                        name: typeof groupByRaw?.name === "string" ? groupByRaw.name : null,
+                        type: typeof groupByRaw?.type === "string" ? groupByRaw.type : null,
+                    }
+                    : null,
+                header: {
+                    titleColumn: typeof headerRaw?.titleColumn === "string" ? headerRaw.titleColumn : null,
+                    iconColumn: typeof headerRaw?.iconColumn === "string" ? headerRaw.iconColumn : null,
+                },
+            });
+        });
+        return views;
+    }
     function isTitleAliasKey(value) {
         return value.trim().toLowerCase() === "title";
     }
@@ -2851,11 +3003,6 @@ export function registerDocTools(server, gql, defaults) {
         }
         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, createOption = true) {
         // Try exact match first
@@ -3167,6 +3314,41 @@ export function registerDocTools(server, gql, defaults) {
             columns: z.array(z.string().min(1)).optional().describe("Optional column name or ID filter."),
         },
     }, readDatabaseCellsHandler);
+    const readDatabaseColumnsHandler = 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 columns = ctx.columnDefs.map(col => ({
+                id: col.id,
+                name: col.name || null,
+                type: col.type,
+                options: col.options,
+            }));
+            return text({
+                databaseBlockId: parsed.databaseBlockId,
+                title: richTextValueToString(ctx.dbBlock.get("prop:title")) || null,
+                rowCount: getDatabaseRowIds(ctx.dbBlock).length,
+                columnCount: columns.length,
+                titleColumnId: ctx.titleCol?.id || null,
+                columns,
+                views: readDatabaseViewDefs(ctx.dbBlock, ctx),
+            });
+        }
+        finally {
+            ctx.socket.disconnect();
+        }
+    };
+    server.registerTool("read_database_columns", {
+        title: "Read Database Columns",
+        description: "Read schema metadata for an AFFiNE database block, including columns, select options, and view column mappings. Useful for empty databases before any rows exist.",
+        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"),
+        },
+    }, readDatabaseColumnsHandler);
     const updateDatabaseCellHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
         if (!workspaceId)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "affine-mcp-server",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "private": false,
   "type": "module",
   "description": "Model Context Protocol server for AFFiNE - enables AI assistants to interact with AFFiNE workspaces, documents, and collaboration features.",
@@ -35,12 +35,18 @@
     "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:comprehensive": "bash tests/run-comprehensive.sh",
+    "test:comprehensive:raw": "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:db-schema": "node tests/test-database-schema.mjs",
+    "test:data-view": "node tests/test-data-view.mjs",
+    "test:data-view-ui": "npx playwright test tests/playwright/verify-data-view.pw.ts --config tests/playwright/playwright.config.ts",
     "test:bearer": "node tests/test-bearer-auth.mjs",
+    "test:supporting-tools": "node tests/test-supporting-tools.mjs",
     "test:tag-visibility": "node tests/test-tag-visibility.mjs",
+    "test:markdown-roundtrip": "node tests/test-markdown-roundtrip.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",