notion-mcp-server 1.0.1 → 2.4.2

package/build/config/index.js

@@ -1,5 +1,7 @@
 // Configuration
 export const CONFIG = {
     serverName: "notion-mcp-server",
-    serverVersion: "1.0.1",
+    serverTitle: "Notion",
+    serverVersion: "1.4.0",
+    serverUrl: "https://github.com/awkoy/notion-mcp-server",
 };

package/build/dispatch/concurrency.js

@@ -0,0 +1,15 @@
+export async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let cursor = 0;
+    async function worker() {
+        while (true) {
+            const index = cursor++;
+            if (index >= items.length)
+                return;
+            results[index] = await fn(items[index], index);
+        }
+    }
+    const workerCount = Math.max(1, Math.min(limit, items.length));
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    return results;
+}

package/build/dispatch/idempotency.js

@@ -0,0 +1,38 @@
+const TTL_MS = 5 * 60 * 1000;
+const MAX_ENTRIES = 512;
+const cache = new Map();
+function evictExpired(now) {
+    for (const [key, entry] of cache) {
+        if (entry.expiresAt <= now)
+            cache.delete(key);
+    }
+    if (cache.size > MAX_ENTRIES) {
+        const overflow = cache.size - MAX_ENTRIES;
+        let removed = 0;
+        for (const key of cache.keys()) {
+            if (removed >= overflow)
+                break;
+            cache.delete(key);
+            removed++;
+        }
+    }
+}
+export function lookup(key) {
+    const now = Date.now();
+    const entry = cache.get(key);
+    if (!entry)
+        return undefined;
+    if (entry.expiresAt <= now) {
+        cache.delete(key);
+        return undefined;
+    }
+    return entry.result;
+}
+export function store(key, result) {
+    const now = Date.now();
+    evictExpired(now);
+    cache.set(key, { result, expiresAt: now + TTL_MS });
+}
+export function buildKey(operation, idempotencyKey) {
+    return `${operation}::${idempotencyKey}`;
+}

