{
  "markdown": "# 📝 Gemini CLI Notion Extension v3.0.4 Enhanced Edition\n\n> Complete Notion workspace automation with [Gemini CLI](https://github.com/google-gemini/gemini-cli) via Model Context Protocol (MCP).\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)\n[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Extension-blue.svg)](https://github.com/google-gemini/gemini-cli)\n[![Version](https://img.shields.io/badge/Version-3.0.4-brightgreen.svg)](https://github.com/PatelPratikkumar/gemini-notion-extension/releases)\n\nTransform your Notion workspace into a powerful automation hub with 46 comprehensive tools, file processing, database templates, and intelligent monitoring.\n\n## ✨ v3.0.3 Enhanced Features (Bug Fix Release)\n\n- **🔧 Critical Fix**: MCP server registration for proper Gemini CLI tool discovery\n- **🐛 Fixed upload_file_to_notion**: Honest implementation with proper file handling modes\n- **🐛 Improved Error Handling**: Better database parent resolution for create_page function\n- **🚀 46 MCP Tools** (38 core + 8 enhanced) covering all Notion operations\n- **📄 File Processing** - Bulk upload, automated scanning, file monitoring\n- **🎯 Database Templates** - Pre-configured schemas for common workflows\n- **📊 Health Analytics** - API monitoring, usage statistics, performance tracking\n- **🤖 Automation Ready** - File watchers, bulk operations, rate limiting\n- **🔄 Production Stable** - Built on proven v2.8 foundation with enhanced capabilities\n- **📝 Markdown Support** - Advanced content conversion with block chunking\n- **🔍 Smart Search** - Enhanced search with analytics and filtering\n- **🔐 Secure Storage** - Cross-platform credential management\n- **🎙️ Voice-Friendly** - Handles transcription errors gracefully\n\n### New in v3.0.3: Enhanced Tool Categories + Bug Fixes\n\n| Category | Tools | Examples |\n|----------|-------|----------|\n| **🔧 Core Notion** | 38 tools | search, create_page, query_database, comments |\n| **📄 File Operations** | 4 tools | upload_file_to_notion, bulk_create_pages_from_files |\n| **🎯 Database Templates** | 1 tool | create_database_from_template (4 templates) |\n| **📊 Health & Analytics** | 2 tools | check_api_health, get_usage_statistics |\n| **🔍 Enhanced Search** | 1 tool | advanced_search (with analytics) |\n| **Total** | **46 tools** | Complete workspace automation |\n\n---\n\n## 📋 Prerequisites\n\nBefore installing, you need:\n\n1. **Node.js 18+** - [Download here](https://nodejs.org/)\n2. **Gemini CLI** - Install globally:\n   ```bash\n   npm install -g @google/gemini-cli\n   ```\n3. **Notion Integration Token** - Get yours below 👇\n\n---\n\n## 🔐 Getting Your Notion API Token\n\n1. Log in to [Notion](https://www.notion.so)\n2. Go to [My Integrations](https://www.notion.so/my-integrations)\n3. Click **\"+ New integration\"**\n4. Configure:\n   - **Name**: `Gemini CLI Extension`\n   - **Associated workspace**: Select your workspace\n   - **Capabilities**: Check all Content, Comment, and User capabilities\n5. Click **\"Submit\"**\n6. Copy the **Internal Integration Token** (starts with `secret_`)\n\n> ⚠️ **Keep your token secret!** Never share it or commit it to git.\n\n---\n\n## 🚀 Installation & Setup\n\n### 📖 **IMPORTANT: Two-Step Installation Process**\n\nThe Notion extension requires **both extension installation AND MCP server registration** for tools to work:\n\n1. **Extension Installation**: Provides metadata, commands, and context\n2. **MCP Server Registration**: Enables the 46 Notion tools in Gemini CLI\n\n**If you skip step 2, you'll get \"Tool not found\" errors.**\n\n---\n\n### 🏃‍♂️ **Quick Setup (Recommended)**\n\n```bash\n# 1. Install extension with auto-update\ngemini extensions install https://github.com/PatelPratikkumar/gemini-notion-extension --auto-update\n\n# 2. Get your Notion API token (see section below)\n# Set as environment variable:\nsetx NOTION_API_KEY \"your_notion_token_here\"  # Windows\nexport NOTION_API_KEY=\"your_notion_token_here\"  # macOS/Linux\n\n# 3. Register MCP server for tool access\ngemini mcp add notion node \"~/.gemini/extensions/notion-extension/dist/bundle.js\" -e NOTION_API_KEY=\"${NOTION_API_KEY}\" --timeout 30000 -s user\n\n# 4. Verify installation\ngemini mcp list\n# Should show: ✓ notion: ... - Connected\n\n# 5. Test tools\necho \"List my Notion databases\" | gemini chat\n```\n\n---\n\n### 📋 **Prerequisites**\n\nBefore installing, ensure you have:\n\n1. **Node.js 18+** - [Download here](https://nodejs.org/)\n2. **Gemini CLI** - Install globally:\n   ```bash\n   npm install -g @google/gemini-cli\n   ```\n3. **Notion Integration Token** - Get yours below 👇\n\n---\n\n### 🔐 **Getting Your Notion API Token**\n\n1. Log in to [Notion](https://www.notion.so)\n2. Go to [My Integrations](https://www.notion.so/my-integrations)\n3. Click **\"+ New integration\"**\n4. Configure:\n   - **Name**: `Gemini CLI Extension`\n   - **Associated workspace**: Select your workspace\n   - **Capabilities**: Check all Content, Comment, and User capabilities\n5. Click **\"Submit\"**\n6. Copy the **Internal Integration Token** (starts with `ntn_`)\n\n> ⚠️ **Keep your token secret!** Never share it or commit it to git.\n\n### 🔗 **Share Pages with Integration**\n\nIn Notion, grant access to pages/databases you want to use:\n1. Open a page or database\n2. Click **\"Share\"** (top right)\n3. Click **\"Add connections\"** or **\"Invite\"**\n4. Select **\"Gemini CLI Extension\"**\n\n---\n\n### 🎯 **Installation Methods**\n\n#### **Method A: Auto-Update Installation (Recommended)**\n\n**For production use with automatic updates:**\n\n```bash\n# 1. Install extension from GitHub\ngemini extensions install https://github.com/PatelPratikkumar/gemini-notion-extension --auto-update\n\n# 2. Set environment variable (choose your OS)\n# Windows (PowerShell - restart terminal after):\nsetx NOTION_API_KEY \"ntn_your_token_here\"\n\n# macOS/Linux (add to ~/.bashrc or ~/.zshrc):\necho 'export NOTION_API_KEY=\"ntn_your_token_here\"' >> ~/.bashrc\nsource ~/.bashrc\n\n# 3. Register MCP server (critical step!)\ngemini mcp add notion node \"~/.gemini/extensions/notion-extension/dist/bundle.js\" \\\n  -e NOTION_API_KEY=\"${NOTION_API_KEY}\" \\\n  --timeout 30000 \\\n  -s user\n\n# 4. Verify setup\ngemini mcp list\necho \"What Notion tools do you have?\" | gemini chat\n```\n\n**Future updates:**\n```bash\n# Update extension\ngemini extensions update notion-extension\n\n# MCP server automatically uses updated code\n# No additional steps needed\n```\n\n#### **Method B: Development Installation**\n\n**For local development and custom modifications:**\n\n```bash\n# 1. Clone repository\ngit clone https://github.com/PatelPratikkumar/gemini-notion-extension.git\ncd gemini-notion-extension\n\n# 2. Install dependencies\nnpm install\n\n# 3. Set environment variable\n# Windows:\nsetx NOTION_API_KEY \"ntn_your_token_here\"\n\n# macOS/Linux:\necho 'export NOTION_API_KEY=\"ntn_your_token_here\"' >> ~/.bashrc\nsource ~/.bashrc\n\n# 4. Build extension\nnpm run build\n\n# 5. Link extension\ngemini extensions link .\n\n# 6. Register MCP server with local path\ngemini mcp add notion node \"$(pwd)/dist/bundle.js\" \\\n  -e NOTION_API_KEY=\"${NOTION_API_KEY}\" \\\n  --timeout 30000 \\\n  -s user\n\n# 7. Verify setup\ngemini mcp list\n```\n\n**Development workflow:**\n```bash\n# After making changes:\nnpm run build\n\n# MCP server automatically uses updated code\n# No need to re-register\n```\n\n#### **Method C: Automated Setup Script**\n\n**For guided setup with automatic configuration:**\n\n```bash\n# 1. Install extension\ngemini extensions install https://github.com/PatelPratikkumar/gemini-notion-extension --auto-update\n\n# 2. Navigate to extension directory\ncd ~/.gemini/extensions/notion-extension\n\n# 3. Run setup script (guides you through token setup and database configuration)\n# Windows:\n.\\setup-windows.ps1\n\n# macOS/Linux:\nchmod +x setup-unix.sh && ./setup-unix.sh\n\n# 4. Register MCP server (still required after setup)\ngemini mcp add notion node \"~/.gemini/extensions/notion-extension/dist/bundle.js\" \\\n  -e NOTION_API_KEY=\"${NOTION_API_KEY}\" \\\n  --timeout 30000 \\\n  -s user\n```\n\n---\n\n## 🗑️ **Uninstallation**\n\n### **Complete Removal**\n\n```bash\n# 1. Remove MCP server\ngemini mcp remove notion\n\n# 2. Uninstall extension\ngemini extensions uninstall notion-extension\n\n# 3. Clean environment variables (optional)\n# Windows:\nreg delete \"HKCU\\Environment\" /v \"NOTION_API_KEY\" /f\n\n# macOS/Linux (remove line from ~/.bashrc):\ngrep -v \"NOTION_API_KEY\" ~/.bashrc > ~/.bashrc.tmp && mv ~/.bashrc.tmp ~/.bashrc\nsource ~/.bashrc\n\n# 4. Remove cached data (optional)\nrm ~/.notion-cache.json  # If exists\nrm ~/.gemini/extensions/notion-extension/ -rf  # If exists\n```\n\n### **Partial Removal (Keep Extension, Remove MCP Server)**\n\n```bash\n# Remove MCP server only (keeps extension for context/commands)\ngemini mcp remove notion\n\n# Extension remains available but tools won't work\n# To restore tools, re-run: gemini mcp add notion...\n```\n\n---\n\n## 🔧 **Troubleshooting**\n\n### **\"Tool not found\" Errors**\n\n**Symptom**: Extension shows as loaded but Notion tools don't work\n\n```bash\n# 1. Check if MCP server is registered\ngemini mcp list\n# Should show: ✓ notion: ... - Connected\n\n# 2. If missing or disconnected, register MCP server:\ngemini mcp add notion node \"~/.gemini/extensions/notion-extension/dist/bundle.js\" \\\n  -e NOTION_API_KEY=\"${NOTION_API_KEY}\" \\\n  --timeout 30000 \\\n  -s user\n\n# 3. Verify environment variable\necho $NOTION_API_KEY  # Should start with 'secret_' or 'ntn_'\n\n# 4. Test connection\necho \"List my Notion databases\" | gemini chat\n```\n\n### **MCP Server Disconnected**\n\n**Symptom**: `gemini mcp list` shows \"Disconnected\" or \"Failed\"\n\n```bash\n# 1. Check MCP server logs\ngemini mcp logs notion\n\n# 2. Increase timeout and re-register\ngemini mcp remove notion\ngemini mcp add notion node \"~/.gemini/extensions/notion-extension/dist/bundle.js\" \\\n  -e NOTION_API_KEY=\"${NOTION_API_KEY}\" \\\n  --timeout 60000 \\\n  -s user\n\n# 3. Check Node.js version (requires 18+)\nnode --version\n```\n\n### **Invalid Notion Token**\n\n**Symptom**: \"Unauthorized\" or \"Invalid token\" errors\n\n```bash\n# 1. Verify token format\necho $NOTION_API_KEY\n# Should start with 'secret_' (old format) or 'ntn_' (new format)\n\n# 2. Test token directly\ncurl -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n     -H \"Notion-Version: 2022-06-28\" \\\n     https://api.notion.com/v1/users/me\n\n# 3. If invalid, get new token from Notion integrations\n# Then update environment variable:\nsetx NOTION_API_KEY \"your_new_token\"  # Windows\nexport NOTION_API_KEY=\"your_new_token\"  # macOS/Linux\n```\n\n### **Extension Version Conflicts**\n\n**Symptom**: Tools work intermittently after updates\n\n```bash\n# 1. Check extension versions\ngemini extensions list\n\n# 2. Force clean reinstall\ngemini extensions uninstall notion-extension\ngemini mcp remove notion\ngemini extensions install https://github.com/PatelPratikkumar/gemini-notion-extension --auto-update\n\n# 3. Re-register MCP server with updated path\ngemini mcp add notion node \"~/.gemini/extensions/notion-extension/dist/bundle.js\" \\\n  -e NOTION_API_KEY=\"${NOTION_API_KEY}\" \\\n  --timeout 30000 \\\n  -s user\n```\n\n### **Environment Variable Issues**\n\n**Windows PowerShell:**\n```powershell\n# Check if variable exists\necho $env:NOTION_API_KEY\n\n# Set permanently\n[Environment]::SetEnvironmentVariable(\"NOTION_API_KEY\", \"your_token\", \"User\")\n\n# Restart PowerShell/terminal after setting\n```\n\n**macOS/Linux:**\n```bash\n# Check if variable exists\necho $NOTION_API_KEY\n\n# Add to shell profile (choose your shell)\necho 'export NOTION_API_KEY=\"your_token\"' >> ~/.bashrc  # Bash\necho 'export NOTION_API_KEY=\"your_token\"' >> ~/.zshrc   # Zsh\nsource ~/.bashrc  # Or ~/.zshrc\n```\n\n### **Common Error Messages**\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `Tool \"notion_list_databases\" not found` | MCP server not registered | Run `gemini mcp add notion...` |\n| `MCP server 'notion' failed to start` | Invalid bundle path or environment | Check file path and `$NOTION_API_KEY` |\n| `Request timed out` | Slow Notion API response | Increase `--timeout` to 60000 |\n| `Unauthorized` | Invalid/expired token | Get new token from Notion integrations |\n| `No databases found` | Pages not shared with integration | Share pages in Notion |\n\n---\n\n## ✅ **Testing Your Installation**\n\n### **Quick Verification**\n\n```bash\n# 1. Check extension status\ngemini extensions list\n# Should show: ✓ notion-extension v3.0.3\n\n# 2. Check MCP server status\ngemini mcp list\n# Should show: ✓ notion: ... - Connected\n\n# 3. Test tool registry\necho \"What Notion tools do you have available?\" | gemini chat\n# Should list 46 Notion tools\n\n# 4. Test basic functionality\necho \"List my Notion databases\" | gemini chat\n# Should show your accessible databases\n```\n\n### **Comprehensive Testing**\n\n```bash\n# Database operations\necho \"Show me all my Notion databases with their properties\" | gemini chat\necho \"Query my Tasks database for incomplete items\" | gemini chat\n\n# Page operations\necho \"Create a test page called 'Gemini CLI Test' with some content\" | gemini chat\necho \"Search for pages containing 'test'\" | gemini chat\n\n# Advanced features\necho \"Get analytics for my most accessed database\" | gemini chat\necho \"Export my Tasks database to CSV format\" | gemini chat\n```\n\n### **Expected Results**\n\n✅ **Working Installation**:\n- Extension appears in `gemini extensions list`\n- MCP server shows as \"Connected\" in `gemini mcp list`\n- All 46 Notion tools are available and functional\n- Can list databases, create pages, and search content\n\n❌ **Common Issues**:\n- **\"Tool not found\"** = MCP server not registered (run `gemini mcp add...`)\n- **\"Unauthorized\"** = Invalid token or pages not shared\n- **\"Disconnected\"** = Check Node.js version and increase timeout\n\n---\n\n## � Extension Management & Updates\n\n### Updating the Extension\n\nThe update method depends on how you installed the extension:\n\n#### Git-Installed Extensions (Automatic Updates Available ✅)\nIf installed with `gemini extensions install https://...`:\n```bash\n# Update specific extension to latest version\ngemini extensions update notion-extension\n\n# Update all extensions at once\ngemini extensions update --all\n```\n\n#### Locally Linked Extensions (Manual Updates Required 🔧)\nIf installed with `gemini extensions link .` (development):\n```bash\ncd /path/to/your/gemini-notion-extension\ngit pull origin main\nnpm install\nnpm run build\n# Extension automatically reflects changes\n```\n\n#### Force Reinstall from GitHub\n```bash\n# For any issues or switching from local to git-managed\ngemini extensions uninstall notion-extension\ngemini extensions install https://github.com/PatelPratikkumar/gemini-notion-extension --auto-update\n```\n\n### Extension Management Commands\n\n```bash\n# List all installed extensions\ngemini extensions list\n\n# Check extension status and info\ngemini extensions list | grep notion-extension\n\n# Disable temporarily (keeps configuration)\ngemini extensions disable notion-extension\n\n# Re-enable extension\ngemini extensions enable notion-extension\n\n# Completely remove extension\ngemini extensions uninstall notion-extension\n\n# Validate extension integrity\ngemini extensions validate .\n```\n\n### Auto-Update Setup\n\nFor automatic updates when installing:\n```bash\n# Install with auto-update enabled\ngemini extensions install https://github.com/PatelPratikkumar/gemini-notion-extension --auto-update\n```\n\n### Version Checking\n\n```bash\n# Check current version\ngemini extensions list | grep notion-extension\n\n# View extension details\ncd ~/.gemini/extensions/notion-extension\ncat package.json | grep version\n```\n\n---\n\n## �🛠️ Complete Tool Reference (46 Tools)\n\n### 🔧 Core Notion Operations (38 Tools)\n\n#### Search & Discovery\n| Tool | Description | Example Usage |\n|------|-------------|---------------|\n| `notion_search` | Search pages and databases by name or content | \"Search for pages about API design\" |\n| `advanced_search` | Enhanced search with analytics and filtering | \"Find all project docs with analytics\" |\n\n#### Page Management  \n| Tool | Description | Example Usage |\n|------|-------------|---------------|\n| `create_page` | Create new pages with markdown content | \"Create a meeting notes page\" |\n| `get_page` | Retrieve page properties and content | \"Show me the project overview page\" |\n| `update_page` | Modify title, icon, cover, properties | \"Update the project status\" |\n| `archive_page` | Archive (soft delete) pages | \"Archive completed project pages\" |\n| `restore_page` | Restore archived pages | \"Restore the archived design doc\" |\n| `duplicate_page` | Copy pages with all content | \"Duplicate the template page\" |\n\n#### Database Operations\n| Tool | Description | Example Usage |\n|------|-------------|---------------|\n| `list_databases` | List all accessible databases | \"Show all my databases\" |\n| `get_database` | Get database schema and properties | \"Show the project database structure\" |\n| `query_database` | Filter and sort database entries | \"Show active projects sorted by date\" |\n| `create_database` | Create new databases with custom schema | \"Create a task tracking database\" |\n| `update_database` | Modify database properties and schema | \"Add a priority field to tasks\" |\n\n#### Block & Content Management\n| Tool | Description | Example Usage |\n|------|-------------|---------------|\n| `get_page_blocks` | Read page content as structured blocks | \"Get the content of the meeting notes\" |\n| `append_blocks` | Add content (markdown supported) | \"Add action items to the page\" |\n| `update_block` | Modify existing blocks | \"Update the project timeline\" |\n| `delete_block` | Remove specific blocks | \"Remove the old requirements section\" |\n\n#### Comments & Collaboration\n| Tool | Description | Example Usage |\n|------|-------------|---------------|\n| `get_comments` | Read all comments on a page | \"Show comments on the proposal\" |\n| `create_comment` | Add comments to pages | \"Add feedback to the design doc\" |\n\n#### Users & Workspace\n| Tool | Description | Example Usage |\n|------|-------------|---------------|\n| `get_user` | Get current user information | \"Show my Notion account info\" |\n| `list_users` | List all workspace members | \"Who has access to this workspace?\" |\n\n### 🚀 Enhanced Operations (8 New Tools)\n\n#### 📄 File Processing & Automation\n| Tool | Description | Example Usage |\n|------|-------------|---------------|\n| `upload_file_to_notion` | Upload files with metadata extraction | \"Upload the PDF contract to the legal database\" |\n| `bulk_create_pages_from_files` | Process multiple files into database entries | \"Create pages for all PDFs in the contracts folder\" |\n| `start_file_watcher` | Monitor folders for new files (framework ready) | \"Watch the scans folder for new documents\" |\n| `stop_file_watcher` | Stop file monitoring processes | \"Stop watching the downloads folder\" |\n| `list_active_watchers` | List all active file monitors | \"Show all active file watchers\" |\n\n#### 🎯 Database Templates\n| Tool | Description | Templates Available |\n|------|-------------|---------------------|\n| `create_database_from_template` | Create databases with pre-configured schemas | **Document Scanner**, Project Tracker, Meeting Notes, Task Management |\n\n**Template Details:**\n- **Document Scanner** - Perfect for PDF automation (Name, File Path, Upload Date, Document Type, Status, Notes)\n- **Project Tracker** - Complete project management (Name, Status, Description, Dates, Priority)  \n- **Meeting Notes** - Structured meetings (Title, Date, Participants, Meeting Type, Action Items)\n- **Task Management** - Task tracking (Task, Status, Priority, Assignee, Due Date, Tags)\n\n#### 📊 Health & Analytics\n| Tool | Description | Monitoring Features |\n|------|-------------|---------------------|\n| `check_api_health` | Comprehensive API health monitoring | Connectivity, latency, uptime, error rates |\n| `get_usage_statistics` | Detailed API usage analytics | Request counts, performance metrics, feature usage |\n\n---\n\n## 🎯 Enhanced Workflow Examples\n\n### 📄 Document Automation Workflow\n```bash\n# 1. Create a document scanning database\n\"Create a document scanner database called 'Legal Documents' in my workspace\"\n\n# 2. Bulk process PDF files\n\"Process all PDF files in my Downloads/Contracts folder and create database entries\"\n\n# 3. Start monitoring for new files\n\"Start watching Downloads/Scans folder for new PDF files\"\n\n# 4. Check processing status\n\"Show me the health status and processing statistics\"\n```\n\n### 🏢 Project Management Setup\n```bash\n# 1. Create project database from template\n\"Create a project tracker database called 'Q1 2025 Projects'\"\n\n# 2. Bulk create projects from file list\n\"Create project entries for all files in my Project-Plans folder\"\n\n# 3. Monitor project database\n\"Show usage statistics for the last 24 hours\"\n\n# 4. Health check\n\"Check API health with detailed metrics\"\n```\n\n### 📊 Analytics & Monitoring\n```bash\n# Monitor workspace health\n\"Check API health with full details\"\n\n# Get usage insights\n\"Show usage statistics for the past week\"\n\n# File processing status  \n\"List all active file watchers and their status\"\n```\n\n---\n\n## 🔧 Configuration\n\n### Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `NOTION_API_KEY` | Notion integration token | Yes |\n\n### Cache File (`.notion-cache.json`)\n\n```json\n{\n  \"conversationDbId\": \"uuid-of-conversation-database\",\n  \"projectDbId\": \"uuid-of-project-database\",\n  \"lastUpdated\": \"2025-01-01T00:00:00.000Z\"\n}\n```\n\n### Gemini Extension Config (`gemini-extension.json`)\n\n```json\n{\n  \"name\": \"notion-extension\",\n  \"description\": \"Full Notion workspace integration\",\n  \"mcpServers\": {\n    \"notion\": {\n      \"command\": \"node\",\n      \"args\": [\"dist/bundle.js\"],\n      \"timeout\": 30\n    }\n  }\n}\n```\n\n---\n\n## 🔐 Security\n\n- **No tokens in code**: API keys stored in OS credential managers\n- **No tokens in git**: `.gitignore` excludes all sensitive files\n- **Environment variable fallback**: Works if credential manager unavailable\n- **Local cache only**: Database IDs stored locally, not synced\n\n### Token Storage Locations\n\n| Platform | Storage | Security |\n|----------|---------|----------|\n| Windows | User environment variable | Process-isolated |\n| macOS | Keychain | Encrypted, requires unlock |\n| Linux | libsecret/GNOME Keyring | Encrypted, session-based |\n\n---\n\n## 🐛 Troubleshooting\n\n### \"Connection failed\" or \"ECONNRESET\"\n\n1. Verify your token: Run setup script again\n2. Check Notion status: [status.notion.so](https://status.notion.so)\n3. Verify page sharing: Ensure pages are shared with integration\n\n### \"Tool not found in registry\"\n\n1. Run from project directory: `cd /path/to/extension && gemini`\n2. Rebuild: `npm run build`\n3. Re-link: `gemini extensions link .`\n\n### \"Database IDs not configured\"\n\n1. Run setup script: `.\\setup-windows.ps1` or `./setup-unix.sh`\n2. Verify `.notion-cache.json` exists\n3. Check you selected databases during setup\n\n### \"API key not found\"\n\n**Windows:**\n```powershell\n# Check if set\n$env:NOTION_API_KEY\n\n# Set manually\n[System.Environment]::SetEnvironmentVariable(\"NOTION_API_KEY\", \"secret_xxx\", \"User\")\n```\n\n**macOS:**\n```bash\n# Check keychain\nsecurity find-generic-password -s \"gemini-notion-extension\" -a \"NOTION_API_KEY\" -w\n\n# Add manually\nsecurity add-generic-password -s \"gemini-notion-extension\" -a \"NOTION_API_KEY\" -w \"secret_xxx\"\n```\n\n**Linux:**\n```bash\n# Check secret\nsecret-tool lookup service gemini-notion-extension account NOTION_API_KEY\n\n# Store manually\necho \"secret_xxx\" | secret-tool store --label=\"Notion API Key\" service gemini-notion-extension account NOTION_API_KEY\n```\n\n---\n\n## 📁 Project Structure\n\n```\ngemini-notion-extension/\n├── src/\n│   ├── server.ts          # MCP server with all tool handlers\n│   ├── tools.ts            # Tool definitions (JSON Schema)\n│   ├── credentials.ts      # Cross-platform credential retrieval\n│   ├── notion-client.ts    # Notion API wrapper\n│   ├── types/              # TypeScript interfaces\n│   └── managers/           # Business logic managers\n├── dist/                   # Compiled JavaScript (generated)\n├── setup-windows.ps1       # Windows setup script\n├── setup-unix.sh          # macOS/Linux setup script\n├── gemini-extension.json   # Gemini CLI manifest\n├── GEMINI.md              # AI playbook\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n---\n\n## 🔄 Version History & Changelog\n\n### v3.0.0 (2025-12-14) 🚀 **ENHANCED EDITION**\n**Major Release: Complete Automation Platform**\n\n#### 🆕 New Enhanced Features\n- **📄 File Processing Suite**: Upload, bulk operations, automated scanning\n- **🎯 Database Templates**: 4 pre-built templates (Document Scanner, Project Tracker, Meeting Notes, Task Management)\n- **📊 Health Analytics**: API monitoring, usage statistics, performance tracking  \n- **🔍 Advanced Search**: Enhanced search with analytics and filtering\n- **🤖 Automation Framework**: File watchers, bulk operations (framework ready)\n\n#### 📈 Enhanced Capabilities\n- **46 Total Tools** (+21% increase from 38 tools)\n- **8 New Enhanced Tools** built on research analysis\n- **Production Monitoring** with health checks and statistics\n- **Template-Based Workflows** for common automation scenarios\n- **File Processing Pipeline** ready for document automation\n\n#### 🔧 Technical Improvements\n- Enhanced server architecture with v3.0 naming\n- Comprehensive tool categorization and documentation\n- Production-ready monitoring and analytics\n- Maintained 100% backward compatibility with v2.8\n\n### v2.8.0 (2025-12-14) ⭐ **FOUNDATION RELEASE**\n#### 💾 Performance & Reliability\n- **TTL Caching**: Smart caching for schemas, lists, pages, users\n- **📊 Metrics**: Track API calls, latency, error rates  \n- **📝 Logging**: Structured logs with levels (debug/info/warn/error)\n- **📴 Offline Queue**: Queue operations when disconnected\n- **📑 5 Templates**: meeting-notes, project-brief, daily-standup, bug-report, code-review\n- **✅ Schema Validation**: Validate before API calls\n- **🏥 Health Check**: Monitor system status  \n- **📦 Batch Ops**: Create/archive pages, delete blocks in bulk\n- **🔢 38 Total Tools** (12 new advanced tools)\n\n### v2.7.0 (2025-12-14)\n#### ⚡ Network & Performance  \n- **Rate Limiting**: Token Bucket algorithm (3 requests/second)\n- **🔄 Retry Logic**: Exponential backoff for 429/5xx errors\n- **📄 Auto-Pagination**: Handle >100 database items automatically\n- **📦 Block Pagination**: Handle >100 blocks per page\n- **✂️ Content Chunking**: Split >50KB content automatically\n- **🔀 Batch Appending**: Handle >100 blocks per request\n- **🌐 Network Error Handling**: ECONNRESET, ETIMEDOUT recovery\n\n### v2.5.0 (2025-12-14)\n#### 🤖 AI Integration\n- **📋 Decision Tree**: Smart tool selection for AI\n- **📝 Workflow Guidance**: Step-by-step AI instructions  \n- **🔧 Context Files**: Enhanced AI understanding\n- **🚀 New Commands**: search-notion, recent-changes\n\n### v2.3.0 (2025-12-14)  \n#### 📦 Deployment\n- **esbuild Bundling**: Standalone installation (~640KB → 685KB in v3.0)\n- **🔧 MCP Configuration**: Proper server setup\n\n### v2.1.0 (2025-12-14)\n#### 🔗 Installation  \n- **GitHub Direct Install**: One-command installation\n- **📚 Troubleshooting**: Comprehensive debugging guide\n\n### v2.0.0 (2025-12-14)\n#### ✨ Core Platform\n- **25 Comprehensive Tools**: Full Notion API coverage\n- **🔐 Secure Credentials**: Cross-platform storage\n- **📝 Markdown Conversion**: Rich content support\n- **🔍 Full-Text Search**: Workspace-wide search\n- **💬 Comments**: Full collaboration support\n- **👥 User Management**: Team features\n- **📁 Project Tools**: Dedicated project management\n- **💾 Conversation Export**: Chat preservation\n- **🛠️ Database Shortcuts**: Simplified access\n\n### v1.0.0 (2025-12-13)\n#### 🎉 Initial Release\n- **Basic Operations**: Pages and databases\n- **Conversation Export**: Simple chat saving\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n---\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create feature branch: `git checkout -b feature/amazing-feature`\n3. Commit changes: `git commit -m 'Add amazing feature'`\n4. Push to branch: `git push origin feature/amazing-feature`\n5. Open Pull Request\n\n---\n\n## 🙏 Acknowledgments\n\n- [Gemini CLI](https://github.com/google-gemini/gemini-cli) by Google\n- [Notion API](https://developers.notion.com/) by Notion\n- [Model Context Protocol](https://modelcontextprotocol.io/) for MCP server framework\n\n---\n\n## ❓ Troubleshooting\n\n### \"NOTION_API_KEY not set\"\n\nMake sure you've run the setup script or set the credential manually:\n- Windows: `echo $env:NOTION_API_KEY`\n- macOS: `security find-generic-password -s \"gemini-notion-extension\" -a \"NOTION_API_KEY\" -w`\n- Linux: `secret-tool lookup service gemini-notion-extension account NOTION_API_KEY`\n\n### Extension Updates\n\n#### \"Extension update failed\"\n```bash\n# Force reinstall from GitHub\ngemini extensions uninstall notion-extension\ngemini extensions install https://github.com/PatelPratikkumar/gemini-notion-extension --auto-update\n```\n\n#### \"Extension is already up to date\" (but you know there's a new version)\n```bash\n# Check GitHub for latest version, then force install\ngemini extensions install https://github.com/PatelPratikkumar/gemini-notion-extension --auto-update\n```\n\n#### Local development version not updating\n```bash\ncd /path/to/gemini-notion-extension\ngit pull origin main\nnpm install\nnpm run build\n```\n\n### \"Extension not loading\"\n\n1. Rebuild: `npm run build`\n2. Relink: `gemini extensions uninstall notion-extension && gemini extensions link .`\n3. Check status: `gemini extensions list`\n\n### \"API errors\" or \"object not found\"\n\n- Verify your integration is shared with the page/database in Notion\n- Check your token at [Notion Integrations](https://www.notion.so/my-integrations)\n- Ensure token has correct capabilities (Content, Comments, User)\n\n### \"Page not accessible\"\n\n1. Open the page in Notion\n2. Click **Share** → **Add connections**\n3. Select your **Gemini CLI Extension** integration\n\n---\n\n**Made with ❤️ for productivity enthusiasts**\n",
  "bytes": 29871,
  "sha": "b3c4d5835403448cbf148b6f215d23be5545035ca9b17506107717e795299c9e",
  "repo_slug": "patelpratikkumar/gemini-notion-extension",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_patelpratikkumar_gemini_notion_extension_027bfd41/readme"
}