notion-mcp-server 1.0.1 → 2.4.2

package/build/operations/databases.js

@@ -0,0 +1,345 @@
+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 { slimDatabase, slimItem, slimList } from "../utils/slim.js";
+import { DATABASE_PROPERTY_SCHEMA } from "../schema/database.js";
+import { PARENT_SCHEMA } from "../schema/page.js";
+import { ICON_SCHEMA } from "../schema/icon.js";
+import { FILE_SCHEMA } from "../schema/file.js";
+import { TEXT_RICH_TEXT_ITEM_REQUEST_SCHEMA } from "../schema/rich-text.js";
+import { WHERE_SCHEMA, compileWhere } from "../schema/filter-dsl.js";
+import { asSdk, } from "../utils/notion-types.js";
+const VERBOSE = z.boolean().optional();
+// Notion's `dataSources.query` accepts page_size up to 100. For
+// query_database, `page_limit` is the cap in ITEMS (rows), distinct from the
+// `paginate.ts` helper's `limit` which counts PAGES — query rows are the
+// natural unit because users care about row counts when they ask for
+// "everything matching this filter".
+const DEFAULT_PAGE_SIZE = 100;
+const MAX_PAGE_SIZE = 100;
+const DEFAULT_ITEM_LIMIT = 1000;
+const MAX_ITEM_LIMIT = 1000;
+// ──────────────────────────────────────────────────────────────────────────
+// create_database
+// ──────────────────────────────────────────────────────────────────────────
+const CreateDatabaseParams = z.object({
+    parent: PARENT_SCHEMA.optional(),
+    title: z.string().optional().describe("Plain-text title shortcut."),
+    title_rich: z.array(TEXT_RICH_TEXT_ITEM_REQUEST_SCHEMA).optional().describe("Rich-text title; overrides `title`."),
+    description: z.array(TEXT_RICH_TEXT_ITEM_REQUEST_SCHEMA).optional(),
+    properties: z.record(z.string(), DATABASE_PROPERTY_SCHEMA),
+    is_inline: z.boolean().optional(),
+    icon: ICON_SCHEMA.nullable().optional(),
+    cover: FILE_SCHEMA.nullable().optional(),
+    verbose: VERBOSE,
+});
+function resolveParent(parent) {
+    if (parent)
+        return parent;
+    const envId = process.env.NOTION_PAGE_ID;
+    if (envId)
+        return { type: "page_id", page_id: envId };
+    return undefined;
+}
+register({
+    name: "create_database",
+    description: "Create a new database. Properties is a map of name → property-type definition.",
+    batchable: true,
+    schema: CreateDatabaseParams,
+    example: {
+        title: "Tasks",
+        properties: {
+            Name: { type: "title", title: {} },
+            Status: {
+                type: "select",
+                select: {
+                    options: [
+                        { name: "Open", color: "blue" },
+                        { name: "Done", color: "green" },
+                    ],
+                },
+            },
+        },
+    },
+    rollback: async (data) => {
+        if (typeof data !== "object" || data === null)
+            return;
+        const id = data.id;
+        if (!id)
+            return;
+        const notion = await getClient();
+        await notion.databases.update(asSdk({ database_id: id, in_trash: true }));
+    },
+    handler: tryHandler(async (params) => {
+        const parent = resolveParent(params.parent);
+        if (!parent) {
+            return {
+                ok: false,
+                error: {
+                    code: "missing_parent",
+                    message: "No parent specified and NOTION_PAGE_ID is not set.",
+                    fix: "Pass `parent: {type:'page_id', page_id:'...'}` or set NOTION_PAGE_ID in the environment.",
+                },
+            };
+        }
+        const titleRich = params.title_rich
+            ? params.title_rich
+            : params.title
+                ? [{ type: "text", text: { content: params.title } }]
+                : [];
+        const notion = await getClient();
+        const body = {
+            parent,
+            title: titleRich,
+            ...(params.description ? { description: params.description } : {}),
+            initial_data_source: { properties: params.properties },
+            is_inline: params.is_inline ?? false,
+            ...(params.icon !== undefined ? { icon: params.icon } : {}),
+            ...(params.cover !== undefined ? { cover: params.cover } : {}),
+        };
+        const response = await notion.databases.create(asSdk(body));
+        return { ok: true, data: slimDatabase(response, params.verbose ?? false) };
+    }),
+});
+// ──────────────────────────────────────────────────────────────────────────
+// query_database
+// ──────────────────────────────────────────────────────────────────────────
+const QueryDatabaseParams = z
+    .object({
+    database_id: z
+        .string()
+        .optional()
+        .describe("Database ID. If the database has exactly one data source, we resolve it automatically. For multi-source databases, pass data_source_id instead."),
+    data_source_id: z
+        .string()
+        .optional()
+        .describe("Data source ID. Use for multi-source databases or when you've already resolved the source via list_data_sources."),
+    where: WHERE_SCHEMA.optional().describe("Typed shorthand filter DSL. Property names map to scalar values (equals) or operator objects like {gte:3, contains:'x'}. Top-level AND/OR arrays and NOT compose. Mutually exclusive with `filter`."),
+    filter: z.unknown().optional().describe("Raw Notion filter JSON. Use this for edge cases the `where` DSL can't express. Mutually exclusive with `where`."),
+    sorts: z.array(z.unknown()).optional(),
+    start_cursor: z.string().optional(),
+    page_size: z.number().min(1).max(MAX_PAGE_SIZE).optional(),
+    paginate: z.boolean().optional().describe("Walk all result pages, up to `page_limit` items. Returns {results, truncated, pages_walked} envelope instead of {has_more, next_cursor}."),
+    page_limit: z
+        .number()
+        .min(1)
+        .max(MAX_ITEM_LIMIT)
+        .optional()
+        .describe(`Maximum items (rows) to return when \`paginate:true\`. Defaults to ${DEFAULT_ITEM_LIMIT}.`),
+    verbose: VERBOSE,
+})
+    .refine((v) => Boolean(v.database_id) !== Boolean(v.data_source_id), {
+    message: "Pass exactly one of `database_id` or `data_source_id`.",
+})
+    .refine((v) => !(v.where !== undefined && v.filter !== undefined), {
+    message: "Pass either `where` (typed DSL) or `filter` (raw Notion JSON), not both.",
+});
+register({
+    name: "query_database",
+    description: "Query a database with optional filter and sorts. Results are page objects.",
+    batchable: false,
+    schema: QueryDatabaseParams,
+    example: {
+        database_id: "<database-id>",
+        filter: { property: "Status", status: { equals: "Done" } },
+        page_size: 50,
+    },
+    handler: tryHandler(async ({ database_id, data_source_id, where, filter, sorts, start_cursor, page_size, paginate, page_limit, verbose, }) => {
+        const notion = await getClient();
+        let dsId = data_source_id;
+        if (!dsId) {
+            const db = await notion.databases.retrieve({ database_id: database_id });
+            const sources = isFullDatabase(db) ? db.data_sources : [];
+            if (sources.length === 0) {
+                return {
+                    ok: false,
+                    error: {
+                        code: "no_data_source",
+                        message: `Database ${database_id} has no data sources.`,
+                        fix: "Pass data_source_id directly, or check the database in Notion.",
+                    },
+                };
+            }
+            if (sources.length > 1) {
+                return {
+                    ok: false,
+                    error: {
+                        code: "multi_source_database",
+                        message: `Database ${database_id} has ${sources.length} data sources. Pass data_source_id explicitly.`,
+                        fix: `Call list_data_sources first, then pass data_source_id. Available IDs: ${sources.map((s) => s.id).join(", ")}.`,
+                    },
+                };
+            }
+            dsId = sources[0].id;
+        }
+        let compiledFilter;
+        if (where !== undefined) {
+            try {
+                compiledFilter = compileWhere(where);
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    error: {
+                        code: "where_compile_error",
+                        message: err instanceof Error ? err.message : String(err),
+                        fix: "Check your `where` clause shape. Pass `__type` on the property to force a property type, or fall back to raw `filter`.",
+                    },
+                };
+            }
+        }
+        else if (filter !== undefined) {
+            compiledFilter = filter;
+        }
+        const baseBody = {
+            data_source_id: dsId,
+            ...(compiledFilter !== undefined ? { filter: compiledFilter } : {}),
+            ...(sorts !== undefined ? { sorts } : {}),
+        };
+        const pageSize = page_size ?? DEFAULT_PAGE_SIZE;
+        const runQuery = (cursor, size) => notion.dataSources.query(asSdk({
+            ...baseBody,
+            ...(cursor !== undefined ? { start_cursor: cursor } : {}),
+            page_size: size,
+        }));
+        // query_database results are data source rows (pages). The SDK response
+        // type also admits data source objects themselves, so dispatch via slimItem
+        // — only the page branch consumes includeProperties=true, which is the
+        // common case and keeps callers off verbose=true (10x larger).
+        const slimRow = (item, v) => slimItem(item, v ?? false, true);
+        if (paginate) {
+            const limit = page_limit ?? DEFAULT_ITEM_LIMIT;
+            const collected = [];
+            let cursor = start_cursor;
+            let pagesWalked = 0;
+            let hasMore = false;
+            while (collected.length < limit) {
+                const remaining = limit - collected.length;
+                const response = await runQuery(cursor, Math.min(pageSize, remaining));
+                pagesWalked += 1;
+                const slim = slimList(response, slimRow, verbose ?? false);
+                for (const item of slim.results) {
+                    if (collected.length >= limit)
+                        break;
+                    collected.push(item);
+                }
+                hasMore = Boolean(slim.has_more && slim.next_cursor);
+                if (!hasMore || collected.length >= limit)
+                    break;
+                cursor = slim.next_cursor ?? undefined;
+            }
+            if (verbose) {
+                return {
+                    ok: true,
+                    data: {
+                        results: collected,
+                        truncated: hasMore && collected.length >= limit,
+                        pages_walked: pagesWalked,
+                    },
+                };
+            }
+            const { parent, rows } = hoistParent(collected);
+            return {
+                ok: true,
+                data: {
+                    ...(parent !== undefined ? { parent } : {}),
+                    results: rows,
+                    truncated: hasMore && collected.length >= limit,
+                    pages_walked: pagesWalked,
+                },
+            };
+        }
+        const response = await runQuery(start_cursor, pageSize);
+        const slim = slimList(response, slimRow, verbose ?? false);
+        if (verbose)
+            return { ok: true, data: slim };
+        const { parent, rows } = hoistParent(slim.results);
+        return {
+            ok: true,
+            data: {
+                ...(parent !== undefined ? { parent } : {}),
+                results: rows,
+                has_more: slim.has_more,
+                next_cursor: slim.next_cursor,
+            },
+        };
+    }),
+});
+// query_database rows always come from one data source, so the `parent`
+// object is identical across every result. Lift it to the list level — on
+// a 100-row page that saves ~80 bytes per row, ≈8KB per response.
+function hoistParent(rows) {
+    if (rows.length === 0)
+        return { rows: [] };
+    const first = rows[0];
+    if (first.parent === undefined)
+        return { rows: rows.slice() };
+    const parent = first.parent;
+    return {
+        parent,
+        rows: rows.map(({ parent: _omit, ...rest }) => rest),
+    };
+}
+// ──────────────────────────────────────────────────────────────────────────
+// update_database
+// ──────────────────────────────────────────────────────────────────────────
+const UpdateDatabaseParams = z.object({
+    database_id: z.string(),
+    title: z.string().optional(),
+    title_rich: z.array(TEXT_RICH_TEXT_ITEM_REQUEST_SCHEMA).optional(),
+    description: z.array(TEXT_RICH_TEXT_ITEM_REQUEST_SCHEMA).optional(),
+    properties: z
+        .record(z.string(), DATABASE_PROPERTY_SCHEMA)
+        .optional()
+        .describe("Deprecated on the 2025-09-03 surface — properties live on the data source. Call update_data_source instead. Rejected here so the migration is explicit."),
+    is_inline: z.boolean().optional(),
+    is_locked: z.boolean().optional(),
+    in_trash: z.boolean().optional(),
+    archived: z.boolean().optional().describe("Deprecated alias for `in_trash`. Use `in_trash` on the 2025-09-03 surface."),
+    icon: ICON_SCHEMA.nullable().optional(),
+    cover: FILE_SCHEMA.nullable().optional(),
+    verbose: VERBOSE,
+});
+register({
+    name: "update_database",
+    description: "Update database-level metadata (title, description, icon, cover, is_inline, is_locked, in_trash). For schema/property changes, use update_data_source.",
+    batchable: true,
+    schema: UpdateDatabaseParams,
+    example: {
+        database_id: "<database-id>",
+        title: "Renamed",
+    },
+    handler: tryHandler(async (params) => {
+        if (params.properties) {
+            return {
+                ok: false,
+                error: {
+                    code: "properties_moved",
+                    message: "Property definitions are no longer accepted on update_database in the 2025-09-03 surface.",
+                    fix: "Call list_data_sources to resolve the data_source_id, then update_data_source with the same properties map.",
+                },
+            };
+        }
+        const titleRich = params.title_rich
+            ? params.title_rich
+            : params.title !== undefined
+                ? [{ type: "text", text: { content: params.title } }]
+                : undefined;
+        const inTrash = params.in_trash ?? params.archived;
+        const notion = await getClient();
+        const body = {
+            database_id: params.database_id,
+            ...(titleRich ? { title: titleRich } : {}),
+            ...(params.description ? { description: params.description } : {}),
+            ...(params.is_inline !== undefined ? { is_inline: params.is_inline } : {}),
+            ...(params.is_locked !== undefined ? { is_locked: params.is_locked } : {}),
+            ...(inTrash !== undefined ? { in_trash: inTrash } : {}),
+            ...(params.icon !== undefined ? { icon: params.icon } : {}),
+            ...(params.cover !== undefined ? { cover: params.cover } : {}),
+        };
+        const response = await notion.databases.update(asSdk(body));
+        return { ok: true, data: slimDatabase(response, params.verbose ?? false) };
+    }),
+});

