@devheerim/notion-mcp-server 1.0.0

package/dist/tools/fetch-page.js

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import { getNotionClient, parseNotionId, formatApiError } from '../notion-client.js';
+import { formatProperties } from '../utils/format-properties.js';
+import { formatBlocks } from '../utils/format-blocks.js';
+import { truncateIfNeeded } from '../utils/format-response.js';
+async function fetchBlocksRecursive(notion, blockId, maxDepth, currentDepth) {
+    const response = await notion.blocks.children.list({ block_id: blockId, page_size: 100 });
+    const blocks = response.results ?? [];
+    if (currentDepth < maxDepth) {
+        for (const block of blocks) {
+            if (block.has_children) {
+                block._children = await fetchBlocksRecursive(notion, block.id, maxDepth, currentDepth + 1);
+            }
+        }
+    }
+    return blocks;
+}
+function flattenBlocks(blocks) {
+    const result = [];
+    for (const block of blocks) {
+        result.push(block);
+        if (block._children && block._children.length > 0) {
+            result.push(...flattenBlocks(block._children));
+        }
+    }
+    return result;
+}
+export function register(server) {
+    server.tool('fetch_page', '페이지 또는 데이터베이스의 상세 정보를 조회합니다. 프로퍼티와 콘텐츠(블록)를 함께 반환합니다.', {
+        page_id: z.string().describe('페이지 또는 데이터베이스 ID / Notion URL'),
+        include_children: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('페이지 콘텐츠 블록 포함 여부 (기본값 true)'),
+        max_depth: z
+            .number()
+            .int()
+            .min(1)
+            .max(3)
+            .optional()
+            .default(2)
+            .describe('블록 재귀 깊이 (1-3, 기본값 2)'),
+    }, async ({ page_id, include_children, max_depth }) => {
+        try {
+            const notion = getNotionClient();
+            const parsedId = parseNotionId(page_id);
+            let pageData;
+            let objectType;
+            try {
+                pageData = await notion.pages.retrieve({ page_id: parsedId });
+                objectType = 'page';
+            }
+            catch (err) {
+                if (err?.status === 404 || err?.code === 'object_not_found') {
+                    pageData = await notion.databases.retrieve({ database_id: parsedId });
+                    objectType = 'database';
+                }
+                else {
+                    throw err;
+                }
+            }
+            const lines = [];
+            // Title
+            const properties = pageData.properties ?? {};
+            let title = 'Untitled';
+            if (objectType === 'page') {
+                for (const prop of Object.values(properties)) {
+                    if (prop?.type === 'title') {
+                        const texts = prop.title ?? [];
+                        title = texts.map((t) => t?.plain_text ?? '').join('') || 'Untitled';
+                        break;
+                    }
+                }
+            }
+            else {
+                const titleArr = pageData.title ?? [];
+                title = titleArr.map((t) => t?.plain_text ?? '').join('') || 'Untitled';
+            }
+            lines.push(`# ${title}`);
+            lines.push('');
+            lines.push(`**ID:** ${pageData.id}`);
+            lines.push(`**Type:** ${objectType}`);
+            lines.push(`**URL:** ${pageData.url ?? ''}`);
+            lines.push(`**Created:** ${pageData.created_time ?? ''}`);
+            lines.push(`**Last Edited:** ${pageData.last_edited_time ?? ''}`);
+            lines.push('');
+            // Properties
+            if (Object.keys(properties).length > 0) {
+                lines.push('## Properties');
+                const formattedProps = formatProperties(properties);
+                for (const [key, value] of Object.entries(formattedProps)) {
+                    if (value) {
+                        lines.push(`- **${key}:** ${value}`);
+                    }
+                }
+                lines.push('');
+            }
+            // Content blocks
+            if (include_children && objectType === 'page') {
+                const blocks = await fetchBlocksRecursive(notion, parsedId, max_depth, 1);
+                const flatBlocks = flattenBlocks(blocks);
+                if (flatBlocks.length > 0) {
+                    lines.push('## Content');
+                    lines.push('');
+                    lines.push(formatBlocks(flatBlocks));
+                }
+            }
+            return {
+                content: [{ type: 'text', text: truncateIfNeeded(lines.join('\n')) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatApiError(error) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/get-comments.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function register(server: McpServer): void;

package/dist/tools/get-comments.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { getNotionClient, parseNotionId, formatApiError } from '../notion-client.js';
+function richTextToPlain(richText) {
+    if (!Array.isArray(richText))
+        return '';
+    return richText.map((t) => t?.plain_text ?? '').join('');
+}
+export function register(server) {
+    server.tool('get_comments', '페이지 또는 블록의 댓글을 조회합니다.', {
+        block_id: z.string().describe('댓글을 조회할 페이지 또는 블록 ID / URL'),
+        start_cursor: z.string().optional().describe('페이지네이션 커서 (선택)'),
+        page_size: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .default(50)
+            .describe('반환할 댓글 수 (1-100, 기본값 50)'),
+    }, async ({ block_id, start_cursor, page_size }) => {
+        try {
+            const notion = getNotionClient();
+            const parsedId = parseNotionId(block_id);
+            const params = {
+                block_id: parsedId,
+                page_size: page_size ?? 50,
+            };
+            if (start_cursor)
+                params['start_cursor'] = start_cursor;
+            const response = await notion.comments.list(params);
+            const comments = response?.results ?? [];
+            const hasMore = response?.has_more ?? false;
+            const nextCursor = response?.next_cursor ?? null;
+            if (comments.length === 0) {
+                return {
+                    content: [{ type: 'text', text: '댓글이 없습니다.' }],
+                };
+            }
+            const lines = [
+                `## 댓글 목록 (${comments.length}개)`,
+                '',
+            ];
+            for (let i = 0; i < comments.length; i++) {
+                const comment = comments[i];
+                const author = comment?.created_by?.name ?? comment?.created_by?.id ?? '알 수 없음';
+                const createdTime = comment?.created_time ?? '';
+                const text = richTextToPlain(comment?.rich_text ?? []);
+                lines.push(`### ${i + 1}. ${author}`);
+                lines.push(`- 시간: ${createdTime}`);
+                lines.push(`- 내용: ${text}`);
+                lines.push(`- ID: ${comment?.id ?? ''}`);
+                if (comment?.discussion_id) {
+                    lines.push(`- 토론 ID: ${comment.discussion_id}`);
+                }
+                lines.push('');
+            }
+            if (hasMore) {
+                lines.push(`*더 많은 댓글이 있습니다. Next cursor: ${nextCursor ?? ''}*`);
+            }
+            return {
+                content: [{ type: 'text', text: lines.join('\n').trim() }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatApiError(error) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/get-users.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function register(server: McpServer): void;

package/dist/tools/get-users.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { getNotionClient, parseNotionId, formatApiError } from '../notion-client.js';
+function formatUser(user) {
+    const lines = [];
+    const name = user?.name ?? '이름 없음';
+    const type = user?.type ?? 'unknown';
+    const id = user?.id ?? '';
+    const avatarUrl = user?.avatar_url ?? '';
+    lines.push(`- 이름: ${name}`);
+    lines.push(`- 유형: ${type}`);
+    lines.push(`- ID: ${id}`);
+    if (type === 'person') {
+        const email = user?.person?.email ?? '';
+        if (email)
+            lines.push(`- 이메일: ${email}`);
+    }
+    else if (type === 'bot') {
+        const ownerType = user?.bot?.owner?.type ?? '';
+        if (ownerType)
+            lines.push(`- 봇 소유자 유형: ${ownerType}`);
+        const workspaceName = user?.bot?.workspace_name ?? '';
+        if (workspaceName)
+            lines.push(`- 워크스페이스: ${workspaceName}`);
+    }
+    if (avatarUrl)
+        lines.push(`- 아바타: ${avatarUrl}`);
+    return lines;
+}
+export function register(server) {
+    server.tool('get_users', '워크스페이스 사용자 목록을 조회하거나 특정 사용자 정보를 가져옵니다.', {
+        user_id: z.string().optional().describe('특정 사용자 ID (선택, 생략 시 전체 목록)'),
+        start_cursor: z.string().optional().describe('페이지네이션 커서 (선택)'),
+        page_size: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .default(50)
+            .describe('반환할 사용자 수 (1-100, 기본값 50)'),
+    }, async ({ user_id, start_cursor, page_size }) => {
+        try {
+            const notion = getNotionClient();
+            if (user_id) {
+                const parsedId = parseNotionId(user_id);
+                const user = await notion.users.retrieve({ user_id: parsedId });
+                const lines = [`## 사용자 정보`, '', ...formatUser(user)];
+                return {
+                    content: [{ type: 'text', text: lines.join('\n') }],
+                };
+            }
+            const params = {
+                page_size: page_size ?? 50,
+            };
+            if (start_cursor)
+                params['start_cursor'] = start_cursor;
+            const response = await notion.users.list(params);
+            const users = response?.results ?? [];
+            const hasMore = response?.has_more ?? false;
+            const nextCursor = response?.next_cursor ?? null;
+            if (users.length === 0) {
+                return {
+                    content: [{ type: 'text', text: '사용자가 없습니다.' }],
+                };
+            }
+            const lines = [`## 사용자 목록 (${users.length}명)`, ''];
+            for (let i = 0; i < users.length; i++) {
+                lines.push(`### ${i + 1}. ${users[i]?.name ?? '이름 없음'}`);
+                lines.push(...formatUser(users[i]));
+                lines.push('');
+            }
+            if (hasMore) {
+                lines.push(`*더 많은 사용자가 있습니다. Next cursor: ${nextCursor ?? ''}*`);
+            }
+            return {
+                content: [{ type: 'text', text: lines.join('\n').trim() }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatApiError(error) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/move-pages.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function register(server: McpServer): void;

package/dist/tools/move-pages.js

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { getNotionClient, parseNotionId, formatApiError } from '../notion-client.js';
+export function register(server) {
+    server.tool('move_pages', '페이지를 다른 부모로 이동합니다.', {
+        page_ids: z
+            .array(z.string())
+            .min(1)
+            .max(50)
+            .describe('이동할 페이지 ID 목록 (최소 1개, 최대 50개)'),
+        parent_type: z
+            .enum(['page_id', 'database_id'])
+            .describe('새 부모의 유형: "page_id" 또는 "database_id"'),
+        parent_id: z.string().describe('새 부모 페이지 또는 데이터베이스 ID / URL'),
+    }, async ({ page_ids, parent_type, parent_id }) => {
+        try {
+            const notion = getNotionClient();
+            const parsedParentId = parseNotionId(parent_id);
+            const parent = parent_type === 'database_id'
+                ? { type: 'database_id', database_id: parsedParentId }
+                : { type: 'page_id', page_id: parsedParentId };
+            const results = [];
+            for (const rawPageId of page_ids) {
+                const parsedPageId = parseNotionId(rawPageId);
+                try {
+                    await notion.pages.update({
+                        page_id: parsedPageId,
+                        parent: parent,
+                    });
+                    results.push({ id: parsedPageId, success: true, message: '이동 완료' });
+                }
+                catch (err) {
+                    results.push({
+                        id: parsedPageId,
+                        success: false,
+                        message: formatApiError(err),
+                    });
+                }
+            }
+            const successCount = results.filter((r) => r.success).length;
+            const failCount = results.length - successCount;
+            const lines = [
+                `## 페이지 이동 결과`,
+                `- 성공: ${successCount}개 / 실패: ${failCount}개`,
+                `- 대상 부모: ${parent_type} = ${parsedParentId}`,
+                '',
+            ];
+            for (const result of results) {
+                const status = result.success ? '성공' : '실패';
+                lines.push(`- [${status}] ${result.id}: ${result.message}`);
+            }
+            if (failCount > 0) {
+                lines.push('');
+                lines.push('참고: Notion API는 페이지 부모 변경에 제한이 있을 수 있습니다. ' +
+                    '특히 다른 워크스페이스나 공유 권한이 다른 페이지로의 이동은 지원되지 않습니다.');
+            }
+            return {
+                content: [{ type: 'text', text: lines.join('\n') }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatApiError(error) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/query-database.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function register(server: McpServer): void;

package/dist/tools/query-database.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { getNotionClient, parseNotionId, formatApiError } from '../notion-client.js';
+import { formatQueryResults, truncateIfNeeded } from '../utils/format-response.js';
+export function register(server) {
+    server.tool('query_database', '데이터베이스를 필터, 정렬, 페이지네이션으로 쿼리합니다. 프로퍼티 기반 정밀 필터링이 가능합니다.', {
+        database_id: z.string().describe('데이터베이스 ID 또는 Notion URL'),
+        filter: z
+            .record(z.any())
+            .optional()
+            .describe('Notion 필터 객체. 단일: {"property": "Status", "select": {"equals": "Done"}}, ' +
+            '복합: {"and": [{"property": "Status", "select": {"equals": "Done"}}, ...]}'),
+        sorts: z
+            .array(z.record(z.any()))
+            .optional()
+            .describe('정렬 배열. 예: [{"property": "Name", "direction": "ascending"}] 또는 ' +
+            '[{"timestamp": "created_time", "direction": "descending"}]'),
+        start_cursor: z.string().optional().describe('페이지네이션 커서'),
+        page_size: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .default(50)
+            .describe('반환할 결과 수 (1-100, 기본값 50)'),
+    }, async ({ database_id, filter, sorts, start_cursor, page_size }) => {
+        try {
+            const notion = getNotionClient();
+            const parsedId = parseNotionId(database_id);
+            const queryParams = {
+                database_id: parsedId,
+                page_size,
+            };
+            if (filter !== undefined)
+                queryParams.filter = filter;
+            if (sorts !== undefined)
+                queryParams.sorts = sorts;
+            if (start_cursor !== undefined)
+                queryParams.start_cursor = start_cursor;
+            const response = await notion.databases.query(queryParams);
+            const formatted = formatQueryResults(response);
+            return {
+                content: [{ type: 'text', text: truncateIfNeeded(formatted) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatApiError(error) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/search.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function register(server: McpServer): void;

package/dist/tools/search.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { getNotionClient, formatApiError } from '../notion-client.js';
+import { formatSearchResults, truncateIfNeeded } from '../utils/format-response.js';
+export function register(server) {
+    server.tool('search', '워크스페이스에서 페이지/데이터베이스를 검색합니다.', {
+        query: z.string().optional().describe('검색어 (선택)'),
+        filter_object_type: z
+            .enum(['page', 'database'])
+            .optional()
+            .describe('검색 대상 타입 필터: "page" 또는 "database"'),
+        sort_direction: z
+            .enum(['ascending', 'descending'])
+            .optional()
+            .default('descending')
+            .describe('정렬 방향 (기본값 descending)'),
+        start_cursor: z.string().optional().describe('페이지네이션 커서'),
+        page_size: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .default(20)
+            .describe('반환할 결과 수 (1-100, 기본값 20)'),
+    }, async ({ query, filter_object_type, sort_direction, start_cursor, page_size }) => {
+        try {
+            const notion = getNotionClient();
+            const searchParams = {
+                page_size,
+                sort: {
+                    direction: sort_direction,
+                    timestamp: 'last_edited_time',
+                },
+            };
+            if (query !== undefined)
+                searchParams.query = query;
+            if (filter_object_type !== undefined) {
+                searchParams.filter = {
+                    value: filter_object_type,
+                    property: 'object',
+                };
+            }
+            if (start_cursor !== undefined)
+                searchParams.start_cursor = start_cursor;
+            const response = await notion.search(searchParams);
+            const formatted = formatSearchResults(response);
+            return {
+                content: [{ type: 'text', text: truncateIfNeeded(formatted) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatApiError(error) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/update-database.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function register(server: McpServer): void;

package/dist/tools/update-database.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { getNotionClient, parseNotionId, formatApiError } from '../notion-client.js';
+export function register(server) {
+    server.tool('update_database', '데이터베이스의 제목, 설명, 프로퍼티 스키마를 수정합니다.', {
+        database_id: z.string().describe('수정할 데이터베이스 ID 또는 URL'),
+        title: z.string().optional().describe('새 데이터베이스 제목 (선택)'),
+        description: z.string().optional().describe('새 데이터베이스 설명 (선택)'),
+        properties: z
+            .record(z.any())
+            .optional()
+            .describe('프로퍼티 스키마 변경사항 (선택). 추가/수정: {"NewProp": {"select": {...}}}, 삭제: {"OldProp": null}'),
+    }, async ({ database_id, title, description, properties }) => {
+        try {
+            const notion = getNotionClient();
+            const parsedId = parseNotionId(database_id);
+            const updateParams = { database_id: parsedId };
+            if (title !== undefined) {
+                updateParams['title'] = [
+                    { type: 'text', text: { content: title } },
+                ];
+            }
+            if (description !== undefined) {
+                updateParams['description'] = [
+                    { type: 'text', text: { content: description } },
+                ];
+            }
+            if (properties !== undefined) {
+                updateParams['properties'] = properties;
+            }
+            const response = await notion.databases.update(updateParams);
+            const responseTitle = (() => {
+                const titleArr = response.title ?? [];
+                return titleArr.map((t) => t?.plain_text ?? '').join('') || '제목 없음';
+            })();
+            const responseDesc = (() => {
+                const descArr = response.description ?? [];
+                return descArr.map((t) => t?.plain_text ?? '').join('');
+            })();
+            const propCount = Object.keys(response.properties ?? {}).length;
+            const url = response.url ?? '';
+            const lines = [
+                `## 데이터베이스 업데이트 완료`,
+                `- ID: ${response.id}`,
+                `- 제목: ${responseTitle}`,
+            ];
+            if (responseDesc)
+                lines.push(`- 설명: ${responseDesc}`);
+            lines.push(`- 프로퍼티 수: ${propCount}`);
+            if (url)
+                lines.push(`- URL: ${url}`);
+            const changed = [];
+            if (title !== undefined)
+                changed.push('제목');
+            if (description !== undefined)
+                changed.push('설명');
+            if (properties !== undefined)
+                changed.push('프로퍼티 스키마');
+            if (changed.length > 0)
+                lines.push(`- 변경된 항목: ${changed.join(', ')}`);
+            return {
+                content: [{ type: 'text', text: lines.join('\n') }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatApiError(error) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/update-page.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function register(server: McpServer): void;

package/dist/tools/update-page.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { getNotionClient, parseNotionId, formatApiError } from '../notion-client.js';
+import { formatProperties } from '../utils/format-properties.js';
+export function register(server) {
+    server.tool('update_page', '기존 페이지의 프로퍼티를 업데이트합니다. 아카이브/복원도 가능합니다.', {
+        page_id: z.string().describe('업데이트할 페이지 ID 또는 Notion URL'),
+        properties: z
+            .record(z.any())
+            .optional()
+            .describe('업데이트할 프로퍼티 객체 (변경할 항목만 포함)'),
+        archived: z
+            .boolean()
+            .optional()
+            .describe('true: 페이지 아카이브, false: 복원'),
+        icon: z
+            .record(z.any())
+            .optional()
+            .describe('아이콘 설정. 예: {"type": "emoji", "emoji": "🎯"}'),
+        cover: z
+            .record(z.any())
+            .optional()
+            .describe('커버 설정. 예: {"type": "external", "external": {"url": "https://..."}}'),
+    }, async ({ page_id, properties, archived, icon, cover }) => {
+        try {
+            const notion = getNotionClient();
+            const parsedId = parseNotionId(page_id);
+            const updateParams = { page_id: parsedId };
+            if (properties !== undefined)
+                updateParams.properties = properties;
+            if (archived !== undefined)
+                updateParams.archived = archived;
+            if (icon !== undefined)
+                updateParams.icon = icon;
+            if (cover !== undefined)
+                updateParams.cover = cover;
+            const response = await notion.pages.update(updateParams);
+            const formattedProps = formatProperties(response.properties ?? {});
+            const lines = [
+                '## 페이지 업데이트 완료',
+                `- ID: ${response.id}`,
+                `- URL: ${response.url ?? ''}`,
+                `- 수정 시간: ${response.last_edited_time ?? ''}`,
+                `- 아카이브 상태: ${response.archived ? '아카이브됨' : '활성'}`,
+                '',
+                '### 현재 프로퍼티',
+            ];
+            for (const [key, value] of Object.entries(formattedProps)) {
+                if (value)
+                    lines.push(`- ${key}: ${value}`);
+            }
+            return {
+                content: [{ type: 'text', text: lines.join('\n') }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatApiError(error) }],
+                isError: true,
+            };
+        }
+    });
+}

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

@@ -0,0 +1 @@
+export declare function formatBlocks(blocks: any[]): string;