@pan-sec/notebooklm-mcp 2026.2.11 → 2026.3.1

package/docs/dependency-risk.md

@@ -0,0 +1,25 @@
+# Dependency Risk Notes
+
+## Patchright
+
+This project uses `patchright` for browser automation because NotebookLM flows
+depend on Playwright-compatible browser control with stealth-oriented behavior.
+Treat it as a higher-risk dependency than ordinary runtime libraries:
+
+- It is a Playwright fork, so upstream security fixes may not land at the same
+  time as Playwright releases.
+- Browser automation packages can run install scripts that fetch browser
+  binaries or drivers.
+- Keep it exact-pinned in `package.json` and review updates manually.
+- CI installs dependencies with `npm ci --ignore-scripts`; browser binaries
+  should be provisioned explicitly in controlled environments.
+- Production deployments should run the MCP server in a least-privilege
+  container or sandbox with a dedicated browser profile directory and no access
+  to unrelated host files.
+
+When upgrading `patchright`, verify:
+
+1. The package tarball integrity in `package-lock.json` changes only as expected.
+2. Notebook creation, source upload, auth setup, and session reuse tests pass.
+3. Any browser installation step is run explicitly, not via automatic package
+   lifecycle scripts in CI.

package/docs/testing-runbook.md

@@ -0,0 +1,166 @@
+# Authenticated Testing Runbook
+
+This runbook is the baseline sequence for future NotebookLM MCP testing in a real authenticated browser session.
+
+## Goal
+
+Use a visible Chrome session to capture valid NotebookLM auth, verify the local repo is healthy, and run a minimal smoke test flow before broader manual or agent-driven testing.
+
+## 1. Local Repo Preflight
+
+Run these from the repo root:
+
+```bash
+npx tsc --noEmit
+npx vitest run
+npx stryker run --dryRunOnly
+npm audit --json
+```
+
+Expected result:
+- TypeScript passes
+- Vitest passes
+- Stryker dry-run passes
+- `npm audit` reports 0 vulnerabilities
+
+## 2. Start Visible Chrome Auth
+
+Use the standalone auth flow from the repo root:
+
+```bash
+node auth-now.mjs
+```
+
+What it does:
+- Opens visible Chrome using the persistent NotebookLM profile
+- Waits for manual Google login
+- Saves encrypted browser state to the local auth store
+
+Expected success signal in the terminal:
+- `NotebookLM detected`
+- `Saved encrypted state.json.pqenc`
+- `Auth complete`
+
+Expected saved file on Linux:
+
+```text
+~/.local/share/notebooklm-mcp/browser_state/state.json.pqenc
+```
+
+## 3. Verify Auth Artifact
+
+Confirm the encrypted state file exists and is freshly updated:
+
+```bash
+stat ~/.local/share/notebooklm-mcp/browser_state/state.json.pqenc
+```
+
+Expected result:
+- File exists
+- Permissions are `0600`
+- Modify time matches the recent auth session
+
+## 4. MCP Health Check
+
+After auth is saved, verify the MCP server can use it.
+
+Important:
+- Browser auth and MCP auth are separate.
+- If you are testing through a direct stdio harness instead of your normal MCP client, you must also provide a valid `NLMCP_AUTH_TOKEN`.
+- For ad hoc local smoke tests, prefer a temporary in-process token over rotating the persisted token.
+
+Recommended prompt:
+
+```text
+Run get_health with deep_check enabled and report auth status, chat_ui_accessible, and any warnings.
+```
+
+Expected result:
+- `authenticated: true`
+- `chat_ui_accessible: true`
+
+If this fails, do not continue to notebook smoke tests until auth is repaired.
+
+## 5. Notebook Smoke Test Sequence
+
+Run this exact sequence in the MCP client:
+
+1. `get_health(deep_check=true)`
+2. `list_notebooks`
+3. `select_notebook` on a known safe test notebook
+4. `ask_question` with a low-risk prompt such as:
+
+```text
+Summarize the main topics covered in this notebook in 3 bullets.
+```
+
+5. `get_quota(sync=true)` if quota behavior matters for the session
+
+Success criteria:
+- Notebook list loads
+- Notebook selection succeeds
+- `ask_question` returns a grounded answer
+- No auth-expired or browser-closed errors occur
+
+For direct test harnesses:
+- Inject a temporary `NLMCP_AUTH_TOKEN` into the server process
+- Pass the same token in MCP request metadata
+- Do not rotate the saved token unless you actually need to replace your client configuration
+
+## 6. Optional Creation Flow Test
+
+Only run this when creation is in scope for the session:
+
+1. `create_notebook` with a disposable test name
+2. `add_source` or `add_folder` with a safe local fixture
+3. `list_sources`
+4. Optional: `generate_audio_overview`, `generate_video_overview`, or `generate_data_table`
+
+Cleanup:
+- Remove disposable test notebooks or clearly label them as temporary
+
+## 7. Recovery Paths
+
+If auth is stale or broken:
+
+1. Close all Chrome/Chromium windows
+2. Re-run visible auth:
+
+```bash
+node auth-now.mjs
+```
+
+If persistent profile/session issues remain:
+
+1. Close all Chrome/Chromium windows
+2. Preview cleanup with library preservation
+3. Confirm cleanup
+4. Re-run auth
+5. Re-run `get_health(deep_check=true)`
+
+Recommended agent prompt:
+
+```text
+Repair NotebookLM auth without deleting my library, then verify with get_health deep_check.
+```
+
+## 8. Session Notes Template
+
+Record these for each authenticated test pass:
+
+- Date:
+- Branch/commit:
+- Auth method: `node auth-now.mjs`
+- Auth artifact updated: yes/no
+- `get_health(deep_check=true)`: pass/fail
+- Notebook smoke test: pass/fail
+- Creation flow test: pass/fail/not run
+- Quota check: pass/fail/not run
+- Issues found:
+
+## Notes
+
+- Prefer visible auth for all interactive login work.
+- Do not use headless auth flows.
+- `cleanup_data` is a recovery tool, not a default auth step.
+- Keep at least one safe disposable notebook available for smoke testing.

