@roomi-fields/notebooklm-mcp 1.5.0 → 1.5.1

package/deployment/docs/09-MULTI-INTERFACE.md

@@ -0,0 +1,293 @@
+# Multi-Interface Mode (v1.3.6+)
+
+> Run Claude Desktop AND HTTP API simultaneously with a single Chrome instance
+
+---
+
+## Overview
+
+The **Stdio-HTTP Proxy** enables Claude Desktop to communicate with the HTTP server, solving the Chrome profile locking issue without requiring separate browser profiles.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        ARCHITECTURE                              │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  Claude Desktop ─────► Stdio-HTTP Proxy ────┐                   │
+│                        (no Chrome)          │                   │
+│                                             ▼                   │
+│  n8n / Zapier ──────────────────────► HTTP Server ──► Chrome    │
+│                                             │                   │
+│  curl / Postman ────────────────────────────┘                   │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Benefits:**
+
+- ✅ Single Chrome instance (no profile conflicts)
+- ✅ Shared authentication state
+- ✅ Claude Desktop + HTTP API running simultaneously
+- ✅ No additional disk space for separate profiles
+
+---
+
+## Quick Start
+
+### Step 1: Start the HTTP Server
+
+> **⚠️ CRITICAL: The HTTP server MUST run on Windows (not WSL)**
+>
+> The server uses Playwright to control Chrome. If you run the server from WSL,
+> it will look for Chrome at Linux paths (`/opt/google/chrome/chrome`) instead
+> of Windows paths and **will fail**.
+>
+> Always start the HTTP server from **PowerShell** or **CMD**, not from WSL bash.
+
+**From PowerShell (recommended):**
+
+```powershell
+cd D:\Claude\notebooklm-mcp-http
+
+# Build if needed
+npm run build
+
+# Start HTTP server (foreground)
+node dist/http-wrapper.js
+
+# Or in background (survives terminal close):
+Start-Process -NoNewWindow node -ArgumentList "dist/http-wrapper.js"
+```
+
+**From WSL (recommended - use helper script):**
+
+```bash
+# Helper script handles everything correctly
+HELPER=/mnt/d/Claude/notebooklm-mcp-http/scripts/mcp-wsl-helper.sh
+
+$HELPER start      # Start server (Windows process)
+$HELPER health     # Check health
+$HELPER auth       # Authenticate (opens Chrome)
+$HELPER ask "question" notebook-id  # Ask a question
+$HELPER stop       # Stop server
+```
+
+**From WSL (manual - launches Windows node process):**
+
+```bash
+# This launches node.exe on Windows, NOT node in WSL
+powershell.exe -Command "Start-Process -NoNewWindow -FilePath 'node' -ArgumentList 'D:/Claude/notebooklm-mcp-http/dist/http-wrapper.js' -WorkingDirectory 'D:/Claude/notebooklm-mcp-http'"
+```
+
+### Step 2: Configure Claude Desktop
+
+Edit your Claude Desktop config file:
+
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "notebooklm": {
+      "command": "node",
+      "args": ["D:/Claude/notebooklm-mcp-http/dist/stdio-http-proxy.js"],
+      "env": {
+        "MCP_HTTP_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+> **Note:** Replace the path with your actual installation path.
+
+### Step 3: Restart Claude Desktop
+
+Close and reopen Claude Desktop. The proxy will connect to your HTTP server.
+
+---
+
+## Configuration Options
+
+### Environment Variables
+
+| Variable       | Default                 | Description          |
+| -------------- | ----------------------- | -------------------- |
+| `MCP_HTTP_URL` | `http://localhost:3000` | HTTP server URL      |
+| `HTTP_PORT`    | `3000`                  | Port for HTTP server |
+| `HTTP_HOST`    | `0.0.0.0`               | Host for HTTP server |
+
+### Custom Port Example
+
+```bash
+# Terminal 1: HTTP server on port 4000
+HTTP_PORT=4000 npm run start:http
+
+# Claude Desktop config
+{
+  "mcpServers": {
+    "notebooklm": {
+      "command": "node",
+      "args": ["/path/to/dist/stdio-http-proxy.js"],
+      "env": {
+        "MCP_HTTP_URL": "http://localhost:4000"
+      }
+    }
+  }
+}
+```
+
+---
+
+## NPM Scripts
+
+| Script         | Description                      |
+| -------------- | -------------------------------- |
+| `start:http`   | Start HTTP server (foreground)   |
+| `start:proxy`  | Start stdio proxy (for testing)  |
+| `daemon:start` | Start HTTP server as PM2 daemon  |
+| `daemon:stop`  | Stop PM2 daemon                  |
+| `daemon:logs`  | View daemon logs                 |
+| `dev:http`     | Development mode with hot reload |
+| `dev:proxy`    | Development mode for proxy       |
+
+---
+
+## Usage Scenarios
+
+### Scenario 1: Claude Desktop Only (via Proxy)
+
+```bash
+# Start HTTP server
+npm run daemon:start
+
+# Configure Claude Desktop with proxy (see above)
+# Use Claude Desktop normally
+```
+
+### Scenario 2: HTTP API Only (n8n, Zapier)
+
+```bash
+# Start HTTP server
+npm run start:http
+
+# Use HTTP API
+curl -X POST http://localhost:3000/ask \
+  -H "Content-Type: application/json" \
+  -d '{"question": "What is X?", "notebook_id": "my-notebook"}'
+```
+
+### Scenario 3: Both Simultaneously
+
+```bash
+# Terminal 1: HTTP server (owns Chrome)
+npm run daemon:start
+
+# Claude Desktop: uses proxy (configured above)
+# n8n/Zapier: uses HTTP API directly
+# Both work simultaneously!
+```
+
+---
+
+## Troubleshooting
+
+### Proxy can't connect to HTTP server
+
+```
+Cannot connect to HTTP server at http://localhost:3000
+```
+
+**Solution:** Ensure HTTP server is running:
+
+```bash
+npm run daemon:status  # Check if running
+npm run daemon:start   # Start if not
+```
+
+### Authentication issues
+
+The HTTP server manages authentication. If you need to re-authenticate:
+
+```bash
+# Via HTTP API
+curl -X POST http://localhost:3000/setup-auth
+
+# Or use Claude Desktop (via proxy)
+# Ask: "Setup NotebookLM authentication"
+```
+
+### WSL Users - Chrome not found
+
+```
+Error: Playwright cannot find Chrome at /opt/google/chrome/chrome
+```
+
+**This means you started the HTTP server from WSL instead of Windows.**
+
+The HTTP server MUST run as a Windows process to access Chrome. Fix:
+
+```bash
+# Use the helper script (recommended)
+HELPER=/mnt/d/Claude/notebooklm-mcp-http/scripts/mcp-wsl-helper.sh
+
+# 1. Stop any running server
+$HELPER stop
+
+# 2. Start server (launches Windows process)
+$HELPER start
+
+# 3. Verify it works
+$HELPER health
+```
+
+**Or manually:**
+
+```bash
+# 1. Kill any WSL server
+pkill -f http-wrapper
+
+# 2. Start as Windows process
+powershell.exe -Command "Start-Process -NoNewWindow -FilePath 'node' -ArgumentList 'D:/Claude/notebooklm-mcp-http/dist/http-wrapper.js' -WorkingDirectory 'D:/Claude/notebooklm-mcp-http'"
+
+# 3. Verify (via PowerShell, not curl from WSL)
+powershell.exe -Command "Invoke-RestMethod -Uri 'http://localhost:3000/health'"
+```
+
+> **Note:** `curl` from WSL may not reach Windows localhost due to network isolation.
+> Always use `powershell.exe` or the helper script.
+
+---
+
+## Comparison: Proxy vs Native Stdio
+
+| Feature              | Native Stdio       | Stdio-HTTP Proxy     |
+| -------------------- | ------------------ | -------------------- |
+| Chrome instance      | Own instance       | Uses HTTP server's   |
+| Run with HTTP server | ❌ Chrome conflict | ✅ Works             |
+| Authentication       | Own profile        | Shared with HTTP     |
+| Dependencies         | Full (Playwright)  | Minimal (fetch only) |
+| Latency              | Direct             | +1 HTTP hop          |
+| Use case             | Standalone         | Multi-interface      |
+
+---
+
+## Future: Multi-Profile Mode (v1.4.0)
+
+The multi-profile feature (separate Chrome profiles per mode) is planned for v1.4.0 but is a **separate feature** from multi-interface:
+
+- **Multi-Interface (v1.3.6):** Single Chrome, multiple clients via proxy
+- **Multi-Profile (v1.4.0):** Multiple Chrome profiles for independent auth
+
+Most users should use the proxy approach for simplicity.
+
+---
+
+## See Also
+
+- [Installation Guide](./01-INSTALL.md)
+- [API Reference](./03-API.md)
+- [Chrome Limitation](../../docs/CHROME_PROFILE_LIMITATION.md)
+- [WSL Usage](./08-WSL-USAGE.md)

package/deployment/docs/10-CONTENT-MANAGEMENT.md

@@ -0,0 +1,421 @@
+# Content Management - NotebookLM MCP
+
+> Add sources and generate audio overviews (podcasts)
+
+---
+
+## Overview
+
+The Content Management module enables you to:
+
+1. **Add Sources** - Upload documents, URLs, text, YouTube videos to notebooks
+2. **Delete Sources** - Remove sources from notebooks
+3. **Generate Audio Overview** - Create podcast-style audio discussions (REAL NotebookLM feature)
+4. **Download Audio** - Save generated audio files locally
+5. **Create Notes** - Add user-created annotations to notebooks
+6. **List Content** - View sources and generated content
+
+---
+
+## Important: What We Actually Support
+
+**REAL NotebookLM Features (fully integrated):**
+
+- Audio Overview generation - Uses NotebookLM's actual podcast feature
+- Audio download - Downloads the real generated audio file
+- Source management - Add files, URLs, text, YouTube videos
+- Q&A with citations - Uses NotebookLM's actual chat
+
+**NOT Supported (removed in v1.4.2):**
+
+The following were removed because they were NOT real NotebookLM integrations. They were just sending prompts to the chat, which you can do yourself with `ask_question`:
+
+- ~~Briefing Doc~~ - Just asked chat to generate a summary
+- ~~Study Guide~~ - Just asked chat to create study materials
+- ~~FAQ~~ - Just asked chat to generate FAQs
+- ~~Timeline~~ - Just asked chat to create a timeline
+- ~~Table of Contents~~ - Just asked chat to create a TOC
+
+If you need these, simply use `ask_question` with your own prompt like "Create a study guide" or "Generate an FAQ".
+
+---
+
+## Quick Start
+
+### Add a URL Source
+
+```bash
+curl -X POST http://localhost:3000/content/sources \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source_type": "url",
+    "url": "https://example.com/article"
+  }'
+```
+
+### Generate Audio Overview
+
+```bash
+curl -X POST http://localhost:3000/content/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content_type": "audio_overview",
+    "custom_instructions": "Focus on practical tips"
+  }'
+```
+
+### Download Audio
+
+```bash
+curl "http://localhost:3000/content/download?content_type=audio_overview"
+```
+
+---
+
+## Source Types
+
+| Type           | Description                 | Required Field |
+| -------------- | --------------------------- | -------------- |
+| `file`         | Local file upload           | `file_path`    |
+| `url`          | Web page URL                | `url`          |
+| `text`         | Plain text / pasted content | `text`         |
+| `youtube`      | YouTube video URL           | `url`          |
+| `google_drive` | Google Drive document link  | `url`          |
+
+### Examples
+
+**Upload a local file:**
+
+```bash
+curl -X POST http://localhost:3000/content/sources \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source_type": "file",
+    "file_path": "/path/to/document.pdf",
+    "title": "My PDF Document"
+  }'
+```
+
+**Add pasted text:**
+
+```bash
+curl -X POST http://localhost:3000/content/sources \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source_type": "text",
+    "text": "Your document content here...",
+    "title": "Research Notes"
+  }'
+```
+
+**Add YouTube video:**
+
+```bash
+curl -X POST http://localhost:3000/content/sources \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source_type": "youtube",
+    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+  }'
+```
+
+---
+
+## Deleting Sources
+
+Remove sources from notebooks using the delete endpoint.
+
+### Delete by ID
+
+```bash
+curl -X DELETE "http://localhost:3000/content/sources/source-123"
+```
+
+### Delete by Name
+
+```bash
+curl -X DELETE "http://localhost:3000/content/sources?source_name=My%20Document"
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "data": {
+    "success": true,
+    "sourceId": "source-123",
+    "sourceName": "My Document"
+  }
+}
+```
+
+**Notes:**
+
+- Use `list_content` first to find source IDs and names
+- Source names support partial matching (case-insensitive)
+- This action is irreversible - sources are permanently deleted
+
+---
+
+## Audio Overview (Podcast)
+
+The audio overview creates a podcast-style discussion between two AI hosts about your notebook content. This is a REAL NotebookLM feature that generates actual audio.
+
+### Generate Audio
+
+```bash
+curl -X POST http://localhost:3000/content/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content_type": "audio_overview",
+    "custom_instructions": "Focus on key concepts for beginners, use simple language"
+  }'
+```
+
+**Custom Instructions Ideas:**
+
+- "Focus on practical applications"
+- "Emphasize the historical context"
+- "Make it accessible to students"
+- "Highlight the key takeaways"
+
+**Note:** Audio generation takes 5-10 minutes. The API will wait for completion.
+
+### Download Audio
+
+```bash
+# Get audio file
+curl "http://localhost:3000/content/download?content_type=audio_overview"
+
+# Save to specific path
+curl "http://localhost:3000/content/download?content_type=audio_overview&output_path=/downloads/podcast.mp3"
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "filePath": "/downloads/podcast.wav",
+  "mimeType": "audio/wav"
+}
+```
+
+---
+
+## Create Notes
+
+Notes are user-created annotations that appear in the NotebookLM Studio panel. They allow you to save research findings, summaries, key insights, or any custom content alongside your sources.
+
+### Create a Note
+
+```bash
+curl -X POST http://localhost:3000/content/notes \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Key Findings Summary",
+    "content": "## Main Points\n\n1. First important finding\n2. Second key insight\n3. Conclusion and next steps"
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "data": {
+    "success": true,
+    "noteTitle": "Key Findings Summary",
+    "status": "created"
+  }
+}
+```
+
+**Parameters:**
+
+| Parameter      | Type   | Required | Description                                  |
+| -------------- | ------ | -------- | -------------------------------------------- |
+| `title`        | string | Yes      | Title of the note                            |
+| `content`      | string | Yes      | Content/body of the note (supports markdown) |
+| `notebook_url` | string | No       | Target notebook URL                          |
+| `session_id`   | string | No       | Reuse existing session                       |
+
+**Use Cases:**
+
+- Save research summaries from NotebookLM conversations
+- Create custom annotations for specific sections
+- Store key quotes and references
+- Build a structured outline from notebook content
+
+### MCP Tool Usage
+
+If using Claude Code or Claude Desktop:
+
+```
+create_note(title="My Research Note", content="Key findings from the analysis...")
+```
+
+---
+
+## Listing Content
+
+View all sources and generated content in a notebook:
+
+```bash
+curl http://localhost:3000/content
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "sources": [
+    {
+      "id": "source-1",
+      "name": "Introduction.pdf",
+      "type": "document",
+      "status": "ready"
+    },
+    {
+      "id": "source-2",
+      "name": "https://example.com",
+      "type": "url",
+      "status": "ready"
+    }
+  ],
+  "generatedContent": [
+    {
+      "id": "audio-overview",
+      "type": "audio_overview",
+      "name": "Audio Overview",
+      "status": "ready",
+      "createdAt": "2025-12-24T10:30:00Z"
+    }
+  ],
+  "sourceCount": 2,
+  "hasAudioOverview": true
+}
+```
+
+---
+
+## MCP Tool Usage
+
+If using Claude Code or Claude Desktop:
+
+### Add Source
+
+```
+add_source(source_type="url", url="https://example.com")
+```
+
+### Delete Source
+
+```
+delete_source(source_name="My Document")
+```
+
+or
+
+```
+delete_source(source_id="source-123")
+```
+
+### Generate Audio
+
+```
+generate_content(content_type="audio_overview", custom_instructions="Focus on key points")
+```
+
+### List Content
+
+```
+list_content()
+```
+
+### Download Audio
+
+```
+download_content(content_type="audio_overview", output_path="/path/to/save.mp3")
+```
+
+---
+
+## Workflow Example
+
+### Research Workflow
+
+1. Add multiple sources:
+
+   ```bash
+   # Add primary source
+   curl -X POST http://localhost:3000/content/sources \
+     -d '{"source_type":"url","url":"https://research-paper.com"}'
+
+   # Add supporting document
+   curl -X POST http://localhost:3000/content/sources \
+     -d '{"source_type":"file","file_path":"/docs/notes.pdf"}'
+   ```
+
+2. Generate audio overview:
+
+   ```bash
+   curl -X POST http://localhost:3000/content/generate \
+     -d '{"content_type":"audio_overview","custom_instructions":"Summarize key findings for researchers"}'
+   ```
+
+3. Download for offline listening:
+   ```bash
+   curl "http://localhost:3000/content/download?content_type=audio_overview&output_path=research.mp3"
+   ```
+
+---
+
+## Error Handling
+
+### Common Errors
+
+| Error                    | Cause                  | Solution                        |
+| ------------------------ | ---------------------- | ------------------------------- |
+| "Source type required"   | Missing `source_type`  | Add the `source_type` parameter |
+| "File not found"         | Invalid `file_path`    | Check file path exists          |
+| "Audio not ready"        | Audio still generating | Wait and retry                  |
+| "No sources in notebook" | Empty notebook         | Add sources first               |
+
+### Timeout Handling
+
+Audio generation can take 5-10 minutes. The API will wait up to 10 minutes for completion. For long operations, consider:
+
+1. Using `session_id` to maintain context
+2. Polling `list_content` to check status
+3. Setting appropriate client timeouts
+
+---
+
+## Best Practices
+
+1. **Add sources before generating audio** - Ensure your notebook has sources before attempting to generate audio.
+
+2. **Use custom instructions** - Tailor the audio by providing clear custom instructions.
+
+3. **Reuse sessions** - Pass `session_id` to avoid creating new browser sessions for each request.
+
+4. **Check content list** - Use `list_content` to verify what's already generated before creating duplicates.
+
+5. **Handle timeouts gracefully** - Audio generation is slow; implement appropriate retry logic.
+
+---
+
+## Version History
+
+| Version | Changes                                     |
+| ------- | ------------------------------------------- |
+| 1.4.2   | Removed fake content generation (FAQ, etc.) |
+| 1.4.0   | Added content management module             |
+| 1.3.7   | Source citation extraction                  |
+
+---
+
+**Complete Content Management Documentation!**