notion-mcp-server 1.0.1 → 2.4.2

package/build/tools/index.js

@@ -1,23 +1,121 @@
+import { z } from "zod";
 import { server } from "../server/index.js";
-import { PAGES_OPERATION_SCHEMA } from "../schema/page.js";
-import { BLOCKS_OPERATION_SCHEMA } from "../schema/blocks.js";
-import { DATABASE_OPERATION_SCHEMA } from "../schema/database.js";
-import { COMMENTS_OPERATION_SCHEMA } from "../schema/comments.js";
-import { USERS_OPERATION_SCHEMA } from "../schema/users.js";
-import { registerPagesOperationTool } from "./pages.js";
-import { registerBlocksOperationTool } from "./blocks.js";
-import { registerDatabaseOperationTool } from "./database.js";
-import { registerCommentsOperationTool } from "./comments.js";
-import { registerUsersOperationTool } from "./users.js";
-export const registerAllTools = () => {
-    // Register combined pages operation tool
-    server.tool("notion_pages", "Perform various page operations (create, archive, restore, search, update)", PAGES_OPERATION_SCHEMA, registerPagesOperationTool);
-    // Register combined blocks operation tool
-    server.tool("notion_blocks", "Perform various block operations (retrieve, update, delete, append children, batch operations)", BLOCKS_OPERATION_SCHEMA, registerBlocksOperationTool);
-    // Register combined database operation tool
-    server.tool("notion_database", "Perform various database operations (create, query, update)", DATABASE_OPERATION_SCHEMA, registerDatabaseOperationTool);
-    // Register combined comments operation tool
-    server.tool("notion_comments", "Perform various comment operations (get, add to page, add to discussion)", COMMENTS_OPERATION_SCHEMA, registerCommentsOperationTool);
-    // Register combined users operation tool
-    server.tool("notion_users", "Perform various user operations (list, get, get bot)", USERS_OPERATION_SCHEMA, registerUsersOperationTool);
+import { initOperations, getOperation, listOperations, operationNames } from "../operations/index.js";
+import { dispatch } from "../dispatch/index.js";
+import { emitJsonSchema } from "../schema/emit.js";
+import { registerAllPrompts } from "../prompts/index.js";
+function jsonContent(value) {
+    // Compact JSON keeps the wire response small. Agents parse JSON either way,
+    // and the ~30% bloat from indentation isn't worth paying for in every reply.
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    return { content: [{ type: "text", text }] };
+}
+function errorContent(value) {
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    return { isError: true, content: [{ type: "text", text }] };
+}
+const EXECUTE_INPUT = {
+    operation: z
+        .string()
+        .describe("Operation name. See notion_describe for the schema of any operation, or read the notion://operations resource for the full menu. Common ops: set_page_title, append_blocks, get_page, search_pages, query_database."),
+    payload: z
+        .record(z.string(), z.unknown())
+        .describe("Operation parameters. Pass either single-op fields directly, or { items: [...], atomic?, idempotency_key?, concurrency? } for batch."),
 };
+const DESCRIBE_INPUT = {
+    operation: z.string().describe("Operation name to describe."),
+};
+const EXECUTE_DESCRIPTION = `Execute a Notion operation by name.
+
+Two ways to call:
+  • Single: { operation: "set_page_title", payload: { page_id, title } }
+  • Batch:  { operation: "set_page_title", payload: { items: [{page_id, title}, ...], atomic?: false, idempotency_key?: "...", concurrency?: 3 } }
+
+If the payload is malformed, the error response includes the full schema + a working example so you can correct and retry in one round-trip. Call notion_describe(operation) ahead of time only for complex shapes (query_database filters, batch_mixed_blocks).
+
+Most responses are slimmed by default. Pass verbose:true inside payload (single) or per-item (batch) to get the raw Notion SDK response.`;
+const DESCRIBE_DESCRIPTION = `Return the JSON Schema and a working example for one operation. Use this BEFORE notion_execute when the payload shape is non-trivial (query filters, structured block trees, database property definitions). For simple ops, just call notion_execute — its errors carry the schema.`;
+export async function registerAllTools() {
+    await initOperations();
+    server.registerTool("notion_execute", {
+        title: "Notion Execute",
+        description: EXECUTE_DESCRIPTION,
+        inputSchema: EXECUTE_INPUT,
+        annotations: {
+            title: "Notion Execute",
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ operation, payload }) => {
+        const result = await dispatch(operation, payload);
+        // Batch results (with per-item results) always go back as structured data —
+        // a partial success is a normal outcome of the tool, not a tool error.
+        const isBatch = typeof result === "object" && result !== null && "summary" in result;
+        if (isBatch || result.ok)
+            return jsonContent(result);
+        return errorContent(result);
+    });
+    server.registerTool("notion_describe", {
+        title: "Notion Describe",
+        description: DESCRIBE_DESCRIPTION,
+        inputSchema: DESCRIBE_INPUT,
+        annotations: {
+            title: "Notion Describe",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ operation }) => {
+        const def = getOperation(operation);
+        if (!def) {
+            return errorContent({
+                ok: false,
+                error: {
+                    code: "unknown_operation",
+                    message: `Unknown operation: "${operation}".`,
+                    fix: `Available: ${operationNames().join(", ")}`,
+                },
+            });
+        }
+        return jsonContent({
+            name: def.name,
+            description: def.description,
+            batchable: def.batchable,
+            schema: emitJsonSchema(def.schema),
+            example: def.example,
+            ...(def.exampleBatch ? { example_batch: def.exampleBatch } : {}),
+        });
+    });
+    // Cheat-sheet resource: a markdown table of every operation
+    server.registerResource("operations-index", "notion://operations", {
+        title: "Notion operations index",
+        description: "Markdown table of every supported operation, batchability, and one-line description.",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "notion://operations",
+                mimeType: "text/markdown",
+                text: renderOperationsIndex(),
+            },
+        ],
+    }));
+    registerAllPrompts();
+}
+function renderOperationsIndex() {
+    const lines = [
+        "# Notion MCP — Operations",
+        "",
+        "Call `notion_execute({operation, payload})` with one of these. Use `notion_describe({operation})` for the full schema.",
+        "",
+        "| Operation | Batchable | Description |",
+        "| --- | --- | --- |",
+    ];
+    for (const def of listOperations()) {
+        lines.push(`| \`${def.name}\` | ${def.batchable ? "yes" : "no"} | ${def.description} |`);
+    }
+    lines.push("", "## `query_database` WHERE DSL", "");
+    lines.push("`query_database.where` is a compact DSL that compiles to the Notion filter object. AND-by-default at the top level; nest `and`/`or`/`not` (case-insensitive — `AND`/`OR`/`NOT` also work) for boolean groups, prefix scalars with `__type` to force the property type, or fall back to raw `filter` for anything the DSL can't express.", "", "Common shapes:", "", "```jsonc", "// Single equality (property type inferred from value, or from data source schema via __type):", "{ \"where\": { \"Status\": \"Open\" } }", "", "// AND of multiple properties (top-level keys are implicit AND):", "{ \"where\": { \"Status\": \"Done\", \"Done\": true } }", "", "// Explicit operator on one property:", "{ \"where\": { \"Priority\": { \"gte\": 3 } } }", "", "// Boolean groups (lowercase or uppercase — both work):", "{ \"where\": { \"or\": [ { \"Status\": \"Open\" }, { \"Status\": \"In progress\" } ] } }", "{ \"where\": { \"and\": [ { \"Status\": \"Done\" }, { \"Priority\": { \"gte\": 5 } } ] } }", "{ \"where\": { \"not\": { \"Status\": \"Done\" } } }", "", "// in / notIn fan out to OR / AND of equals:", "{ \"where\": { \"Status\": { \"in\": [\"Open\", \"In progress\"] } } }", "", "// Force property type when value shape is ambiguous (e.g. a string that's actually a multi_select tag):", "{ \"where\": { \"Tags\": { \"__type\": \"multi_select\", \"eq\": \"alpha\" } } }", "{ \"where\": { \"Created\": { \"__type\": \"date\", \"on_or_after\": \"2026-01-01\" } } }", "```", "", "If a column is literally named `and`/`or`/`not`, wrap it as an operator object (e.g. `{ \"and\": { \"__type\": \"select\", \"eq\": \"x\" } }`) so it isn't parsed as a combinator. For anything the DSL can't express, pass `filter` (raw Notion filter object) instead of `where`.");
+    return lines.join("\n");
+}

