notion-mcp-server 2.10.1 → 2.12.0

package/README.md

@@ -12,7 +12,7 @@ Give your AI full read/write access to Notion with **one token and one paste**.
 Three reasons it exists when Notion ships its own MCP:
 
 - **Built for agents, not humans-in-the-loop.** Notion's hosted MCP is OAuth-only — it cannot run headless. This server authenticates with a token, so it works in **CI, cron jobs, background agents, and self-hosted deployments** where nobody can click "Authorize".
-- **~90% less context overhead.** Two MCP tools (`notion_execute` + `notion_describe`) dispatch **43 operations**, instead of one tool schema per endpoint flooding your agent's context.
+- **97% smaller tool footprint at connection.** Two MCP tools (**422 tokens**) instead of one schema per endpoint — the official open-source server loads **17,163 tokens** of tool schemas before you do anything. Operation schemas load on demand via `notion_describe`, so even a typical multi-operation task stays 85–95% lighter. [Measured, reproducible →](./benchmarks)
 - **The operational stuff is built in.** Batched mutations with atomic rollback, idempotency keys, automatic retry on rate limits, slim token-efficient responses, full markdown round-trip, and self-healing validation errors that let the model fix its own bad payloads in one turn.
 
 <a href="https://glama.ai/mcp/servers/zrh07hteaa">
@@ -123,7 +123,7 @@ If you just want to chat with your Notion in claude.ai's web UI, use Notion's ho
 
 | Capability | Official Notion MCP (open source) | **This server** |
 | --- | --- | --- |
-| **Tool surface** | ~24 tools (one per endpoint) loaded into context | **2 tools** — the LLM loads ~90% less schema |
+| **Tool surface** | 24 tools (one per endpoint), 17,163 tokens loaded into context | **2 tools**, 422 tokens — [97% less schema at connection](./benchmarks) |
 | **Operations covered** | ~24 endpoints | **43 operations** (plus a `trash_page` alias) across pages, blocks, databases, data sources, views, templates, comments, users, files |
 | **Batch mutations** | Not documented | ✅ Universal `{ items: [...] }` envelope; up to **10 in parallel** |
 | **Atomic batches + rollback** | Not documented | ✅ `atomic: true` aborts on first failure, best-effort archives entities created earlier |

package/build/operations/files.js

@@ -1,4 +1,7 @@
 import { z } from "zod";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename } from "node:path";
 import { getClient } from "../services/notion.js";
 import { register } from "./registry.js";
 import { tryHandler } from "../utils/handler.js";
@@ -16,7 +19,23 @@ const SourceSchema = z.discriminatedUnion("type", [
         type: z.literal("url"),
         url: z.url().describe("Public URL to fetch the file bytes from."),
     }),
+    z.object({
+        type: z.literal("path"),
+        path: z
+            .string()
+            .describe("Local filesystem path (absolute, or ~-relative). The server reads the file directly — bytes never pass through the tool call, so this is the fastest, cheapest source for files on the same machine as the server."),
+    }),
 ]);
+// Expand a leading ~ or ~/ to the current user's home directory. Node's fs
+// does not do this itself, and ~-relative paths are the common shape a caller
+// hands to a local stdio server.
+function expandHome(p) {
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/"))
+        return homedir() + p.slice(1);
+    return p;
+}
 // Returns Uint8Array<ArrayBuffer> — the DOM Blob constructor's BlobPart type
 // rejects Uint8Array<ArrayBufferLike> under newer @types/node (it widens to
 // include SharedArrayBuffer). Allocating fresh guarantees the concrete type.
@@ -27,6 +46,12 @@ async function resolveBytes(source) {
         out.set(buf);
         return out;
     }
