@roomi-fields/notebooklm-mcp 1.5.0 → 1.5.1

package/deployment/docs/07-AUTO-DISCOVERY.md

@@ -0,0 +1,236 @@
+# Auto-Discovery Pattern
+
+## Overview
+
+Auto-Discovery enables autonomous resource discovery for AI orchestrators. Instead of manually cataloging notebooks, the system queries NotebookLM to generate its own metadata.
+
+## Architecture
+
+### Three-Level Progressive Disclosure
+
+**Level 0 - Metadata Registry (Lightweight)**
+
+```
+library.json: 5KB for 50 notebooks
+├── Loaded at startup
+├── Cached in memory
+└── Zero NotebookLM queries
+```
+
+**Level 1 - Contextual Matching (Local)**
+
+```
+User query → Tag/description matching → Relevant notebooks
+Example: "gmail automation" → Match tags: ["gmail", "n8n", "automation"]
+Cost: 0 NotebookLM queries (local only)
+```
+
+**Level 2 - Deep Query (Rate-Limited)**
+
+```
+Selected notebook → Query NotebookLM → Precise answer
+Cost: 1 NotebookLM query (rate-limited by Google)
+```
+
+## For Orchestrators
+
+### Claude Code
+
+```typescript
+// Autonomous workflow
+User: "Build n8n Gmail workflow"
+
+// Claude internally:
+1. Scan library metadata (instant)
+2. Match: "n8n-workflows-api" (tags: ["n8n", "gmail"])
+3. Query NotebookLM: "Gmail node configuration?"
+4. Implement with accurate info
+```
+
+### n8n
+
+```yaml
+# Workflow node
+HTTP Request: GET /notebooks/match?task=gmail automation
+→ Returns: relevant notebook
+
+HTTP Request: POST /notebooks/{id}/ask
+→ Query: "Available Gmail triggers?"
+→ Response: precise documentation
+```
+
+### Cursor / IDEs
+
+```typescript
+// Context-aware matching
+Developer: "How to use n8n API?"
+→ MCP: find_relevant_notebook({ task: "n8n API" })
+→ Match: "n8n-workflows-api"
+→ Query notebook for details
+```
+
+## Metadata Generation
+
+### Prompt to NotebookLM
+
+The system sends this prompt to each notebook:
+
+```
+Analyze your complete content and respond ONLY in JSON format:
+{
+  "name": "kebab-case-name",
+  "description": "Two sentences max.",
+  "tags": ["8-10", "keywords", "covering", "concepts", "actions", "contexts"]
+}
+```
+
+### Validation Rules
+
+- **name**: 3 words max, kebab-case, no spaces
+- **description**: 2 sentences, under 150 chars
+- **tags**: 8-10 keywords (concepts + actions + contexts)
+
+### Example Generated Metadata
+
+```json
+{
+  "name": "n8n-workflows-api",
+  "description": "Complete n8n API documentation covering workflow creation and node configuration. Includes authentication, webhooks, and error handling.",
+  "tags": [
+    "n8n",
+    "api",
+    "workflows",
+    "automation",
+    "webhooks",
+    "nodes",
+    "integration",
+    "documentation"
+  ]
+}
+```
+
+## Benefits
+
+### For Users
+
+- **Zero friction**: 30 seconds to add notebook (vs 5 minutes manual)
+- **No metadata expertise**: System generates relevant tags automatically
+- **Scalable**: Works with 1 or 100 notebooks
+
+### For Orchestrators
+
+- **Autonomous discovery**: Find relevant docs without human guidance
+- **Token efficient**: Metadata scan costs ~500 tokens (vs 50k+ full read)
+- **Rate limit preservation**: 1 query per notebook add (vs N queries per research)
+
+### For Product
+
+- **Enhanced experience**: Auto-discovery enables frictionless notebook management
+- **Scalable architecture**: Handles growing documentation libraries efficiently
+- **Progressive disclosure**: Optimizes API usage and response times
+
+## Comparison with Claude Skills
+
+| Aspect            | Claude Skills            | NotebookLM Auto-Discovery |
+| ----------------- | ------------------------ | ------------------------- |
+| Metadata source   | SKILL.md file            | NotebookLM query          |
+| Access cost       | Free (local files)       | Rate-limited (Google API) |
+| Content depth     | Full docs bundled        | Query on-demand           |
+| Discovery pattern | Read files progressively | Match → Query if needed   |
+| Update mechanism  | Edit files               | Re-query notebook         |
+
+**Key difference**: Skills are free/local, Notebooks are rate-limited/remote
+→ **Auto-Discovery optimizes for minimal queries via smart metadata matching**
+
+## Error Handling
+
+### Common Issues
+
+**Invalid metadata format**:
+
+```json
+{
+  "error": "Invalid name format",
+  "details": "Must be kebab-case, 3 words max"
+}
+```
+
+→ System retries with same prompt (max 2 retries)
+
+**NotebookLM timeout**:
+
+```json
+{
+  "error": "NotebookLM query timeout",
+  "hint": "Try again in a few seconds"
+}
+```
+
+→ Rate limit hit, wait and retry
+
+**Notebook not accessible**:
+
+```json
+{
+  "error": "Notebook not found",
+  "hint": "Check notebook URL and sharing settings"
+}
+```
+
+→ Verify notebook is shared with "Anyone with link"
+
+## Testing
+
+### Public Test Notebooks
+
+The following public notebooks are available for testing auto-discovery:
+
+```bash
+# Test with PowerShell script (all notebooks)
+.\deployment\scripts\test-auto-discovery.ps1 -TestAll
+
+# Test with specific notebook
+.\deployment\scripts\test-auto-discovery.ps1 -NotebookUrl "https://notebooklm.google.com/notebook/0d5cd576-2583-4835-8848-a5b7b6a97cea"
+```
+
+**Available public notebooks**:
+
+1. `https://notebooklm.google.com/notebook/0d5cd576-2583-4835-8848-a5b7b6a97cea`
+2. `https://notebooklm.google.com/notebook/505ee4b1-ad05-4673-a06b-1ec106c2b940`
+3. `https://notebooklm.google.com/notebook/a09e40ad-d41f-43af-a3ca-5fc82bd459e5`
+4. `https://notebooklm.google.com/notebook/19bde485-a9c1-4809-8884-e872b2b67b44`
+5. `https://notebooklm.google.com/notebook/19fdf6bd-1975-40a3-9801-c554130bc64a`
+
+### Expected Results
+
+Each auto-discovery test should:
+
+- ✅ Return 200 OK
+- ✅ Generate valid kebab-case name (1-3 words)
+- ✅ Generate description ≤150 chars
+- ✅ Generate 8-10 relevant topics
+- ✅ Set `auto_generated: true`
+- ✅ Add notebook to library automatically
+
+## Future Enhancements
+
+### Phase 2: Smart Refresh
+
+```typescript
+PATCH /notebooks/:id/refresh
+→ Re-query NotebookLM to update metadata if content changed
+```
+
+### Phase 3: Semantic Matching
+
+```typescript
+GET /notebooks/match?query=gmail&semantic=true
+→ Use embeddings for advanced matching beyond tags
+```
+
+### Phase 4: Usage Analytics
+
+```typescript
+GET /notebooks/:id/related
+→ "Notebooks often queried together"
+```