package/build/utils/error.js

@@ -1,12 +1,11 @@
-import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
 import { APIResponseError } from "@notionhq/client";
+import { AuthError } from "../services/auth.js";
 /**
  * Error codes from Notion API
  * @see https://developers.notion.com/reference/status-codes#error-codes
  */
 export var NotionErrorCode;
 (function (NotionErrorCode) {
-    // 400 errors
     NotionErrorCode["InvalidJson"] = "invalid_json";
     NotionErrorCode["InvalidRequestUrl"] = "invalid_request_url";
     NotionErrorCode["InvalidRequest"] = "invalid_request";
@@ -16,112 +15,152 @@ export var NotionErrorCode;
     NotionErrorCode["UnsupportedExport"] = "unsupported_export";
     NotionErrorCode["UnsupportedJsonType"] = "unsupported_json_type";
     NotionErrorCode["UnsupportedJsonKey"] = "unsupported_json_key";
-    // 401 errors
     NotionErrorCode["Unauthorized"] = "unauthorized";
     NotionErrorCode["InvalidApiKey"] = "invalid_api_key";
-    // 403 errors
     NotionErrorCode["RestrictedResource"] = "restricted_resource";
     NotionErrorCode["InsufficientPermissions"] = "insufficient_permissions";
-    // 404 errors
     NotionErrorCode["ObjectNotFound"] = "object_not_found";
-    // 409 errors
     NotionErrorCode["ConflictError"] = "conflict_error";
     NotionErrorCode["AlreadyExists"] = "already_exists";
-    // 429 errors
     NotionErrorCode["RateLimited"] = "rate_limited";
-    // 500 errors
     NotionErrorCode["InternalServerError"] = "internal_server_error";
-    // 503 errors
     NotionErrorCode["ServiceUnavailable"] = "service_unavailable";
+    NotionErrorCode["GatewayTimeout"] = "gateway_timeout";
     NotionErrorCode["DatabaseConnectionUnavailable"] = "database_connection_unavailable";
 })(NotionErrorCode || (NotionErrorCode = {}));
 /**
- * Map of error messages for specific Notion error codes
+ * Codes that indicate a transient failure — the request either never ran or
+ * the server is asking us to back off. Safe to retry with exponential backoff.
+ * Shared by the dispatch retry wrapper and any caller that wants to classify
+ * an error envelope without re-encoding the same rules.
  */
