@atikk-co-jp/notion-mcp-server 0.6.0 → 0.8.0

package/dist/src/schemas/index.js

@@ -1,10 +1,2 @@
-// Database schemas
-// Block schemas
-export { AudioBlockSchema, BlockChildrenSchema, BlockSchema, BookmarkBlockSchema, BreadcrumbBlockSchema, BulletedListItemBlockSchema, CalloutBlockSchema, ChildDatabaseBlockSchema, ChildPageBlockSchema, CodeBlockSchema, ColumnBlockSchema, ColumnListBlockSchema, DividerBlockSchema, EmbedBlockSchema, EmojiIconBlockSchema, EquationBlockSchema, ExternalFileSchema, ExternalIconBlockSchema, FileBlockSchema, FileIconBlockSchema, FileObjectSchema, FileUploadSchema, Heading1BlockSchema, Heading2BlockSchema, Heading3BlockSchema, IconBlockSchema, ImageBlockSchema, LinkPreviewBlockSchema, LinkToPageBlockSchema, NotionFileSchema, NumberedListItemBlockSchema, ParagraphBlockSchema, PdfBlockSchema, QuoteBlockSchema, SyncedBlockDuplicateSchema, SyncedBlockOriginalSchema, SyncedBlockSchema, TableBlockSchema, TableOfContentsBlockSchema, TableRowBlockSchema, TemplateBlockSchema, ToDoBlockSchema, ToggleBlockSchema, UnsupportedBlockSchema, VideoBlockSchema, } from './block.js';
-// Common schemas
-export { AnnotationsSchema, ColorSchema, CoverSchema, DatabaseMentionSchema, DatabaseParentSchema, DateMentionSchema, EmojiIconSchema, EquationRichTextSchema, ExternalIconSchema, IconSchema, LinkPreviewMentionSchema, MentionRichTextSchema, MentionSchema, PageMentionSchema, PageParentSchema, ParentSchema, RichTextArraySchema, RichTextSchema, SimpleTextSchema, TemplateMentionDateSchema, TemplateMentionSchema, TemplateMentionUserSchema, TextRichTextSchema, UserMentionSchema, } from './common.js';
-export { CheckboxPropertySchemaSchema, CreatedByPropertySchemaSchema, CreatedTimePropertySchemaSchema, DatabasePropertiesSchema, DatabasePropertySchemaSchema, DatabaseTitleSchema, DatePropertySchemaSchema, EmailPropertySchemaSchema, FilesPropertySchemaSchema, FormulaPropertySchemaSchema, LastEditedByPropertySchemaSchema, LastEditedTimePropertySchemaSchema, MultiSelectPropertySchemaSchema, NumberPropertySchemaSchema, PeoplePropertySchemaSchema, PhoneNumberPropertySchemaSchema, RelationPropertySchemaSchema, RichTextPropertySchemaSchema, RollupPropertySchemaSchema, SelectOptionSchema, SelectPropertySchemaSchema, TitlePropertySchemaSchema, UrlPropertySchemaSchema, } from './database.js';
-// Filter and sort schemas
-export { FilterSchema, PropertyFilterSchema, SortSchema, SortsSchema, TimestampFilterSchema, } from './filter.js';
-// Page property schemas
-export { CheckboxPropertySchema, CreatedByPropertySchema, CreatedTimePropertySchema, DatePropertySchema, EmailPropertySchema, FilesPropertySchema, FormulaPropertySchema, LastEditedByPropertySchema, LastEditedTimePropertySchema, MultiSelectPropertySchema, NumberPropertySchema, PeoplePropertySchema, PhoneNumberPropertySchema, PropertiesSchema, PropertyValueSchema, RelationPropertySchema, RichTextPropertySchema, RollupPropertySchema, SelectPropertySchema, StatusPropertySchema, TitlePropertySchema, UniqueIdPropertySchema, UrlPropertySchema, UserObjectSchema, VerificationPropertySchema, } from './page.js';
+// Field descriptions for MCP tool schemas
+export { F, Fields } from './descriptions/index.js';

package/dist/src/tools/__tests__/context-size.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context-size.test.d.ts.map

