affine-mcp-server 1.10.1 → 1.11.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.10.1-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-1.11.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,17 @@ 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: 61 focused tools with WebSocket-based document editing
+- Tools: 76 focused tools with WebSocket-based document editing
 - Status: Active
  
-> New in v1.10.1: Refreshed packaged docs and release metadata for the v1.10.x toolset, and tightened tag-publish validation with E2E coverage. No runtime or tool-behavior changes.
+> New in v1.11.0: Added sidebar organize tools, configurable tool filtering, `delete_database_row`, and richer markdown import formatting for lists and table cells.
 
 ## 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, inspect schema, add columns and rows, and read or update cell values via MCP tools
+- Sidebar data: collections, folders, and organize links for AFFiNE workspace trees
+- Database workflows: create database blocks, inspect schema, add/update/delete 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,13 +96,17 @@ The MCP server will use these credentials automatically.
 Other CLI commands:
 - `affine-mcp --help` / `-h` / `help` — show command help
 - `affine-mcp status` — show current config and test connection
+- `affine-mcp status --json` — machine-readable status output
 - `affine-mcp doctor` — run config and connectivity diagnostics
 - `affine-mcp show-config` — print the effective config with secrets redacted
 - `affine-mcp config-path` — print the config file path
-- `affine-mcp snippet <claude|cursor|codex> [--env]` — print ready-to-paste client configuration snippets
+- `affine-mcp snippet <claude|cursor|codex|all> [--env]` — print ready-to-paste client configuration snippets
 - `affine-mcp logout` — remove stored credentials
 - `affine-mcp --version` / `-v` / `version` — print the installed CLI version and exit
 
+Non-interactive login helpers:
+- `affine-mcp login --url <url> --token <token> --workspace-id <id> --force`
+
 ### Environment variables
 
 You can also configure via environment variables (they override the config file):
@@ -109,6 +114,7 @@ You can also configure via environment variables (they override the config file)
 - Required: `AFFINE_BASE_URL`
 - Auth (choose one): `AFFINE_API_TOKEN` | `AFFINE_COOKIE` | `AFFINE_EMAIL` + `AFFINE_PASSWORD`
 - Optional: `AFFINE_GRAPHQL_PATH` (default `/graphql`), `AFFINE_WORKSPACE_ID`, `AFFINE_LOGIN_AT_START` (set `sync` only when you must block startup)
+- Tool filtering: `AFFINE_DISABLED_GROUPS`, `AFFINE_DISABLED_TOOLS` (see [Filtering Exposed Tools](#filtering-exposed-tools))
 
 Authentication priority:
 1) `AFFINE_API_TOKEN` → 2) `AFFINE_COOKIE` → 3) `AFFINE_EMAIL` + `AFFINE_PASSWORD`
@@ -193,6 +199,7 @@ Tips
 - If your password contains `!` (zsh history expansion), wrap it in single quotes in shells or use the JSON config above.
 - `affine-mcp doctor` is the fastest way to confirm that your saved config still works.
 - `affine-mcp snippet claude --env` and `affine-mcp snippet codex --env` can generate ready-to-paste client setup from your current config.
+- `affine-mcp snippet all --env` prints Claude, Cursor, and Codex setup in one shot.
 
 ### Codex CLI
 
@@ -354,6 +361,7 @@ Endpoints currently available:
 - `/healthz` - HTTP liveness probe
 - `/readyz` - HTTP readiness probe
 
+
 ## Available Tools
 
 ### Workspace
@@ -365,6 +373,23 @@ Endpoints currently available:
 - `list_workspace_tree` – return the workspace document hierarchy as a tree
 - `get_orphan_docs` – find documents that are not linked from any parent doc in the sidebar tree
 