+export const RETRYABLE_NOTION_CODES = new Set([
+    NotionErrorCode.RateLimited,
+    NotionErrorCode.InternalServerError,
+    NotionErrorCode.ServiceUnavailable,
+    NotionErrorCode.GatewayTimeout,
+    NotionErrorCode.DatabaseConnectionUnavailable,
+]);
+export function isRetryableNotionCode(code) {
+    return code !== undefined && RETRYABLE_NOTION_CODES.has(code);
+}
 const ERROR_MESSAGES = {
-    // 400 errors
-    [NotionErrorCode.InvalidJson]: "The request body could not be decoded as JSON",
-    [NotionErrorCode.InvalidRequestUrl]: "The request URL is not valid",
-    [NotionErrorCode.InvalidRequest]: "This request is not supported",
-    [NotionErrorCode.ValidationError]: "The request body does not match the schema for the expected parameters",
-    [NotionErrorCode.MissingVersion]: "The request is missing the required Notion-Version header",
-    [NotionErrorCode.UnsupportedVersion]: "The specified version is not supported",
-    [NotionErrorCode.UnsupportedExport]: "The specified export type is not supported",
-    [NotionErrorCode.UnsupportedJsonType]: "The specified JSON type is not supported",
-    [NotionErrorCode.UnsupportedJsonKey]: "The specified JSON key is not supported",
-    // 401 errors
-    [NotionErrorCode.Unauthorized]: "The bearer token is not valid",
-    [NotionErrorCode.InvalidApiKey]: "The API key is invalid",
-    // 403 errors
-    [NotionErrorCode.RestrictedResource]: "The resource is restricted and cannot be accessed with this token",
-    [NotionErrorCode.InsufficientPermissions]: "The bearer token does not have permission to perform this operation",
-    // 404 errors
-    [NotionErrorCode.ObjectNotFound]: "The requested resource does not exist",
-    // 409 errors
-    [NotionErrorCode.ConflictError]: "The transaction could not be completed due to a conflict",
-    [NotionErrorCode.AlreadyExists]: "The resource already exists",
-    // 429 errors
-    [NotionErrorCode.RateLimited]: "The request was rate limited. Retry later with exponential backoff",
-    // 500 errors
-    [NotionErrorCode.InternalServerError]: "An unexpected error occurred on the Notion servers",
-    // 503 errors
-    [NotionErrorCode.ServiceUnavailable]: "The Notion service is unavailable. Retry later with exponential backoff",
-    [NotionErrorCode.DatabaseConnectionUnavailable]: "The database connection is unavailable. Retry later with exponential backoff",
+    [NotionErrorCode.InvalidJson]: {
+        message: "The request body could not be decoded as JSON.",
+        fix: "Pass the payload as an object, not as a JSON-encoded string.",
+    },
+    [NotionErrorCode.InvalidRequestUrl]: {
+        message: "The request URL is not valid.",
+    },
+    [NotionErrorCode.InvalidRequest]: {
+        message: "This request is not supported.",
+    },
+    [NotionErrorCode.ValidationError]: {
+        message: "The request body does not match the schema for the expected parameters.",
+        fix: "Call notion_describe with this operation name to fetch the schema, then retry. Check the 'path' field on the error for the specific bad property.",
+    },
+    [NotionErrorCode.MissingVersion]: {
+        message: "The request is missing the required Notion-Version header.",
+    },
+    [NotionErrorCode.UnsupportedVersion]: {
+        message: "The specified Notion-Version is not supported.",
+    },
+    [NotionErrorCode.UnsupportedExport]: {
+        message: "The specified export type is not supported.",
+    },
+    [NotionErrorCode.UnsupportedJsonType]: {
+        message: "The specified JSON type is not supported.",
+    },
+    [NotionErrorCode.UnsupportedJsonKey]: {
+        message: "The specified JSON key is not supported.",
+    },
+    [NotionErrorCode.Unauthorized]: {
+        message: "The bearer token is not valid.",
+        fix: "Set the NOTION_TOKEN environment variable to a valid Notion integration token (starts with `ntn_` or `secret_`).",
+    },
+    [NotionErrorCode.InvalidApiKey]: {
+        message: "The API key is invalid.",
+        fix: "Generate a new internal integration token in Notion → Settings → Integrations → My integrations.",
+    },
+    [NotionErrorCode.RestrictedResource]: {
+        message: "The resource is restricted and cannot be accessed with this token.",
+        fix: "In Notion, open Settings → Connections → [your integration] → Capabilities and enable the missing scope (e.g. 'Read user information' for /users endpoints, 'Insert content' for block writes). For pages/databases, also confirm the integration is shared with the resource via the page's ••• → Add connections menu.",
+    },
+    [NotionErrorCode.InsufficientPermissions]: {
+        message: "The bearer token does not have permission to perform this operation.",
+        fix: "Open the integration in Notion → Settings → Connections and enable the missing capability, then share the target page/database with the integration.",
+    },
+    [NotionErrorCode.ObjectNotFound]: {
+        message: "The requested resource does not exist.",
+        fix: "Either the ID is wrong, the integration hasn't been shared with the page/database (use the page's ••• → Add connections menu in Notion), or the object is in trash.",
+    },
+    [NotionErrorCode.ConflictError]: {
+        message: "The transaction could not be completed due to a conflict.",
+        fix: "Retry the operation after a short delay.",
+    },
+    [NotionErrorCode.AlreadyExists]: {
+        message: "The resource already exists.",
+    },
+    [NotionErrorCode.RateLimited]: {
+        message: "The request was rate limited.",
+        fix: "Retry later with exponential backoff. Notion limits to ~3 requests per second per integration.",
+    },
+    [NotionErrorCode.InternalServerError]: {
+        message: "An unexpected error occurred on the Notion servers.",
+        fix: "Retry the operation; if it persists, check status.notion.so.",
+    },
+    [NotionErrorCode.ServiceUnavailable]: {
+        message: "The Notion service is unavailable.",
+        fix: "Retry later with exponential backoff.",
+    },
+    [NotionErrorCode.GatewayTimeout]: {
+        message: "The Notion gateway timed out before the request could complete.",
+        fix: "Retry later with exponential backoff.",
+    },
+    [NotionErrorCode.DatabaseConnectionUnavailable]: {
+        message: "The database connection is unavailable.",
+        fix: "Retry later with exponential backoff.",
+    },
 };