+    if (source.type === "path") {
+        const buf = await readFile(expandHome(source.path));
+        const out = new Uint8Array(buf.byteLength);
+        out.set(buf);
+        return out;
+    }
     const res = await fetch(source.url);
     if (!res.ok) {
         throw new Error(`Failed to fetch ${source.url}: ${res.status} ${res.statusText}`);
@@ -97,8 +122,17 @@ const EXTENSION_TO_MIME = {
     // Documents
     csv: "text/csv",
     json: "application/json",
+    md: "text/markdown",
+    markdown: "text/markdown",
     pdf: "application/pdf",
     txt: "text/plain",
+    // Microsoft Office
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ppt: "application/vnd.ms-powerpoint",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
 };
 function inferContentType(filename) {
     const dot = filename.lastIndexOf(".");
@@ -115,7 +149,10 @@ const UploadFileParams = z.object({
         .enum(["single", "multi"])
         .optional()
         .describe("'single' (default) = one create+send call. 'multi' = chunk into 5MB parts then complete."),
-    filename: z.string(),
+    filename: z
+        .string()
+        .optional()
+        .describe("Required for base64 and url sources. Optional for a path source — defaults to the file's basename."),
     content_type: z.string().optional(),
     source: SourceSchema,
 });
@@ -123,7 +160,7 @@ register({
     name: "upload_file",
     access: "write",
     domain: "files",
-    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.",
+    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  • Local path:   `source: { type: \"path\", path: \"/abs/or/~/file.pdf\" }` (server reads the file directly — preferred for local files; filename is derived from the path if omitted).\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: {
@@ -133,19 +170,34 @@ register({
     },
     handler: tryHandler(async ({ mode, filename, content_type, source }) => {
         const effectiveMode = mode ?? "single";
+        // A path source carries its own name; fall back to the basename when the
+        // caller doesn't pass filename explicitly. base64/url have no name to
+        // derive, so filename stays required there.
+        const effectiveFilename = filename ??
+            (source.type === "path" ? basename(expandHome(source.path)) : undefined);
+        if (!effectiveFilename) {
+            return {
+                ok: false,
+                error: {
+                    code: "validation_error",
+                    message: "filename is required for base64 and url sources (there is no name to derive).",
+                    fix: 'Pass `filename` (e.g. "report.pdf"), or use a path source to derive it from the path.',
+                },
+            };
+        }
         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);
+        const effectiveType = content_type ?? inferContentType(effectiveFilename);
         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.`,
+                    message: `Could not infer content_type from filename "${effectiveFilename}". 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.",
                 },
             };
@@ -153,13 +205,16 @@ register({
         if (effectiveMode === "single") {
             const createBody = {
                 mode: "single_part",
-                filename,
+                filename: effectiveFilename,
                 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 }) },
+                file: {
+                    filename: effectiveFilename,
+                    data: new Blob([bytes], { type: effectiveType }),
+                },
             };
             const sent = await notion.fileUploads.send(sendBody);
             return { ok: true, data: slimFileUpload(sent) };
@@ -167,7 +222,7 @@ register({
         const parts = splitIntoParts(bytes);
         const createBody = {
             mode: "multi_part",
-            filename,
+            filename: effectiveFilename,
             content_type: effectiveType,
             number_of_parts: parts.length,
         };
@@ -176,7 +231,10 @@ register({
             const partNumber = index + 1;
             const sendBody = {
                 file_upload_id: created.id,
-                file: { filename, data: new Blob([part], { type: effectiveType }) },
+                file: {
+                    filename: effectiveFilename,
+                    data: new Blob([part], { type: effectiveType }),
+                },
                 part_number: String(partNumber),
             };
             try {

package/build/schema/database.js

@@ -125,9 +125,9 @@ export const RELATION_DB_PROPERTY_SCHEMA = z.object({
     type: z.literal("relation").describe("Relation property type"),
     relation: z
         .object({
-        database_id: z
+        data_source_id: z
             .string()
-            .describe("The ID of the database this relation refers to"),
+            .describe("The ID of the data source this relation refers to"),
         synced_property_name: z
             .string()
             .optional()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notion-mcp-server",
-  "version": "2.10.1",
+  "version": "2.12.0",
   "mcpName": "io.github.awkoy/notion-mcp-server",
   "type": "module",
   "bin": {