Notion MCP Server V2

# Notion ServerV2 Integration with Chatbot Agentic v3 ## 🚀 Overview This integration combines the **complete Notion ServerV2 functionality** with the **chatbot_agentic_v3** to create a powerful AI agent that can interact with Notion workspaces through natural language conversations. ## ✅ What's Integrated ### **Complete Notion ServerV2 Features** - **Core Operations**: Search, read, create, list pages/databases - **Analytics Operations**: Workspace analytics, content analysis, activity patterns - **Update Operations**: Add paragraphs, headings, bullets, todos, templates - **Bulk Operations**: Bulk create, list, analyze pages - **Utilities**: Full text extraction, UUID validation, block parsing ### **15 Notion Functions Available to the Agent** 1. `notion_search_content` - Search pages and databases 2. `notion_read_page` - Read page content with full block parsing 3. `notion_create_page` - Create new pages with content 4. `notion_list_pages` - List all pages with metadata 5. `notion_list_databases` - List all databases 6. `notion_workspace_analytics` - Comprehensive workspace insights 7. `notion_content_analytics` - Content structure analysis 8. `notion_activity_analytics` - Activity patterns analysis 9. `notion_add_paragraph` - Add paragraph blocks 10. `notion_add_heading` - Add heading blocks (levels 1-3) 11. `notion_add_bullet_point` - Add bulleted list items 12. `notion_add_todo` - Add to-do items 13. `notion_bulk_create_pages` - Create multiple pages at once 14. `notion_bulk_list_pages` - List all pages with details 15. `notion_bulk_analyze_pages` - Analyze pages by search criteria ## 🏗️ Architecture ### **Integration Components** ``` chatbot_agentic_v3.py ├── Notion ServerV2 Components │ ├── CoreOperations (CRUD operations) │ ├── AnalyticsOperations (workspace insights) │ ├── BulkOperations (bulk processing) │ ├── UpdateOperations (content updates) │ └── NotionUtils (utilities) ├── Function Schemas (for OpenAI agent) ├── Execution Handler (routes function calls) └── Error Management (comprehensive error handling) ``` ### **Key Features** - **Automatic Initialization**: Detects Notion token and initializes all components - **Graceful Degradation**: Continues without Notion if token missing - **Comprehensive Error Handling**: Detailed error messages and recovery - **Async Support**: Handles async operations properly - **Output Capture**: Captures console output for function returns ## 🔧 Setup ### **1. Environment Variables** ```bash # Required OPENAI_API_KEY=your_openai_api_key NOTION_TOKEN=your_notion_integration_token # or NOTION_API_KEY=your_notion_integration_token # Optional (existing chatbot config) # Your existing config variables... ``` ### **2. Installation** ```bash pip install notion-client # Your existing requirements... ``` ### **3. Notion Integration Setup** 1. Go to [Notion Integrations](https://www.notion.so/my-integrations) 2. Create a new integration 3. Copy the integration token 4. Share your pages/databases with the integration ## 🎯 Usage Examples ### **Natural Language Queries** ```python # Initialize chatbot chatbot = Chatbot() # The agent can now handle these requests: response = chatbot.chat("Search for pages about 'project management' in my Notion workspace") response = chatbot.chat("List all pages in my workspace") response = chatbot.chat("Show me analytics for my Notion workspace") response = chatbot.chat("Create a new page called 'Meeting Notes' with agenda content") response = chatbot.chat("Add a to-do item to my project page") response = chatbot.chat("Analyze the content structure of my workspace") ``` ### **Direct Function Calls** ```python # Search content state, result = chatbot.notion_search_content("project") # Read page state, result = chatbot.notion_read_page("Meeting Notes") # Create page state, result = chatbot.notion_create_page("New Project", "Initial project description") # Workspace analytics state, result = chatbot.notion_workspace_analytics() ``` ## 📊 Capabilities ### **Search & Discovery** - Full-text search across pages and databases - Filter results by object type - Extract titles, IDs, and metadata - Smart page identification (ID or title) ### **Content Management** - Read complete page content with block parsing - Create pages with structured content - Add various block types (paragraphs, headings, lists, todos) - Support for rich text and formatting ### **Analytics & Insights** - Workspace overview (total pages, databases, activity) - Content structure analysis (block types, content distribution) - Activity patterns (recent edits, usage trends) - Database structure analysis ### **Bulk Operations** - Create multiple pages simultaneously - Bulk analysis of page collections - Batch operations with detailed reporting - Error handling for partial failures ## 🔄 Function Call Flow ``` User Query → OpenAI Agent → Function Selection → Notion ServerV2 → Results → Agent Response ``` 1. **User Input**: Natural language query 2. **Agent Processing**: OpenAI determines appropriate function 3. **Function Execution**: Notion ServerV2 operations 4. **Result Processing**: Format and return results 5. **Response Generation**: Natural language response with results ## 🛡️ Error Handling ### **Comprehensive Error Management** - **Token Validation**: Checks for Notion token availability - **API Error Handling**: Graceful handling of Notion API errors - **Async Operation Management**: Proper async/await handling - **Partial Failure Recovery**: Continues operation on partial failures - **Detailed Error Messages**: Informative error responses ### **Fallback Mechanisms** - Continues without Notion if token missing - Provides helpful error messages - Maintains chatbot functionality for non-Notion operations ## 📈 Performance Considerations ### **Optimizations** - **Lazy Loading**: Only initializes Notion components when needed - **Result Limiting**: Configurable limits for large result sets - **Output Capture**: Efficient console output handling - **Async Processing**: Non-blocking operations where possible ### **Resource Management** - Proper event loop management for async operations - Memory-efficient block parsing - Reasonable default limits for bulk operations ## 🔍 Testing ### **Run Integration Tests** ```bash python test_notion_integration.py ``` ### **Test Coverage** - Notion client initialization - Function schema registration - Core operation execution - Error handling validation - Output formatting verification ## 🎨 Customization ### **Adding New Functions** 1. **Add to ServerV2**: Create new operation in appropriate class 2. **Add Wrapper**: Create wrapper function in chatbot 3. **Register Schema**: Add to agent_functions list 4. **Update Execution**: Add to execute_function_call method ### **Modifying Behavior** - **Response Formatting**: Customize result formatting in wrapper functions - **Error Messages**: Modify error handling in execution methods - **Limits**: Adjust default limits for queries and results ## 🚀 Example Conversations ### **Workspace Management** ``` User: "What's in my Notion workspace?" Agent: [Calls notion_workspace_analytics] "Your workspace contains 45 pages and 3 databases. You've been most active in the last week with 12 pages updated..." User: "Find all pages about machine learning" Agent: [Calls notion_search_content with "machine learning"] "I found 8 pages about machine learning: 1. ML Project Overview 2. Deep Learning Notes ..." ``` ### **Content Creation** ``` User: "Create a project planning page" Agent: [Calls notion_create_page] "I've created a new page called 'Project Planning' with initial content. Page ID: 12345-67890-abcdef You can find it at: https://notion.so/..." User: "Add a todo list to my project page" Agent: [Calls notion_add_todo] "I've added the to-do item to your project page successfully!" ``` ## 📝 Notes ### **Current Limitations** - Requires Notion integration token - Limited to accessible pages/databases - Some operations require specific page IDs - Bulk operations have reasonable limits ### **Future Enhancements** - Database record manipulation - Advanced filtering and sorting - Template system expansion - Real-time notifications - Enhanced error recovery --- **🎉 Your chatbot now has complete Notion ServerV2 integration!** The agent can search, read, create, analyze, and manage your Notion workspace through natural language conversations.