notion-mcp-server 1.0.1 → 2.4.2

package/build/operations/blocks.js

@@ -0,0 +1,331 @@
+import { z } from "zod";
+import { getClient } from "../services/notion.js";
+import { register } from "./registry.js";
+import { tryHandler } from "../utils/handler.js";
+import { slimBlock, slimList } from "../utils/slim.js";
+import { parseMarkdownToBlocks } from "../markdown/parse.js";
+import { TEXT_BLOCK_REQUEST_SCHEMA } from "../schema/blocks.js";
+import { asSdk, } from "../utils/notion-types.js";
+const VERBOSE = z.boolean().optional();
+// ──────────────────────────────────────────────────────────────────────────
+// append_blocks
+// ──────────────────────────────────────────────────────────────────────────
+const AppendBlocksParams = z
+    .object({
+    block_id: z.string().describe("Parent page ID or block ID to append into."),
+    markdown: z.string().optional().describe("Content to append, as markdown. Parsed server-side."),
+    children: z.array(z.unknown()).optional().describe("Structured Notion blocks. Mutually exclusive with markdown."),
+    after: z.string().optional().describe("Append immediately after this block ID (legacy ordering)."),
+    position: z.enum(["start", "end"]).optional().describe("Append at start or end. Preferred over `after`."),
+    verbose: VERBOSE,
+})
+    .refine((v) => Boolean(v.markdown) !== Boolean(v.children), {
+    message: "Pass exactly one of `markdown` or `children`.",
+})
+    .refine((v) => !(v.after && v.position), {
+    message: "Pass at most one of `after` or `position`.",
+});
+register({
+    name: "append_blocks",
+    description: "Append children to a page or block. Use markdown for prose content.",
+    batchable: true,
+    schema: AppendBlocksParams,
+    example: {
+        block_id: "<page-or-block-id>",
+        markdown: "## Section\n\n- bullet 1\n- bullet 2",
+    },
+    exampleBatch: {
+        items: [
+            { block_id: "<page-id-1>", markdown: "Body 1" },
+            { block_id: "<page-id-2>", markdown: "Body 2" },
+        ],
+    },
+    handler: tryHandler(async ({ block_id, markdown, children, after, position, verbose }) => {
+        const blocks = markdown ? parseMarkdownToBlocks(markdown) : (children ?? []);
+        if (blocks.length === 0) {
+            return {
+                ok: false,
+                error: {
+                    code: "empty_content",
+                    message: "No blocks to append (markdown parsed to empty, or children array is empty).",
+                },
+            };
+        }
+        const positionArg = position
+            ? { type: position }
+            : after
+                ? { type: "after_block", after_block: { id: after } }
+                : undefined;
+        const notion = await getClient();
+        const body = {
+            block_id,
+            children: asSdk(blocks),
+            ...(positionArg ? { position: positionArg } : {}),
+        };
+        const response = await notion.blocks.children.append(asSdk(body));
+        // Notion returns just the new blocks for default/end/after positions, but
+        // the full updated child set for `position: "start"` (new blocks appear
+        // first). Slice to the requested count so the response stays bounded.
+        // If the response is shorter than expected (shouldn't happen, but be safe),
+        // surface only what we got and skip ID emission rather than return wrong IDs.
+        const canMapIds = response.results.length >= blocks.length;
+        const newBlocks = canMapIds
+            ? response.results.slice(0, blocks.length)
+            : response.results;
+        if (verbose) {
+            return {
+                ok: true,
+                data: {
+                    appended: blocks.length,
+                    results: newBlocks.map((r) => slimBlock(r, true)),
+                },
+            };
+        }
+        return {
+            ok: true,
+            data: {
+                appended: blocks.length,
+                ...(canMapIds ? { ids: newBlocks.map((r) => r.id) } : {}),
+            },
+        };
+    }),
+});
+// ──────────────────────────────────────────────────────────────────────────
+// get_block
+// ──────────────────────────────────────────────────────────────────────────
+const GetBlockParams = z.object({
+    block_id: z.string().describe("Block ID to retrieve."),
+    verbose: VERBOSE,
+});
+register({
+    name: "get_block",
+    description: "Retrieve a single block by ID (metadata + type-specific body). For its children, use get_block_children.",
+    batchable: true,
+    schema: GetBlockParams,
+    example: { block_id: "<block-id>" },
+    exampleBatch: {
+        items: [{ block_id: "<block-id-1>" }, { block_id: "<block-id-2>" }],
+    },
+    handler: tryHandler(async ({ block_id, verbose }) => {
+        const notion = await getClient();
+        const response = await notion.blocks.retrieve({ block_id });
+        return { ok: true, data: slimBlock(response, verbose ?? false) };
+    }),
+});
+// ──────────────────────────────────────────────────────────────────────────
+// get_block_children
+// ──────────────────────────────────────────────────────────────────────────
+const GetBlockChildrenParams = z.object({
+    block_id: z.string().describe("Page ID or block ID. For a page, returns its top-level blocks."),
+    start_cursor: z.string().optional(),
+    page_size: z.number().min(1).max(100).optional(),
+    verbose: VERBOSE,
+});
+register({
+    name: "get_block_children",
+    description: "List child blocks under a page or block, paginated.",
+    batchable: false,
+    schema: GetBlockChildrenParams,
+    example: { block_id: "<page-id>", page_size: 100 },
+    handler: tryHandler(async ({ block_id, start_cursor, page_size, verbose }) => {
+        const notion = await getClient();
+        const response = await notion.blocks.children.list({
+            block_id,
+            start_cursor,
+            page_size: page_size ?? 100,
+        });
+        return { ok: true, data: slimList(response, slimBlock, verbose ?? false) };
+    }),
+});
+function extractTypedBody(block) {
+    return { [block.type]: block[block.type] };
+}
+// Block-type keys recognized in update_block's structured `data`.
+// When `data` has exactly one of these keys and no explicit `type`,
+// we infer the discriminator so the caller can write {to_do:{...}}
+// instead of {type:"to_do", to_do:{...}}.
+const INFERRABLE_BLOCK_TYPES = new Set([
+    "paragraph",
+    "heading_1",
+    "heading_2",
+    "heading_3",
+    "heading_4",
+    "quote",
+    "callout",
+    "toggle",
+    "bulleted_list_item",
+    "numbered_list_item",
+    "to_do",
+    "code",
+    "divider",
+    "image",
+    "tab",
+]);
+function inferDataType(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return input;
+    const obj = input;
+    if (typeof obj.type === "string")
+        return obj;
+    const matched = Object.keys(obj).filter((k) => INFERRABLE_BLOCK_TYPES.has(k));
+    if (matched.length === 1) {
+        return { type: matched[0], ...obj };
+    }
+    return obj;
+}
+const UpdateBlockParams = z
+    .object({
+    block_id: z.string(),
+    markdown: z
+        .string()
+        .optional()
+        .describe("New content as markdown. Must parse to exactly one block matching the existing block's type."),
+    data: z
+        .preprocess(inferDataType, TEXT_BLOCK_REQUEST_SCHEMA)
+        .optional()
+        .describe("Structured block envelope: `{type, <type>: {...}}` (e.g. `{type:\"to_do\", to_do:{rich_text:[...], checked:true}}`). When `type` is omitted, it is inferred from the sole block-type key, so `{to_do:{...}}` works as well. Type must match the existing block."),
+    verbose: VERBOSE,
+})
+    .refine((v) => Boolean(v.markdown) !== Boolean(v.data), {
+    message: "Pass exactly one of `markdown` or `data`.",
+});
+register({
+    name: "update_block",
+    description: "Update an existing block's content. Pass `markdown` for prose blocks (parsed locally to a single block), or `data` for structured updates such as toggling a to_do's `checked` field or setting a code block's language.",
+    batchable: true,
+    schema: UpdateBlockParams,
+    example: { block_id: "<block-id>", markdown: "Updated paragraph text." },
+    exampleBatch: {
+        items: [
+            { block_id: "<block-id-1>", markdown: "First update." },
+            {
+                block_id: "<block-id-2>",
+                data: { to_do: { rich_text: [{ type: "text", text: { content: "Done" } }], checked: true } },
+            },
+        ],
+    },
+    handler: tryHandler(async ({ block_id, markdown, data, verbose }) => {
+        let body;
+        if (markdown) {
+            const parsed = parseMarkdownToBlocks(markdown);
+            if (parsed.length !== 1) {
+                return {
+                    ok: false,
+                    error: {
+                        code: "markdown_multiblock",
+                        message: `Update requires exactly one block; markdown parsed to ${parsed.length}.`,
+                        fix: "Use append_blocks for multi-block content, or shorten markdown to a single block.",
+                    },
+                };
+            }
+            body = extractTypedBody(parsed[0]);
+        }
+        else {
+            body = extractTypedBody(data);
+        }
+        const notion = await getClient();
+        const response = await notion.blocks.update(asSdk({ block_id, ...body }));
+        return { ok: true, data: slimBlock(response, verbose ?? false) };
+    }),
+});
+// ──────────────────────────────────────────────────────────────────────────
+// delete_block
+// ──────────────────────────────────────────────────────────────────────────
+const DeleteBlockParams = z.object({ block_id: z.string(), verbose: VERBOSE });
+register({
+    name: "delete_block",
+    description: "Archive (soft-delete) a block.",
+    batchable: true,
+    schema: DeleteBlockParams,
+    example: { block_id: "<block-id>" },
+    exampleBatch: { items: [{ block_id: "<block-id-1>" }, { block_id: "<block-id-2>" }] },
+    handler: tryHandler(async ({ block_id, verbose }) => {
+        const notion = await getClient();
+        const response = await notion.blocks.delete({ block_id });
+        return { ok: true, data: slimBlock(response, verbose ?? false) };
+    }),
+});
+// ──────────────────────────────────────────────────────────────────────────
+// batch_mixed_blocks  (power-user escape hatch for atomic-ish mixed ops)
+// ──────────────────────────────────────────────────────────────────────────
+const MixedOp = z.discriminatedUnion("op", [
+    z.object({
+        op: z.literal("append"),
+        block_id: z.string(),
+        markdown: z.string().optional(),
+        children: z.array(z.unknown()).optional(),
+    }),
+    z.object({
+        op: z.literal("update"),
+        block_id: z.string(),
+        markdown: z.string().optional(),
+        data: z.preprocess(inferDataType, TEXT_BLOCK_REQUEST_SCHEMA).optional(),
+    }),
+    z.object({
+        op: z.literal("delete"),
+        block_id: z.string(),
+    }),
+]);
+const BatchMixedBlocksParams = z.object({
+    operations: z.array(MixedOp).min(1),
+    verbose: VERBOSE,
+});
+register({
+    name: "batch_mixed_blocks",
+    description: "Run a sequence of mixed block operations (append/update/delete) in order. Uses a non-standard envelope: { operations: [{ op: \"append\"|\"update\"|\"delete\", ... }] } — NOT the universal { items: [...] } batch envelope. For pure single-op batches, prefer the items[] form on append_blocks / update_block / delete_block.",
+    batchable: false,
+    schema: BatchMixedBlocksParams,
+    example: {
+        operations: [
+            { op: "append", block_id: "<page-id>", markdown: "Header\n" },
+            { op: "update", block_id: "<block-id>", markdown: "New text" },
+            { op: "delete", block_id: "<other-block-id>" },
+        ],
+    },
+    handler: tryHandler(async ({ operations, verbose }) => {
+        const notion = await getClient();
+        const results = [];
+        for (const op of operations) {
+            if (op.op === "append") {
+                const blocks = op.markdown
+                    ? parseMarkdownToBlocks(op.markdown)
+                    : (op.children ?? []);
+                const r = await notion.blocks.children.append(asSdk({
+                    block_id: op.block_id,
+                    children: asSdk(blocks),
+                }));
+                const canMapIds = r.results.length >= blocks.length;
+                const newBlocks = canMapIds ? r.results.slice(0, blocks.length) : r.results;
+                results.push(verbose
+                    ? { op: "append", appended: blocks.length, results: newBlocks.map((x) => slimBlock(x, true)) }
+                    : {
+                        op: "append",
+                        appended: blocks.length,
+                        ...(canMapIds ? { ids: newBlocks.map((x) => x.id) } : {}),
+                    });
+            }
+            else if (op.op === "update") {
+                let body;
+                if (op.markdown) {
+                    const parsed = parseMarkdownToBlocks(op.markdown);
+                    if (parsed.length !== 1)
+                        throw new Error("update markdown must be a single block");
+                    body = extractTypedBody(parsed[0]);
+                }
+                else if (op.data) {
+                    body = extractTypedBody(op.data);
+                }
+                else {
+                    throw new Error("update requires markdown or data");
+                }
+                const r = await notion.blocks.update(asSdk({ block_id: op.block_id, ...body }));
+                results.push({ op: "update", block: slimBlock(r, verbose ?? false) });
+            }
+            else {
+                const r = await notion.blocks.delete({ block_id: op.block_id });
+                results.push({ op: "delete", block: slimBlock(r, verbose ?? false) });
+            }
+        }
+        return { ok: true, data: { count: results.length, results } };
+    }),
+});

