@atikk-co-jp/notion-mcp-server 0.7.0 → 0.8.1

package/dist/src/tools/retrieve-database.js

@@ -1,11 +1,10 @@
 import { z } from 'zod';
+import { isFullDatabase } from '../notion-client.js';
+import { F } from '../schemas/descriptions/index.js';
 import { formatResponse, formatSimpleResponse, handleError } from '../utils/index.js';
 const inputSchema = {
-    database_id: z.string().describe('Database ID'),
-    format: z
-        .enum(['json', 'simple'])
-        .optional()
-        .describe("Output format: 'simple' (default) or 'json'"),
+    database_id: z.string().describe(F.database_id),
+    format: z.enum(['json', 'simple']).optional().describe(F.format),
 };
 export function registerRetrieveDatabase(server, notion) {
     server.registerTool('retrieve-database', {
@@ -19,11 +18,17 @@ export function registerRetrieveDatabase(server, notion) {
             if (format === 'json') {
                 return formatResponse(response);
             }
+            // Need full database for simple format
+            if (!isFullDatabase(response)) {
+                return formatResponse(response);
+            }
             // Simple format: extract essential info
             const simpleResponse = {
                 id: response.id,
                 title: response.title.map((t) => t.plain_text).join(''),
-                description: response.description.map((t) => t.plain_text).join(''),
+                description: response.description
+                    .map((t) => t.plain_text)
+                    .join(''),
                 url: response.url,
                 is_inline: response.is_inline,
                 in_trash: response.in_trash,

package/dist/src/tools/retrieve-page-property.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retrieve-page-property.d.ts","sourceRoot":"","sources":["../../../src/tools/retrieve-page-property.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAmBvD,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAiC1F"}
+{"version":3,"file":"retrieve-page-property.d.ts","sourceRoot":"","sources":["../../../src/tools/retrieve-page-property.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAWvD,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAiC1F"}

package/dist/src/tools/retrieve-page-property.js

@@ -1,10 +1,11 @@
 import { z } from 'zod';
+import { F } from '../schemas/descriptions/index.js';
 import { formatPaginatedResponse, formatResponse, handleError } from '../utils/index.js';
 const inputSchema = {
-    page_id: z.string().describe('Page ID'),
-    property_id: z.string().describe('Property ID (from page properties)'),
-    start_cursor: z.string().optional().describe('Pagination cursor'),
-    page_size: z.number().optional().describe('Number of results (1-100)'),
+    page_id: z.string().describe(F.page_id),
+    property_id: z.string().describe(F.property_id),
+    start_cursor: z.string().optional().describe(F.start_cursor),
+    page_size: z.number().optional().describe(F.page_size),
 };
 export function registerRetrievePageProperty(server, notion) {
     server.registerTool('retrieve-page-property', {
@@ -12,7 +13,7 @@ export function registerRetrievePageProperty(server, notion) {
         inputSchema,
     }, async ({ page_id, property_id, start_cursor, page_size }) => {
         try {
-            const response = await notion.pages.retrieveProperty({
+            const response = await notion.pages.properties.retrieve({
                 page_id,
                 property_id,
                 start_cursor,

package/dist/src/tools/retrieve-page.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { NotionClient } from '../notion-client.js';
+import { type NotionClient } from '../notion-client.js';
 export declare function registerRetrievePage(server: McpServer, notion: NotionClient): void;
 //# sourceMappingURL=retrieve-page.d.ts.map

package/dist/src/tools/retrieve-page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retrieve-page.d.ts","sourceRoot":"","sources":["../../../src/tools/retrieve-page.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAQxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAkCvD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAgDlF"}
+{"version":3,"file":"retrieve-page.d.ts","sourceRoot":"","sources":["../../../src/tools/retrieve-page.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGxE,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAA;AAU5B,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAkDlF"}

package/dist/src/tools/retrieve-page.js

@@ -1,18 +1,12 @@
 import { z } from 'zod';
-import { blocksToMarkdown, pageToSimple, } from '../converters/index.js';
+import { blocksToMarkdown, pageToSimple } from '../converters/index.js';
+import { isFullBlock, isFullPage, } from '../notion-client.js';
+import { F } from '../schemas/descriptions/index.js';
 import { formatResponse, formatSimpleResponse, handleError } from '../utils/index.js';
 const inputSchema = {
-    page_id: z.string().describe('The ID of the page to retrieve'),
-    format: z
-        .enum(['json', 'simple'])
-        .optional()
-        .default('simple')
-        .describe("Output format: 'simple' (default) returns simplified property values with reduced token usage, 'json' returns raw Notion API response"),
-    include_content: z
-        .boolean()
-        .optional()
-        .default(true)
-        .describe('Include page content (blocks) as markdown. Default is true. Set to false to only retrieve page properties.'),
+    page_id: z.string().describe(F.page_id),
+    format: z.enum(['json', 'simple']).optional().default('simple').describe(F.format),
+    include_content: z.boolean().optional().default(true).describe(F.include_content),
 };
 export function registerRetrievePage(server, notion) {
     server.registerTool('retrieve-page', {
@@ -24,19 +18,20 @@ export function registerRetrievePage(server, notion) {
             // コンテンツを取得
             let content;
             if (include_content) {
-                const blocksResponse = await notion.blocks.children.list({
-                    block_id: page_id,
-                });
+                const blocksResponse = await notion.blocks.children.list({ block_id: page_id });
+                // Filter to full blocks
+                const blocks = blocksResponse.results.filter(isFullBlock);
                 // 子ブロックを再帰的に取得するヘルパー
                 const fetchChildren = async (blockId) => {
-                    const res = await notion.blocks.children.list({
-                        block_id: blockId,
-                    });
-                    return res.results;
+                    const res = await notion.blocks.children.list({ block_id: blockId });
+                    return res.results.filter(isFullBlock);
                 };
-                content = await blocksToMarkdown(blocksResponse.results, { fetchChildren });
+                content = await blocksToMarkdown(blocks, { fetchChildren });
             }
             if (format === 'simple') {
+                if (!isFullPage(response)) {
+                    return formatResponse(response);
+                }
                 const simple = pageToSimple(response);
                 if (content !== undefined) {
                     return formatSimpleResponse({ ...simple, content });

package/dist/src/tools/retrieve-user.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retrieve-user.d.ts","sourceRoot":"","sources":["../../../src/tools/retrieve-user.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAOvD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAiBlF"}
+{"version":3,"file":"retrieve-user.d.ts","sourceRoot":"","sources":["../../../src/tools/retrieve-user.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAQvD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAiBlF"}

package/dist/src/tools/retrieve-user.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
+import { F } from '../schemas/descriptions/index.js';
 import { formatResponse, handleError } from '../utils/index.js';
 const inputSchema = {
-    user_id: z.string().describe('User ID'),
+    user_id: z.string().describe(F.user_id),
 };
 export function registerRetrieveUser(server, notion) {
     server.registerTool('retrieve-user', {

package/dist/src/tools/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/tools/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AA8CvD,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAiD5E"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/tools/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AA6BvD,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAmD5E"}

package/dist/src/tools/search.js

@@ -1,33 +1,24 @@
 import { z } from 'zod';
-import { formatPaginatedResponse, handleError } from '../utils/index.js';
+import { F } from '../schemas/descriptions/index.js';
+import { formatPaginatedResponse, handleErrorWithContext } from '../utils/index.js';
 const inputSchema = {
-    query: z.string().optional().describe('Text to search for in page titles and content'),
+    query: z.string().optional().describe(F.query),
     filter: z
         .object({
         value: z.enum(['page', 'data_source']),
         property: z.literal('object'),
     })
         .optional()
-        .describe('Filter to limit results to pages or data sources. ' +
-        'Example: { "value": "page", "property": "object" }'),
+        .describe(F.filter_search),
     sort: z
         .object({
         direction: z.enum(['ascending', 'descending']),
         timestamp: z.literal('last_edited_time'),
     })
         .optional()
-        .describe('Sort order for results. ' +
-        'Example: { "direction": "descending", "timestamp": "last_edited_time" }'),
-    start_cursor: z
-        .string()
-        .optional()
-        .describe('Cursor for pagination. Use the next_cursor from previous response.'),
-    page_size: z
-        .number()
-        .min(1)
-        .max(100)
-        .optional()
-        .describe('Number of results to return (1-100). Default is 100.'),
+        .describe(F.sort),
+    start_cursor: z.string().optional().describe(F.start_cursor),
+    page_size: z.number().min(1).max(100).optional().describe(F.page_size),
 };
 export function registerSearch(server, notion) {
     server.registerTool('search', {
@@ -59,7 +50,9 @@ export function registerSearch(server, notion) {
             return formatPaginatedResponse(response.results, response.has_more, response.next_cursor);
         }
         catch (error) {
-            return handleError(error);
+            return handleErrorWithContext(error, notion, {
+                exampleType: 'filter',
+            });
         }
     });
 }

package/dist/src/tools/update-block-simple.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { NotionClient } from '../notion-client.js';
+import { type NotionClient } from '../notion-client.js';
 export declare function registerUpdateBlockSimple(server: McpServer, notion: NotionClient): void;
 //# sourceMappingURL=update-block-simple.d.ts.map

package/dist/src/tools/update-block-simple.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-block-simple.d.ts","sourceRoot":"","sources":["../../../src/tools/update-block-simple.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAwBvD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CA2DvF"}
+{"version":3,"file":"update-block-simple.d.ts","sourceRoot":"","sources":["../../../src/tools/update-block-simple.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGxE,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAyBpE,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAiEvF"}

package/dist/src/tools/update-block-simple.js

@@ -1,9 +1,11 @@
 import { z } from 'zod';
 import { parseInlineMarkdown } from '../converters/index.js';
+import { isFullBlock } from '../notion-client.js';
+import { F } from '../schemas/descriptions/index.js';
 import { formatResponse, handleError } from '../utils/index.js';
 const inputSchema = {
-    block_id: z.string().describe('Block ID to update'),
-    content: z.string().describe('New content in Markdown format'),
+    block_id: z.string().describe(F.block_id),
+    content: z.string().describe(F.content),
 };
 // Supported block types for simple update
 const SUPPORTED_TYPES = [
@@ -28,6 +30,14 @@ export function registerUpdateBlockSimple(server, notion) {
         try {
             // First, retrieve the block to get its type
             const existingBlock = await notion.blocks.retrieve({ block_id });
+            if (!isFullBlock(existingBlock)) {
+                return {
+                    content: [
+                        { type: 'text', text: 'Error: Could not retrieve full block details.' },
+                    ],
+                    isError: true,
+                };
+            }
             const blockType = existingBlock.type;
             if (!SUPPORTED_TYPES.includes(blockType)) {
                 return {
@@ -46,11 +56,11 @@ export function registerUpdateBlockSimple(server, notion) {
             const params = {
                 block_id,
             };
-            if (blockType === 'to_do') {
+            if (blockType === 'to_do' && existingBlock.type === 'to_do') {
                 // Preserve the checked state for to_do blocks
                 params[blockType] = {
                     rich_text: richText,
-                    checked: existingBlock.to_do?.checked ?? false,
+                    checked: existingBlock.to_do.checked ?? false,
                 };
             }
             else {

package/dist/src/tools/update-block.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-block.d.ts","sourceRoot":"","sources":["../../../src/tools/update-block.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AASvD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CA4BjF"}
+{"version":3,"file":"update-block.d.ts","sourceRoot":"","sources":["../../../src/tools/update-block.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAUvD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CA8BjF"}

package/dist/src/tools/update-block.js

@@ -1,9 +1,10 @@
 import { z } from 'zod';
-import { formatResponse, handleError } from '../utils/index.js';
+import { F } from '../schemas/descriptions/index.js';
+import { formatResponse, handleErrorWithContext } from '../utils/index.js';
 const inputSchema = {
-    block_id: z.string().describe('Block ID to update'),
-    block: z.record(z.string(), z.any()).describe('Block data with type-specific properties'),
-    archived: z.boolean().optional().describe('Set to true to archive the block'),
+    block_id: z.string().describe(F.block_id),
+    block: z.record(z.string(), z.any()).describe(F.block),
+    archived: z.boolean().optional().describe(F.archived),
 };
 export function registerUpdateBlock(server, notion) {
     server.registerTool('update-block', {
@@ -24,7 +25,9 @@ export function registerUpdateBlock(server, notion) {
             return formatResponse(response);
         }
         catch (error) {
-            return handleError(error);
+            return handleErrorWithContext(error, notion, {
+                exampleType: 'block',
+            });
         }
     });
 }

package/dist/src/tools/update-data-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-data-source.d.ts","sourceRoot":"","sources":["../../../src/tools/update-data-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAYvD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CA6BtF"}
+{"version":3,"file":"update-data-source.d.ts","sourceRoot":"","sources":["../../../src/tools/update-data-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAcvD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CA+BtF"}

package/dist/src/tools/update-data-source.js

@@ -1,12 +1,10 @@
 import { z } from 'zod';
+import { F } from '../schemas/descriptions/index.js';
 import { formatResponse, handleErrorWithContext } from '../utils/index.js';
 // Minimal schema for MCP (full validation by Notion API)
 const inputSchema = {
-    data_source_id: z.string().describe('Data source ID'),
-    properties: z
-        .record(z.string(), z.any())
-        .optional()
-        .describe('Properties to add/update/delete (set to null to delete)'),
+    data_source_id: z.string().describe(F.data_source_id),
+    properties: z.record(z.string(), z.any()).optional().describe(F.properties_update),
 };
 export function registerUpdateDataSource(server, notion) {
     server.registerTool('update-data-source', {
@@ -20,12 +18,14 @@ export function registerUpdateDataSource(server, notion) {
             if (properties !== undefined) {
                 params.properties = properties;
             }
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const response = await notion.dataSources.update(params);
             return formatResponse(response);
         }
         catch (error) {
-            return handleErrorWithContext(error, notion, data_source_id);
+            return handleErrorWithContext(error, notion, {
+                dataSourceId: data_source_id,
+                exampleType: 'schema',
+            });
         }
     });
 }

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

@@ -1 +1 @@
-{"version":3,"file":"update-database.d.ts","sourceRoot":"","sources":["../../../src/tools/update-database.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAgBvD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CA4DpF"}
+{"version":3,"file":"update-database.d.ts","sourceRoot":"","sources":["../../../src/tools/update-database.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAkBvD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAgCpF"}

package/dist/src/tools/update-database.js

@@ -1,16 +1,18 @@
 import { z } from 'zod';
-import { formatResponse, handleError } from '../utils/index.js';
+import { F } from '../schemas/descriptions/index.js';
+import { formatResponse, handleErrorWithContext } from '../utils/index.js';
 // Minimal schema for MCP (full validation by Notion API)
 // Note: Properties (schema) updates should use update-data-source in API 2025-09-03
+// Uses z.any() for title/description/icon/cover to reduce context size (~3,700 tokens saved)
 const inputSchema = {
-    database_id: z.string().describe('Database ID'),
-    title: z.array(z.any()).optional().describe('New title'),
-    description: z.array(z.any()).optional().describe('New description'),
-    icon: z.any().optional().describe('Icon object { type: "emoji", emoji: "📝" } or null to remove. Emoji must be an actual emoji character.'),
-    cover: z.any().optional().describe('Cover (null to remove)'),
-    is_inline: z.boolean().optional().describe('Inline database'),
-    archived: z.boolean().optional().describe('Archive status'),
-    is_locked: z.boolean().optional().describe('Lock the database to prevent edits in the UI. Set to true to lock, false to unlock.'),
+    database_id: z.string().describe(F.database_id),
+    title: z.any().optional().describe(F.title),
+    description: z.any().optional().describe(F.description),
+    icon: z.any().nullable().optional().describe(F.icon),
+    cover: z.any().nullable().optional().describe(F.cover),
+    is_inline: z.boolean().optional().describe(F.is_inline),
+    archived: z.boolean().optional().describe(F.archived),
+    is_locked: z.boolean().optional().describe(F.is_locked),
 };
 export function registerUpdateDatabase(server, notion) {
     server.registerTool('update-database', {
@@ -19,36 +21,24 @@ export function registerUpdateDatabase(server, notion) {
         inputSchema,
     }, async ({ database_id, title, description, icon, cover, is_inline, archived, is_locked }) => {
         try {
+            // Build params with only defined values (API validates full structure)
             const params = {
                 database_id,
+                ...(title !== undefined && { title }),
+                ...(description !== undefined && { description }),
+                ...(icon !== undefined && { icon }),
+                ...(cover !== undefined && { cover }),
+                ...(is_inline !== undefined && { is_inline }),
+                ...(archived !== undefined && { archived }),
+                ...(is_locked !== undefined && { is_locked }),
             };
-            if (title !== undefined) {
-                params.title = title;
-            }
-            if (description !== undefined) {
-                params.description = description;
-            }
-            if (icon !== undefined) {
-                params.icon = icon;
-            }
-            if (cover !== undefined) {
-                params.cover = cover;
-            }
-            if (is_inline !== undefined) {
-                params.is_inline = is_inline;
-            }
-            if (archived !== undefined) {
-                params.archived = archived;
-            }
-            if (is_locked !== undefined) {
-                params.is_locked = is_locked;
-            }
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const response = await notion.databases.update(params);
             return formatResponse(response);
         }
         catch (error) {
-            return handleError(error);
+            return handleErrorWithContext(error, notion, {
+                exampleType: 'richTextArray',
+            });
         }
     });
 }

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

@@ -1 +1 @@
-{"version":3,"file":"update-page.d.ts","sourceRoot":"","sources":["../../../src/tools/update-page.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAkBvD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAoDhF"}
+{"version":3,"file":"update-page.d.ts","sourceRoot":"","sources":["../../../src/tools/update-page.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAoBvD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAsDhF"}

package/dist/src/tools/update-page.js

@@ -1,13 +1,14 @@
 import { z } from 'zod';
+import { F } from '../schemas/descriptions/index.js';
 import { formatResponse, handleErrorWithContext } from '../utils/index.js';
 // Minimal schema for MCP (full validation by Notion API)
 const inputSchema = {
-    page_id: z.string().describe('Page ID'),
-    properties: z.record(z.string(), z.any()).optional().describe('Properties to update'),
-    archived: z.boolean().optional().describe('Archive the page'),
-    icon: z.any().optional().describe('Page icon { type: "emoji", emoji: "📝" } or { type: "external", external: { url: "..." } }, or null to remove. Emoji must be an actual emoji character.'),
-    cover: z.any().optional().describe('Cover image (null to remove)'),
-    is_locked: z.boolean().optional().describe('Lock the page to prevent edits in the UI. Set to true to lock, false to unlock.'),
+    page_id: z.string().describe(F.page_id),
+    properties: z.record(z.string(), z.any()).optional().describe(F.properties),
+    archived: z.boolean().optional().describe(F.archived),
+    icon: z.any().optional().describe(F.icon),
+    cover: z.any().optional().describe(F.cover),
+    is_locked: z.boolean().optional().describe(F.is_locked),
 };
 export function registerUpdatePage(server, notion) {
     server.registerTool('update-page', {
@@ -40,8 +41,10 @@ export function registerUpdatePage(server, notion) {
         }
         catch (error) {
             // Note: update-page uses page_id, not data_source_id,
-            // so we can't show available properties without additional API call
-            return handleErrorWithContext(error, notion);
+            // so we can't fetch property list, but we can still show format examples
+            return handleErrorWithContext(error, notion, {
+                exampleType: 'page',
+            });
         }
     });
 }

package/dist/src/utils/error-handler.d.ts

@@ -1,4 +1,5 @@
-import type { NotionClient } from '../notion-client.js';
+import { type NotionClient } from '../notion-client.js';
+import { type ExampleType } from '../schemas/descriptions/index.js';
 export interface McpTextContent {
     type: 'text';
     text: string;
@@ -9,14 +10,22 @@ export interface McpResponse {
     isError?: boolean;
 }
 export declare function handleError(error: unknown): McpResponse;
-interface HandleErrorOptions {
-    /** Additional hint to append after property list (e.g., usage examples) */
+export interface HandleErrorOptions {
+    /** Data source ID to fetch schema for property list */
+    dataSourceId?: string;
+    /** Type of examples to show */
+    exampleType?: ExampleType;
+    /** Additional hint to append (e.g., usage examples) */
     hint?: string;
 }
 /**
- * Enhanced error handler that includes available properties for validation errors.
- * Use this for tools that operate on data sources (create-page, update-page, etc.)
+ * Enhanced error handler that includes contextual help for validation errors.
+ *
+ * Usage:
+ * - Page tools: handleErrorWithContext(error, notion, { dataSourceId, exampleType: 'page' })
+ * - Schema tools: handleErrorWithContext(error, notion, { dataSourceId, exampleType: 'schema' })
+ * - Block tools: handleErrorWithContext(error, notion, { exampleType: 'block' })
+ * - Filter tools: handleErrorWithContext(error, notion, { exampleType: 'filter' })
  */
-export declare function handleErrorWithContext(error: unknown, notion: NotionClient, dataSourceId?: string, options?: HandleErrorOptions): Promise<McpResponse>;
-export {};
+export declare function handleErrorWithContext(error: unknown, notion: NotionClient, options?: HandleErrorOptions): Promise<McpResponse>;
 //# sourceMappingURL=error-handler.d.ts.map

package/dist/src/utils/error-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../../src/utils/error-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IACtB,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAkBD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAoBvD;AA2DD,UAAU,kBAAkB;IAC1B,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,YAAY,EACpB,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAsBtB"}
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../../src/utils/error-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACzE,OAAO,EACL,KAAK,WAAW,EAIjB,MAAM,kCAAkC,CAAA;AAOzC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IACtB,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAaD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAoBvD;AAuED,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,+BAA+B;IAC/B,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAsCtB"}

package/dist/src/utils/error-handler.js

@@ -1,3 +1,5 @@
+import { isFullDataSource } from '../notion-client.js';
+import { getExamplesByType, PagePropertyExamples, SchemaPropertyExamples, } from '../schemas/descriptions/index.js';
 function isNotionApiError(error) {
     if (!(error instanceof Error))
         return false;
@@ -65,36 +67,61 @@ function formatNotionError(error) {
 function isValidationError(error) {
     if (!(error instanceof Error))
         return false;
-    // Check if error message contains validation_error code
     return error.message.includes('validation_error');
 }
-function formatPropertyList(properties) {
-    return Object.entries(properties)
+function formatPropertyList(properties, exampleType) {
+    const propList = Object.entries(properties)
         .map(([name, prop]) => `  - ${name} (${prop.type})`)
         .join('\n');
+    // Get unique property types and their examples based on exampleType
+    const examples = exampleType === 'page' ? PagePropertyExamples : SchemaPropertyExamples;
+    const uniqueTypes = [...new Set(Object.values(properties).map((p) => p.type))];
+    const exampleLines = uniqueTypes
+        .filter((type) => examples[type])
+        .map((type) => `  ${type}: ${examples[type]}`)
+        .join('\n');
+    if (exampleLines) {
+        const label = exampleType === 'page' ? 'Page property' : 'Schema property';
+        return `${propList}\n\n${label} format examples:\n${exampleLines}`;
+    }
+    return propList;
 }
 /**
- * Enhanced error handler that includes available properties for validation errors.
- * Use this for tools that operate on data sources (create-page, update-page, etc.)
+ * Enhanced error handler that includes contextual help for validation errors.
+ *
+ * Usage:
+ * - Page tools: handleErrorWithContext(error, notion, { dataSourceId, exampleType: 'page' })
+ * - Schema tools: handleErrorWithContext(error, notion, { dataSourceId, exampleType: 'schema' })
+ * - Block tools: handleErrorWithContext(error, notion, { exampleType: 'block' })
+ * - Filter tools: handleErrorWithContext(error, notion, { exampleType: 'filter' })
  */
-export async function handleErrorWithContext(error, notion, dataSourceId, options) {
+export async function handleErrorWithContext(error, notion, options) {
     const baseResponse = handleError(error);
-    // For validation errors with a data source ID, append available properties
-    if (isValidationError(error) && dataSourceId) {
+    if (!isValidationError(error)) {
+        return baseResponse;
+    }
+    // For data source related errors, fetch and show property list
+    if (options?.dataSourceId &&
+        (options.exampleType === 'page' || options.exampleType === 'schema')) {
         try {
-            const schema = await notion.dataSources.retrieve({
-                data_source_id: dataSourceId,
-            });
-            const propList = formatPropertyList(schema.properties);
-            baseResponse.content[0].text += `\n\nAvailable properties:\n${propList}`;
-            // Add optional hint
-            if (options?.hint) {
-                baseResponse.content[0].text += `\n\n${options.hint}`;
+            const schema = await notion.dataSources.retrieve({ data_source_id: options.dataSourceId });
+            if (isFullDataSource(schema)) {
+                const propList = formatPropertyList(schema.properties, options.exampleType);
+                baseResponse.content[0].text += `\n\nAvailable properties:\n${propList}`;
             }
         }
         catch {
-            // Ignore schema fetch errors - keep the original error message
+            // Ignore schema fetch errors - still show examples below
         }
     }
+    // For other types (block, richTextArray, filter), show examples directly
+    if (options?.exampleType && options.exampleType !== 'page' && options.exampleType !== 'schema') {
+        const examples = getExamplesByType(options.exampleType);
+        baseResponse.content[0].text += `\n\n${examples}`;
+    }
+    // Add optional hint
+    if (options?.hint) {
+        baseResponse.content[0].text += `\n\n${options.hint}`;
+    }
     return baseResponse;
 }

package/dist/src/utils/index.d.ts

@@ -1,3 +1,3 @@
-export { handleError, handleErrorWithContext, type McpResponse, type McpTextContent } from './error-handler.js';
+export { handleError, handleErrorWithContext, type McpResponse, type McpTextContent, } from './error-handler.js';
 export { formatMarkdownResponse, formatPaginatedResponse, formatResponse, formatSimplePaginatedResponse, formatSimpleResponse, formatSuccessMessage, } from './response-formatter.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAC/G,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACd,6BAA6B,EAC7B,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACd,6BAA6B,EAC7B,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,yBAAyB,CAAA"}

package/dist/src/utils/index.js

@@ -1,2 +1,2 @@
-export { handleError, handleErrorWithContext } from './error-handler.js';
+export { handleError, handleErrorWithContext, } from './error-handler.js';
 export { formatMarkdownResponse, formatPaginatedResponse, formatResponse, formatSimplePaginatedResponse, formatSimpleResponse, formatSuccessMessage, } from './response-formatter.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atikk-co-jp/notion-mcp-server",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "MCP server for Notion API - Create, read, update pages and databases",
   "type": "module",
   "license": "MIT",
@@ -52,6 +52,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
+    "@notionhq/client": "^5.6.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {