notebooklm-mcp-structured: Instructions file for Claude Code

NotebookLM MCP Structured

Enhanced MCP server for NotebookLM with client-side prompt structuring for source fidelity in professional document analysis.

Stack

• Language: TypeScript (ES2022, Node16 modules)
• Runtime: Node.js >= 18.0.0
• Framework: MCP SDK (@modelcontextprotocol/sdk)
• Browser automation: Patchright (Playwright fork with stealth features)
• Validation: Zod
• Testing: node:test unit tests for the singleton module (npm run test:unit) plus an integration script (npm run test:singleton); the rest of the server is manually tested via tsx src/index.ts

Structure

src/
├── index.ts                    # Entry point: role dispatch (proxy/backend/direct) + CLI commands
├── server-core.ts              # Shared server core: managers + MCP Server factory, reused by all three roles
├── config.ts                   # Configuration: defaults, ENV overrides, paths, timing constants
├── errors.ts                   # Custom errors + page closed detection helper
├── selectors.ts                # Centralized DOM selectors for NotebookLM UI
├── types.ts                    # Global TypeScript interfaces
├── singleton/
│   ├── proxy.ts                 # Proxy role: stdio<->HTTP JSON-RPC pipe, handshake replay on reconnect
│   ├── backend.ts               # Backend role: shared server over localhost Streamable HTTP
│   ├── spawn.ts                 # Backend discovery, spawn lock, version-skew handling
│   └── registry.ts              # singleton.json / singleton.lock read-write helpers
├── auth/
│   └── auth-manager.ts         # Google auth: login, cookies, state persistence
├── session/
│   ├── session-manager.ts      # Session lifecycle, cleanup, limits
│   ├── browser-session.ts      # Page interactions, question/answer flow
│   └── shared-context-manager.ts # Shared browser context (fingerprint)
├── library/
│   ├── notebook-library.ts     # Notebook collection management (CRUD)
│   └── types.ts                # Library-specific types
├── tools/
│   ├── index.ts                # Exports definitions + handlers
│   ├── definitions.ts          # Tool definitions aggregator
│   ├── handlers.ts             # Tool implementation logic
│   ├── definitions/
│   │   ├── ask-question.ts     # Core tool with structuring guidelines
│   │   ├── notebook-management.ts # Library tools
│   │   ├── session-management.ts # Session tools
│   │   └── system.ts           # Health, auth, cleanup tools
│   └── templates/
│       └── structuring-guidelines.ts # Prompt structuring template
├── resources/
│   └── resource-handlers.ts    # MCP resources for notebooks
└── utils/
    ├── cleanup-manager.ts      # Deep cleanup of browser data
    ├── cli-handler.ts          # CLI config commands
    ├── connection-checker.ts   # Chrome state detection
    ├── logger.ts               # Colored console logging (testable with DI)
    ├── page-utils.ts           # Response detection, streaming handling
    ├── settings-manager.ts     # Profile-based tool filtering
    └── stealth-utils.ts        # Human-like typing/mouse