@roomi-fields/notebooklm-mcp 1.3.6 → 1.5.1

package/deployment/docs/11-MULTI-ACCOUNT.md

@@ -0,0 +1,295 @@
+# Multi-Account Management
+
+The NotebookLM MCP server supports multiple Google accounts with automatic rotation when rate limits are hit.
+
+## Overview
+
+NotebookLM has a **50 queries per day limit** per Google account (free tier). With multi-account support, the server can automatically switch to another account when the limit is reached, giving you up to **150 queries/day** with 3 accounts.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Account Manager                          │
+├─────────────────────────────────────────────────────────────┤
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │  Account 1   │  │  Account 2   │  │  Account 3   │      │
+│  │  (Primary)   │  │  (Secondary) │  │  (Tertiary)  │      │
+│  │  50/day      │  │  50/day      │  │  50/day      │      │
+│  └──────────────┘  └──────────────┘  └──────────────┘      │
+│                                                             │
+│  Rotation Strategy: least_used | round_robin | failover    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Configuration
+
+### Account Directory Structure
+
+Each account has its own directory under `DATA_DIR/accounts/`:
+
+```
+DATA_DIR/
+├── accounts/
+│   ├── account-{timestamp1}/
+│   │   ├── config.json      # Account configuration
+│   │   ├── quota.json       # Usage tracking
+│   │   ├── state.json       # Account state
+│   │   ├── browser_state/
+│   │   │   └── state.json   # Playwright storage state
+│   │   └── profile/         # Chrome profile directory
+│   │
+│   ├── account-{timestamp2}/
+│   │   └── ...
+│   │
+│   └── config.json          # Global accounts config
+│
+├── browser_state/
+│   └── state.json           # Active account's state
+│
+└── chrome_profile/          # Active account's Chrome profile
+```
+
+### Account Config File
+
+`accounts/account-{id}/config.json`:
+
+```json
+{
+  "id": "account-1766565732376",
+  "email": "user@gmail.com",
+  "enabled": true,
+  "priority": 1,
+  "totp_secret": "BASE32SECRET..." // Optional for 2FA
+}
+```
+
+### Quota Tracking
+
+`accounts/account-{id}/quota.json`:
+
+```json
+{
+  "used": 15,
+  "limit": 50,
+  "resetAt": "2025-12-31T00:00:00.000Z",
+  "lastUpdated": "2025-12-30T10:00:00.000Z"
+}
+```
+
+### Global Config
+
+`accounts/config.json`:
+
+```json
+{
+  "rotationStrategy": "least_used",
+  "autoRotateOnRateLimit": true,
+  "maxConsecutiveFailures": 3
+}
+```
+
+## Rotation Strategies
+
+### `least_used` (Default)
+
+Selects the account with the most remaining quota. Best for maximizing throughput.
+
+### `round_robin`
+
+Cycles through accounts in order. Best for even distribution.
+
+### `failover`
+
+Uses accounts in priority order. Only switches when current account fails.
+
+## Rate Limit Detection
+
+The server detects rate limits via:
+
+1. **Response text**: "Le système n'a pas pu répondre" (general error)
+2. **Input field**: "Vous avez atteint la limite quotidienne de discussions"
+3. **Page body**: Rate limit keywords in French/English
+
+### Detection Keywords
+
+French:
+
+- "limite quotidienne de discussions"
+- "atteint la limite quotidienne"
+- "vous avez atteint la limite"
+- "revenez plus tard"
+
+English:
+
+- "daily limit reached"
+- "rate limit exceeded"
+- "quota exhausted"
+- "too many requests"
+
+## Automatic Rotation Flow
+
+When a rate limit is detected:
+
+```
+1. Rate limit detected
+   ↓
+2. Mark current account as quota exhausted
+   ↓
+3. Close browser sessions (releases profile lock)
+   ↓
+4. Wait 2 seconds for Chrome to release files
+   ↓
+5. Select next available account (based on strategy)
+   ↓
+6. Sync new account's profile to main profile:
+   - Copy state.json → browser_state/
+   - Copy profile/ → chrome_profile/
+   ↓
+7. Retry the request with new account
+```
+
+## Adding a New Account
+
+### Via CLI
+
+```bash
+npm run accounts add
+```
+
+Follow the interactive prompts to:
+
+1. Enter email address
+2. Enter password
+3. Optionally enter TOTP secret for 2FA
+
+### Manually
+
+1. Create account directory:
+
+   ```bash
+   mkdir -p DATA_DIR/accounts/account-$(date +%s)
+   ```
+
+2. Create `config.json`:
+
+   ```json
+   {
+     "id": "account-...",
+     "email": "newaccount@gmail.com",
+     "enabled": true,
+     "priority": 2
+   }
+   ```
+
+3. Run auto-login to authenticate:
+
+   ```bash
+   npm run accounts test account-... -- --show
+   ```
+
+4. Sync to main profile if this should be the active account.
+
+## CLI Commands
+
+```bash
+# List all accounts
+npm run accounts list
+
+# Add new account
+npm run accounts add
+
+# Test account authentication
+npm run accounts test <account-id> -- --show
+
+# Remove account
+npm run accounts remove <account-id>
+```
+
+## Troubleshooting
+
+### All Accounts Exhausted
+
+If all accounts hit their daily limit:
+
+1. **Wait** until midnight UTC for quotas to reset
+2. **Manually reset** quotas for testing:
+   ```bash
+   echo '{"used": 0, "limit": 50, ...}' > accounts/account-xxx/quota.json
+   ```
+
+### Account Won't Switch
+
+Check if:
+
+1. Profile lock is released (close all Chrome instances)
+2. Account has quota remaining
+3. Account is enabled in config.json
+4. Account hasn't exceeded failure threshold
+
+### Authentication Expired
+
+Re-authenticate the account:
+
+```bash
+npm run accounts test <account-id> -- --show
+```
+
+Then sync to main profile if needed.
+
+## API Integration
+
+The `/ask` endpoint automatically handles account rotation. No changes needed to API calls.
+
+If rotation fails, the response includes:
+
+```json
+{
+  "success": false,
+  "error": "NotebookLM rate limit reached... Automatic account rotation failed..."
+}
+```
+
+## Language Switching
+
+Each account may have a different Google Account language setting. The server uses UI selectors that must match the NotebookLM language.
+
+### Automated Language Switch
+
+Use the provided script to switch an account's language:
+
+```bash
+./scripts/switch-account-language.sh --account=mathieu --lang=fr --show
+```
+
+**What it does:**
+
+1. Stops the server and Chrome
+2. Deletes the Chrome profile cache for the account
+3. Re-authenticates (opens browser for login)
+4. Syncs the new profile to main
+5. Restarts server with the correct `NOTEBOOKLM_UI_LOCALE`
+
+**Important:** The Google Account's language setting must match. Change it at:
+https://myaccount.google.com/language
+
+### Environment Variable
+
+Set the UI locale when starting the server:
+
+```bash
+NOTEBOOKLM_UI_LOCALE=en node dist/http-wrapper.js
+```
+
+See [Adding a Language](../../docs/ADDING_A_LANGUAGE.md) for details on the i18n system.
+
+---
+
+## Best Practices
+
+1. **Use 3+ accounts** for production workloads
+2. **Enable TOTP** for unattended authentication
+3. **Monitor quotas** via logs or quota.json files
+4. **Stagger usage** across accounts to avoid hitting limits simultaneously
+5. **Test rotation** before deploying to production
+6. **Match UI locale** with each account's Google language setting