package/dist/src/tools/__tests__/context-size.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-size.test.d.ts","sourceRoot":"","sources":["../../../../src/tools/__tests__/context-size.test.ts"],"names":[],"mappings":""}

package/dist/src/tools/__tests__/context-size.test.js

@@ -0,0 +1,143 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { describe, expect, it } from 'vitest';
+import { toJSONSchema } from 'zod/v4/core';
+import { NotionClient } from '../../notion-client.js';
+import { registerAllTools } from '../index.js';
+/**
+ * Test that all tools don't consume excessive context when registered with MCP.
+ *
+ * Context is consumed by:
+ * 1. Tool description - the description string passed to registerTool
+ * 2. Input schema - converted to JSON Schema via toJSONSchema (Zod v4)
+ *
+ * These tests measure the actual JSON Schema that MCP sends to LLMs.
+ * Token counts are approximated as chars/4 (rough estimate for JSON).
+ */
+// Thresholds in estimated tokens (chars / 4)
+// Based on actual MCP tool registration token counts from user data
+const SINGLE_TOOL_MAX_TOKENS = 1500; // Max tokens for a single tool
+const TOTAL_TOOLS_MAX_TOKENS = 30000; // Max total tokens for all tools combined
+const TOTAL_TOOLS_WARNING_TOKENS = 35000; // Warning threshold
+// Known large tools that need optimization (tracked for future improvement)
+// NOTE: query-data-source, update-database, create-database were optimized using
+// z.any() with FieldDescriptions, reducing ~13,500 tokens. All tools now fit within
+// the standard SINGLE_TOOL_MAX_TOKENS threshold.
+const KNOWN_LARGE_TOOLS = {
+// Currently empty - all tools have been optimized
+};
+// Access internal registered tools from McpServer
+// Using type assertion chain to avoid explicit any
+function getRegisteredTools(server) {
+    return server
+        ._registeredTools;
+}
+// Create a mock notion client for testing (won't make actual API calls)
+function createMockNotionClient() {
+    return new NotionClient({ auth: 'test-token' });
+}
+// Convert Zod schema to JSON Schema (same as MCP does internally)
+function zodToJsonSchema(zodSchema) {
+    try {
+        // Use Zod v4's toJSONSchema - same as MCP SDK uses
+        return toJSONSchema(zodSchema);
+    }
+    catch {
+        // Fallback for non-Zod schemas
+        return {};
+    }
+}
+// Calculate the context size for a single tool (in estimated tokens)
+function calculateToolContextSize(tool) {
+    const descriptionChars = tool.description?.length ?? 0;
+    // Convert to JSON Schema (same as MCP does)
+    const jsonSchema = tool.inputSchema ? zodToJsonSchema(tool.inputSchema) : {};
+    const schemaChars = JSON.stringify(jsonSchema).length;
+    const totalChars = descriptionChars + schemaChars;
+    // Rough token estimate: ~4 chars per token for JSON
+    const estimatedTokens = Math.ceil(totalChars / 4);
+    return {
+        descriptionChars,
+        schemaChars,
+        totalChars,
+        estimatedTokens,
+    };
+}
+describe('Tool context size', () => {
+    const server = new McpServer({ name: 'test-server', version: '1.0.0' });
+    const notion = createMockNotionClient();
+    // Register all tools
+    registerAllTools(server, notion);
+    const registeredTools = getRegisteredTools(server);
+    const toolNames = Object.keys(registeredTools);
+    describe('Individual tool sizes', () => {
+        it.each(toolNames)('%s should not exceed token limit', (toolName) => {
+            const tool = registeredTools[toolName];
+            const { estimatedTokens, descriptionChars, schemaChars } = calculateToolContextSize(tool);
+            // Check if this is a known large tool with special limits
+            const knownLargeTool = KNOWN_LARGE_TOOLS[toolName];
+            const maxAllowed = knownLargeTool?.maxAllowed ?? SINGLE_TOOL_MAX_TOKENS;
+            // Log sizes for debugging (visible in verbose mode)
+            console.log(`${toolName}: ~${estimatedTokens} tokens (desc=${descriptionChars}, schema=${schemaChars} chars)` +
+                (knownLargeTool ? ` [KNOWN LARGE: ${knownLargeTool.reason}]` : ''));
+            expect(estimatedTokens).toBeLessThanOrEqual(maxAllowed);
+        });
+    });
+    describe('Total context size', () => {
+        it('should report total context size and check limits', () => {
+            let totalTokens = 0;
+            let totalTokensExcludingKnownLarge = 0;
+            const toolSizes = [];
+            for (const [name, tool] of Object.entries(registeredTools)) {
+                const { estimatedTokens } = calculateToolContextSize(tool);
+                const isKnownLarge = name in KNOWN_LARGE_TOOLS;
+                totalTokens += estimatedTokens;
+                if (!isKnownLarge) {
+                    totalTokensExcludingKnownLarge += estimatedTokens;
+                }
+                toolSizes.push({ name, tokens: estimatedTokens, isKnownLarge });
+            }
+            // Sort by size descending for the report
+            toolSizes.sort((a, b) => b.tokens - a.tokens);
+            console.log('\n=== Tool Context Size Report (Estimated Tokens) ===');
+            console.log(`Total tools: ${toolNames.length}`);
+            console.log(`Total estimated tokens: ~${totalTokens}`);
+            console.log(`Total (excluding known large): ~${totalTokensExcludingKnownLarge}`);
+            console.log(`Target limit: ${TOTAL_TOOLS_MAX_TOKENS} tokens`);
+            console.log(`Warning limit: ${TOTAL_TOOLS_WARNING_TOKENS} tokens`);
+            console.log(`Usage (excluding known large): ${((totalTokensExcludingKnownLarge / TOTAL_TOOLS_MAX_TOKENS) * 100).toFixed(1)}%`);
+            console.log('\nTop 10 largest tools:');
+            toolSizes.slice(0, 10).forEach(({ name, tokens, isKnownLarge }, i) => {
+                const marker = isKnownLarge ? ' [KNOWN LARGE]' : '';
+                console.log(`  ${i + 1}. ${name}: ~${tokens} tokens${marker}`);
+            });
+            // Check that tools excluding known large ones are within target
+            expect(totalTokensExcludingKnownLarge).toBeLessThanOrEqual(TOTAL_TOOLS_MAX_TOKENS);
+            // Warn if total exceeds warning threshold (test still passes but logs warning)
+            if (totalTokens > TOTAL_TOOLS_WARNING_TOKENS) {
+                console.warn(`\n⚠️  WARNING: Total tokens (~${totalTokens}) exceeds warning threshold (${TOTAL_TOOLS_WARNING_TOKENS})`);
+                console.warn('   Consider optimizing known large tools by replacing complex schemas with z.any()');
+            }
+        });
+    });
+    describe('Schema complexity checks', () => {
+        it.each(toolNames)('%s should use z.any() for complex nested structures', (toolName) => {
+            const tool = registeredTools[toolName];
+            if (!tool.inputSchema)
+                return;
+            const schemaStr = JSON.stringify(tool.inputSchema);
+            // Check that complex properties don't have deeply nested definitions
+            // If they did, the schema would contain many "properties" keys
+            const propertiesCount = (schemaStr.match(/"properties":/g) || []).length;
+            // Allow max 2 levels of nesting (root + one level of additionalProperties)
+            expect(propertiesCount).toBeLessThanOrEqual(3);
+        });
+    });
+    describe('Description length checks', () => {
+        const MAX_DESCRIPTION_LENGTH = 500;
+        it.each(toolNames)('%s description should be concise', (toolName) => {
+            const tool = registeredTools[toolName];
+            const descLength = tool.description?.length ?? 0;
+            expect(descLength).toBeLessThanOrEqual(MAX_DESCRIPTION_LENGTH);
+        });
+    });
+});