-/**
- * Get a more descriptive error message for a given Notion error code
- */
-function getErrorMessage(notionErrorCode, defaultMessage) {
-    return (ERROR_MESSAGES[notionErrorCode] ||
-        defaultMessage ||
-        "An unknown error occurred");
+function lookup(code) {
+    return ERROR_MESSAGES[code] ?? { message: "An unknown error occurred." };
 }
-/**
- * Handles a Notion API error and returns an appropriate CallToolResult with error details
- */
-export function handleNotionError(error) {
+export function toErrorEnvelope(error) {
     if (error instanceof APIResponseError) {
-        const code = error.code;
-        const message = getErrorMessage(code, error.message);
-        // Instead of mapping to specific error codes, just use InternalError as a fallback
+        const entry = lookup(error.code);
+        const body = error.body;
         return {
-            content: [
-                {
-                    type: "text",
-                    text: `Error: ${message} (${code})`,
-                },
-            ],
-            error: {
-                code: ErrorCode.InternalError,
-                message,
-            },
+            code: error.code,
+            message: entry.message + (error.message && error.message !== entry.message ? ` (${error.message})` : ""),
+            ...(entry.fix ? { fix: entry.fix } : {}),
+            ...(String(error.code) === NotionErrorCode.ValidationError && body
+                ? { path: extractValidationPath(body) }
+                : {}),
         };
     }
-    if (error instanceof Error) {
+    if (error instanceof AuthError) {
         return {
-            content: [
-                {
-                    type: "text",
-                    text: `Error: ${error.message}`,
-                },
-            ],
-            error: {
-                code: ErrorCode.InternalError,
-                message: error.message,
-            },
+            code: "auth_error",
+            message: `Notion auth failed: ${error.message}`,
+            fix: "Set NOTION_TOKEN env var, or configure OAuth credentials if using the auth gateway.",
         };
     }
-    // Handle unknown errors
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Error: ${String(error)}`,
-            },
-        ],
-        error: {
-            code: ErrorCode.InternalError,
-            message: String(error),
-        },
-    };
+    if (error instanceof Error) {
+        return { code: "internal_error", message: error.message };
+    }
+    return { code: "unknown_error", message: String(error) };
+}
+function extractValidationPath(body) {
+    if (typeof body !== "object" || body === null)
+        return undefined;
+    const maybe = body.details;
+    if (!Array.isArray(maybe))
+        return undefined;
+    const first = maybe[0];
+    if (typeof first === "object" &&
+        first !== null &&
+        Array.isArray(first.path)) {
+        return first.path;
+    }
+    return undefined;
 }

package/build/utils/handler.js

@@ -0,0 +1,11 @@
+import { toErrorEnvelope } from "./error.js";
+export function tryHandler(fn) {
+    return async (params) => {
+        try {
+            return await fn(params);
+        }
+        catch (error) {
+            return { ok: false, error: toErrorEnvelope(error) };
+        }
+    };
+}

package/build/utils/learning-error.js

@@ -0,0 +1,40 @@
+import { emitJsonSchema } from "../schema/emit.js";
+import { sliceJsonSchema, summarizeSchema } from "./schema-slice.js";
+// Top-level .refine() failures (XOR rules etc.) carry the whole-payload
+// example as actionable guidance — the full JSON schema would only add
+// noise. Skip the schema for those and any other top-level-only issue
+// where the example is self-explanatory.
+function shouldIncludeSchema(issues) {
+    return issues.some((i) => i.path.length > 0);
+}
+export function buildValidationError(def, zodError) {
+    const issues = zodError.issues.map((i) => ({
+        path: i.path,
+        message: i.message,
+    }));
+    const firstPath = issues[0]?.path ?? [];
+    const firstMsg = issues[0]?.message ?? "Validation failed";
+    const includeSchema = shouldIncludeSchema(zodError.issues);
+    // Slice the schema down to the failing field's subtree and summarize any
+    // unions so the envelope stays small — the unsliced schema for ops like
+    // set_page_property or update_database is 5-13KB.
+    let schemaForError;
+    if (includeSchema) {
+        const fullSchema = emitJsonSchema(def.schema);
+        const sliced = firstPath.length > 0 ? sliceJsonSchema(fullSchema, firstPath) : fullSchema;
+        schemaForError = summarizeSchema(sliced);
+    }
+    return {
+        code: "validation_error",
+        operation: def.name,
+        message: `${firstMsg}${firstPath.length ? ` at ${firstPath.join(".")}` : ""}`,
+        path: firstPath.length ? firstPath : undefined,
+        issues,
+        ...(includeSchema ? { schema: schemaForError } : {}),
+        example: def.example,
+        ...(def.exampleBatch ? { example_batch: def.exampleBatch } : {}),
+        fix: includeSchema
+            ? "Match the example shape. The schema above shows the failing field; call notion_describe for the full operation schema. For batch mode, wrap items in { items: [...] }."
+            : "A working example is included above. Match the example shape and retry. For batch mode, wrap items in { items: [...] }.",
+    };
+}

package/build/utils/notion-types.js

@@ -0,0 +1,16 @@
+// Bridge between Zod-validated request shapes and the SDK's strict
+// discriminated-union request types. Zod can describe loose shapes
+// (z.record, z.unknown), but `@notionhq/client` request types use
+// branded discriminated unions that Zod inference can't preserve.
+//
+// Each helper below is a single typed boundary cast: the runtime payload
+// has already been validated by Zod; the cast only tells TypeScript what
+// the SDK expects on the wire. Prefer these over `as never` so the cast
+// target stays visible and grep-able.
+/**
+ * Cast a Zod-validated payload to its SDK request shape. The runtime value
+ * has already been narrowed by the schema; this only widens the static type.
+ */
+export function asSdk(value) {
+    return value;
+}

package/build/utils/paginate.js

@@ -0,0 +1,35 @@
+// Walks a Notion-style paginated endpoint until the server says has_more=false
+// or we've fetched `limit` pages (whichever comes first). The cap protects
+// against pathologically long walks — the caller surfaces `truncated:true` so
+// the user can re-call with a higher `page_limit` or a narrower query.
+//
+// `limit` is in PAGES, not items: a fetch-page typically returns up to 100
+// items, so the default of 10 pages caps at ~1000 items.
+export const DEFAULT_PAGE_LIMIT = 10;
+export async function paginateAll(fetchPage, opts = {}) {
+    const limit = opts.limit ?? DEFAULT_PAGE_LIMIT;
+    const merged = [];
+    let cursor = undefined;
+    let pages_walked = 0;
+    let truncated = false;
+    while (true) {
+        const page = await fetchPage(cursor);
+        pages_walked += 1;
+        merged.push(...page.results);
+        if (!page.has_more)
+            break;
+        if (!page.next_cursor) {
+            // Notion shouldn't return has_more=true with null next_cursor, but if it
+            // does we can't continue — surface truncation so the caller can re-query
+            // or report the gap rather than silently treating it as complete.
+            truncated = true;
+            break;
+        }
+        if (pages_walked >= limit) {
+            truncated = true;
+            break;
+        }
+        cursor = page.next_cursor;
+    }
+    return { results: merged, truncated, pages_walked };
+}