package/build/dispatch/index.js

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { getOperation, operationNames } from "../operations/registry.js";
+import { buildKey, lookup, store } from "./idempotency.js";
+import { mapWithConcurrency } from "./concurrency.js";
+import { rateLimiter } from "./rate-limit.js";
+import { isRetryableErrorCode, withRetry } from "./retry.js";
+import { buildValidationError } from "../utils/learning-error.js";
+import { toErrorEnvelope } from "../utils/error.js";
+const DEFAULT_CONCURRENCY = 3;
+const MAX_CONCURRENCY = 10;
+function isBatchPayload(payload) {
+    return (typeof payload === "object" &&
+        payload !== null &&
+        Array.isArray(payload.items));
+}
+function unknownOperationError(name) {
+    return {
+        code: "unknown_operation",
+        message: `Unknown operation: "${name}". Use notion_describe with a valid operation name, or check the notion://operations resource for the full list.`,
+        fix: `Available operations: ${operationNames().join(", ")}`,
+    };
+}
+export async function dispatch(operationName, payload) {
+    const def = getOperation(operationName);
+    if (!def) {
+        return { ok: false, error: unknownOperationError(operationName) };
+    }
+    if (isBatchPayload(payload)) {
+        if (!def.batchable) {
+            // batch_mixed_blocks looks batch-shaped but uses its own `operations[]`
+            // envelope (mixed op kinds, no per-item rollback). Point callers at the
+            // right shape instead of the generic not_batchable message.
+            if (operationName === "batch_mixed_blocks") {
+                return {
+                    ok: false,
+                    error: {
+                        code: "wrong_envelope",
+                        message: 'batch_mixed_blocks uses its own envelope: { operations: [{ op: "append"|"update"|"delete", ... }] }. The universal { items: [...] } envelope does not apply here.',
+                        fix: 'Wrap your operations as { operations: [{ op: "append", block_id, markdown }, { op: "update", ... }, { op: "delete", ... }] }. Or use the items[] form on append_blocks / update_block / delete_block for single-kind batches.',
+                    },
+                };
+            }
+            return {
+                ok: false,
+                error: {
+                    code: "not_batchable",
+                    message: `Operation "${operationName}" does not support batch mode.`,
+                    fix: "Call it with a single payload object instead of { items: [...] }.",
+                },
+            };
+        }
+        return runBatch(def, payload);
+    }
+    return runSingle(def, payload);
+}
+// Run the handler under the shared rate limiter, retrying on transient SDK
+// failures. Token is acquired inside withRetry so each retry attempt counts
+// against the per-second budget instead of bursting on retry storms.
+function runHandlerWithLimitAndRetry(def, params) {
+    return withRetry(async () => {
+        await rateLimiter.acquire();
+        return def.handler(params);
+    }, { isRetryableResult: (r) => r.ok === false && isRetryableErrorCode(r.error.code) });
+}
+async function runSingle(def, payload) {
+    const parsed = def.schema.safeParse(payload);
+    if (!parsed.success) {
+        return { ok: false, error: buildValidationError(def, parsed.error) };
+    }
+    try {
+        return await runHandlerWithLimitAndRetry(def, parsed.data);
+    }
+    catch (error) {
+        return { ok: false, error: toErrorEnvelope(error) };
+    }
+}
+async function runBatch(def, payload) {
+    const idempotencyKey = payload.idempotency_key;
+    if (idempotencyKey) {
+        const cached = lookup(buildKey(def.name, idempotencyKey));
+        if (cached)
+            return cached;
+    }
+    const atomic = payload.atomic === true;
+    // Atomic mode requires serial execution: with concurrency > 1, the `aborted`
+    // flag is set only after the first failure resolves, but other workers have
+    // already started in-flight requests, so later items execute when they
+    // shouldn't. Force concurrency=1 to make the abort barrier reliable.
+    const requested = payload.concurrency ?? DEFAULT_CONCURRENCY;
+    const concurrency = atomic ? 1 : Math.max(1, Math.min(requested, MAX_CONCURRENCY));
+    const items = payload.items;
+    const createdForRollback = [];
+    let aborted = false;
+    const results = await mapWithConcurrency(items, concurrency, async (item, index) => {
+        if (aborted) {
+            return {
+                index,
+                ok: false,
+                error: {
+                    code: "aborted",
+                    message: "Skipped: a prior item failed in atomic batch.",
+                },
+            };
+        }
+        const parsed = def.schema.safeParse(item);
+        if (!parsed.success) {
+            const failure = {
+                index,
+                ok: false,
+                error: buildValidationError(def, parsed.error),
+            };
+            if (atomic)
+                aborted = true;
+            return failure;
+        }
+        try {
+            const result = await runHandlerWithLimitAndRetry(def, parsed.data);
+            if (result.ok) {
+                const success = { index, ok: true, data: result.data };
+                if (atomic && def.rollback)
+                    createdForRollback.push({ item: success });
+                return success;
+            }
+            const failure = {
+                index,
+                ok: false,
+                error: result.error,
+            };
+            if (atomic)
+                aborted = true;
+            return failure;
+        }
+        catch (error) {
+            const failure = {
+                index,
+                ok: false,
+                error: toErrorEnvelope(error),
+            };
+            if (atomic)
+                aborted = true;
+            return failure;
+        }
+    });
+    const succeeded = results.filter((r) => r.ok).length;
+    const failed = results.length - succeeded;
+    let rolledBack;
+    if (atomic && failed > 0 && def.rollback && createdForRollback.length > 0) {
+        rolledBack = 0;
+        for (const { item } of createdForRollback) {
+            if (!item.ok)
+                continue;
+            try {
+                await def.rollback(item.data);
+                rolledBack++;
+            }
+            catch {
+                // best-effort: swallow rollback errors so we still return the original failure
+            }
+        }
+    }
+    const batchResult = {
+        ok: failed === 0,
+        summary: { total: results.length, succeeded, failed },
+        results,
+        ...(rolledBack !== undefined ? { rolled_back: rolledBack } : {}),
+    };
+    if (idempotencyKey) {
+        store(buildKey(def.name, idempotencyKey), batchResult);
+    }
+    return batchResult;
+}
+export const BATCH_ENVELOPE_HELP = `Batch mode: pass { items: [...], atomic?: boolean, idempotency_key?: string, concurrency?: 1-10 }. Each item is validated independently; failures are reported per-item. atomic:true forces serial execution (concurrency=1) and triggers best-effort rollback of created entities on first failure; subsequent items are skipped with code:"aborted".`;
+export const _internal = { isBatchPayload };
+// Re-export Zod for downstream operation files to share a single version
+export { z };

