142 lines
5.2 KiB
Markdown
142 lines
5.2 KiB
Markdown
# Notion MCP Server - Tools Summary
|
|
|
|
## Overview
|
|
Successfully built **43 MCP tools** across 6 categories for comprehensive Notion API coverage.
|
|
|
|
## Tool Categories
|
|
|
|
### 1. Pages (7 tools) - `src/tools/pages.ts`
|
|
- `notion_get_page` - Retrieve page by ID
|
|
- `notion_create_page` - Create page in database or as child page
|
|
- `notion_update_page` - Update page properties/metadata
|
|
- `notion_archive_page` - Archive a page
|
|
- `notion_restore_page` - Restore archived page
|
|
- `notion_get_page_property` - Get specific property from page
|
|
|
|
### 2. Databases (5 tools) - `src/tools/databases.ts`
|
|
- `notion_get_database` - Retrieve database schema
|
|
- `notion_create_database` - Create new database
|
|
- `notion_update_database` - Update database schema/metadata
|
|
- `notion_query_database` - Query with filters and sorts (paginated)
|
|
- `notion_query_database_all` - Query all results (auto-pagination)
|
|
|
|
### 3. Blocks (23 tools) - `src/tools/blocks.ts`
|
|
**Core Block Operations:**
|
|
- `notion_get_block` - Retrieve block by ID
|
|
- `notion_get_block_children` - Get child blocks (paginated)
|
|
- `notion_get_block_children_all` - Get all children (auto-pagination)
|
|
- `notion_append_block_children` - Append blocks to parent
|
|
- `notion_update_block` - Update block content
|
|
- `notion_delete_block` - Delete/archive block
|
|
|
|
**Block Creation Helpers (17 types):**
|
|
- `notion_create_paragraph` - Paragraph block
|
|
- `notion_create_heading` - Heading (H1/H2/H3)
|
|
- `notion_create_todo` - To-do checkbox item
|
|
- `notion_create_bulleted_list_item` - Bulleted list
|
|
- `notion_create_numbered_list_item` - Numbered list
|
|
- `notion_create_toggle` - Toggle/collapsible block
|
|
- `notion_create_code` - Code block with syntax highlighting
|
|
- `notion_create_quote` - Quote block
|
|
- `notion_create_callout` - Callout with icon
|
|
- `notion_create_divider` - Horizontal divider
|
|
- `notion_create_bookmark` - Bookmark URL
|
|
- `notion_create_image` - Image from URL
|
|
- `notion_create_video` - Video embed
|
|
- `notion_create_embed` - Generic embed
|
|
- `notion_create_table` - Table with rows/columns
|
|
|
|
### 4. Users (4 tools) - `src/tools/users.ts`
|
|
- `notion_get_user` - Retrieve user by ID
|
|
- `notion_list_users` - List workspace users (paginated)
|
|
- `notion_list_users_all` - List all users (auto-pagination)
|
|
- `notion_get_me` - Get bot/integration user info
|
|
|
|
### 5. Comments (3 tools) - `src/tools/comments.ts`
|
|
- `notion_create_comment` - Add comment to page/block
|
|
- `notion_list_comments` - List comments (paginated)
|
|
- `notion_list_comments_all` - List all comments (auto-pagination)
|
|
|
|
### 6. Search (4 tools) - `src/tools/search.ts`
|
|
- `notion_search` - Full-text search with filters/sorting (paginated)
|
|
- `notion_search_all` - Search all results (auto-pagination)
|
|
- `notion_search_pages` - Search pages only
|
|
- `notion_search_databases` - Search databases only
|
|
|
|
## Architecture
|
|
|
|
### Input Validation
|
|
- All tools use **Zod** schemas for type-safe input validation
|
|
- Schemas defined inline with tool handlers
|
|
- Runtime validation with helpful error messages
|
|
|
|
### Naming Convention
|
|
- All tools follow `notion_verb_noun` pattern
|
|
- Clear, consistent naming for discoverability
|
|
- Examples: `notion_create_page`, `notion_query_database`, `notion_append_block_children`
|
|
|
|
### File Structure
|
|
```
|
|
src/tools/
|
|
├── index.ts # Barrel export + central routing
|
|
├── pages.ts # Page operations (7 tools)
|
|
├── databases.ts # Database operations (5 tools)
|
|
├── blocks.ts # Block operations (23 tools)
|
|
├── users.ts # User operations (4 tools)
|
|
├── comments.ts # Comment operations (3 tools)
|
|
└── search.ts # Search operations (4 tools)
|
|
```
|
|
|
|
Each file exports:
|
|
- `getTools(client: NotionClient): Tool[]` - Tool definitions
|
|
- `handle[Category]Tool(toolName, args, client)` - Execution handler
|
|
|
|
### Central Routing
|
|
`src/tools/index.ts` provides:
|
|
- `getAllTools(client)` - Returns all 43 tools
|
|
- `handleToolCall(toolName, args, client)` - Routes to appropriate handler
|
|
|
|
## Notion API Features Covered
|
|
|
|
### Rich Text Support
|
|
- All text fields support Notion's rich_text format
|
|
- Helper function `textToRichText()` for simple text conversion
|
|
- Supports colors, formatting, links
|
|
|
|
### Property Types
|
|
- Full support for all Notion property types
|
|
- Database schema creation/updates
|
|
- Page property manipulation
|
|
|
|
### Filters & Sorts
|
|
- Compound filters (and/or)
|
|
- Property filters for all types
|
|
- Sorting by property or timestamp
|
|
|
|
### Block Types
|
|
- 25+ block types supported
|
|
- Nested blocks (children)
|
|
- Block-specific properties (color, checkboxes, language, etc.)
|
|
|
|
### Pagination
|
|
- Manual pagination tools (start_cursor support)
|
|
- Auto-pagination tools (`*_all` variants)
|
|
- Configurable page_size (max 100)
|
|
|
|
## TypeScript Compilation
|
|
✅ All files compile successfully with `tsc --noEmit`
|
|
✅ Full type safety with Notion types from `src/types/index.ts`
|
|
✅ No TypeScript errors
|
|
|
|
## Next Steps
|
|
To integrate these tools into the server:
|
|
1. Import in `src/server.ts`: `import { getAllTools, handleToolCall } from './tools/index.js';`
|
|
2. Replace inline tools in `ListToolsRequestSchema` handler with `getAllTools(this.client)`
|
|
3. Replace switch statement in `CallToolRequestSchema` with `handleToolCall(name, args, this.client)`
|
|
|
|
## Tool Count Summary
|
|
- **Total Tools:** 43
|
|
- **Target Range:** 35-50 ✅
|
|
- **Categories:** 6
|
|
- **Lines of Code:** ~57,000 bytes across tool files
|