+### Organization
+- `list_collections` – list workspace collections
+- `get_collection` – get a collection by id
+- `create_collection` – create a collection
+- `update_collection` – rename a collection
+- `delete_collection` – delete a collection
+- `add_doc_to_collection` – add a document to a collection allow-list
+- `remove_doc_from_collection` – remove a document from a collection allow-list
+- `list_organize_nodes` – experimental organize/folder tree dump
+- `create_folder` – experimental root or nested folder creation
+- `rename_folder` – experimental folder rename
+- `delete_folder` – experimental recursive folder delete
+- `move_organize_node` – experimental folder/link move
+- `add_organize_link` – experimental doc/tag/collection link under a folder
+- `delete_organize_link` – experimental doc/tag/collection link delete
+
+
 ### Documents
 - `list_docs` – list documents with pagination (includes `node.tags`)
 - `list_tags` – list all tags in a workspace
@@ -391,6 +416,7 @@ Endpoints currently available:
 - `batch_create_docs` – create up to 20 documents in a single call
 - `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)
+- `delete_database_row` – delete a row from a database block by row block id
 - `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)
@@ -419,6 +445,40 @@ Endpoints currently available:
 ### Blob Storage
 - `upload_blob`, `delete_blob`, `cleanup_blobs`
 
+## Filtering Exposed Tools
+
+Optional environment variables to narrow the exposed surface. 
+
+### Group-level — `AFFINE_DISABLED_GROUPS`
+
+| Group name | Tools included |
+|---|---|
+| `workspaces` | `list_workspaces`, `get_workspace`, `create_workspace`, `update_workspace`, `delete_workspace` |
+| `docs` | `list_docs`, `read_doc`, `search_docs`, `create_doc`, `create_doc_from_markdown`, `create_doc_from_template`, `duplicate_doc`, `append_paragraph`, `append_block`, `append_markdown`, `replace_doc_with_markdown`, `delete_doc`, `publish_doc`, `revoke_doc`, `list_tags`, `list_docs_by_tag`, `create_tag`, `add_tag_to_doc`, `remove_tag_from_doc`, `list_workspace_tree`, `get_orphan_docs`, `list_children`, `update_doc_title`, `get_doc_by_title`, `get_docs_by_tag`, `list_backlinks`, `move_doc`, `batch_create_docs`, `cleanup_orphan_embeds`, `find_and_replace`, `add_database_column`, `add_database_row`, `delete_database_row`, `read_database_columns`, `read_database_cells`, `update_database_cell`, `update_database_row` |
+| `comments` | `list_comments`, `create_comment`, `update_comment`, `delete_comment`, `resolve_comment` |
+| `history` | `list_histories` |
+| `organize` | `list_collections`, `get_collection`, `create_collection`, `update_collection`, `delete_collection`, `add_doc_to_collection`, `remove_doc_from_collection`, `list_organize_nodes`, `create_folder`, `rename_folder`, `delete_folder`, `move_organize_node`, `add_organize_link`, `delete_organize_link` |
+| `users` | `current_user`, `sign_in`, `update_profile`, `update_settings` |
+| `access_tokens` | `list_access_tokens`, `generate_access_token`, `revoke_access_token` |
+| `blobs` | `upload_blob`, `delete_blob`, `cleanup_blobs` |
+| `notifications` | `list_notifications`, `read_all_notifications` |
+
+```json
+"env": {
+  "AFFINE_DISABLED_GROUPS": "comments,history,blobs,users"
+}
+```
+
+### Tool-level — `AFFINE_DISABLED_TOOLS`
+
+Disables individual tools by exact name (comma-separated). 
+
+```json
+"env": {
+  "AFFINE_DISABLED_TOOLS": "delete_workspace,delete_doc"
+}
+```
+
 ## Use Locally (clone)
 
 ```bash
@@ -447,7 +507,7 @@ npm run pack:check
 - 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:db-schema`, `npm run test:supporting-tools`, `npm run test:bearer`, `npm run test:http-email-password`, `npm run test:http-bearer`, `npm run test:oauth-http`, `npm run test:doc-discovery`, `npm run test:cli-version`, `npm run test:cli-commands`, `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:organize`, `npm run test:bearer`, `npm run test:http-email-password`, `npm run test:http-bearer`, `npm run test:oauth-http`, `npm run test:doc-discovery`, `npm run test:cli-version`, `npm run test:cli-commands`, `npm run test:cli-live`, `npm run test:tool-filtering`, `npm run test:markdown-rich-text-import`, `npm run test:playwright`.
 
 ## Troubleshooting
 