package/build/dispatch/rate-limit.js

@@ -0,0 +1,56 @@
+// Global limiter for Notion API calls. Notion enforces ~3 requests per second
+// per integration; without a cap, dispatch's parallel execution (concurrency
+// up to 10) hits 429s on larger batches. One shared instance means the limit
+// holds across single calls, batch items, and concurrent dispatches.
+//
+// Implementation: a token bucket with capacity=1, equivalent to strict
+// pacing — each acquire reserves the next slot at `1000 / rate` ms after the
+// previous one. This guarantees the sliding-window invariant of "no more
+// than `rate` calls in any 1-second window", whereas a bucket with capacity
+// equal to rate would allow a 2*rate burst across the bucket-refill boundary.
+//
+// Rate is read from NOTION_RATE_LIMIT (requests/second). Default 3.
+export const DEFAULT_RATE_PER_SECOND = 3;
+export const RATE_LIMIT_ENV_VAR = "NOTION_RATE_LIMIT";
+const MS_PER_SECOND = 1_000;
+export class TokenBucket {
+    rate;
+    nextSlot = 0;
+    intervalMs;
+    constructor(rate) {
+        this.rate = rate;
+        if (!(rate > 0))
+            throw new Error(`TokenBucket rate must be > 0, got ${rate}`);
+        this.intervalMs = MS_PER_SECOND / rate;
+    }
+    acquire() {
+        const now = Date.now();
+        const slot = Math.max(now, this.nextSlot);
+        this.nextSlot = slot + this.intervalMs;
+        const delay = slot - now;
+        if (delay <= 0)
+            return Promise.resolve();
+        return new Promise((resolve) => setTimeout(resolve, delay));
+    }
+}
+function readRateFromEnv() {
+    const raw = process.env[RATE_LIMIT_ENV_VAR];
+    if (!raw)
+        return DEFAULT_RATE_PER_SECOND;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_RATE_PER_SECOND;
+}
+let instance = new TokenBucket(readRateFromEnv());
+export const rateLimiter = {
+    acquire() {
+        return instance.acquire();
+    },
+};
+// Replace the singleton bucket. Used by tests and by callers that need to
+// re-read NOTION_RATE_LIMIT after the env var has been mutated.
+export function configureRateLimiter(rate) {
+    instance = new TokenBucket(rate ?? readRateFromEnv());
+}
+export function getRateLimiterBucket() {
+    return instance;
+}

package/build/dispatch/retry.js

