@roomi-fields/notebooklm-mcp 1.5.0 → 1.5.1

package/deployment/docs/01-INSTALL.md

@@ -0,0 +1,611 @@
+# Installation Guide - NotebookLM MCP HTTP Server
+
+> Complete installation from scratch on Windows 10/11
+
+---
+
+## 📋 Table of Contents
+
+1. [Prerequisites](#-prerequisites)
+2. [Node.js Installation](#-nodejs-installation)
+3. [Project Cloning](#-project-cloning)
+4. [Dependencies Installation](#-dependencies-installation)
+5. [Compilation](#-compilation)
+6. [Authentication Configuration](#-authentication-configuration)
+7. [Notebooks Configuration](#-notebooks-configuration)
+8. [Verification](#-verification)
+9. [Startup](#-startup)
+
+---
+
+## 📌 Prerequisites
+
+Before starting, you need:
+
+### Hardware
+
+- **RAM:** 2 GB minimum (4 GB recommended)
+- **Disk:** 500 MB free space
+- **Network:** Stable Internet connection
+
+### Software
+
+- **Windows 10/11** (64-bit)
+- **PowerShell 5.1+** (included in Windows)
+- **Browser:** Chrome installed (Playwright will use it)
+
+### Accounts
+
+- **Google Account** with access to https://notebooklm.google.com
+- At least **1 NotebookLM notebook** already created
+
+---
+
+## 📥 Node.js Installation
+
+### Check if Node.js is already installed
+
+```powershell
+node --version
+npm --version
+```
+
+If you see version numbers (e.g., `v20.9.0` and `10.1.0`), Node.js is installed. ✅
+If not, continue below. ⬇️
+
+### Download Node.js
+
+1. Go to https://nodejs.org/
+2. Download the **LTS** (Long Term Support) version for Windows
+3. Run the `.msi` installer
+4. Follow the installation wizard:
+   - ✅ Accept the license
+   - ✅ Standard installation (default path: `C:\Program Files\nodejs\`)
+   - ✅ Check "Automatically install the necessary tools" if offered
+
+5. Restart PowerShell and verify:
+
+```powershell
+node --version   # Should display: v20.x.x or higher
+npm --version    # Should display: 10.x.x or higher
+```
+
+---
+
+## 📂 Project Cloning
+
+### Method 1: With Git
+
+```powershell
+# Install Git if not already done: https://git-scm.com/download/win
+
+# Clone the repository
+cd D:\
+git clone https://github.com/PleasePrompto/notebooklm-mcp.git notebooklm-http
+cd notebooklm-http
+```
+
+### Method 2: ZIP Download
+
+1. Download the ZIP from GitHub
+2. Extract to `D:\notebooklm-http\`
+3. Open PowerShell in this folder
+
+---
+
+## 📦 Dependencies Installation
+
+```powershell
+# Make sure you're in the right directory
+cd D:\notebooklm-http
+
+# Install all npm dependencies
+npm install
+```
+
+**What gets installed:**
+
+- `express` - HTTP server
+- `patchright` - Stealth Playwright to automate Chrome
+- `@anthropic-ai/sdk` - MCP SDK
+- And ~50 other necessary packages
+
+**Duration:** 2-5 minutes depending on your Internet connection
+
+**Expected result:**
+
+```
+added 150 packages in 3m
+```
+
+---
+
+## 🔨 Compilation
+
+The project is written in TypeScript and must be compiled to JavaScript:
+
+```powershell
+npm run build
+```
+
+**Expected result:**
+
+```
+> notebooklm-mcp@1.1.2 build
+> tsc
+
+> notebooklm-mcp@1.1.2 postbuild
+> chmod +x dist/index.js
+
+✓ Compilation successful
+```
+
+**Verification:**
+
+```powershell
+ls dist\http-wrapper.js
+```
+
+If the file exists, compilation is OK! ✅
+
+---
+
+## 🔐 Authentication Configuration
+
+**IMPORTANT:** This step is done **ONLY ONCE**.
+Authentication will be saved and valid for ~399 days.
+
+### PowerShell Script (Recommended)
+
+**Note:** The path depends on your current directory.
+
+**If you're at the project root:**
+
+```powershell
+.\deployment\scripts\setup-auth.ps1
+```
+
+**If you're in the deployment folder:**
+
+```powershell
+.\scripts\setup-auth.ps1
+```
+
+**Or use npm (works everywhere):**
+
+```powershell
+npm run setup-auth
+```
+
+**What will happen:**
+
+1. The script checks if authentication already exists
+   - If yes: asks for confirmation to reset
+   - If no: continues directly
+
+2. Chrome opens (visible window)
+
+3. **Actions to do in Chrome:**
+   - Sign in to your Google account
+   - Go to https://notebooklm.google.com
+   - Wait for the page to load completely
+   - You should see your notebooks
+   - **Close Chrome** (click the red X)
+
+4. The script verifies that files are correctly created
+
+**Expected result:**
+
+```
+✅ Authentication configured successfully!
+💡 Google session valid for ~399 days
+
+Files created:
+  ✅ state.json created (X KB)
+  ✅ Cookies created (XXX KB)
+```
+
+### 📁 Authentication Files Location
+
+**IMPORTANT:** Authentication files are NOT stored in the project directory, but in the Windows user directory:
+
+**Full path:**
+
+```
+C:\Users\<YOUR_NAME>\AppData\Local\notebooklm-mcp\Data\
+```
+
+**File structure:**
+
+```
+C:\Users\<YOUR_NAME>\AppData\Local\notebooklm-mcp\Data\
+├── chrome_profile\           ← Complete Chrome profile (Google cookies)
+│   └── Default\
+│       └── Cookies           ← Cookies file (must be >10KB)
+│
+├── browser_state\
+│   └── state.json            ← Authentication state (16 critical cookies)
+│
+└── library.json              ← Library of configured notebooks
+```
+
+**To verify on your PC:**
+
+```powershell
+# Display the path
+echo $env:LOCALAPPDATA\notebooklm-mcp\Data
+
+# List files
+dir $env:LOCALAPPDATA\notebooklm-mcp\Data
+dir $env:LOCALAPPDATA\notebooklm-mcp\Data\chrome_profile\Default\Cookies
+dir $env:LOCALAPPDATA\notebooklm-mcp\Data\browser_state\state.json
+```
+
+**Expected files:**
+
+- `Cookies` - SQLite database (>10 KB) - **Contains your Google cookies**
+- `state.json` - JSON file with 16 critical cookies - **Valid for 399 days**
+- `library.json` - Library of your NotebookLM notebooks (created automatically)
+
+---
+
+## 📚 Notebooks Configuration
+
+Once authentication is configured, you must add at least one notebook to your library.
+
+### Option 1: Via HTTP API (Recommended)
+
+**Prerequisite:** Start the HTTP server first
+
+```powershell
+# In a first terminal
+npm run start:http
+```
+
+**In a second PowerShell terminal:**
+
+```powershell
+# Prepare notebook data
+$body = @{
+    url = "https://notebooklm.google.com/notebook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+    name = "My Notebook"
+    description = "A sample notebook"
+    topics = @("topic1", "topic2", "topic3")
+} | ConvertTo-Json
+
+# Add the notebook (automatic validation)
+Invoke-RestMethod -Uri "http://localhost:3000/notebooks" `
+    -Method Post `
+    -Body $body `
+    -ContentType "application/json"
+```
+
+**⏱️ Note:** Adding takes 15-30 seconds because the server validates that the notebook actually exists.
+
+**Automatic validations:**
+
+- ✅ NotebookLM URL format
+- ✅ Notebook actually accessible (live check)
+- ✅ No duplicate name
+- ✅ Valid Google session
+
+**How to get a notebook URL:**
+
+1. Go to https://notebooklm.google.com
+2. Open your notebook
+3. Copy the URL from the address bar
+
+Expected format: `https://notebooklm.google.com/notebook/[id]`
+
+### Option 2: Manual Modification (Advanced)
+
+Edit `library.json` directly:
+
+```powershell
+# Open the file
+code "$env:LOCALAPPDATA\notebooklm-mcp\Data\library.json"
+```
+
+**⚠️ Warning:** This method bypasses automatic validations.
+
+**Example structure:**
+
+```json
+{
+  "notebooks": [
+    {
+      "id": "my-notebook",
+      "url": "https://notebooklm.google.com/notebook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+      "name": "My Notebook",
+      "description": "A sample notebook",
+      "topics": ["topic1", "topic2", "topic3"],
+      "content_types": ["documentation", "examples"],
+      "use_cases": ["Learning about the topic"],
+      "added_at": "2025-11-22T08:49:16.735Z",
+      "last_used": "2025-11-22T08:49:16.735Z",
+      "use_count": 0,
+      "tags": []
+    }
+  ],
+  "active_notebook_id": "my-notebook",
+  "last_modified": "2025-11-22T08:49:16.735Z",
+  "version": "1.0.0"
+}
+```
+
+**Restart the server after manual modification.**
+
+### Verify Configuration
+
+```powershell
+# List configured notebooks
+Invoke-RestMethod -Uri "http://localhost:3000/notebooks"
+```
+
+**Expected result:**
+
+```json
+{
+  "success": true,
+  "data": {
+    "notebooks": [
+      {
+        "id": "my-notebook",
+        "name": "My Notebook",
+        "url": "https://notebooklm.google.com/notebook/xxx",
+        "active": true
+      }
+    ],
+    "count": 1
+  }
+}
+```
+
+**📖 For more details on notebook management, see [06-NOTEBOOK-LIBRARY.md](./06-NOTEBOOK-LIBRARY.md)**
+
+---
+
+### ⚠️ AUTHENTICATION FILES SECURITY
+
+- These files contain your **authenticated Google cookies**
+- **NEVER** share these files
+- **NEVER** commit them to Git (already protected by .gitignore)
+- To reset auth: delete the `Data\` folder and run `npm run setup-auth` again
+
+If all files are present and not empty, authentication is configured! ✅
+
+---
+
+## ✅ Verification
+
+Before starting the server, let's verify that everything is OK:
+
+### Complete Checklist
+
+```powershell
+# 1. Node.js installed
+node --version
+# ✅ Should display v20.x.x or higher
+
+# 2. Dependencies installed
+ls node_modules\express
+# ✅ The folder must exist
+
+# 3. Code compiled
+ls dist\http-wrapper.js
+# ✅ The file must exist
+
+# 4. Authentication configured
+ls Data\chrome_profile\Default\Cookies
+ls Data\browser_state\state.json
+# ✅ Both files must exist and not be empty
+
+# 5. Port 3000 free
+netstat -ano | findstr :3000
+# ✅ No result = port free
+# ❌ A result = port occupied (see TROUBLESHOOTING.md)
+```
+
+If all checks are ✅, you're ready! 🎉
+
+---
+
+## ▶️ Startup
+
+### Method 1: Foreground Mode (Development)
+
+```powershell
+npm run start:http
+```
+
+**Expected result:**
+
+```
+✅ [14:30:15] 🌐 HTTP Wrapper listening on 0.0.0.0:3000
+ℹ️  [14:30:15]    Health check: http://localhost:3000/health
+ℹ️  [14:30:15]    Ask question: POST http://localhost:3000/ask
+ℹ️  [14:30:15]    List notebooks: GET http://localhost:3000/notebooks
+
+ℹ️  [14:30:15] 📖 API Documentation:
+ℹ️  [14:30:15]    POST /ask - Ask a question to NotebookLM
+ℹ️  [14:30:15]    GET /health - Check server health
+ℹ️  [14:30:15]    GET /notebooks - List all notebooks
+```
+
+**The server is started!** 🚀
+
+⚠️ **Note:** The terminal must stay open. Press `Ctrl+C` to stop.
+
+---
+
+### Method 2: Background Daemon Mode (Production) ⭐
+
+**For production use, run the server in background without keeping the terminal open:**
+
+```powershell
+# Start server in background
+npm run daemon:start
+
+# Check status
+npm run daemon:status
+
+# View logs in real-time
+npm run daemon:logs
+
+# Stop server
+npm run daemon:stop
+```
+
+**Expected result:**
+
+```
+[PM2] App [notebooklm-mcp] launched (1 instances)
+┌────┬────────────────┬──────┬─────────┬────────┐
+│ id │ name           │ mode │ status  │ uptime │
+├────┼────────────────┼──────┼─────────┼────────┤
+│ 0  │ notebooklm-mcp │ fork │ online  │ 0s     │
+└────┴────────────────┴──────┴─────────┴────────┘
+```
+
+**Advantages of daemon mode:**
+
+- ✅ Runs in background (no terminal window)
+- ✅ Auto-restart on crash
+- ✅ Logs saved to `logs/pm2-*.log`
+- ✅ Survives terminal close
+
+**Daemon management commands:**
+
+```powershell
+npm run daemon:start    # Start server
+npm run daemon:stop     # Stop server
+npm run daemon:restart  # Restart server
+npm run daemon:logs     # View logs (Ctrl+C to exit)
+npm run daemon:status   # Check status
+npm run daemon:delete   # Remove from PM2 list
+```
+
+### Health Test
+
+Open a **new PowerShell terminal** and test:
+
+```powershell
+curl http://localhost:3000/health
+```
+
+**Expected response:**
+
+```json
+{
+  "success": true,
+  "data": {
+    "authenticated": true,
+    "sessions": 0,
+    "library_notebooks": 1,
+    "context_age_hours": 0.0
+  }
+}
+```
+
+If `"authenticated": true`, everything works! ✅
+
+### Complete Test with Question
+
+```powershell
+curl -X POST http://localhost:3000/ask `
+  -H "Content-Type: application/json" `
+  -d '{"question":"What is the main topic?","notebook_id":"my-notebook"}'
+```
+
+**Wait 30-60 seconds** (NotebookLM generation time).
+
+**Expected response:**
+
+```json
+{
+  "success": true,
+  "data": {
+    "status": "success",
+    "question": "What is the main topic?",
+    "answer": "Based on the sources, the main topic is...",
+    "session_id": "abc123",
+    "notebook_url": "https://notebooklm.google.com/notebook/...",
+    "session_info": {
+      "age_seconds": 35,
+      "message_count": 1
+    }
+  }
+}
+```
+
+If you receive a JSON response with `"success": true` and an `"answer"`, **congratulations!** 🎉
+Your NotebookLM HTTP server is operational!
+
+### Automated Tests (Recommended)
+
+For complete validation, use the test scripts:
+
+```powershell
+# Quick test (30 seconds)
+.\deployment\scripts\test-server.ps1
+
+# Complete tests (5-10 minutes)
+.\deployment\scripts\test-api.ps1
+```
+
+**Expected result:**
+
+```
+✅ ALL TESTS PASSED!
+
+Total tests: 10
+Successful tests: 10
+Failed tests: 0
+Success rate: 100%
+```
+
+**👉 Complete test documentation:** [Test Scripts](../scripts/README.md)
+
+---
+
+## 🚪 Stop the Server
+
+In the terminal where the server is running, press:
+
+```
+Ctrl + C
+```
+
+The server stops gracefully with:
+
+```
+SIGINT received, shutting down gracefully...
+```
+
+---
+
+## ➡️ Next Steps
+
+✅ Installation complete!
+
+**Now you can:**
+
+1. **[Advanced Configuration](./02-CONFIGURATION.md)** - Environment variables, firewall, security
+2. **[API Documentation](./03-API.md)** - All available endpoints
+3. **[n8n Integration](./04-N8N-INTEGRATION.md)** - Connect with n8n step-by-step
+4. **[Troubleshooting](./05-TROUBLESHOOTING.md)** - Solutions to common problems
+
+---
+
+## 🆘 Problems?
+
+If something doesn't work:
+
+1. Consult **[05-TROUBLESHOOTING.md](./05-TROUBLESHOOTING.md)**
+2. Check server logs
+3. Test with `npm run setup-auth` again
+4. Open a GitHub issue with the logs
+
+---
+
+**Congratulations! Your NotebookLM HTTP server is installed and operational! 🎉**