package/dist/cli.js

@@ -105,6 +105,29 @@ async function gql(baseUrl, auth, query, variables) {
 function parseFlag(args, ...flags) {
     return args.some((arg) => flags.includes(arg));
 }
+function consumeOption(args, flag) {
+    const index = args.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) {
+        throw new CliError(`Missing value for '${flag}'.`);
+    }
+    args.splice(index, 2);
+    return value;
+}
+function consumeFlags(args, ...flags) {
+    let found = false;
+    for (const flag of flags) {
+        let index = args.indexOf(flag);
+        while (index !== -1) {
+            args.splice(index, 1);
+            found = true;
+            index = args.indexOf(flag);
+        }
+    }
+    return found;
+}
 function ensureNoUnexpectedArgs(args, command) {
     if (args.length > 0) {
         throw new CliError(`Unexpected arguments for '${command}': ${args.join(" ")}`);
@@ -178,6 +201,14 @@ async function resolveCliAuth(baseUrl) {
     }
     throw new CliError("No authentication configured. Run 'affine-mcp login' or set AFFINE_API_TOKEN.");
 }
+async function inspectConnection(baseUrl, auth) {
+    const data = await gql(baseUrl, auth, "query { currentUser { name email } workspaces { id } }");
+    return {
+        userName: data.currentUser.name,
+        userEmail: data.currentUser.email,
+        workspaceCount: data.workspaces.length,
+    };
+}
 function printHelp(command) {
     if (command) {
         const definition = COMMANDS[command];
@@ -208,7 +239,11 @@ function printHelp(command) {
     console.log("  affine-mcp --version");
     console.log("  affine-mcp --help");
 }
-async function detectWorkspace(baseUrl, auth) {
+async function detectWorkspace(baseUrl, auth, preferredWorkspaceId) {
+    if (preferredWorkspaceId) {
+        console.error(`Using workspace override: ${preferredWorkspaceId}`);
+        return preferredWorkspaceId;
+    }
     console.error("Detecting workspaces...");
     try {
         const data = await gql(baseUrl, auth, `query {
@@ -306,7 +341,13 @@ async function loginWithToken(baseUrl) {
     const workspaceId = await detectWorkspace(baseUrl, { token });
     return { token, workspaceId };
 }
-async function login(_args) {
+async function login(args) {
+    const parsedArgs = [...args];
+    const providedUrl = consumeOption(parsedArgs, "--url");
+    const providedToken = consumeOption(parsedArgs, "--token");
+    const providedWorkspaceId = consumeOption(parsedArgs, "--workspace-id");
+    const force = consumeFlags(parsedArgs, "--force", "-f");
+    ensureNoUnexpectedArgs(parsedArgs, "login");
     console.error("Affine MCP Server — Login\n");
     const existing = loadConfigFile();
     if (existing.AFFINE_API_TOKEN) {
@@ -314,24 +355,53 @@ async function login(_args) {
         console.error(`  URL:       ${existing.AFFINE_BASE_URL || "(default)"}`);
         console.error("  Token:     (set)");
         console.error(`  Workspace: ${existing.AFFINE_WORKSPACE_ID || "(none)"}\n`);
-        const overwrite = await ask("Overwrite? [y/N] ");
-        if (!/^[yY]$/.test(overwrite)) {
-            console.error("Keeping existing config.");
-            return;
+        if (!force) {
+            const overwrite = await ask("Overwrite? [y/N] ");
+            if (!/^[yY]$/.test(overwrite)) {
+                console.error("Keeping existing config.");
+                return;
+            }
+            console.error("");
+        }
+        else {
+            console.error("Overwriting existing config (--force).\n");
         }
-        console.error("");
     }
     const defaultUrl = "https://app.affine.pro";
-    const rawUrl = (await ask(`Affine URL [${defaultUrl}]: `)) || defaultUrl;
+    const rawUrl = providedUrl ?? ((await ask(`Affine URL [${defaultUrl}]: `)) || defaultUrl);
     const baseUrl = validateBaseUrl(rawUrl);
-    const isSelfHosted = !baseUrl.includes("affine.pro");
     let result;
-    if (isSelfHosted) {
-        const method = await ask("\nAuth method — [1] Email/password (recommended)  [2] Paste API token: ");
-        result = method === "2" ? await loginWithToken(baseUrl) : await loginWithEmail(baseUrl);
+    if (providedToken) {
+        console.error("Testing provided token...");
+        try {
+            const info = await inspectConnection(baseUrl, { token: providedToken });
+            console.error(`✓ Authenticated as: ${info.userName} <${info.userEmail}>\n`);
+        }
+        catch (err) {
+            throw new CliError(`Authentication failed: ${err.message}`);
+        }
+        result = {
+            token: providedToken,
+            workspaceId: await detectWorkspace(baseUrl, { token: providedToken }, providedWorkspaceId),
+        };
     }
     else {
-        result = await loginWithToken(baseUrl);
+        const isSelfHosted = !baseUrl.includes("affine.pro");
+        if (isSelfHosted) {
+            const method = await ask("\nAuth method — [1] Email/password (recommended)  [2] Paste API token: ");
+            const loginResult = method === "2" ? await loginWithToken(baseUrl) : await loginWithEmail(baseUrl);
+            result = {
+                ...loginResult,
+                workspaceId: providedWorkspaceId || loginResult.workspaceId,
+            };
+        }
+        else {
+            const loginResult = await loginWithToken(baseUrl);
+            result = {
+                ...loginResult,
+                workspaceId: providedWorkspaceId || loginResult.workspaceId,
+            };
+        }
     }
     writeConfigFile({
         AFFINE_BASE_URL: baseUrl,
@@ -342,19 +412,32 @@ async function login(_args) {
     console.error("The MCP server will use these credentials automatically.");
 }
 async function status(args) {
-    ensureNoUnexpectedArgs(args, "status");
+    const parsedArgs = [...args];
+    const asJson = consumeFlags(parsedArgs, "--json");
+    ensureNoUnexpectedArgs(parsedArgs, "status");
     const config = loadConfigFile();
     if (!config.AFFINE_API_TOKEN) {
         throw new CliError("Not logged in. Run: affine-mcp login");
     }
-    console.error(`Config: ${CONFIG_FILE}`);
-    console.error(`URL:       ${config.AFFINE_BASE_URL || "(default)"}`);
-    console.error("Token:     (set)");
-    console.error(`Workspace: ${config.AFFINE_WORKSPACE_ID || "(none)"}\n`);
     try {
-        const data = await gql(config.AFFINE_BASE_URL || "https://app.affine.pro", { token: config.AFFINE_API_TOKEN }, "query { currentUser { name email } workspaces { id } }");
-        console.error(`User: ${data.currentUser.name} <${data.currentUser.email}>`);
-        console.error(`Workspaces: ${data.workspaces.length}`);
+        const inspection = await inspectConnection(config.AFFINE_BASE_URL || "https://app.affine.pro", { token: config.AFFINE_API_TOKEN });
+        if (asJson) {
+            console.log(JSON.stringify({
+                configFile: CONFIG_FILE,
+                baseUrl: config.AFFINE_BASE_URL || "https://app.affine.pro",
+                workspaceId: config.AFFINE_WORKSPACE_ID || null,
+                userName: inspection.userName,
+                userEmail: inspection.userEmail,
+                workspaceCount: inspection.workspaceCount,
+            }, null, 2));
+            return;
+        }
+        console.error(`Config: ${CONFIG_FILE}`);
+        console.error(`URL:       ${config.AFFINE_BASE_URL || "(default)"}`);
+        console.error("Token:     (set)");
+        console.error(`Workspace: ${config.AFFINE_WORKSPACE_ID || "(none)"}\n`);
+        console.error(`User: ${inspection.userName} <${inspection.userEmail}>`);
+        console.error(`Workspaces: ${inspection.workspaceCount}`);
     }
     catch (err) {
         throw new CliError(`Connection failed: ${err.message}`);
@@ -375,11 +458,9 @@ function configPath(args) {
     console.log(CONFIG_FILE);
 }
 function showConfig(args) {
-    const asJson = parseFlag(args, "--json");
-    const unexpectedArgs = args.filter((arg) => arg !== "--json");
-    if (unexpectedArgs.length > 0) {
-        throw new CliError(`Unexpected arguments for 'show-config': ${unexpectedArgs.join(" ")}`);
-    }
+    const parsedArgs = [...args];
+    const asJson = consumeFlags(parsedArgs, "--json");
+    ensureNoUnexpectedArgs(parsedArgs, "show-config");
     const summary = buildEffectiveConfigSummary();
     if (asJson) {
         console.log(JSON.stringify(summary, null, 2));
@@ -405,11 +486,9 @@ function showConfig(args) {
         console.log(`OAuth scopes: ${summary.oauthScopes.join(", ")} (${summary.sources.oauthScopes})`);
 }
 async function doctor(args) {
-    const asJson = parseFlag(args, "--json");
-    const unexpectedArgs = args.filter((arg) => arg !== "--json");
-    if (unexpectedArgs.length > 0) {
-        throw new CliError(`Unexpected arguments for 'doctor': ${unexpectedArgs.join(" ")}`);
-    }
+    const parsedArgs = [...args];
+    const asJson = consumeFlags(parsedArgs, "--json");
+    ensureNoUnexpectedArgs(parsedArgs, "doctor");
     const summary = buildEffectiveConfigSummary();
     const checks = [];
     checks.push({
@@ -447,11 +526,11 @@ async function doctor(args) {
             clearTimeout(healthTimer);
         }
         try {
-            const data = await gql(summary.baseUrl, auth, "query { currentUser { name email } workspaces { id } }");
+            const data = await inspectConnection(summary.baseUrl, auth);
             checks.push({
                 name: "graphql-auth",
                 ok: true,
-                detail: `${data.currentUser.email} (${data.workspaces.length} workspace(s))`,
+                detail: `${data.userEmail} (${data.workspaceCount} workspace(s))`,
             });
         }
         catch (err) {
@@ -522,16 +601,39 @@ function getSnippetEnv() {
     return env;
 }
 function snippet(args) {
-    const target = args[0];
+    const parsedArgs = [...args];
+    const includeEnv = consumeFlags(parsedArgs, "--env");
+    const target = parsedArgs[0];
     if (!target) {
         throw new CliError("Usage: affine-mcp snippet <claude|cursor|codex> [--env]");
     }
-    const includeEnv = parseFlag(args, "--env");
-    const unexpectedArgs = args.slice(1).filter((arg) => arg !== "--env");
-    if (unexpectedArgs.length > 0) {
-        throw new CliError(`Unexpected arguments for 'snippet': ${unexpectedArgs.join(" ")}`);
-    }
+    ensureNoUnexpectedArgs(parsedArgs.slice(1), "snippet");
     const env = includeEnv ? getSnippetEnv() : undefined;
+    if (target === "all") {
+        const payload = {
+            claude: {
+                mcpServers: {
+                    affine: {
+                        command: "affine-mcp",
+                        ...(env && Object.keys(env).length > 0 ? { env } : {}),
+                    },
+                },
+            },
+            cursor: {
+                mcpServers: {
+                    affine: {
+                        command: "affine-mcp",
+                        ...(env && Object.keys(env).length > 0 ? { env } : {}),
+                    },
+                },
+            },
+            codex: env && Object.keys(env).length > 0
+                ? `codex mcp add affine ${Object.entries(env).map(([key, value]) => `--env ${key}=${JSON.stringify(value)}`).join(" ")} -- affine-mcp`
+                : "codex mcp add affine -- affine-mcp",
+        };
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
     if (target === "claude" || target === "cursor") {
         const payload = {
             mcpServers: {
@@ -555,7 +657,7 @@ function snippet(args) {
         console.log(`codex mcp add affine ${envArgs} -- affine-mcp`);
         return;
     }
-    throw new CliError(`Unknown snippet target '${target}'. Expected claude, cursor, or codex.`);
+    throw new CliError(`Unknown snippet target '${target}'. Expected claude, cursor, codex, or all.`);
 }
 function help(args) {
     if (args.length > 1) {
@@ -571,12 +673,12 @@ const COMMANDS = {
     },
     login: {
         summary: "Interactive login and config bootstrap",
-        usage: "affine-mcp login",
+        usage: "affine-mcp login [--url <url>] [--token <token>] [--workspace-id <id>] [--force]",
         handler: login,
     },
     status: {
         summary: "Test the saved config and print current user info",
-        usage: "affine-mcp status",
+        usage: "affine-mcp status [--json]",
         handler: status,
     },
     logout: {
@@ -601,7 +703,7 @@ const COMMANDS = {
     },
     snippet: {
         summary: "Print ready-to-paste Claude/Cursor/Codex snippets",
-        usage: "affine-mcp snippet <claude|cursor|codex> [--env]",
+        usage: "affine-mcp snippet <claude|cursor|codex|all> [--env]",
         handler: snippet,
     },
 };

package/dist/index.js

@@ -13,8 +13,11 @@ import { registerBlobTools } from "./tools/blobStorage.js";
 import { registerNotificationTools } from "./tools/notifications.js";
 import { loginWithPassword } from "./auth.js";
 import { registerAuthTools } from "./tools/auth.js";
+import { registerOrganizeTools } from "./tools/organize.js";
 import { runCli } from "./cli.js";
 import { startHttpMcpServer } from "./sse.js";
+import { existsSync } from "fs";
+import { CONFIG_FILE } from "./config.js";
 // CLI commands: affine-mcp login|status|logout|version
 const rawArgs = process.argv.slice(2);
 const cliArgs = rawArgs[0] === "--" ? rawArgs.slice(1) : rawArgs;
@@ -40,9 +43,22 @@ if (subcommand) {
 const config = loadConfig();
 const transportMode = (process.env.MCP_TRANSPORT || "stdio").toLowerCase();
 const useHttpTransport = transportMode === "sse" || transportMode === "http" || transportMode === "streamable";
+// ---------------------------------------------------------------------------
+// Tool filtering — parsed once at module load (not per-session in HTTP mode)
+// ---------------------------------------------------------------------------
+const KNOWN_GROUPS = new Set([
+    "workspaces", "docs", "comments", "history", "organize",
+    "users", "access_tokens", "blobs", "notifications",
+]);
+const DISABLED_GROUPS = new Set((process.env.AFFINE_DISABLED_GROUPS || "")
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean));
+const DISABLED_TOOLS = new Set((process.env.AFFINE_DISABLED_TOOLS || "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean));
 // Startup diagnostics (visible in Claude Code MCP server logs via stderr)
-import { existsSync } from "fs";
-import { CONFIG_FILE } from "./config.js";
 console.error(`[affine-mcp] Config: ${CONFIG_FILE} (${existsSync(CONFIG_FILE) ? 'found' : 'missing'})`);
 console.error(`[affine-mcp] Endpoint: ${config.baseUrl}${config.graphqlPath}`);
 const hasAuth = !!(config.apiToken || config.cookie || (config.email && config.password));
@@ -54,6 +70,13 @@ if (hasAuth && config.baseUrl.startsWith("http://")
     console.error("WARNING: Credentials configured over plain HTTP. Use HTTPS for remote servers.");
 }
 console.error(`[affine-mcp] Workspace: ${config.defaultWorkspaceId ? 'set' : '(none)'}`);
+// Warn about unknown group names (likely typos) before they silently do nothing
+for (const g of DISABLED_GROUPS) {
+    if (!KNOWN_GROUPS.has(g)) {
+        console.error(`[affine-mcp] WARNING: Unknown group "${g}" in AFFINE_DISABLED_GROUPS — ` +
+            `valid groups: ${[...KNOWN_GROUPS].join(", ")}`);
+    }
+}
 if (config.authMode === "oauth" && !useHttpTransport) {
     throw new Error("AFFINE_MCP_AUTH_MODE=oauth requires MCP_TRANSPORT=http (or streamable/sse).");
 }
@@ -132,18 +155,52 @@ async function buildServer() {
         console.error("WARNING: No authentication configured. Some operations may fail.");
         console.error("Set AFFINE_API_TOKEN or run: affine-mcp login");
     }
-    registerWorkspaceTools(server, gql);
-    registerDocTools(server, gql, { workspaceId: config.defaultWorkspaceId });
-    registerCommentTools(server, gql, { workspaceId: config.defaultWorkspaceId });
-    registerHistoryTools(server, gql, { workspaceId: config.defaultWorkspaceId });
-    registerUserTools(server, gql);
-    registerUserCRUDTools(server, gql);
-    registerAccessTokenTools(server, gql);
-    registerBlobTools(server, gql);
-    registerNotificationTools(server, gql);
-    if (config.authMode !== "oauth") {
-        registerAuthTools(server, gql, config.baseUrl);
+    // ---------------------------------------------------------------------------
+    // Per-tool blacklist: patch registerTool on this server instance so individual
+    // tools in AFFINE_DISABLED_TOOLS are silently skipped during registration.
+    // All tool files use server.registerTool exclusively — no need to patch server.tool.
+    // ---------------------------------------------------------------------------
+    if (DISABLED_TOOLS.size > 0) {
+        const originalRegisterTool = server.registerTool?.bind(server);
+        if (typeof originalRegisterTool !== "function") {
+            console.error("[affine-mcp] WARNING: server.registerTool not found — " +
+                "AFFINE_DISABLED_TOOLS will have no effect. " +
+                "The MCP SDK API may have changed.");
+        }
+        else {
+            server.registerTool = (name, options, handler) => {
+                if (DISABLED_TOOLS.has(name))
+                    return;
+                return originalRegisterTool(name, options, handler);
+            };
+        }
+    }
+    // Log filters directly from environment variables
+    console.error(`[affine-mcp] Disabled groups: ${process.env.AFFINE_DISABLED_GROUPS || "(none)"}`);
+    console.error(`[affine-mcp] Disabled tools: ${process.env.AFFINE_DISABLED_TOOLS || "(none)"}`);
+    if (!DISABLED_GROUPS.has("workspaces"))
+        registerWorkspaceTools(server, gql);
+    if (!DISABLED_GROUPS.has("docs"))
+        registerDocTools(server, gql, { workspaceId: config.defaultWorkspaceId });
+    if (!DISABLED_GROUPS.has("comments"))
+        registerCommentTools(server, gql, { workspaceId: config.defaultWorkspaceId });
+    if (!DISABLED_GROUPS.has("history"))
+        registerHistoryTools(server, gql, { workspaceId: config.defaultWorkspaceId });
+    if (!DISABLED_GROUPS.has("organize"))
+        registerOrganizeTools(server, gql, { workspaceId: config.defaultWorkspaceId });
+    if (!DISABLED_GROUPS.has("users")) {
+        registerUserTools(server, gql);
+        registerUserCRUDTools(server, gql);
+        if (config.authMode !== "oauth") {
+            registerAuthTools(server, gql, config.baseUrl);
+        }
     }
+    if (!DISABLED_GROUPS.has("access_tokens"))
+        registerAccessTokenTools(server, gql);
+    if (!DISABLED_GROUPS.has("blobs"))
+        registerBlobTools(server, gql);
+    if (!DISABLED_GROUPS.has("notifications"))
+        registerNotificationTools(server, gql);
     return server;
 }
 async function start() {