@@ -0,0 +1,97 @@
+import { APIErrorCode, APIResponseError, RequestTimeoutError, UnknownHTTPResponseError, } from "@notionhq/client";
+import { isRetryableNotionCode } from "../utils/error.js";
+const DEFAULT_ATTEMPTS = 5;
+const DEFAULT_BASE_MS = 250;
+const DEFAULT_MAX_MS = 8_000;
+const SERVER_ERROR_STATUS_MIN = 500;
+const RETRY_AFTER_HEADER = "retry-after";
+const MS_PER_SECOND = 1_000;
+// Re-export so dispatch and tests can classify codes against the same set
+// without crossing modules twice.
+export { isRetryableNotionCode as isRetryableErrorCode };
+export function isRetryableSdkError(err) {
+    if (APIResponseError.isAPIResponseError(err)) {
+        return (err.code === APIErrorCode.RateLimited ||
+            err.status >= SERVER_ERROR_STATUS_MIN);
+    }
+    if (UnknownHTTPResponseError.isUnknownHTTPResponseError(err)) {
+        return err.status >= SERVER_ERROR_STATUS_MIN;
+    }
+    if (RequestTimeoutError.isRequestTimeoutError(err)) {
+        return true;
+    }
+    return false;
+}
+function parseRetryAfter(raw) {
+    if (!raw)
+        return null;
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * MS_PER_SECOND);
+    const dateMs = Date.parse(raw);
+    if (!Number.isNaN(dateMs))
+        return Math.max(0, dateMs - Date.now());
+    return null;
+}
+// The SDK types `headers` as `unknown` (see fetch-types.d.ts). At runtime it's
+// either a global `Headers` instance (native fetch) or a plain
+// header-name → value record (legacy / test stubs). Handle both without
+// assertions by feature-detecting.
+function readRetryAfterHeader(headers) {
+    if (typeof Headers !== "undefined" && headers instanceof Headers) {
+        return headers.get(RETRY_AFTER_HEADER);
+    }
+    if (headers === null || typeof headers !== "object")
+        return null;
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() !== RETRY_AFTER_HEADER)
+            continue;
+        const first = Array.isArray(value) ? value[0] : value;
+        return typeof first === "string" ? first : null;
+    }
+    return null;
+}
+function readRetryAfterMs(err) {
+    if (!APIResponseError.isAPIResponseError(err) &&
+        !UnknownHTTPResponseError.isUnknownHTTPResponseError(err)) {
+        return null;
+    }
+    return parseRetryAfter(readRetryAfterHeader(err.headers));
+}
+function computeBackoff(baseMs, maxMs, attempt, retryAfterMs) {
+    if (retryAfterMs !== null)
+        return Math.min(retryAfterMs, maxMs);
+    const ceiling = Math.min(maxMs, baseMs * 2 ** attempt);
+    return Math.random() * ceiling;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function withRetry(fn, opts = {}) {
+    const attempts = opts.attempts ?? DEFAULT_ATTEMPTS;
+    const baseMs = opts.baseMs ?? DEFAULT_BASE_MS;
+    const maxMs = opts.maxMs ?? DEFAULT_MAX_MS;
+    const shouldRetry = opts.shouldRetry ?? isRetryableSdkError;
+    const { isRetryableResult } = opts;
+    let lastErr;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        try {
+            const result = await fn();
+            if (isRetryableResult && isRetryableResult(result)) {
+                if (attempt === attempts - 1)
+                    return result;
+                await sleep(computeBackoff(baseMs, maxMs, attempt, null));
+                continue;
+            }
+            return result;
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt === attempts - 1 || !shouldRetry(err))
+                throw err;
+            await sleep(computeBackoff(baseMs, maxMs, attempt, readRetryAfterMs(err)));
+        }
+    }
+    // Unreachable: the loop either returns or throws on the final attempt.
+    throw lastErr;
+}

package/build/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { startServer } from "./server/index.js";
 import { registerAllTools } from "./tools/index.js";
