@roomi-fields/notebooklm-mcp 1.3.3 → 1.3.5

package/docs/CHROME_PROFILE_LIMITATION.md

@@ -1,212 +1,229 @@
-# Chrome Profile Limitation
-
-## 🚨 Current Limitation (v1.3.2)
-
-**The HTTP server and MCP stdio modes cannot run simultaneously** due to Chrome profile locking.
-
-### Why This Happens
-
-The NotebookLM MCP server uses a persistent Chrome profile to maintain authentication between sessions. This profile is stored at:
-
-```
-Windows: C:\Users\<username>\AppData\Local\notebooklm-mcp\Data\chrome_profile
-Linux:   ~/.local/share/notebooklm-mcp/chrome_profile
-macOS:   ~/Library/Application Support/notebooklm-mcp/chrome_profile
-```
-
-**The problem:** Chrome can only open a profile in one instance at a time. When you try to run both:
-- HTTP server (via `npm run daemon:start` or `npm run start:http`)
-- MCP stdio server (via Claude Desktop, Cursor, etc.)
-
-The second instance will fail to launch Chrome with this error:
-```
-Error: browserType.launchPersistentContext: Target page, context or browser has been closed
-```
-
-### Who Is Affected?
-
-| Scenario | Affected? | Why |
-|----------|-----------|-----|
-| **Single mode user** | ❌ No | Only runs one server at a time |
-| **HTTP-only user** | ❌ No | Only uses HTTP server for n8n/Zapier |
-| **MCP-only user** | ❌ No | Only uses Claude Desktop/Cursor |
-| **Dual mode user** | ✅ Yes | Wants both HTTP API and Claude Desktop integration |
-
-### Current Workarounds
-
-#### Option A: Use HTTP Server Only
-```bash
-# Start HTTP server
-npm run daemon:start
-
-# Stop MCP stdio server (remove from Claude Desktop config)
-# Use HTTP API for all integrations (n8n, Zapier, custom apps)
-```
-
-#### Option B: Use MCP Stdio Only
-```bash
-# Stop HTTP server
-npm run daemon:stop
-
-# Use only Claude Desktop/Cursor/Codex integration
-```
-
-#### Option C: Switch Between Modes
-```bash
-# For n8n workflows
-npm run daemon:start
-
-# For Claude Desktop work
-npm run daemon:stop
-# Then restart Claude Desktop
-```
-
-## 🔮 Planned Solution (v1.4.0+)
-
-### Option 1: Separate Chrome Profiles by Mode ⭐ (Selected)
-
-**Implementation:** Detect the runtime mode and use different Chrome profiles.
-
-```typescript
-// Automatic profile detection based on mode
-const getProfilePath = () => {
-  const baseDir = getDataDirectory();
-  const mode = process.env.MCP_MODE || (process.stdout.isTTY ? 'stdio' : 'http');
-
-  return {
-    stdio: path.join(baseDir, 'chrome_profile_stdio'),  // For Claude Desktop
-    http: path.join(baseDir, 'chrome_profile_http'),     // For HTTP server
-  }[mode];
-};
-```
-
-**Benefits:**
-- ✅ Both modes can run simultaneously
-- ✅ No user configuration needed
-- ✅ Separate authentication per mode
-- ✅ Simple implementation
-
-**Trade-offs:**
-- Each mode needs separate authentication (one-time setup)
-- Two Chrome profiles consume more disk space (~100-200MB each)
-
-### Option 2: Shared Session via IPC
-
-**Implementation:** HTTP server becomes the master, stdio clients connect to it.
-
-**Benefits:**
-- ✅ Single Chrome instance
-- ✅ Shared authentication
-
-**Trade-offs:**
-- ❌ Complex architecture
-- ❌ HTTP server must be running for stdio to work
-- ❌ Requires inter-process communication
-
-### Option 3: Better Error Messages
-
-**Implementation:** Detect profile lock and show helpful error.
-
-**Benefits:**
-- ✅ Clear user guidance
-
-**Trade-offs:**
-- ❌ Doesn't solve the root problem
-- ❌ Users still can't run both modes
-
-## 🛠️ Implementation Plan
-
-### Phase 1: Separate Chrome Profiles (v1.4.0)
-
-**Changes:**
-1. Add `MCP_MODE` environment variable detection
-2. Create mode-specific profile directories
-3. Update authentication flow to use correct profile
-4. Update documentation
-
-**Code locations:**
-- `src/auth/shared-context-manager.ts` - Profile path logic
-- `src/config.ts` - Mode detection
-- `src/index.ts` - HTTP server mode flag
-- `src/http-wrapper.ts` - HTTP mode environment
-
-**Backwards compatibility:**
-- Existing `chrome_profile` directory will be migrated to `chrome_profile_stdio`
-- HTTP server will create new `chrome_profile_http`
-- Users will need to re-authenticate HTTP mode once
-
-### Phase 2: Migration & Testing
-
-**Migration script:**
-```typescript
-// Auto-migrate existing profile to stdio mode
-if (exists('chrome_profile') && !exists('chrome_profile_stdio')) {
-  rename('chrome_profile', 'chrome_profile_stdio');
-  log('Migrated existing profile to stdio mode');
-}
-```
-
-**Testing checklist:**
-- [ ] HTTP server starts with separate profile
-- [ ] MCP stdio starts with separate profile
-- [ ] Both can run simultaneously
-- [ ] Authentication works independently in each mode
-- [ ] Existing users migrate smoothly
-- [ ] Documentation updated
-
-### Phase 3: Documentation Updates
-
-**Files to update:**
-- `README.md` - Remove limitation warning
-- `deployment/docs/01-INSTALL.md` - Update installation flow
-- `deployment/docs/05-TROUBLESHOOTING.md` - Update troubleshooting
-- `CHANGELOG.md` - Document breaking changes
-
-## 📝 For Developers
-
-### Testing the Fix Locally
-
-```bash
-# Terminal 1: Start HTTP server
-MCP_MODE=http npm run start:http
-
-# Terminal 2: Start stdio server (simulate Claude Desktop)
-MCP_MODE=stdio node dist/index.js
-
-# Both should start without conflict
-```
-
-### Verifying Profile Separation
-
-```bash
-# Check both profiles exist
-ls -la ~/.local/share/notebooklm-mcp/
-# Should show:
-# - chrome_profile_http/
-# - chrome_profile_stdio/
-
-# Check profile usage
-lsof | grep chrome_profile  # Linux/macOS
-# or
-Get-Process | Where-Object {$_.Path -like "*chrome*"}  # Windows PowerShell
-```
-
-## 🤝 Contributing
-
-If you want to implement this feature or have alternative solutions:
-
-1. Open an issue on GitHub describing your approach
-2. Reference this document in your PR
-3. Include tests for both HTTP and stdio modes running simultaneously
-4. Update documentation accordingly
-
-## 📚 Related Issues
-
-- [Issue #XX] Chrome profile conflict between HTTP and stdio modes
-- [Issue #YY] Support running multiple MCP server instances
-
-## 🔗 See Also
-
-- [Installation Guide](../deployment/docs/01-INSTALL.md)
-- [Troubleshooting Guide](../deployment/docs/05-TROUBLESHOOTING.md)
-- [Architecture Overview](../deployment/docs/02-CONFIGURATION.md)
+# Chrome Profile Limitation
+
+## 🚨 Current Limitation (v1.3.2)
+
+**The HTTP server and MCP stdio modes cannot run simultaneously** due to Chrome profile locking.
+
+### Why This Happens
+
+The NotebookLM MCP server uses a persistent Chrome profile to maintain authentication between sessions. This profile is stored at:
+
+```
+Windows: C:\Users\<username>\AppData\Local\notebooklm-mcp\Data\chrome_profile
+Linux:   ~/.local/share/notebooklm-mcp/chrome_profile
+macOS:   ~/Library/Application Support/notebooklm-mcp/chrome_profile
+```
+
+**The problem:** Chrome can only open a profile in one instance at a time. When you try to run both:
+
+- HTTP server (via `npm run daemon:start` or `npm run start:http`)
+- MCP stdio server (via Claude Desktop, Cursor, etc.)
+
+The second instance will fail to launch Chrome with this error:
+
+```
+Error: browserType.launchPersistentContext: Target page, context or browser has been closed
+```
+
+### Who Is Affected?
+
+| Scenario             | Affected? | Why                                                |
+| -------------------- | --------- | -------------------------------------------------- |
+| **Single mode user** | ❌ No     | Only runs one server at a time                     |
+| **HTTP-only user**   | ❌ No     | Only uses HTTP server for n8n/Zapier               |
+| **MCP-only user**    | ❌ No     | Only uses Claude Desktop/Cursor                    |
+| **Dual mode user**   | ✅ Yes    | Wants both HTTP API and Claude Desktop integration |
+
+### Current Workarounds
+
+#### Option A: Use HTTP Server Only
+
+```bash
+# Start HTTP server
+npm run daemon:start
+
+# Stop MCP stdio server (remove from Claude Desktop config)
+# Use HTTP API for all integrations (n8n, Zapier, custom apps)
+```
+
+#### Option B: Use MCP Stdio Only
+
+```bash
+# Stop HTTP server
+npm run daemon:stop
+
+# Use only Claude Desktop/Cursor/Codex integration
+```
+
+#### Option C: Switch Between Modes
+
+```bash
+# For n8n workflows
+npm run daemon:start
+
+# For Claude Desktop work
+npm run daemon:stop
+# Then restart Claude Desktop
+```
+
+## 🔮 Planned Solution (v1.4.0+)
+
+### Option 1: Separate Chrome Profiles by Mode ⭐ (Selected)
+
+**Implementation:** Detect the runtime mode and use different Chrome profiles.
+
+```typescript
+// Automatic profile detection based on mode
+const getProfilePath = () => {
+  const baseDir = getDataDirectory();
+  const mode = process.env.MCP_MODE || (process.stdout.isTTY ? 'stdio' : 'http');
+
+  return {
+    stdio: path.join(baseDir, 'chrome_profile_stdio'), // For Claude Desktop
+    http: path.join(baseDir, 'chrome_profile_http'), // For HTTP server
+  }[mode];
+};
+```
+
+**Benefits:**
+
+- ✅ Both modes can run simultaneously
+- ✅ No user configuration needed
+- ✅ Separate authentication per mode
+- ✅ Simple implementation
+
+**Trade-offs:**
+
+- Each mode needs separate authentication (one-time setup)
+- Two Chrome profiles consume more disk space (~100-200MB each)
+
+### Option 2: Shared Session via IPC
+
+**Implementation:** HTTP server becomes the master, stdio clients connect to it.
+
+**Benefits:**
+
+- ✅ Single Chrome instance
+- ✅ Shared authentication
+
+**Trade-offs:**
+
+- ❌ Complex architecture
+- ❌ HTTP server must be running for stdio to work
+- ❌ Requires inter-process communication
+
+### Option 3: Better Error Messages
+
+**Implementation:** Detect profile lock and show helpful error.
+
+**Benefits:**
+
+- ✅ Clear user guidance
+
+**Trade-offs:**
+
+- ❌ Doesn't solve the root problem
+- ❌ Users still can't run both modes
+
+## 🛠️ Implementation Plan
+
+### Phase 1: Separate Chrome Profiles (v1.4.0)
+
+**Changes:**
+
+1. Add `MCP_MODE` environment variable detection
+2. Create mode-specific profile directories
+3. Update authentication flow to use correct profile
+4. Update documentation
+
+**Code locations:**
+
+- `src/auth/shared-context-manager.ts` - Profile path logic
+- `src/config.ts` - Mode detection
+- `src/index.ts` - HTTP server mode flag
+- `src/http-wrapper.ts` - HTTP mode environment
+
+**Backwards compatibility:**
+
+- Existing `chrome_profile` directory will be migrated to `chrome_profile_stdio`
+- HTTP server will create new `chrome_profile_http`
+- Users will need to re-authenticate HTTP mode once
+
+### Phase 2: Migration & Testing
+
+**Migration script:**
+
+```typescript
+// Auto-migrate existing profile to stdio mode
+if (exists('chrome_profile') && !exists('chrome_profile_stdio')) {
+  rename('chrome_profile', 'chrome_profile_stdio');
+  log('Migrated existing profile to stdio mode');
+}
+```
+
+**Testing checklist:**
+
+- [ ] HTTP server starts with separate profile
+- [ ] MCP stdio starts with separate profile
+- [ ] Both can run simultaneously
+- [ ] Authentication works independently in each mode
+- [ ] Existing users migrate smoothly
+- [ ] Documentation updated
+
+### Phase 3: Documentation Updates
+
+**Files to update:**
+
+- `README.md` - Remove limitation warning
+- `deployment/docs/01-INSTALL.md` - Update installation flow
+- `deployment/docs/05-TROUBLESHOOTING.md` - Update troubleshooting
+- `CHANGELOG.md` - Document breaking changes
+
+## 📝 For Developers
+
+### Testing the Fix Locally
+
+```bash
+# Terminal 1: Start HTTP server
+MCP_MODE=http npm run start:http
+
+# Terminal 2: Start stdio server (simulate Claude Desktop)
+MCP_MODE=stdio node dist/index.js
+
+# Both should start without conflict
+```
+
+### Verifying Profile Separation
+
+```bash
+# Check both profiles exist
+ls -la ~/.local/share/notebooklm-mcp/
+# Should show:
+# - chrome_profile_http/
+# - chrome_profile_stdio/
+
+# Check profile usage
+lsof | grep chrome_profile  # Linux/macOS
+# or
+Get-Process | Where-Object {$_.Path -like "*chrome*"}  # Windows PowerShell
+```
+
+## 🤝 Contributing
+
+If you want to implement this feature or have alternative solutions:
+
+1. Open an issue on GitHub describing your approach
+2. Reference this document in your PR
+3. Include tests for both HTTP and stdio modes running simultaneously
+4. Update documentation accordingly
+
+## 📚 Related Issues
+
+- [Issue #XX] Chrome profile conflict between HTTP and stdio modes
+- [Issue #YY] Support running multiple MCP server instances
+
+## 🔗 See Also
+
+- [Installation Guide](../deployment/docs/01-INSTALL.md)
+- [Troubleshooting Guide](../deployment/docs/05-TROUBLESHOOTING.md)
+- [Architecture Overview](../deployment/docs/02-CONFIGURATION.md)

package/package.json

@@ -1,78 +1,107 @@
-{
-  "name": "@roomi-fields/notebooklm-mcp",
-  "version": "1.3.3",
-  "description": "MCP server for NotebookLM API with HTTP REST API - Zero hallucinations from your notebooks",
-  "type": "module",
-  "bin": {
-    "notebooklm-mcp": "dist/index.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "watch": "tsc --watch",
-    "dev": "tsx watch src/index.ts",
-    "dev:http": "tsx watch src/http-wrapper.ts",
-    "start:http": "node dist/http-wrapper.js",
-    "daemon:start": "pm2 start ecosystem.config.cjs",
-    "daemon:stop": "pm2 stop notebooklm-mcp",
-    "daemon:restart": "pm2 restart notebooklm-mcp",
-    "daemon:logs": "pm2 logs notebooklm-mcp",
-    "daemon:status": "pm2 status",
-    "daemon:delete": "pm2 delete notebooklm-mcp",
-    "setup-auth": "node dist/index.js",
-    "prepare": "npm run build",
-    "test": "tsx src/index.ts"
-  },
-  "keywords": [
-    "mcp",
-    "notebooklm",
-    "gemini",
-    "ai",
-    "claude",
-    "n8n",
-    "automation",
-    "rest-api",
-    "http-server",
-    "workflow"
-  ],
-  "author": "Romain Peyrichou (https://github.com/roomi-fields)",
-  "contributors": [
-    "Gérôme Dexheimer <hello@geromedexheimer.de> (https://github.com/PleasePrompto)"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/roomi-fields/notebooklm-mcp.git"
-  },
-  "homepage": "https://github.com/roomi-fields/notebooklm-mcp#readme",
-  "bugs": {
-    "url": "https://github.com/roomi-fields/notebooklm-mcp/issues"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "NOTEBOOKLM_USAGE.md",
-    "LICENSE",
-    "docs"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "cors": "^2.8.5",
-    "dotenv": "^16.4.0",
-    "env-paths": "^3.0.0",
-    "express": "^4.18.2",
-    "globby": "^14.1.0",
-    "patchright": "^1.48.2",
-    "zod": "^3.22.0"
-  },
-  "devDependencies": {
-    "@types/cors": "^2.8.17",
-    "@types/express": "^4.17.21",
-    "@types/node": "^20.11.0",
-    "pm2": "^5.4.2",
-    "tsx": "^4.7.0",
-    "typescript": "^5.3.3"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "@roomi-fields/notebooklm-mcp",
+  "version": "1.3.5",
+  "description": "MCP server for NotebookLM API with HTTP REST API - Zero hallucinations from your notebooks",
+  "type": "module",
+  "bin": {
+    "notebooklm-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "help": "node dist/cli/help.js",
+    "setup-auth": "node dist/cli/setup-auth.js",
+    "de-auth": "node dist/cli/de-auth.js",
+    "start:http": "node dist/http-wrapper.js",
+    "dev:http": "tsx watch src/http-wrapper.ts",
+    "daemon:start": "pm2 start ecosystem.config.cjs",
+    "daemon:stop": "pm2 stop notebooklm-mcp",
+    "daemon:restart": "pm2 restart notebooklm-mcp",
+    "daemon:logs": "pm2 logs notebooklm-mcp",
+    "daemon:status": "pm2 status",
+    "daemon:delete": "pm2 delete notebooklm-mcp",
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "dev": "tsx watch src/index.ts",
+    "prepare": "husky",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
+    "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+    "test:ci": "node --experimental-vm-modules node_modules/jest/bin/jest.js --ci --coverage --reporters=default",
+    "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js --testPathPatterns=unit",
+    "test:integration": "node --experimental-vm-modules node_modules/jest/bin/jest.js --testPathPatterns=integration"
+  },
+  "keywords": [
+    "mcp",
+    "notebooklm",
+    "gemini",
+    "ai",
+    "claude",
+    "n8n",
+    "automation",
+    "rest-api",
+    "http-server",
+    "workflow"
+  ],
+  "author": "Romain Peyrichou (https://github.com/roomi-fields)",
+  "contributors": [
+    "Gérôme Dexheimer <hello@geromedexheimer.de> (https://github.com/PleasePrompto)"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/roomi-fields/notebooklm-mcp.git"
+  },
+  "homepage": "https://github.com/roomi-fields/notebooklm-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/roomi-fields/notebooklm-mcp/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "NOTEBOOKLM_USAGE.md",
+    "LICENSE",
+    "docs"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.0",
+    "env-paths": "^3.0.0",
+    "express": "^4.18.2",
+    "globby": "^14.1.0",
+    "patchright": "^1.48.2",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@jest/globals": "^30.2.0",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^8.48.0",
+    "@typescript-eslint/parser": "^8.48.0",
+    "eslint": "^9.39.1",
+    "husky": "^9.1.7",
+    "jest": "^30.2.0",
+    "lint-staged": "^16.2.7",
+    "pm2": "^6.0.14",
+    "prettier": "^3.6.2",
+    "ts-jest": "^29.4.5",
+    "tsx": "^4.7.0",
+    "type-coverage": "^2.29.7",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.48.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  }
+}