package/build/operations/comments.js

@@ -0,0 +1,191 @@
+import { z } from "zod";
+import { getClient } from "../services/notion.js";
+import { register } from "./registry.js";
+import { tryHandler } from "../utils/handler.js";
+import { slimComment, slimList } from "../utils/slim.js";
+import { asSdk } from "../utils/notion-types.js";
+import { paginateAll } from "../utils/paginate.js";
+const VERBOSE = z.boolean().optional();
+function plainTextRich(text) {
+    return [{ type: "text", text: { content: text } }];
+}
+// ──────────────────────────────────────────────────────────────────────────
+// list_comments
+// ──────────────────────────────────────────────────────────────────────────
+const ListCommentsParams = z.object({
+    block_id: z.string().describe("Page or block ID to list comments from."),
+    start_cursor: z.string().optional(),
+    page_size: z.number().min(1).max(100).optional(),
+    paginate: z
+        .boolean()
+        .optional()
+        .describe("Auto-walk all pages and return combined results. Ignores start_cursor when set."),
+    page_limit: z
+        .number()
+        .min(1)
+        .max(1000)
+        .optional()
+        .describe("Max pages to fetch when paginate=true (default 10, ~1000 comments with page_size=100)."),
+    verbose: VERBOSE,
+});
+register({
+    name: "list_comments",
+    description: "List comments on a page or block. Pass paginate:true to auto-walk all pages.",
+    batchable: false,
+    schema: ListCommentsParams,
+    example: { block_id: "<page-id>" },
+    handler: tryHandler(async ({ block_id, start_cursor, page_size, paginate, page_limit, verbose }) => {
+        const notion = await getClient();
+        if (paginate) {
+            const { results, truncated, pages_walked } = await paginateAll(async (cursor) => {
+                const r = await notion.comments.list({
+                    block_id,
+                    start_cursor: cursor,
+                    page_size: page_size ?? 100,
+                });
+                return { results: r.results, has_more: r.has_more, next_cursor: r.next_cursor };
+            }, { limit: page_limit });
+            return {
+                ok: true,
+                data: {
+                    results: results.map((c) => slimComment(c, verbose ?? false)),
+                    truncated,
+                    pages_walked,
+                },
+            };
+        }
+        const response = await notion.comments.list({
+            block_id,
+            start_cursor,
+            page_size: page_size ?? 50,
+        });
+        return { ok: true, data: slimList(response, slimComment, verbose ?? false) };
+    }),
+});
+// ──────────────────────────────────────────────────────────────────────────
+// add_page_comment
+// ──────────────────────────────────────────────────────────────────────────
+const AddPageCommentParams = z
+    .object({
+    page_id: z.string(),
+    text: z.string().optional().describe("Plain-text comment body."),
+    markdown: z.string().optional().describe("Comment body as markdown. Mutually exclusive with text."),
+    verbose: VERBOSE,
+})
+    .refine((v) => Boolean(v.text) !== Boolean(v.markdown), {
+    message: "Pass exactly one of `text` or `markdown`.",
+});
+register({
+    name: "add_page_comment",
+    description: "Add a top-level comment to a page. Body can be plain text or markdown.",
+    batchable: true,
+    schema: AddPageCommentParams,
+    example: { page_id: "<page-id>", text: "Looks good to me." },
+    exampleBatch: {
+        items: [
+            { page_id: "<page-id>", text: "First note." },
+            { page_id: "<page-id>", markdown: "**Second** note." },
+        ],
+    },
+    handler: tryHandler(async ({ page_id, text, markdown, verbose }) => {
+        const notion = await getClient();
+        const body = markdown !== undefined
+            ? { parent: { page_id }, markdown }
+            : { parent: { page_id }, rich_text: plainTextRich(text) };
+        const response = await notion.comments.create(asSdk(body));
+        return { ok: true, data: slimComment(response, verbose ?? false) };
+    }),
+});
+// ──────────────────────────────────────────────────────────────────────────
+// add_discussion_comment
+// ──────────────────────────────────────────────────────────────────────────
+const AddDiscussionCommentParams = z
+    .object({
+    discussion_id: z.string(),
+    text: z.string().optional(),
+    markdown: z.string().optional().describe("Comment body as markdown. Mutually exclusive with text."),
+    verbose: VERBOSE,
+})
+    .refine((v) => Boolean(v.text) !== Boolean(v.markdown), {
+    message: "Pass exactly one of `text` or `markdown`.",
+});
+register({
+    name: "add_discussion_comment",
+    description: "Reply to an existing discussion thread. Body can be plain text or markdown.",
+    batchable: true,
+    schema: AddDiscussionCommentParams,
+    example: { discussion_id: "<discussion-id>", text: "Thanks for the heads-up." },
+    handler: tryHandler(async ({ discussion_id, text, markdown, verbose }) => {
+        const notion = await getClient();
+        const body = markdown !== undefined
+            ? { discussion_id, markdown }
+            : { discussion_id, rich_text: plainTextRich(text) };
+        const response = await notion.comments.create(asSdk(body));
+        return { ok: true, data: slimComment(response, verbose ?? false) };
+    }),
+});
+// ──────────────────────────────────────────────────────────────────────────
+// get_comment
+// ──────────────────────────────────────────────────────────────────────────
+const GetCommentParams = z.object({
+    comment_id: z.string(),
+    verbose: VERBOSE,
+});
+register({
+    name: "get_comment",
+    description: "Retrieve a single comment by ID.",
+    batchable: true,
+    schema: GetCommentParams,
+    example: { comment_id: "<comment-id>" },
+    handler: tryHandler(async ({ comment_id, verbose }) => {
+        const notion = await getClient();
+        const response = await notion.comments.retrieve({ comment_id });
+        return { ok: true, data: slimComment(response, verbose ?? false) };
+    }),
+});
+// ──────────────────────────────────────────────────────────────────────────
+// update_comment
+// ──────────────────────────────────────────────────────────────────────────
+const UpdateCommentParams = z
+    .object({
+    comment_id: z.string(),
+    rich_text: z.array(z.unknown()).optional(),
+    markdown: z.string().optional(),
+    verbose: VERBOSE,
+})
+    .refine((v) => Boolean(v.rich_text) !== Boolean(v.markdown), {
+    message: "Pass exactly one of `rich_text` or `markdown`.",
+});
+register({
+    name: "update_comment",
+    description: "Replace a comment's body. Pass markdown or rich_text (not both).",
+    batchable: true,
+    schema: UpdateCommentParams,
+    example: { comment_id: "<comment-id>", markdown: "Updated body" },
+    handler: tryHandler(async ({ comment_id, rich_text, markdown, verbose }) => {
+        const notion = await getClient();
+        const body = markdown !== undefined
+            ? { comment_id, markdown }
+            : { comment_id, rich_text };
+        const response = await notion.comments.update(asSdk(body));
+        return { ok: true, data: slimComment(response, verbose ?? false) };
+    }),
+});
+// ──────────────────────────────────────────────────────────────────────────
+// delete_comment
+// ──────────────────────────────────────────────────────────────────────────
+const DeleteCommentParams = z.object({
+    comment_id: z.string(),
+});
+register({
+    name: "delete_comment",
+    description: "Delete a comment.",
+    batchable: true,
+    schema: DeleteCommentParams,
+    example: { comment_id: "<comment-id>" },
+    handler: tryHandler(async ({ comment_id }) => {
+        const notion = await getClient();
+        await notion.comments.delete({ comment_id });
+        return { ok: true, data: { deleted: comment_id } };
+    }),
+});

