# Notion MCP Server V2 🚀

A comprehensive **Model Context Protocol (MCP) server** for Notion integration with enhanced functionality, robust error handling, production-ready features, and **bulletproof validation**.

## ✨ Features

### 🔧 **Core Operations**

- ✅ **Search**: Find pages and databases with advanced filtering
- ✅ **Page Operations**: Create, read, update pages with full content support
- ✅ **Content Management**: Add paragraphs, headings, bullet points, todos, **links, and bookmarks**
- ✅ **Database Operations**: List and query databases

### 🔗 **Advanced Content Types** _(NEW)_

- ✅ **Bookmarks**: Add external website links with URL validation
- ✅ **Link to Page**: Create internal links between Notion pages
- ✅ **Rich Content**: Support for all major Notion block types
- ✅ **Content Splitting**: Automatic handling of long content (2000+ chars)

### 📊 **Analytics & Insights**

- ✅ **Workspace Analytics**: Total pages, databases, recent activity
- ✅ **Content Analytics**: Structure analysis and metrics
- ✅ **Activity Tracking**: Recent edits and usage patterns
- ✅ **Performance Metrics**: Optimized with configurable timeouts

### 🔄 **Bulk Operations** _(OPTIMIZED)_

- ✅ **Smart Pagination**: Prevents timeouts with configurable limits
- ✅ **Bulk Content Addition**: Add multiple content blocks at once
- ✅ **Bulk Page Operations**: Create and manage multiple pages
- ✅ **Performance Controls**: Optional block counts for faster responses

### 🌐 **API Interfaces**

- ✅ **FastAPI REST API**: Production-ready HTTP endpoints
- ✅ **Interactive CLI**: Command-line interface for direct usage
- ✅ **MCP Compatible**: Full Model Context Protocol support
- ✅ **Agent Integration**: Unified endpoint for AI agents

### 🛡️ **Production Features** _(ENHANCED)_

- ✅ **Bulletproof Validation**: Comprehensive input validation and error handling
- ✅ **Configuration Management**: Environment-based settings
- ✅ **Smart Error Recovery**: Detailed error messages and recovery guidance
- ✅ **Health Checks**: Monitoring and status endpoints with feature detection
- ✅ **Structured Logging**: Configurable logging with performance insights
- ✅ **CORS Support**: Cross-origin resource sharing
- ✅ **Timeout Optimization**: Dynamic timeouts based on operation complexity

### 🧪 **Testing & Quality** _(COMPREHENSIVE)_

- ✅ **46KB Test Suite**: 1,158 lines of comprehensive tests
- ✅ **13+ Test Categories**: Core, content, bulk, links, analytics, edge cases
- ✅ **Validation Testing**: Tests for all error scenarios and edge cases
- ✅ **Performance Testing**: Timeout and optimization validation
- ✅ **Detailed Reporting**: JSON reports with timing and categorization

## 🏗️ Architecture

```
notion_mcp_server/
├── 📄 __init__.py           # Package initialization
├── 🔧 config.py             # Configuration management
├── 🌐 api_serverV2.py       # FastAPI REST API server (49KB)
├── 💻 serverV2.py           # Interactive CLI server
├── ⚙️ core_operations.py    # Basic CRUD operations
├── 📊 analytics_operations.py # Analytics and metrics
├── 🔄 bulk_operations.py    # Bulk processing
├── ✏️ update_operations.py  # Content updates (35KB)
├── 🛠️ notion_utils.py      # Utility functions
├── 🧪 test_server.py        # Comprehensive test suite (48KB)
└── 📖 README.md             # This file
```

## 📦 Installation

### Prerequisites

- Python 3.8+
- Notion account with integration token
- pip or conda package manager

### Setup

1. **Install Dependencies**

```bash
pip install notion-client fastapi uvicorn python-dotenv pydantic requests
```

2. **Environment Configuration**
   Create a `.env` file in your project root:

```env
# Required
NOTION_TOKEN=ntn_your_integration_token_here

# Optional Server Settings
HOST=0.0.0.0
PORT=8081
DEBUG=false

# Optional Feature Settings
MAX_PAGE_SIZE=100
DEFAULT_PAGE_SIZE=20
MAX_CONTENT_LENGTH=2000
ENABLE_ANALYTICS=true
ENABLE_BULK_OPERATIONS=true

# Optional Logging
LOG_LEVEL=INFO
```