package/dist/src/tools/__tests__/error-handler.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=error-handler.test.d.ts.map

package/dist/src/tools/__tests__/error-handler.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.test.d.ts","sourceRoot":"","sources":["../../../../src/tools/__tests__/error-handler.test.ts"],"names":[],"mappings":""}

package/dist/src/tools/__tests__/error-handler.test.js

@@ -0,0 +1,125 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+const toolsDir = resolve(import.meta.dirname, '..');
+const toolErrorConfigs = [
+    // Tools using handleErrorWithContext
+    { toolFile: 'append-block-children.ts', handler: 'handleErrorWithContext', exampleType: 'block' },
+    {
+        toolFile: 'create-comment.ts',
+        handler: 'handleErrorWithContext',
+        exampleType: 'richTextArray',
+    },
+    { toolFile: 'create-database.ts', handler: 'handleErrorWithContext', exampleType: 'schema' },
+    {
+        toolFile: 'create-page.ts',
+        handler: 'handleErrorWithContext',
+        exampleType: 'page',
+        hasDataSourceId: true,
+    },
+    {
+        toolFile: 'create-page-simple.ts',
+        handler: 'handleErrorWithContext',
+        exampleType: 'page',
+        hasDataSourceId: true,
+    },
+    { toolFile: 'query-data-source.ts', handler: 'handleErrorWithContext', exampleType: 'filter' },
+    { toolFile: 'search.ts', handler: 'handleErrorWithContext', exampleType: 'filter' },
+    { toolFile: 'update-block.ts', handler: 'handleErrorWithContext', exampleType: 'block' },
+    {
+        toolFile: 'update-data-source.ts',
+        handler: 'handleErrorWithContext',
+        exampleType: 'schema',
+        hasDataSourceId: true,
+    },
+    {
+        toolFile: 'update-database.ts',
+        handler: 'handleErrorWithContext',
+        exampleType: 'richTextArray',
+    },
+    { toolFile: 'update-page.ts', handler: 'handleErrorWithContext', exampleType: 'page' },
+    // Tools using handleError (no contextual help needed)
+    { toolFile: 'append-blocks-simple.ts', handler: 'handleError' },
+    { toolFile: 'archive-database.ts', handler: 'handleError' },
+    { toolFile: 'archive-page.ts', handler: 'handleError' },
+    { toolFile: 'create-comment-simple.ts', handler: 'handleError' },
+    { toolFile: 'delete-block.ts', handler: 'handleError' },
+    { toolFile: 'get-block-children.ts', handler: 'handleError' },
+    { toolFile: 'list-comments.ts', handler: 'handleError' },
+    { toolFile: 'list-users.ts', handler: 'handleError' },
+    { toolFile: 'move-page.ts', handler: 'handleError' },
+    { toolFile: 'retrieve-block.ts', handler: 'handleError' },
+    { toolFile: 'retrieve-bot-user.ts', handler: 'handleError' },
+    { toolFile: 'retrieve-data-source.ts', handler: 'handleError' },
+    { toolFile: 'retrieve-database.ts', handler: 'handleError' },
+    { toolFile: 'retrieve-page.ts', handler: 'handleError' },
+    { toolFile: 'retrieve-page-property.ts', handler: 'handleError' },
+    { toolFile: 'retrieve-user.ts', handler: 'handleError' },
+    { toolFile: 'update-block-simple.ts', handler: 'handleError' },
+];
+describe('Tool error handlers', () => {
+    describe.each(toolErrorConfigs)('$toolFile', ({ toolFile, handler, exampleType, hasDataSourceId, }) => {
+        const filePath = resolve(toolsDir, toolFile);
+        const content = readFileSync(filePath, 'utf-8');
+        it(`should import ${handler}`, () => {
+            const importRegex = new RegExp(`import\\s+\\{[^}]*\\b${handler}\\b[^}]*\\}`);
+            expect(content).toMatch(importRegex);
+        });
+        it(`should call ${handler} in catch block`, () => {
+            const callRegex = new RegExp(`return\\s+${handler}\\(error`);
+            expect(content).toMatch(callRegex);
+        });
+        if (handler === 'handleErrorWithContext') {
+            it(`should use exampleType: '${exampleType}'`, () => {
+                const exampleTypeRegex = new RegExp(`exampleType:\\s*['"]${exampleType}['"]`);
+                expect(content).toMatch(exampleTypeRegex);
+            });
+            if (hasDataSourceId) {
+                it('should pass dataSourceId option', () => {
+                    expect(content).toMatch(/dataSourceId:\s*\w+/);
+                });
+            }
+        }
+        if (handler === 'handleError') {
+            it('should not use handleErrorWithContext', () => {
+                expect(content).not.toMatch(/handleErrorWithContext/);
+            });
+        }
+    });
+});
+describe('All tool files are covered', () => {
+    it('should have a config for each tool file (excluding index.ts)', () => {
+        const expectedToolFiles = [
+            'append-block-children.ts',
+            'append-blocks-simple.ts',
+            'archive-database.ts',
+            'archive-page.ts',
+            'create-comment.ts',
+            'create-comment-simple.ts',
+            'create-database.ts',
+            'create-page.ts',
+            'create-page-simple.ts',
+            'delete-block.ts',
+            'get-block-children.ts',
+            'list-comments.ts',
+            'list-users.ts',
+            'move-page.ts',
+            'query-data-source.ts',
+            'retrieve-block.ts',
+            'retrieve-bot-user.ts',
+            'retrieve-data-source.ts',
+            'retrieve-database.ts',
+            'retrieve-page.ts',
+            'retrieve-page-property.ts',
+            'retrieve-user.ts',
+            'search.ts',
+            'update-block.ts',
+            'update-block-simple.ts',
+            'update-data-source.ts',
+            'update-database.ts',
+            'update-page.ts',
+        ];
+        const configuredFiles = toolErrorConfigs.map((c) => c.toolFile).sort();
+        expect(configuredFiles).toEqual(expectedToolFiles.sort());
+    });
+});