package/build/operations/data-sources.js

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import { isFullDatabase } from "@notionhq/client";
+import { getClient } from "../services/notion.js";
+import { register } from "./registry.js";
+import { tryHandler } from "../utils/handler.js";
+import { slimDataSource } from "../utils/slim.js";
+import { DATABASE_PROPERTY_SCHEMA } from "../schema/database.js";
+import { asSdk } from "../utils/notion-types.js";
+const VERBOSE = z.boolean().optional();
+const ListDataSourcesParams = z.object({
+    database_id: z.string().describe("Database ID to list data sources for."),
+    verbose: VERBOSE,
+});
+register({
+    name: "list_data_sources",
+    description: "List data sources under a database. Use this before query_database when targeting multi-source databases.",
+    batchable: false,
+    schema: ListDataSourcesParams,
+    example: { database_id: "<database-id>" },
+    handler: tryHandler(async ({ database_id, verbose }) => {
+        const notion = await getClient();
+        const db = await notion.databases.retrieve({ database_id });
+        const sources = isFullDatabase(db) ? db.data_sources : [];
+        return {
+            ok: true,
+            data: verbose
+                ? { database_id, data_sources: sources }
+                : {
+                    database_id,
+                    data_sources: sources.map((s) => ({ id: s.id, name: s.name })),
+                },
+        };
+    }),
+});
+const GetDataSourceParams = z.object({
+    data_source_id: z.string(),
+    verbose: VERBOSE,
+});
+register({
+    name: "get_data_source",
+    description: "Retrieve a single data source's schema (its property definitions and parent database).",
+    batchable: true,
+    schema: GetDataSourceParams,
+    example: { data_source_id: "<data-source-id>" },
+    exampleBatch: { items: [{ data_source_id: "<ds-1>" }, { data_source_id: "<ds-2>" }] },
+    handler: tryHandler(async ({ data_source_id, verbose }) => {
+        const notion = await getClient();
+        const ds = await notion.dataSources.retrieve({ data_source_id });
+        return { ok: true, data: slimDataSource(ds, verbose ?? false) };
+    }),
+});
+const UpdateDataSourceParams = z.object({
+    data_source_id: z.string(),
+    title: z.array(z.unknown()).optional().describe("Rich text array for the data source title."),
+    properties: z.record(z.string(), DATABASE_PROPERTY_SCHEMA).optional(),
+    icon: z.unknown().optional(),
+    archived: z.boolean().optional(),
+    in_trash: z.boolean().optional(),
+    verbose: VERBOSE,
+});
+register({
+    name: "update_data_source",
+    description: "Update a data source's schema (properties, title, icon). For database-level metadata use update_database.",
+    batchable: true,
+    schema: UpdateDataSourceParams,
+    example: {
+        data_source_id: "<data-source-id>",
+        properties: {
+            Status: { type: "status", status: { options: [] } },
+        },
+    },
+    handler: tryHandler(async ({ data_source_id, title, properties, icon, archived, in_trash, verbose }) => {
+        const notion = await getClient();
+        const body = {
+            data_source_id,
+            ...(title !== undefined ? { title } : {}),
+            ...(properties !== undefined ? { properties } : {}),
+            ...(icon !== undefined ? { icon } : {}),
+            ...(archived !== undefined ? { archived } : {}),
+            ...(in_trash !== undefined ? { in_trash } : {}),
+        };
+        const response = await notion.dataSources.update(asSdk(body));
+        return { ok: true, data: slimDataSource(response, verbose ?? false) };
+    }),
+});