package/deployment/docs/README.md

@@ -0,0 +1,207 @@
+# NotebookLM MCP HTTP Server Documentation
+
+> Complete documentation for the NotebookLM HTTP server
+
+---
+
+## 🚀 Quick Start
+
+**New to the project?** Start with the installation guide:
+
+👉 [**01-INSTALL.md**](./01-INSTALL.md) — Complete installation from scratch (Windows)
+
+---
+
+## 📚 Complete Documentation
+
+| Document                                               | Description                                 | For whom?               |
+| ------------------------------------------------------ | ------------------------------------------- | ----------------------- |
+| [**01-INSTALL.md**](./01-INSTALL.md)                   | Complete installation guide from scratch    | First installation      |
+| [**02-CONFIGURATION.md**](./02-CONFIGURATION.md)       | Environment variables, security, deployment | Advanced configuration  |
+| [**03-API.md**](./03-API.md)                           | Complete REST API reference                 | Developers, integration |
+| [**04-N8N-INTEGRATION.md**](./04-N8N-INTEGRATION.md)   | Integration guide with n8n                  | n8n users               |
+| [**05-TROUBLESHOOTING.md**](./05-TROUBLESHOOTING.md)   | Solutions to common problems                | Debugging, errors       |
+| [**06-NOTEBOOK-LIBRARY.md**](./06-NOTEBOOK-LIBRARY.md) | Multi-notebook library management           | Notebook management     |
+| [**07-AUTO-DISCOVERY.md**](./07-AUTO-DISCOVERY.md)     | Autonomous resource discovery pattern       | Auto-discovery feature  |
+| [**11-MULTI-ACCOUNT.md**](./11-MULTI-ACCOUNT.md)       | Multi-account management and rotation       | Rate limit handling     |
+| [**Test Scripts**](../scripts/README.md)               | PowerShell validation scripts               | Testing, CI/CD          |
+
+---
+
+## 🎯 Guides by Use Case
+
+### I'm getting started
+
+1. [Installation](./01-INSTALL.md) — Install Node.js, compile, authenticate
+2. [Notebook configuration](./06-NOTEBOOK-LIBRARY.md#-guide-de-d%C3%A9marrage) — Add your first notebook
+3. [Testing](./01-INSTALL.md#-v%C3%A9rification) — Verify everything works
+
+### I'm integrating with n8n
+
+1. [Installation](./01-INSTALL.md)
+2. [Network configuration](./02-CONFIGURATION.md#-s%C3%A9curit%C3%A9)
+3. [n8n integration](./04-N8N-INTEGRATION.md)
+
+### I have a problem
+
+1. [Troubleshooting](./05-TROUBLESHOOTING.md) — Common problems and solutions
+2. [Configuration](./02-CONFIGURATION.md#-troubleshooting-configuration) — Configuration issues
+
+### I want to manage multiple notebooks
+
+1. [Notebook library](./06-NOTEBOOK-LIBRARY.md) — Complete guide
+2. [Notebooks API](./03-API.md#5-add-notebook) — Management endpoints
+
+### I want to test my installation
+
+1. [Test scripts](../scripts/README.md) — Automated tests
+2. [Quick test](../scripts/README.md#-test-serverps1) — Validation in 30 seconds
+3. [Complete tests](../scripts/README.md#-test-apips1) — Full suite (10 tests)
+
+### I'm hitting rate limits
+
+1. [Multi-account setup](./11-MULTI-ACCOUNT.md) — Configure multiple accounts
+2. [Automatic rotation](./11-MULTI-ACCOUNT.md#automatic-rotation-flow) — How rotation works
+3. [Quota management](./11-MULTI-ACCOUNT.md#troubleshooting) — Reset and monitor quotas
+
+---
+
+## 📖 Quick Reference
+
+### Main Endpoints
+
+| Endpoint                   | Method | Description                           |
+| -------------------------- | ------ | ------------------------------------- |
+| `/health`                  | GET    | Check server status                   |
+| `/ask`                     | POST   | Ask a question to NotebookLM          |
+| `/notebooks`               | GET    | List notebooks                        |
+| `/notebooks`               | POST   | Add a notebook (with validation)      |
+| `/notebooks/auto-discover` | POST   | Auto-generate notebook metadata       |
+| `/notebooks/:id`           | DELETE | Delete a notebook                     |
+| `/notebooks/:id/activate`  | PUT    | Activate a notebook                   |
+| `/content/sources`         | POST   | Add source to notebook                |
+| `/content/generate`        | POST   | Generate content (audio, video, etc.) |
+| `/content/download`        | GET    | Download/export generated content     |
+
+**👉 [Complete API reference](./03-API.md)**
+
+### Useful Scripts
+
+| Command                                | Description                              |
+| -------------------------------------- | ---------------------------------------- |
+| `npm run build`                        | Compile TypeScript                       |
+| `npm run start:http`                   | Start HTTP server (foreground)           |
+| `npm run daemon:start`                 | Start server in background (daemon mode) |
+| `npm run daemon:stop`                  | Stop background server                   |
+| `npm run daemon:logs`                  | View background server logs              |
+| `npm run daemon:status`                | Check daemon status                      |
+| `npm run dev:http`                     | Development mode (auto-reload)           |
+| `npm run setup-auth`                   | Configure Google authentication          |
+| `.\deployment\scripts\setup-auth.ps1`  | PowerShell authentication script         |
+| `.\deployment\scripts\test-server.ps1` | Quick tests (3 tests, 30s)               |
+| `.\deployment\scripts\test-api.ps1`    | Complete tests (10 tests, 5-10min)       |
+| `.\deployment\scripts\test-errors.ps1` | Error case tests (12 tests)              |
+
+### Important Files
+
+| File           | Location                                                     | Description          |
+| -------------- | ------------------------------------------------------------ | -------------------- |
+| `state.json`   | `%LOCALAPPDATA%\notebooklm-mcp\Data\browser_state\`          | Authentication state |
+| `Cookies`      | `%LOCALAPPDATA%\notebooklm-mcp\Data\chrome_profile\Default\` | Google cookies       |
+| `library.json` | `%LOCALAPPDATA%\notebooklm-mcp\Data\`                        | Notebook library     |
+
+---
+
+## 🆘 Need Help?
+
+### Common Problems
+
+**Server won't start**
+→ [Troubleshooting - EADDRINUSE](./05-TROUBLESHOOTING.md#probl%C3%A8me-eaddrinuse-address-already-in-use)
+
+**Authentication fails**
+→ [Troubleshooting - Authentication](./05-TROUBLESHOOTING.md#probl%C3%A8me-authentication-failed)
+
+**Invalid notebook**
+→ [Notebook Library - Validation](./06-NOTEBOOK-LIBRARY.md#-validations-automatiques)
+
+**n8n cannot connect**
+→ [Configuration - Firewall](./02-CONFIGURATION.md#2-firewall-windows)
+
+### External Documentation
+
+- [NotebookLM](https://notebooklm.google.com) — Official Google service
+- [n8n](https://n8n.io) — Automation platform
+- [Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright) — Stealth browser automation
+- [Model Context Protocol](https://modelcontextprotocol.io/) — MCP specification
+
+---
+
+## Changelog
+
+### v1.4.2 (2025-12-29)
+
+**Removed fake content generation:**
+
+- Removed `generate_content` endpoint for FAQ, Study Guide, Briefing Doc, Timeline, TOC
+- These were NOT real NotebookLM features - just chat prompts
+- Only REAL content generation: Audio Overview (podcast)
+- Updated all documentation for honesty
+
+### v1.4.0 (2025-12-24)
+
+**Content Management:**
+
+- Audio Overview generation (podcast) - REAL NotebookLM feature
+- Audio download
+- Source management (files, URLs, text, YouTube)
+
+### v1.3.1 (2025-01-24)
+
+**New features:**
+
+- MCP Auto-Discovery Tool: `auto_discover_notebook` for Claude Desktop/Cursor
+- Parity with HTTP API: MCP clients now have auto-discovery capability
+- Zero-friction notebook addition: just URL, metadata auto-generated
+
+**Critical Fixes:**
+
+- Claude Desktop compatibility: Disabled `CompleteRequestSchema` handler
+- Fixed "Server does not support completions" error on connection
+
+### v1.1.2 (2025-11-22)
+
+**New features:**
+
+- ✅ Multi-notebook library system
+- ✅ Live validation of notebooks when adding
+- ✅ Protection against duplicate names
+- ✅ DELETE and PUT endpoints for notebooks
+- ✅ Detailed and contextualized error messages
+
+**Fixes:**
+
+- ✅ Fixed Cookies path (Default/Network/Cookies)
+- ✅ Cookies threshold lowered to 10KB
+- ✅ Better temporary session management
+
+**Documentation:**
+
+- ✅ New guide [06-NOTEBOOK-LIBRARY.md](./06-NOTEBOOK-LIBRARY.md)
+- ✅ "Notebook Configuration" section in [01-INSTALL.md](./01-INSTALL.md)
+- ✅ Enhanced API in [03-API.md](./03-API.md)
+
+---
+
+## 📝 Contributing
+
+Found an error in the documentation? An unclear section?
+
+**Open an issue:** [GitHub Issues](https://github.com/roomi-fields/notebooklm-mcp/issues)
+
+Or directly propose a PR to improve the documentation!
+
+---
+
+**Documentation updated:** 2025-12-29
+**Version:** 1.4.2