@devheerim/notion-mcp-server 1.0.0

package/dist/utils/format-blocks.js

@@ -0,0 +1,234 @@
+export function formatBlocks(blocks) {
+    const lines = [];
+    let numberedListCounter = 0;
+    for (const block of blocks) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const type = block.type;
+        // Reset numbered list counter when we hit a non-numbered block
+        if (type !== 'numbered_list_item') {
+            numberedListCounter = 0;
+        }
+        switch (type) {
+            case 'paragraph': {
+                const text = richTextToString(block.paragraph?.rich_text ?? []);
+                lines.push(text);
+                lines.push('');
+                break;
+            }
+            case 'heading_1': {
+                const text = richTextToString(block.heading_1?.rich_text ?? []);
+                lines.push(`# ${text}`);
+                lines.push('');
+                break;
+            }
+            case 'heading_2': {
+                const text = richTextToString(block.heading_2?.rich_text ?? []);
+                lines.push(`## ${text}`);
+                lines.push('');
+                break;
+            }
+            case 'heading_3': {
+                const text = richTextToString(block.heading_3?.rich_text ?? []);
+                lines.push(`### ${text}`);
+                lines.push('');
+                break;
+            }
+            case 'bulleted_list_item': {
+                const text = richTextToString(block.bulleted_list_item?.rich_text ?? []);
+                lines.push(`- ${text}`);
+                break;
+            }
+            case 'numbered_list_item': {
+                numberedListCounter++;
+                const text = richTextToString(block.numbered_list_item?.rich_text ?? []);
+                lines.push(`${numberedListCounter}. ${text}`);
+                break;
+            }
+            case 'to_do': {
+                const checked = block.to_do?.checked ?? false;
+                const text = richTextToString(block.to_do?.rich_text ?? []);
+                lines.push(`- [${checked ? 'x' : ' '}] ${text}`);
+                break;
+            }
+            case 'toggle': {
+                const text = richTextToString(block.toggle?.rich_text ?? []);
+                lines.push(`> ${text}`);
+                if (block.has_children) {
+                    lines.push('> *(has children)*');
+                }
+                lines.push('');
+                break;
+            }
+            case 'code': {
+                const text = richTextToString(block.code?.rich_text ?? []);
+                const language = block.code?.language ?? '';
+                lines.push('```' + language);
+                lines.push(text);
+                lines.push('```');
+                lines.push('');
+                break;
+            }
+            case 'quote': {
+                const text = richTextToString(block.quote?.rich_text ?? []);
+                lines.push(`> ${text}`);
+                lines.push('');
+                break;
+            }
+            case 'callout': {
+                const text = richTextToString(block.callout?.rich_text ?? []);
+                const emoji = block.callout?.icon?.emoji ?? '';
+                lines.push(`> ${emoji} ${text}`.trim());
+                lines.push('');
+                break;
+            }
+            case 'divider': {
+                lines.push('---');
+                lines.push('');
+                break;
+            }
+            case 'image': {
+                const image = block.image;
+                let url = '';
+                if (image?.type === 'external') {
+                    url = image.external?.url ?? '';
+                }
+                else if (image?.type === 'file') {
+                    url = image.file?.url ?? '';
+                }
+                const caption = richTextToString(image?.caption ?? []);
+                lines.push(`![${caption || 'image'}](${url})`);
+                lines.push('');
+                break;
+            }
+            case 'bookmark': {
+                const url = block.bookmark?.url ?? '';
+                const caption = richTextToString(block.bookmark?.caption ?? []);
+                lines.push(`[${caption || 'bookmark'}](${url})`);
+                lines.push('');
+                break;
+            }
+            case 'table': {
+                // Table rows are nested as children; the table block itself just has metadata
+                // We emit a note; actual rows come as child blocks
+                lines.push('');
+                break;
+            }
+            case 'table_row': {
+                const cells = block.table_row?.cells ?? [];
+                const cellStrings = cells.map((cell) => richTextToString(cell));
+                lines.push(`| ${cellStrings.join(' | ')} |`);
+                break;
+            }
+            case 'child_page': {
+                const title = block.child_page?.title ?? 'Untitled';
+                lines.push(`📄 Page: ${title}`);
+                lines.push('');
+                break;
+            }
+            case 'child_database': {
+                const title = block.child_database?.title ?? 'Untitled';
+                lines.push(`📊 Database: ${title}`);
+                lines.push('');
+                break;
+            }
+            case 'embed': {
+                const url = block.embed?.url ?? '';
+                lines.push(`[embed](${url})`);
+                lines.push('');
+                break;
+            }
+            case 'video': {
+                const video = block.video;
+                let url = '';
+                if (video?.type === 'external') {
+                    url = video.external?.url ?? '';
+                }
+                else if (video?.type === 'file') {
+                    url = video.file?.url ?? '';
+                }
+                lines.push(`[video](${url})`);
+                lines.push('');
+                break;
+            }
+            case 'file': {
+                const file = block.file;
+                let url = '';
+                if (file?.type === 'external') {
+                    url = file.external?.url ?? '';
+                }
+                else if (file?.type === 'file') {
+                    url = file.file?.url ?? '';
+                }
+                lines.push(`[file](${url})`);
+                lines.push('');
+                break;
+            }
+            case 'pdf': {
+                const pdf = block.pdf;
+                let url = '';
+                if (pdf?.type === 'external') {
+                    url = pdf.external?.url ?? '';
+                }
+                else if (pdf?.type === 'file') {
+                    url = pdf.file?.url ?? '';
+                }
+                lines.push(`[pdf](${url})`);
+                lines.push('');
+                break;
+            }
+            case 'link_preview': {
+                const url = block.link_preview?.url ?? '';
+                lines.push(`[link](${url})`);
+                lines.push('');
+                break;
+            }
+            case 'synced_block': {
+                // Children are the actual content; mark as synced
+                if (block.has_children) {
+                    lines.push('*(synced block with children)*');
+                }
+                break;
+            }
+            case 'column_list':
+            case 'column': {
+                // Children hold the actual content
+                if (block.has_children) {
+                    lines.push('');
+                }
+                break;
+            }
+            case 'equation': {
+                const expression = block.equation?.expression ?? '';
+                lines.push(`$${expression}$`);
+                lines.push('');
+                break;
+            }
+            case 'table_of_contents': {
+                lines.push('[TOC]');
+                lines.push('');
+                break;
+            }
+            case 'breadcrumb': {
+                // Skip breadcrumb blocks
+                break;
+            }
+            case 'unsupported': {
+                lines.push('[unsupported block]');
+                lines.push('');
+                break;
+            }
+            default: {
+                lines.push('[unsupported block]');
+                lines.push('');
+                break;
+            }
+        }
+    }
+    return lines.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+function richTextToString(richText) {
+    if (!Array.isArray(richText))
+        return '';
+    return richText.map((t) => t?.plain_text ?? '').join('');
+}