3. **Get Your Notion Token**

- Go to [Notion Integrations](https://www.notion.so/profile/integrations)
- Create a new integration
- Copy the token (starts with `ntn_`)
- Share your pages/databases with the integration

## 🚀 Usage

### 1. FastAPI Server (Production)

**Start the server:**

```bash
python -m notion_mcp_server.api_serverV2
```

**Server will be available at:**

- API: `http://localhost:8081`
- Documentation: `http://localhost:8081/docs`
- Health Check: `http://localhost:8081/health`

### 2. Interactive CLI

```bash
python -m notion_mcp_server.serverV2
```

### 3. Python Integration

```python
from notion_mcp_server import ComprehensiveNotionServer
import asyncio

async def example():
    server = ComprehensiveNotionServer("your_notion_token")
    await server.core_ops.search_content("search term")

asyncio.run(example())
```

## 📚 API Documentation

### 🔍 **Search Endpoint**

```http
POST /api/search
Content-Type: application/json

{
  "query": "search term",
  "page_size": 10
}
```

### 📄 **Create Page**

```http
POST /api/page/create
Content-Type: application/json

{
  "title": "My New Page",
  "content": "Initial content",
  "parent_id": "optional-parent-page-id"
}
```

### 📖 **Read Page**

```http
POST /api/page/read
Content-Type: application/json

{
  "identifier": "page-id-or-title"
}
```

### ✏️ **Add Content** _(ENHANCED)_

```http
POST /api/page/add-content
Content-Type: application/json

{
  "page_id": "page-id",
  "content_type": "paragraph",
  "content": "New paragraph content"
}
```

**Supported content types:**

- `paragraph` - Regular text
- `heading_1` - Large heading
- `heading_2` - Medium heading
- `heading_3` - Small heading
- `bulleted_list_item` - Bullet point
- `to_do` - Checkbox item
- `bookmark` - External website link _(NEW)_
- `link_to_page` - Internal page link _(NEW)_

### 🔗 **Link Content Types** _(NEW)_

**Add Bookmark (External Link):**

```http
POST /api/page/add-content
Content-Type: application/json

{
  "page_id": "page-id",
  "content_type": "bookmark",
  "content": "OpenAI Website",
  "url": "https://www.openai.com"
}
```

**Add Link to Page (Internal Link):**

```http
POST /api/page/add-content
Content-Type: application/json

{
  "page_id": "page-id",
  "content_type": "link_to_page",
  "content": "Link to related page",
  "page_reference": "target-page-id-or-title"
}
```

### 🔄 **Bulk Content Addition** _(ENHANCED)_

```http
POST /api/page/bulk-add-content
Content-Type: application/json

{
  "page_id": "page-id",
  "items": [
    {
      "content_type": "heading_2",
      "content": "Section Title"
    },
    {
      "content_type": "paragraph",
      "content": "Paragraph content"
    },
    {
      "content_type": "bookmark",
      "url": "https://example.com",
      "content": "External Link"
    },
    {
      "content_type": "link_to_page",
      "page_reference": "other-page-id",
      "content": "Internal Link"
    },
    {
      "content_type": "to_do",
      "content": "Task item",
      "checked": false
    }
  ]
}
```

### 📊 **Analytics**

```http
POST /api/analytics
Content-Type: application/json

{
  "type": "workspace"
}
```

**Analytics types:** `workspace`, `content`, `activity`, `database`

### 🔄 **Bulk Operations** _(OPTIMIZED)_

```http
POST /api/bulk
Content-Type: application/json

{
  "operation": "list",
  "query": "{\"limit\": 10, \"include_block_counts\": false}"
}
```

**Optimization options:**

- `limit`: Number of pages to process (1-50)
- `include_block_counts`: Whether to calculate block counts (slower)

**Operations:** `list`, `analyze`, `create`

### 🤖 **Agent Integration**

```http
POST /api/agent/query
Content-Type: application/json

{
  "action": "search",
  "parameters": {
    "query": "search term",
    "page_size": 10
  }
}
```

**Available actions:** `search`, `read_page`, `create_page`, `add_content`, `bulk_add_content`, `analytics`, `bulk_operations`

## 🧪 Testing _(COMPREHENSIVE)_

Run the comprehensive test suite:

```bash
# Start the server first
python -m notion_mcp_server.api_serverV2

# In another terminal, run tests
cd src/notion_mcp_server
python test_server.py
```

**Test Coverage (1,158 lines, 13+ categories):**

- ✅ **Core Operations**: Health checks, search, page creation/reading
- ✅ **Content Addition**: All content types including links and bookmarks
- ✅ **Bulk Content**: Multiple content blocks and optimization
- ✅ **Link Functionality**: Bookmark and link_to_page validation
- ✅ **Analytics**: All analytics types and performance
- ✅ **Bulk Operations**: Optimized pagination and limits
- ✅ **Agent Integration**: All agent query actions
- ✅ **Edge Cases**: Error handling, validation, timeouts
- ✅ **Exception Handling**: Network issues, invalid inputs

**Test Features:**

- 🎯 **Detailed Reporting**: Success rates, timing, categorization
- 📊 **Performance Insights**: Response times and bottlenecks
- 📄 **JSON Reports**: Exportable test results with timestamps
- 🧹 **Cleanup Scripts**: Automatic test data management

## ⚙️ Configuration

### Environment Variables

| Variable                 | Default      | Description                   |
| ------------------------ | ------------ | ----------------------------- |
| `NOTION_TOKEN`           | _(required)_ | Your Notion integration token |
| `HOST`                   | `0.0.0.0`    | Server host address           |
| `PORT`                   | `8081`       | Server port                   |
| `DEBUG`                  | `false`      | Enable debug mode             |
| `MAX_PAGE_SIZE`          | `100`        | Maximum results per page      |
| `DEFAULT_PAGE_SIZE`      | `20`         | Default results per page      |
| `MAX_CONTENT_LENGTH`     | `2000`       | Maximum content block length  |
| `ENABLE_ANALYTICS`       | `true`       | Enable analytics endpoints    |
| `ENABLE_BULK_OPERATIONS` | `true`       | Enable bulk operations        |
| `LOG_LEVEL`              | `INFO`       | Logging level                 |

### Configuration Validation

The server automatically validates all configuration on startup and provides clear error messages for invalid settings.

## 🔧 Integration Examples

### With AI Agents

```python
import requests

# Search for content
response = requests.post("http://localhost:8081/api/agent/query", json={
    "action": "search",
    "parameters": {"query": "project notes"}
})

# Create a new page with links
response = requests.post("http://localhost:8081/api/agent/query", json={
    "action": "create_page",
    "parameters": {
        "title": "AI Generated Page",
        "content": "This page was created by an AI agent"
    }
})

# Add bookmark to page
response = requests.post("http://localhost:8081/api/agent/query", json={
    "action": "add_content",
    "parameters": {
        "page_id": "page-id",
        "content_type": "bookmark",
        "content": "Useful Resource",
        "url": "https://example.com"
    }
})
```

### With Your Chatbot

```python
# Already integrated in your chatbot_agentic_v3.py!
# Enhanced with ALL new functions:

# Core functions
server.notion_search_content()
server.notion_read_page()
server.notion_create_page()

# Content addition with links
server.notion_add_paragraph()
server.notion_add_heading()
server.notion_add_bullet_point()
server.notion_add_todo()

# Smart content helpers
server.notion_add_structured_content()  # Multi-section content
server.notion_add_smart_content()       # AI-friendly content parsing

# Bulk operations
server.notion_bulk_create_pages()
server.notion_bulk_list_pages()
server.notion_bulk_analyze_pages()

# Analytics
server.notion_workspace_analytics()
server.notion_content_analytics()
server.notion_activity_analytics()
```

## 📈 Performance Features _(ENHANCED)_

- **Async Operations**: Non-blocking I/O for better performance
- **Smart Timeouts**: Dynamic timeouts (30s standard, 60s bulk, 45s analytics)
- **Pagination Controls**: Configurable limits to prevent timeouts
- **Connection Pooling**: Efficient Notion API connections
- **Request Validation**: Fast input validation and sanitization
- **Error Recovery**: Graceful handling of API failures
- **Memory Efficient**: Optimized for low memory usage
- **Progress Yielding**: Prevents blocking during bulk operations

## 🛡️ Security & Validation Features _(BULLETPROOF)_

- **Token Validation**: Automatic Notion token validation
- **Input Sanitization**: Protection against malicious input
- **Comprehensive Validation**: All content types validated
  - Bookmark URLs must be valid HTTP/HTTPS
  - Page references must exist
  - Content length limits enforced
  - Required fields validation
- **Rate Limiting Ready**: Framework for rate limiting (configurable)
- **CORS Support**: Secure cross-origin requests
- **Environment Isolation**: Secure environment variable handling
- **HTTP Status Handling**: Proper error code processing

## 📋 Error Handling _(ENHANCED)_

The server provides detailed error messages for all scenarios:

### Validation Errors

- **Missing URLs**: "URL is required for bookmark content type"
- **Invalid Page References**: "Target page not found: page-name"
- **Empty Content**: "Content cannot be empty"
- **Invalid Content Types**: Clear list of supported types

### API Errors

- **Invalid Tokens**: Clear guidance for token setup
- **Missing Pages**: Helpful suggestions for page access
- **API Limits**: Graceful handling of Notion API limits
- **Network Issues**: Automatic retry mechanisms
- **Timeout Prevention**: Smart limits and pagination

### HTTP Status Codes

- **200**: Successful operations
- **400**: Validation errors (missing fields, invalid formats)
- **404**: Resource not found (pages, invalid references)
- **500**: Server errors (with detailed diagnostics)
- **503**: Server not initialized

## 🆔 Version History

### V2.1.0 (Current) _(MAJOR UPDATE)_

- 🔗 **Link Functionality**: Bookmarks and link_to_page support
- 🛡️ **Bulletproof Validation**: Comprehensive input validation
- ⚡ **Timeout Optimization**: Fixed bulk operations with smart pagination
- 🧪 **Enhanced Test Suite**: 48KB comprehensive testing (1,158 lines)
- 📊 **HTTP Status Handling**: Proper error code processing in tests
- 🎯 **Performance Controls**: Configurable timeouts and limits
- 📈 **Smart Content**: AI-friendly content parsing helpers

### V2.0.0 (Previous)

- ✅ Complete rewrite with enhanced features
- ✅ Configuration management system
- ✅ Basic test suite
- ✅ Production-ready error handling
- ✅ Bulk operations support
- ✅ Enhanced content management
- ✅ Agent integration endpoints

### V1.0.0 (Legacy)

- ✅ Basic MCP server functionality
- ✅ Core operations (search, read, create)
- ✅ Simple CLI interface

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes with tests
4. Run the comprehensive test suite: `python test_server.py`
5. Ensure all tests pass (aim for 90%+ success rate)
6. Submit a pull request

**Testing Requirements:**

- All new features must include tests
- Validation scenarios must be covered
- Performance implications should be documented
- Error handling paths must be tested

## 📞 Support

If you encounter issues:

1. **Check Configuration**: Ensure all environment variables are set correctly
2. **Verify Token**: Make sure your Notion token is valid and has proper permissions
3. **Run Health Check**: Visit `/health` endpoint to verify server status
4. **Run Test Suite**: Use `python test_server.py` to identify specific issues
5. **Check Logs**: Review server logs for detailed error messages
6. **Test Validation**: Ensure your content meets validation requirements

**Common Issues:**

- **Link validation errors**: Ensure URLs start with http/https
- **Timeout issues**: Use pagination controls for large operations
- **Page not found**: Verify page sharing with integration
- **Content too long**: Content blocks limited to 2000 characters

### 📧 **Contact Information**

For direct support or questions:

- **📱 Phone**: +918449035579
- **📧 Email**: ankitmalik844903@gmail.com
- **👨‍💻 Developer**: Ankit Malik

Feel free to reach out for:

- ✅ Technical support and troubleshooting
- ✅ Feature requests and suggestions
- ✅ Integration assistance
- ✅ Bug reports and issues
- ✅ Custom development needs

## 📄 License

This project is part of the Agentic Long-Term Memory system.

---

**🎉 Your Notion MCP Server V2.1 is bulletproof and production-ready!**

**⚡ New in V2.1:**

- 🔗 **Link Support** - Bookmarks and internal page links
- 🛡️ **Bulletproof Validation** - Comprehensive error prevention
- ⚡ **Timeout Optimization** - Smart pagination and limits
- 🧪 **48KB Test Suite** - Comprehensive testing and reporting
- 🎯 **Performance Controls** - Configurable timeouts and limits

**📊 Quality Metrics:**

- **1,158 lines** of test coverage
- **13+ test categories** including edge cases
- **90%+ success rate** target for all operations
- **Sub-5 second** response times for optimized operations