package/docs/usage-guide.md

@@ -3,6 +3,7 @@
 This guide covers advanced usage patterns, best practices, and detailed examples for the NotebookLM MCP server.
 
 > 📘 For installation and quick start, see the main [README](../README.md).
+> 🧪 For repeatable authenticated validation, use the [Authenticated Testing Runbook](./testing-runbook.md).
 
 ## Research Patterns
 
@@ -242,4 +243,4 @@ Agent: "According to our architecture guidelines..."
 
 ---
 
-Remember: The power of this integration lies in letting your agent **ask multiple questions** – gathering context and building comprehensive understanding before responding. Don't rush the research phase!
+Remember: The power of this integration lies in letting your agent **ask multiple questions** – gathering context and building comprehensive understanding before responding. Don't rush the research phase!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pan-sec/notebooklm-mcp",
-  "version": "2026.2.11",
+  "version": "2026.3.1",
   "mcpName": "io.github.Pantheon-Security/notebooklm-mcp-secure",
   "description": "Security-hardened MCP server for NotebookLM API with compliance-ready architecture (GDPR, SOC2, CSSF controls implemented)",
   "type": "module",
@@ -13,10 +13,16 @@
     "watch": "tsc --watch",
     "dev": "tsx watch src/index.ts",
     "prepare": "npm run build",
+    "ci:install": "npm ci --ignore-scripts",
     "test": "npx vitest run",
+    "test:integration": "npx vitest run tests/mcp-server.integration.test.ts",
+    "test:property": "npx vitest run tests/property-based.test.ts",
+    "test:mutation": "npx stryker run --dryRunOnly",
     "test:watch": "npx vitest",
+    "test:coverage": "npx vitest run --coverage",
     "security-check": "npm audit",
-    "security-scan": "medusa scan . --fail-on high"
+    "security-scan": "medusa scan . --fail-on high",
+    "discover-selectors": "npx tsx scripts/run-discovery.ts"
   },
   "keywords": [
     "mcp",
@@ -55,20 +61,33 @@
     "docs"
   ],
   "dependencies": {
-    "@google/genai": "^1.41.0",
-    "@modelcontextprotocol/sdk": "^1.25.3",
-    "@noble/post-quantum": "^0.5.4",
-    "dotenv": "^17.2.3",
-    "env-paths": "^4.0.0",
-    "globby": "^16.1.0",
-    "patchright": "^1.57.0",
-    "pdf-lib": "^1.17.1",
-    "zod": "^4.3.6"
+    "@google/genai": "1.41.0",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@noble/post-quantum": "0.5.4",
+    "dotenv": "17.2.3",
+    "env-paths": "4.0.0",
+    "globby": "16.1.0",
+    "patchright": "1.57.0",
+    "pdf-lib": "1.17.1"
+  },
+  "overrides": {
+    "@google/genai": {
+      "protobufjs": "7.5.5"
+    },
+    "glob": {
+      "minimatch": "9.0.7"
+    },
+    "micromatch": {
+      "picomatch": "2.3.2"
+    }
   },
   "devDependencies": {
-    "@types/node": "^20.19.30",
-    "tsx": "^4.21.0",
-    "typescript": "^5.3.3"
+    "@stryker-mutator/core": "9.6.1",
+    "@types/node": "20.19.30",
+    "@vitest/coverage-v8": "4.1.4",
+    "fast-check": "4.7.0",
+    "tsx": "4.21.0",
+    "typescript": "5.3.3"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -85,8 +104,7 @@
     "responseValidation": true,
     "postQuantumEncryption": true,
     "secretsScanning": true,
-    "certificatePinning": true,
-    "memoryScubbing": true,
+    "memoryScrubbing": true,
     "medusaIntegration": true,
     "secureByDefaultAuth": true,
     "exponentialBackoffLockout": true,