package/dist/src/tools/append-block-children.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"append-block-children.d.ts","sourceRoot":"","sources":["../../../src/tools/append-block-children.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAWvD,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAiCzF"}
+{"version":3,"file":"append-block-children.d.ts","sourceRoot":"","sources":["../../../src/tools/append-block-children.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAevD,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAmCzF"}

package/dist/src/tools/append-block-children.js

@@ -1,10 +1,11 @@
 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)
 const inputSchema = {
-    block_id: z.string().describe('Block or page ID'),
-    children: z.array(z.any()).describe('Block objects to append'),
-    after: z.string().optional().describe('Insert after this block ID'),
+    block_id: z.string().describe(F.block_id),
+    children: z.array(z.any()).describe(F.children),
+    after: z.string().optional().describe(F.after),
 };
 export function registerAppendBlockChildren(server, notion) {
     server.registerTool('append-block-children', {
@@ -26,7 +27,9 @@ export function registerAppendBlockChildren(server, notion) {
             return formatResponse(response);
         }
         catch (error) {
-            return handleError(error);
+            return handleErrorWithContext(error, notion, {
+                exampleType: 'block',
+            });
         }
     });
 }

package/dist/src/tools/append-blocks-simple.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"append-blocks-simple.d.ts","sourceRoot":"","sources":["../../../src/tools/append-blocks-simple.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAUvD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAqCxF"}
+{"version":3,"file":"append-blocks-simple.d.ts","sourceRoot":"","sources":["../../../src/tools/append-blocks-simple.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAIxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAWvD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CA0BxF"}

package/dist/src/tools/append-blocks-simple.js

@@ -1,32 +1,28 @@
 import { z } from 'zod';
 import { markdownToBlocks } from '../converters/index.js';
+import { F } from '../schemas/descriptions/index.js';
 import { formatResponse, handleError } from '../utils/index.js';
 // Minimal schema for MCP
 const inputSchema = {
-    block_id: z.string().describe('Page or block ID to append to'),
-    content: z.string().describe('Content in Markdown'),
-    after: z.string().optional().describe('Insert after this block ID'),
+    block_id: z.string().describe(F.block_id),
+    content: z.string().describe(F.content),
+    after: z.string().optional().describe(F.after),
 };
 export function registerAppendBlocksSimple(server, notion) {
     server.registerTool('append-blocks-simple', {
         description: 'Append blocks to a page using Markdown. ' +
             'Simpler than append-block-children: just provide markdown text. ' +
-            'Supports: headings (#), lists (- or 1.), checkboxes (- [ ]), code blocks (```), quotes (>), images (![]()), bold (**), italic (*), links ([]()), etc.',
+            'Supports: headings (#), lists (- or 1.), checkboxes (- [ ]), code blocks (```), quotes (>), tables (| |), images (![]()), bold (**), italic (*), links ([]()), etc.',
         inputSchema,
     }, async ({ block_id, content, after }) => {
         try {
-            // Convert markdown to blocks
+            // Convert markdown to blocks and cast to SDK type
             const children = markdownToBlocks(content);
-            // Build params
-            const params = {
+            const response = await notion.blocks.children.append({
                 block_id,
                 children,
-            };
-            if (after) {
-                params.after = after;
-            }
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const response = await notion.blocks.children.append(params);
+                ...(after && { after }),
+            });
             return formatResponse(response);
         }
         catch (error) {

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

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

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

@@ -1,18 +1,18 @@
 import { z } from 'zod';
+import { F } from '../schemas/descriptions/index.js';
 import { formatResponse, handleError } from '../utils/index.js';
 const inputSchema = {
-    database_id: z.string().describe('Database ID to archive'),
+    database_id: z.string().describe(F.database_id),
 };
 export function registerArchiveDatabase(server, notion) {
     server.registerTool('archive-database', {
-        description: 'Archive (delete) a Notion database by moving it to trash. ' +
-            'This is equivalent to update-database with archived: true.',
+        description: 'Move a database to trash. Recoverable for 30 days via Notion UI.',
         inputSchema,
     }, async ({ database_id }) => {
         try {
             const response = await notion.databases.update({
                 database_id,
-                archived: true,
+                in_trash: true,
             });
             return formatResponse(response);
         }

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

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

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

@@ -1,12 +1,12 @@
 import { z } from 'zod';
+import { F } from '../schemas/descriptions/index.js';
 import { formatResponse, handleError } from '../utils/index.js';
 const inputSchema = {
-    page_id: z.string().describe('Page ID to archive'),
+    page_id: z.string().describe(F.page_id),
 };
 export function registerArchivePage(server, notion) {
     server.registerTool('archive-page', {
-        description: 'Archive (delete) a Notion page by moving it to trash. ' +
-            'This is equivalent to update-page with archived: true.',
+        description: 'Move a page to trash. Recoverable for 30 days via Notion UI.',
         inputSchema,
     }, async ({ page_id }) => {
         try {

package/dist/src/tools/create-comment-simple.d.ts

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

package/dist/src/tools/create-comment-simple.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-comment-simple.d.ts","sourceRoot":"","sources":["../../../src/tools/create-comment-simple.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAWvD,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAmDzF"}

package/dist/src/tools/create-comment-simple.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { parseInlineMarkdown } from '../converters/index.js';
+import { F } from '../schemas/descriptions/index.js';
+import { formatResponse, handleError } from '../utils/index.js';
+const inputSchema = {
+    page_id: z.string().optional().describe(F.page_id),
+    block_id: z.string().optional().describe(F.block_id),
+    discussion_id: z.string().optional().describe(F.discussion_id),
+    content: z.string().describe(F.content),
+};
+export function registerCreateCommentSimple(server, notion) {
+    server.registerTool('create-comment-simple', {
+        description: 'Add a comment using Markdown. Simpler than create-comment.',
+        inputSchema,
+    }, async ({ page_id, block_id, discussion_id, content }) => {
+        try {
+            // Validate: exactly one of page_id, block_id, or discussion_id must be provided
+            const providedCount = [page_id, block_id, discussion_id].filter(Boolean).length;
+            if (providedCount !== 1) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Error: Provide exactly one of page_id, block_id, or discussion_id.',
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const rich_text = parseInlineMarkdown(content);
+            // Build params based on which ID was provided
+            const params = {
+                rich_text,
+            };
+            if (discussion_id) {
+                params.discussion_id = discussion_id;
+            }
+            else if (page_id) {
+                params.parent = { page_id };
+            }
+            else if (block_id) {
+                params.parent = { block_id };
+            }
+            const response = await notion.comments.create(params);
+            return formatResponse(response);
+        }
+        catch (error) {
+            return handleError(error);
+        }
+    });
+}

package/dist/src/tools/create-comment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-comment.d.ts","sourceRoot":"","sources":["../../../src/tools/create-comment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAUvD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAqCnF"}
+{"version":3,"file":"create-comment.d.ts","sourceRoot":"","sources":["../../../src/tools/create-comment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAYvD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAuDnF"}

package/dist/src/tools/create-comment.js

@@ -1,10 +1,12 @@
 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)
 const inputSchema = {
-    page_id: z.string().describe('Page ID'),
-    rich_text: z.array(z.any()).describe('Comment content as rich text'),
-    discussion_id: z.string().optional().describe('Reply to existing discussion'),
+    page_id: z.string().optional().describe(F.page_id),
+    block_id: z.string().optional().describe(F.block_id),
+    discussion_id: z.string().optional().describe(F.discussion_id),
+    rich_text: z.array(z.any()).describe(F.rich_text),
 };
 export function registerCreateComment(server, notion) {
     server.registerTool('create-comment', {
@@ -13,23 +15,41 @@ export function registerCreateComment(server, notion) {
             'Use discussion_id to reply to an existing comment thread. ' +
             'Returns the created comment with its ID.',
         inputSchema,
-    }, async ({ page_id, rich_text, discussion_id }) => {
+    }, async ({ page_id, block_id, discussion_id, rich_text }) => {
         try {
-            // The Notion API requires either parent or discussion_id
+            // Validate: exactly one of page_id, block_id, or discussion_id must be provided
+            const providedCount = [page_id, block_id, discussion_id].filter(Boolean).length;
+            if (providedCount !== 1) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Error: Provide exactly one of page_id, block_id, or discussion_id.',
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Build params based on which ID was provided
             const params = {
                 rich_text,
             };
             if (discussion_id) {
                 params.discussion_id = discussion_id;
             }
-            else {
+            else if (page_id) {
                 params.parent = { page_id };
             }
+            else if (block_id) {
+                params.parent = { block_id };
+            }
             const response = await notion.comments.create(params);
             return formatResponse(response);
         }
         catch (error) {
-            return handleError(error);
+            return handleErrorWithContext(error, notion, {
+                exampleType: 'richTextArray',
+            });
         }
     });
 }

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

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

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

@@ -1,15 +1,15 @@
 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)
+// Uses z.any() for title/icon/cover to reduce context size (~2,300 tokens saved)
 const inputSchema = {
-    parent_page_id: z.string().describe('Parent page ID'),
-    title: z.array(z.any()).optional().describe('Database title'),
-    properties: z
-        .record(z.string(), z.any())
-        .describe('Property schema (must include one title property)'),
-    icon: z.any().optional().describe('Database icon { type: "emoji", emoji: "📝" } or { type: "external", external: { url: "..." } }. Emoji must be an actual emoji character.'),
-    cover: z.any().optional().describe('Cover image'),
-    is_inline: z.boolean().optional().describe('Inline database'),
+    parent_page_id: z.string().describe(F.parent_page_id),
+    title: z.any().optional().describe(F.title),
+    properties: z.record(z.string(), z.any()).describe(F.properties_schema),
+    icon: z.any().optional().describe(F.icon),
+    cover: z.any().optional().describe(F.cover),
+    is_inline: z.boolean().optional().describe(F.is_inline),
 };
 export function registerCreateDatabase(server, notion) {
     server.registerTool('create-database', {
@@ -19,28 +19,22 @@ export function registerCreateDatabase(server, notion) {
         inputSchema,
     }, async ({ parent_page_id, title, properties, icon, cover, is_inline }) => {
         try {
+            // Build params with only defined values (API validates full structure)
             const params = {
-                parent: { page_id: parent_page_id },
-                initial_data_source: { properties: properties },
+                parent: { type: 'page_id', page_id: parent_page_id },
+                initial_data_source: { properties },
+                ...(title !== undefined && { title }),
+                ...(icon !== undefined && { icon }),
+                ...(cover !== undefined && { cover }),
+                ...(is_inline !== undefined && { is_inline }),
             };
-            if (title) {
-                params.title = title;
-            }
-            if (icon) {
-                params.icon = icon;
-            }
-            if (cover) {
-                params.cover = cover;
-            }
-            if (is_inline !== undefined) {
-                params.is_inline = is_inline;
-            }
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const response = await notion.databases.create(params);
             return formatResponse(response);
         }
         catch (error) {
-            return handleError(error);
+            return handleErrorWithContext(error, notion, {
+                exampleType: 'schema',
+            });
         }
     });
 }

package/dist/src/tools/create-page-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 registerCreatePageSimple(server: McpServer, notion: NotionClient): void;
 //# sourceMappingURL=create-page-simple.d.ts.map