package/dist/utils/format-properties.d.ts

@@ -0,0 +1 @@
+export declare function formatProperties(properties: Record<string, any>): Record<string, string>;

package/dist/utils/format-properties.js

@@ -0,0 +1,158 @@
+export function formatProperties(properties) {
+    const result = {};
+    for (const [key, property] of Object.entries(properties)) {
+        result[key] = formatProperty(property);
+    }
+    return result;
+}
+function formatProperty(property) {
+    if (!property || typeof property !== 'object') {
+        return String(property ?? '');
+    }
+    const type = property.type;
+    switch (type) {
+        case 'title': {
+            const texts = property.title ?? [];
+            return texts.map((t) => t.plain_text ?? '').join('');
+        }
+        case 'rich_text': {
+            const texts = property.rich_text ?? [];
+            return texts.map((t) => t.plain_text ?? '').join('');
+        }
+        case 'number': {
+            const num = property.number;
+            return num === null || num === undefined ? '' : String(num);
+        }
+        case 'select': {
+            return property.select?.name ?? '';
+        }
+        case 'multi_select': {
+            const options = property.multi_select ?? [];
+            return options.map((o) => o.name ?? '').join(', ');
+        }
+        case 'date': {
+            const date = property.date;
+            if (!date)
+                return '';
+            if (date.end) {
+                return `${date.start} ~ ${date.end}`;
+            }
+            return date.start ?? '';
+        }
+        case 'people': {
+            const people = property.people ?? [];
+            return people
+                .map((p) => p.name ?? p.id ?? '')
+                .filter(Boolean)
+                .join(', ');
+        }
+        case 'files': {
+            const files = property.files ?? [];
+            return files
+                .map((f) => {
+                if (f.type === 'external')
+                    return f.external?.url ?? '';
+                if (f.type === 'file')
+                    return f.file?.url ?? '';
+                return '';
+            })
+                .filter(Boolean)
+                .join(', ');
+        }
+        case 'checkbox': {
+            return property.checkbox ? 'Yes' : 'No';
+        }
+        case 'url': {
+            return property.url ?? '';
+        }
+        case 'email': {
+            return property.email ?? '';
+        }
+        case 'phone_number': {
+            return property.phone_number ?? '';
+        }
+        case 'formula': {
+            const formula = property.formula;
+            if (!formula)
+                return '';
+            switch (formula.type) {
+                case 'string':
+                    return formula.string ?? '';
+                case 'number':
+                    return formula.number === null || formula.number === undefined
+                        ? ''
+                        : String(formula.number);
+                case 'boolean':
+                    return formula.boolean ? 'true' : 'false';
+                case 'date':
+                    if (formula.date?.end) {
+                        return `${formula.date.start} ~ ${formula.date.end}`;
+                    }
+                    return formula.date?.start ?? '';
+                default:
+                    return '';
+            }
+        }
+        case 'relation': {
+            const relations = property.relation ?? [];
+            return relations.map((r) => r.id ?? '').filter(Boolean).join(', ');
+        }
+        case 'rollup': {
+            const rollup = property.rollup;
+            if (!rollup)
+                return '';
+            switch (rollup.type) {
+                case 'number':
+                    return rollup.number === null || rollup.number === undefined
+                        ? ''
+                        : String(rollup.number);
+                case 'date':
+                    if (rollup.date?.end) {
+                        return `${rollup.date.start} ~ ${rollup.date.end}`;
+                    }
+                    return rollup.date?.start ?? '';
+                case 'array': {
+                    const items = rollup.array ?? [];
+                    return items
+                        .map((item) => formatProperty(item))
+                        .filter(Boolean)
+                        .join(', ');
+                }
+                default:
+                    return '';
+            }
+        }
+        case 'status': {
+            return property.status?.name ?? '';
+        }
+        case 'created_time': {
+            return property.created_time ?? '';
+        }
+        case 'created_by': {
+            return property.created_by?.name ?? property.created_by?.id ?? '';
+        }
+        case 'last_edited_time': {
+            return property.last_edited_time ?? '';
+        }
+        case 'last_edited_by': {
+            return property.last_edited_by?.name ?? property.last_edited_by?.id ?? '';
+        }
+        case 'unique_id': {
+            const uid = property.unique_id;
+            if (!uid)
+                return '';
+            if (uid.prefix) {
+                return `${uid.prefix}-${uid.number}`;
+            }
+            return String(uid.number ?? '');
+        }
+        default: {
+            try {
+                return JSON.stringify(property);
+            }
+            catch {
+                return '';
+            }
+        }
+    }
+}