package/deployment/docs/08-WSL-USAGE.md

@@ -0,0 +1,363 @@
+# WSL Usage Guide
+
+This guide explains how to use the NotebookLM MCP Server with Claude Code from WSL (Windows Subsystem for Linux).
+
+## Architecture Overview
+
+Due to browser requirements (Playwright needs Chrome), the HTTP server must run on **Windows**. Claude Code in WSL communicates with it through a stdio-HTTP proxy.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         WINDOWS                                  │
+│  ┌─────────────────────┐    ┌─────────────────────────────┐     │
+│  │  HTTP Server        │    │       Chrome Browser        │     │
+│  │  (node.exe)         │◄──►│   (Playwright-controlled)   │     │
+│  │  localhost:3000     │    │                             │     │
+│  └─────────────────────┘    └─────────────────────────────┘     │
+│            ▲                                                     │
+└────────────┼─────────────────────────────────────────────────────┘
+             │ HTTP (localhost:3000)
+┌────────────┼─────────────────────────────────────────────────────┐
+│            │                  WSL                                │
+│  ┌─────────┴───────────────────────────────────────────────────┐│
+│  │  Claude Code                                                ││
+│  │  └── stdio-http-proxy.js (node.exe)                         ││
+│  │      - Translates MCP stdio ←→ HTTP calls                   ││
+│  │      - Points to localhost:3000                             ││
+│  └─────────────────────────────────────────────────────────────┘│
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Quick Start
+
+### 1. Start the HTTP Server on Windows
+
+**CRITICAL: The HTTP server MUST run on Windows, NOT in WSL**
+
+Open a **Windows terminal** (PowerShell or CMD, not WSL):
+
+```powershell
+cd D:\Claude\notebooklm-mcp-http
+npm run start:http
+```
+
+**Verification:** The logs must show Windows paths:
+
+```
+Chrome Profile: C:\Users\...\AppData\Local\notebooklm-mcp\Data\chrome_profile
+Listening on 0.0.0.0:3000
+```
+
+If you see `/opt/google/chrome/chrome` in error messages, the server is running under WSL, not Windows!
+
+### 2. Configure MCP in Your Project
+
+Create `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "notebooklm": {
+      "type": "stdio",
+      "command": "node.exe",
+      "args": ["D:\\Claude\\notebooklm-mcp-http\\dist\\stdio-http-proxy.js"],
+      "env": {
+        "NOTEBOOKLM_HTTP_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+**Important:** Use `stdio-http-proxy.js` (NOT `index.js`)
+
+### 3. Enable the MCP Server
+
+The first time you use it, Claude Code needs to trust the `.mcp.json` servers. Either:
+
+- Restart Claude Code and accept when prompted
+- Or manually add to `~/.claude.json` in your project section:
+
+```json
+"enabledMcpjsonServers": ["notebooklm"],
+"hasTrustDialogAccepted": true,
+```
+
+### 4. Verify Configuration
+
+```bash
+# In Claude Code, run:
+/mcp
+```
+
+You should see `notebooklm` listed and connected.
+
+### 5. Authenticate (First Time)
+
+Ask Claude to authenticate:
+
+> "Log me in to NotebookLM"
+
+This opens Chrome on Windows for Google authentication.
+
+## Available MCP Tools
+
+| Tool                | Description                        |
+| ------------------- | ---------------------------------- |
+| `ask_question`      | Ask a question to a notebook       |
+| `list_notebooks`    | List all available notebooks       |
+| `get_health`        | Check server health status         |
+| `search_notebooks`  | Search notebooks by keyword        |
+| `get_notebook`      | Get details of a specific notebook |
+| `add_notebook`      | Add a new notebook to the library  |
+| `activate_notebook` | Set a notebook as the default      |
+
+Example usage:
+
+```
+mcp__notebooklm__ask_question(question="...", notebook_id="my-notebook")
+```
+
+## Troubleshooting
+
+### Error: "Chrome not found at /opt/google/chrome/chrome"
+
+**Cause:** The HTTP server is running under WSL instead of Windows.
+
+**Solution:**
+
+```powershell
+# From Windows (not WSL):
+taskkill /F /IM node.exe
+cd D:\Claude\notebooklm-mcp-http
+npm run start:http
+```
+
+### Check which process is listening on port 3000
+
+```powershell
+netstat -ano | findstr :3000
+```
+
+If multiple processes are listed, there may be conflicts. Kill the unwanted ones:
+
+```powershell
+taskkill /F /PID <pid_to_kill>
+```
+
+### Test that the server works (from Windows)
+
+```powershell
+curl http://localhost:3000/health
+```
+
+Should return: `{"success":true,"data":{"status":"ok",...}}`
+
+### MCP shows "Not connected"
+
+1. Ensure the HTTP server is running on Windows
+2. Restart Claude Code after starting the HTTP server
+3. Check that `.mcp.json` uses `stdio-http-proxy.js` (not `index.js`)
+
+### Port 3000 already in use
+
+Kill all node processes and restart:
+
+```powershell
+taskkill /F /IM node.exe
+cd D:\Claude\notebooklm-mcp-http
+npm run start:http
+```
+
+### Authentication expired
+
+Ask Claude: "Check NotebookLM health" or "Re-authenticate to NotebookLM"
+
+### Chrome profile locked
+
+Close all Chrome windows and restart:
+
+```powershell
+taskkill /IM chrome.exe /F
+```
+
+Then restart the HTTP server.
+
+## Configuration Reference
+
+### Project-Level Config (`.mcp.json`)
+
+Shareable via git, stored in project root:
+
+```json
+{
+  "mcpServers": {
+    "notebooklm": {
+      "type": "stdio",
+      "command": "node.exe",
+      "args": ["D:\\Claude\\notebooklm-mcp-http\\dist\\stdio-http-proxy.js"],
+      "env": {
+        "NOTEBOOKLM_HTTP_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+### Local Config (`~/.claude.json`)
+
+Private to you, per-project settings in the `projects` section:
+
+```json
+"/mnt/d/Claude/your-project": {
+  "mcpServers": {
+    "notebooklm": {
+      "type": "stdio",
+      "command": "node.exe",
+      "args": ["D:\\Claude\\notebooklm-mcp-http\\dist\\stdio-http-proxy.js"],
+      "env": {
+        "NOTEBOOKLM_HTTP_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+### Key Points
+
+- Use `node.exe` (Windows) not `node` (Linux)
+- Use Windows paths with double backslashes: `D:\\Claude\\...`
+- Use `stdio-http-proxy.js` to connect to the HTTP server
+- The HTTP server must be started separately on Windows
+- The `.mcp.json` servers must be enabled via `enabledMcpjsonServers`
+
+## Data Sharing Between WSL and Windows
+
+The server stores authentication and data in:
+
+- **Windows**: `C:\Users\<user>\AppData\Local\notebooklm-mcp\Data\`
+- **WSL symlink**: `~/.local/share/notebooklm-mcp` → Windows path
+
+This symlink ensures both environments share the same authentication state.
+
+To create the symlink (if not already done):
+
+```bash
+rm -rf ~/.local/share/notebooklm-mcp
+ln -sf /mnt/c/Users/<user>/AppData/Local/notebooklm-mcp/Data ~/.local/share/notebooklm-mcp
+```
+
+## Helper Scripts (Windows)
+
+The project includes PowerShell scripts for managing the server:
+
+```powershell
+# Start server with auto-restart
+.\scripts\start-server.ps1
+
+# Stop server
+.\scripts\stop-server.ps1
+
+# Check server status
+.\scripts\check-server.ps1
+```
+
+### Run in Background (Hidden Window)
+
+```powershell
+Start-Process powershell -ArgumentList "-ExecutionPolicy Bypass -File D:\Claude\notebooklm-mcp-http\scripts\start-server.ps1" -WindowStyle Hidden
+```
+
+### Windows Task Scheduler (Auto-start on Login)
+
+1. Open Task Scheduler (`taskschd.msc`)
+2. Create Basic Task: "NotebookLM MCP Server"
+3. Trigger: "When I log on"
+4. Action: Start a program
+   - Program: `powershell.exe`
+   - Arguments: `-ExecutionPolicy Bypass -WindowStyle Hidden -File "D:\Claude\notebooklm-mcp-http\scripts\start-server.ps1"`
+5. Check "Open Properties dialog" and set "Run whether user is logged on or not"
+
+## Authentication Procedure (TOTP/2FA)
+
+If authentication expires, follow this procedure **from Windows**:
+
+### Step 1: Kill existing processes
+
+```powershell
+taskkill /F /IM chrome.exe
+taskkill /F /IM node.exe
+```
+
+### Step 2: Run accounts test with visible browser
+
+```powershell
+cd D:\Claude\notebooklm-mcp-http
+npm run accounts test account-XXXXXXXXXXXXX -- --show
+```
+
+This will:
+
+- Open Chrome with the account profile
+- Auto-login with email/password/TOTP
+- Navigate to NotebookLM home page
+- Save authentication state
+
+**Note:** "TOTP input field not found" is OK if Google skips 2FA (trusted device).
+
+### Step 3: Sync profile to main location
+
+```powershell
+# From PowerShell or WSL:
+copy C:\Users\USERNAME\AppData\Local\notebooklm-mcp\Data\accounts\account-XXXXXXXXXXXXX\browser_state\* C:\Users\USERNAME\AppData\Local\notebooklm-mcp\Data\browser_state\
+```
+
+Or from WSL:
+
+```bash
+cp /mnt/c/Users/USERNAME/AppData/Local/notebooklm-mcp/Data/accounts/account-*/browser_state/* /mnt/c/Users/USERNAME/AppData/Local/notebooklm-mcp/Data/browser_state/
+```
+
+### Step 4: Start HTTP server
+
+```powershell
+cd D:\Claude\notebooklm-mcp-http
+npm run start:http
+```
+
+## Quick Test Commands (from WSL)
+
+```bash
+# Start server on Windows (from WSL)
+cmd.exe /c "cd /d D:\\Claude\\notebooklm-mcp-http && start /B node dist/http-wrapper.js"
+
+# Check health (from WSL via Windows curl)
+cmd.exe /c "curl http://localhost:3000/health"
+
+# Ask a question
+cmd.exe /c 'curl -s -X POST http://localhost:3000/ask -H "Content-Type: application/json" -d "{\"question\": \"Test\", \"notebook_id\": \"notebook-1\"}"'
+```
+
+## Available Notebooks
+
+| ID         | Name               | URL                                    | Topics         |
+| ---------- | ------------------ | -------------------------------------- | -------------- |
+| notebook-1 | Example Notebook 1 | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | topic1, topic2 |
+| notebook-2 | Example Notebook 2 | `yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy` | topic3, topic4 |
+
+> **Note:** Replace these with your actual notebook UUIDs from NotebookLM.
+
+## IMPORTANT: Never Run Under WSL
+
+The HTTP server must ALWAYS run on Windows native, never under WSL.
+
+**Why?**
+
+- Playwright/Chrome requires Windows Chrome, not Linux Chrome
+- WSL Chrome path (`/opt/google/chrome/chrome`) doesn't exist
+- Running under WSL will cause: `Chromium distribution 'chrome' is not found`
+
+**How to verify the server is on Windows:**
+
+1. The startup logs should show Windows paths: `C:\Users\...\AppData\...`
+2. Run `.\scripts\check-server.ps1` from PowerShell