-registerAllTools();
 async function main() {
     try {
+        await registerAllTools();
         await startServer();
     }
     catch (error) {

package/build/markdown/parse.js

@@ -0,0 +1,265 @@
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+const processor = unified().use(remarkParse).use(remarkGfm);
+export function parseMarkdownToBlocks(markdown) {
+    if (!markdown.trim())
+        return [];
+    const tree = processor.parse(markdown);
+    return tree.children.flatMap(convertBlock);
+}
+function convertBlock(node) {
+    switch (node.type) {
+        case "paragraph":
+            return [paragraphFrom(node)];
+        case "heading":
+            return [headingFrom(node)];
+        case "list":
+            return convertList(node);
+        case "blockquote":
+            return convertBlockquote(node);
+        case "code":
+            return [codeFrom(node)];
+        case "thematicBreak":
+            return [{ type: "divider", divider: {} }];
+        default:
+            return [];
+    }
+}
+function paragraphFrom(node) {
+    if (node.children.length === 1 && node.children[0].type === "image") {
+        return imageFrom(node.children[0]);
+    }
+    const inlineImage = node.children.find((c) => c.type === "image");
+    if (inlineImage && node.children.length === 1) {
+        return imageFrom(inlineImage);
+    }
+    return {
+        type: "paragraph",
+        paragraph: { rich_text: phrasingToRichText(node.children) },
+    };
+}
+function headingFrom(node) {
+    const level = Math.min(4, node.depth);
+    const key = `heading_${level}`;
+    return {
+        type: key,
+        [key]: { rich_text: phrasingToRichText(node.children) },
+    };
+}
+function convertList(node) {
+    const isOrdered = node.ordered === true;
+    const type = isOrdered ? "numbered_list_item" : "bulleted_list_item";
+    return node.children.map((item) => listItemBlock(item, type));
+}
+function listItemBlock(item, defaultType) {
+    const isToDo = typeof item.checked === "boolean";
+    const firstParaIdx = item.children.findIndex((c) => c.type === "paragraph");
+    const head = firstParaIdx >= 0
+        ? item.children[firstParaIdx]
+        : { type: "paragraph", children: [] };
+    const richText = phrasingToRichText(head.children);
+    const tail = item.children.filter((_, i) => i !== firstParaIdx);
+    const children = tail.flatMap(convertBlock);
+    if (isToDo) {
+        return {
+            type: "to_do",
+            to_do: {
+                rich_text: richText,
+                checked: item.checked === true,
+                ...(children.length ? { children } : {}),
+            },
+        };
+    }
+    return {
+        type: defaultType,
+        [defaultType]: {
+            rich_text: richText,
+            ...(children.length ? { children } : {}),
+        },
+    };
+}
+function convertBlockquote(node) {
+    const children = node.children.flatMap(convertBlock);
+    if (children.length === 0)
+        return [];
+    const [first, ...rest] = children;
+    if (first.type === "paragraph") {
+        const paragraph = first.paragraph;
+        return [
+            {
+                type: "quote",
+                quote: {
+                    rich_text: paragraph.rich_text,
+                    ...(rest.length ? { children: rest } : {}),
+                },
+            },
+        ];
+    }
+    return [
+        {
+            type: "quote",
+            quote: { rich_text: [], children },
+        },
+    ];
+}
+function codeFrom(node) {
+    return {
+        type: "code",
+        code: {
+            rich_text: [
+                {
+                    type: "text",
+                    text: { content: node.value },
+                },
+            ],
+            language: normalizeLanguage(node.lang),
+        },
+    };
+}
+function imageFrom(node) {
+    return {
+        type: "image",
+        image: {
+            type: "external",
+            external: { url: node.url },
+            ...(node.alt
+                ? {
+                    caption: [
+                        { type: "text", text: { content: node.alt } },
+                    ],
+                }
+                : {}),
+        },
+    };
+}
+function phrasingToRichText(nodes, annotations = {}) {
+    const out = [];
+    for (const node of nodes) {
+        pushPhrasing(node, annotations, out);
+    }
+    return mergeAdjacent(out);
+}
+function pushPhrasing(node, annotations, out) {
+    switch (node.type) {
+        case "text":
+            out.push(textRT(node.value, annotations));
+            return;
+        case "strong":
+            for (const c of node.children) {
+                pushPhrasing(c, { ...annotations, bold: true }, out);
+            }
+            return;
+        case "emphasis":
+            for (const c of node.children) {
+                pushPhrasing(c, { ...annotations, italic: true }, out);
+            }
+            return;
+        case "delete":
+            for (const c of node.children) {
+                pushPhrasing(c, { ...annotations, strikethrough: true }, out);
+            }
+            return;
+        case "inlineCode":
+            out.push(textRT(node.value, { ...annotations, code: true }));
+            return;
+        case "link": {
+            const link = node;
+            const inner = [];
+            for (const c of link.children)
+                pushPhrasing(c, annotations, inner);
+            const merged = mergeAdjacent(inner);
+            for (const r of merged) {
+                if (r.type === "text")
+                    r.text.link = { url: link.url };
+                out.push(r);
+            }
+            return;
+        }
+        case "break":
+            out.push(textRT("\n", annotations));
+            return;
+        default:
+            // Unhandled inline (image inside paragraph already promoted; html, footnote, etc.)
+            return;
+    }
+}
+function textRT(content, annotations) {
+    const cleaned = clean(annotations);
+    return {
+        type: "text",
+        text: { content },
+        ...(Object.keys(cleaned).length ? { annotations: cleaned } : {}),
+    };
+}
+function clean(a) {
+    const out = {};
+    if (a.bold)
+        out.bold = true;
+    if (a.italic)
+        out.italic = true;
+    if (a.strikethrough)
+        out.strikethrough = true;
+    if (a.underline)
+        out.underline = true;
+    if (a.code)
+        out.code = true;
+    return out;
+}
+function mergeAdjacent(items) {
+    const out = [];
+    for (const item of items) {
+        const prev = out[out.length - 1];
+        if (prev &&
+            prev.type === "text" &&
+            item.type === "text" &&
+            sameAnnotations(prev.annotations, item.annotations) &&
+            sameLink(prev.text.link, item.text.link)) {
+            prev.text.content += item.text.content;
+            continue;
+        }
+        out.push(item);
+    }
+    return out;
+}
+function sameAnnotations(a, b) {
+    return JSON.stringify(a ?? {}) === JSON.stringify(b ?? {});
+}
+function sameLink(a, b) {
+    return (a?.url ?? null) === (b?.url ?? null);
+}
+const KNOWN_LANGUAGES = new Set([
+    "abap", "arduino", "bash", "basic", "c", "clojure", "coffeescript", "c++",
+    "c#", "css", "dart", "diff", "docker", "elixir", "elm", "erlang", "flow",
+    "fortran", "f#", "gherkin", "glsl", "go", "graphql", "groovy", "haskell",
+    "html", "java", "javascript", "json", "julia", "kotlin", "latex", "less",
+    "lisp", "livescript", "lua", "makefile", "markdown", "markup", "matlab",
+    "mermaid", "nix", "objective-c", "ocaml", "pascal", "perl", "php", "plain text",
+    "powershell", "prolog", "protobuf", "python", "r", "reason", "ruby", "rust",
+    "sass", "scala", "scheme", "scss", "shell", "sql", "swift", "typescript",
+    "vb.net", "verilog", "vhdl", "visual basic", "webassembly", "xml", "yaml",
+]);
+function normalizeLanguage(lang) {
+    if (!lang)
+        return "plain text";
+    const lower = lang.toLowerCase();
+    if (KNOWN_LANGUAGES.has(lower))
+        return lower;
+    const aliases = {
+        js: "javascript",
+        ts: "typescript",
+        py: "python",
+        rb: "ruby",
+        sh: "shell",
+        yml: "yaml",
+        md: "markdown",
+        "c++": "c++",
+        cpp: "c++",
+        cs: "c#",
+        "objc": "objective-c",
+        rs: "rust",
+        tsx: "typescript",
+        jsx: "javascript",
+    };
+    return aliases[lower] ?? "plain text";
+}