package/dist/utils/format-response.d.ts

@@ -0,0 +1,3 @@
+export declare function formatQueryResults(response: any): string;
+export declare function formatSearchResults(response: any): string;
+export declare function truncateIfNeeded(text: string, maxLength?: number): string;

package/dist/utils/format-response.js

@@ -0,0 +1,85 @@
+import { formatProperties } from './format-properties.js';
+export function formatQueryResults(response) {
+    const results = response?.results ?? [];
+    const total = response?.total_count ?? results.length;
+    const hasMore = response?.has_more ?? false;
+    const nextCursor = response?.next_cursor ?? null;
+    const lines = [];
+    const showing = results.length;
+    lines.push(`## Query Results (${total} total, showing 1-${showing})`);
+    lines.push('');
+    for (let i = 0; i < results.length; i++) {
+        const page = results[i];
+        const properties = page?.properties ?? {};
+        const formattedProps = formatProperties(properties);
+        // Find the title property
+        const title = findTitle(properties, formattedProps);
+        lines.push(`### ${i + 1}. ${title || 'Untitled'}`);
+        for (const [key, value] of Object.entries(formattedProps)) {
+            if (value) {
+                lines.push(`- ${key}: ${value}`);
+            }
+        }
+        lines.push(`  ID: ${page?.id ?? ''}`);
+        lines.push('');
+    }
+    if (hasMore) {
+        lines.push(`*More results available. Next cursor: ${nextCursor ?? ''}*`);
+    }
+    return lines.join('\n').trim();
+}
+export function formatSearchResults(response) {
+    const results = response?.results ?? [];
+    const hasMore = response?.has_more ?? false;
+    const nextCursor = response?.next_cursor ?? null;
+    const lines = [];
+    lines.push(`## Search Results (${results.length} found)`);
+    lines.push('');
+    for (let i = 0; i < results.length; i++) {
+        const item = results[i];
+        const objectType = item?.object ?? 'unknown';
+        const id = item?.id ?? '';
+        const lastEdited = item?.last_edited_time ?? '';
+        let title = 'Untitled';
+        if (objectType === 'page') {
+            const properties = item?.properties ?? {};
+            title = extractPageTitle(properties) || item?.title?.[0]?.plain_text || 'Untitled';
+        }
+        else if (objectType === 'database') {
+            const titleArr = item?.title ?? [];
+            title = titleArr.map((t) => t?.plain_text ?? '').join('') || 'Untitled';
+        }
+        lines.push(`${i + 1}. **${title}** (${objectType})`);
+        lines.push(`   Last edited: ${lastEdited} | ID: ${id}`);
+        lines.push('');
+    }
+    if (hasMore) {
+        lines.push(`*More results available. Next cursor: ${nextCursor ?? ''}*`);
+    }
+    return lines.join('\n').trim();
+}
+export function truncateIfNeeded(text, maxLength = 50000) {
+    if (text.length <= maxLength)
+        return text;
+    const truncated = text.slice(0, maxLength);
+    return truncated + `\n\n...[truncated, ${text.length - maxLength} characters omitted]`;
+}
+function findTitle(properties, formattedProps) {
+    // Try to find a 'title' type property first
+    for (const [key, prop] of Object.entries(properties)) {
+        if (prop?.type === 'title') {
+            return formattedProps[key] ?? '';
+        }
+    }
+    // Fall back to a key literally named "Name" or "Title"
+    return formattedProps['Name'] ?? formattedProps['Title'] ?? '';
+}
+function extractPageTitle(properties) {
+    for (const prop of Object.values(properties)) {
+        if (prop?.type === 'title') {
+            const texts = prop.title ?? [];
+            return texts.map((t) => t?.plain_text ?? '').join('');
+        }
+    }
+    return '';
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@devheerim/notion-mcp-server",
+  "version": "1.0.0",
+  "description": "Notion API MCP server with powerful database query support including filters, sorts, and pagination",
+  "type": "module",
+  "license": "MIT",
+  "author": "devheerim",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Henry-Hong/Notion-MCP.git"
+  },
+  "homepage": "https://github.com/Henry-Hong/Notion-MCP#readme",
+  "bugs": {
+    "url": "https://github.com/Henry-Hong/Notion-MCP/issues"
+  },
+  "keywords": [
+    "notion",
+    "mcp",
+    "model-context-protocol",
+    "notion-api",
+    "claude",
+    "ai",
+    "database",
+    "mcp-server"
+  ],
+  "bin": {
+    "notion-mcp-server": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@notionhq/client": "^2.2.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "tsx": "^4.19.0",
+    "@types/node": "^22.0.0"
+  }
+}