package/build/operations/files.js

@@ -0,0 +1,239 @@
+import { z } from "zod";
+import { getClient } from "../services/notion.js";
+import { register } from "./registry.js";
+import { tryHandler } from "../utils/handler.js";
+import { slimFileUpload, slimList } from "../utils/slim.js";
+// Notion's documented per-part ceiling for multi-part uploads.
+const MAX_PART_BYTES = 5 * 1024 * 1024;
+const FILE_UPLOAD_STATUS = ["pending", "uploaded", "expired", "failed"];
+const VERBOSE = z.boolean().optional();
+const SourceSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("base64"),
+        data: z.string().describe("Base64-encoded file bytes."),
+    }),
+    z.object({
+        type: z.literal("url"),
+        url: z.url().describe("Public URL to fetch the file bytes from."),
+    }),
+]);
+async function resolveBytes(source) {
+    if (source.type === "base64")
+        return Buffer.from(source.data, "base64");
+    const res = await fetch(source.url);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch ${source.url}: ${res.status} ${res.statusText}`);
+    }
+    return Buffer.from(await res.arrayBuffer());
+}
+function splitIntoParts(buf, partSize = MAX_PART_BYTES) {
+    const parts = [];
+    for (let offset = 0; offset < buf.length; offset += partSize) {
+        parts.push(buf.subarray(offset, Math.min(offset + partSize, buf.length)));
+    }
+    return parts;
+}
+// Notion's File Upload API requires the Blob's type on send() to match
+// the content_type stored at create(). It does NOT accept
+// application/octet-stream as a fallback. The allowlist below mirrors the
+// MIME types documented at
+// https://developers.notion.com/docs/working-with-files-and-media — when the
+// caller doesn't pass content_type, infer it from the filename extension so
+// create + send agree.
+const EXTENSION_TO_MIME = {
+    // Audio
+    aac: "audio/aac",
+    flac: "audio/x-flac",
+    m4a: "audio/mp4",
+    mid: "audio/midi",
+    midi: "audio/midi",
+    mp3: "audio/mpeg",
+    oga: "audio/ogg",
+    ogg: "audio/ogg",
+    wav: "audio/wav",
+    weba: "audio/webm",
+    wma: "audio/x-ms-wma",
+    // Image
+    apng: "image/apng",
+    avif: "image/avif",
+    bmp: "image/bmp",
+    gif: "image/gif",
+    heic: "image/heic",
+    ico: "image/vnd.microsoft.icon",
+    jpeg: "image/jpeg",
+    jpg: "image/jpeg",
+    png: "image/png",
+    svg: "image/svg+xml",
+    tif: "image/tiff",
+    tiff: "image/tiff",
+    webp: "image/webp",
+    // Video
+    "3gp": "video/3gpp",
+    "3g2": "video/3gpp2",
+    amv: "video/x-amv",
+    asf: "video/x-ms-asf",
+    avi: "video/x-msvideo",
+    f4v: "video/x-f4v",
+    flv: "video/x-flv",
+    m4v: "video/mp4",
+    mkv: "video/x-matroska",
+    mov: "video/quicktime",
+    mp4: "video/mp4",
+    mpeg: "video/mpeg",
+    mpg: "video/mpeg",
+    ogv: "video/ogg",
+    qt: "video/quicktime",
+    webm: "video/webm",
+    // Documents
+    csv: "text/csv",
+    json: "application/json",
+    pdf: "application/pdf",
+    txt: "text/plain",
+};
+function inferContentType(filename) {
+    const dot = filename.lastIndexOf(".");
+    if (dot < 0 || dot === filename.length - 1)
+        return undefined;
+    const ext = filename.slice(dot + 1).toLowerCase();
+    return EXTENSION_TO_MIME[ext];
+}
+// ──────────────────────────────────────────────────────────────────────────
+// upload_file
+// ──────────────────────────────────────────────────────────────────────────
+const UploadFileParams = z.object({
+    mode: z
+        .enum(["single", "multi"])
+        .optional()
+        .describe("'single' (default) = one create+send call. 'multi' = chunk into 5MB parts then complete."),
+    filename: z.string(),
+    content_type: z.string().optional(),
+    source: SourceSchema,
+});
+register({
+    name: "upload_file",
+    description: "Upload a file via Notion's file_uploads API. Handles single-part (one create + one send) and multi-part (create + N sends + complete) transparently.\n\nSource shapes:\n  • Base64 bytes: `source: { type: \"base64\", data: \"<b64 string>\" }`\n  • Public URL:   `source: { type: \"url\", url: \"https://example.com/file.pdf\" }` (the server fetches it server-side).\n\n`mode` defaults to \"single\"; only pass \"multi\" for files larger than ~5MB.",
+    batchable: false,
+    schema: UploadFileParams,
+    example: {
+        filename: "report.pdf",
+        content_type: "application/pdf",
+        source: { type: "base64", data: "JVBERi0xLjQK..." },
+    },
+    handler: tryHandler(async ({ mode, filename, content_type, source }) => {
+        const effectiveMode = mode ?? "single";
+        const notion = await getClient();
+        const bytes = await resolveBytes(source);
+        // Notion rejects send() when the Blob's MIME doesn't match the
+        // content_type stored at create(), and rejects application/octet-stream
+        // outright. Resolve a single MIME for both sides: caller's content_type
+        // wins, else infer from the filename extension.
+        const effectiveType = content_type ?? inferContentType(filename);
+        if (!effectiveType) {
+            return {
+                ok: false,
+                error: {
+                    code: "validation_error",
+                    message: `Could not infer content_type from filename "${filename}". Notion's File Upload API rejects application/octet-stream and only accepts a fixed allowlist of MIME types.`,
+                    fix: "Pass `content_type` explicitly (e.g. \"application/pdf\", \"image/png\", \"text/plain\"). See https://developers.notion.com/docs/working-with-files-and-media for the full list.",
+                },
+            };
+        }
+        if (effectiveMode === "single") {
+            const createBody = {
+                mode: "single_part",
+                filename,
+                content_type: effectiveType,
+            };
+            const created = await notion.fileUploads.create(createBody);
+            const sendBody = {
+                file_upload_id: created.id,
+                file: { filename, data: new Blob([bytes], { type: effectiveType }) },
+            };
+            const sent = await notion.fileUploads.send(sendBody);
+            return { ok: true, data: slimFileUpload(sent) };
+        }
+        const parts = splitIntoParts(bytes);
+        const createBody = {
+            mode: "multi_part",
+            filename,
+            content_type: effectiveType,
+            number_of_parts: parts.length,
+        };
+        const created = await notion.fileUploads.create(createBody);
+        for (const [index, part] of parts.entries()) {
+            const partNumber = index + 1;
+            const sendBody = {
+                file_upload_id: created.id,
+                file: { filename, data: new Blob([part], { type: effectiveType }) },
+                part_number: String(partNumber),
+            };
+            try {
+                await notion.fileUploads.send(sendBody);
+            }
+            catch (err) {
+                // Notion has no abort endpoint — the upload object expires on its
+                // own. Surface part number + upload id so the caller can either
+                // retry the upload from scratch or look up the dangling object.
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Multi-part upload ${created.id} failed on part ${partNumber}/${parts.length}: ${reason}. The upload object will expire automatically; re-call upload_file to retry.`);
+            }
+        }
+        const completed = await notion.fileUploads.complete({
+            file_upload_id: created.id,
+        });
+        return { ok: true, data: slimFileUpload(completed) };
+    }),
+});
+// ──────────────────────────────────────────────────────────────────────────
+// list_file_uploads
+// ──────────────────────────────────────────────────────────────────────────
+const ListFileUploadsParams = z.object({
+    status: z.enum(FILE_UPLOAD_STATUS).optional(),
+    start_cursor: z.string().optional(),
+    page_size: z.number().min(1).max(100).optional(),
+    verbose: VERBOSE,
+});
+register({
+    name: "list_file_uploads",
+    description: "List file uploads, optionally filtered by status.",
+    batchable: false,
+    schema: ListFileUploadsParams,
+    example: { status: "uploaded" },
+    handler: tryHandler(async ({ status, start_cursor, page_size, verbose }) => {
+        const notion = await getClient();
+        const response = await notion.fileUploads.list({
+            ...(status !== undefined ? { status } : {}),
+            ...(start_cursor !== undefined ? { start_cursor } : {}),
+            ...(page_size !== undefined ? { page_size } : {}),
+        });
+        return {
+            ok: true,
+            data: slimList(response, slimFileUpload, verbose ?? false),
+        };
+    }),
+});
+// ──────────────────────────────────────────────────────────────────────────
+// get_file_upload
+// ──────────────────────────────────────────────────────────────────────────
+const GetFileUploadParams = z.object({
+    file_upload_id: z.string(),
+    verbose: VERBOSE,
+});
+register({
+    name: "get_file_upload",
+    description: "Retrieve a single file upload by ID.",
+    batchable: true,
+    schema: GetFileUploadParams,
+    example: { file_upload_id: "<file-upload-id>" },
+    exampleBatch: {
+        items: [
+            { file_upload_id: "<fu-1>" },
+            { file_upload_id: "<fu-2>" },
+        ],
+    },
+    handler: tryHandler(async ({ file_upload_id, verbose }) => {
+        const notion = await getClient();
+        const response = await notion.fileUploads.retrieve({ file_upload_id });
+        return { ok: true, data: slimFileUpload(response, verbose ?? false) };
+    }),
+});

package/build/operations/index.js

@@ -0,0 +1,19 @@
+import { registerSharedSubSchemas } from "../schema/refs.js";
+let initialized = false;
+export async function initOperations() {
+    if (initialized)
+        return;
+    initialized = true;
+    registerSharedSubSchemas();
+    // Side-effect imports register every operation into the central registry.
+    await Promise.all([
+        import("./pages.js"),
+        import("./blocks.js"),
+        import("./databases.js"),
+        import("./data-sources.js"),
+        import("./comments.js"),
+        import("./users.js"),
+        import("./files.js"),
+    ]);
+}
+export { listOperations, getOperation, operationNames } from "./registry.js";