Instructions

Implementation Reference

• src/tools/handlers.ts:41-177 (handler)

  Main handler function that executes the 'ask_question' tool. Manages browser sessions, resolves notebooks, interacts with NotebookLM via browser automation, handles errors and rate limits, and returns structured results including session information for follow-ups.

  async handleAskQuestion(
    args: {
      question: string;
      session_id?: string;
      notebook_id?: string;
      notebook_url?: string;
      show_browser?: boolean;
      browser_options?: BrowserOptions;
    },
    sendProgress?: ProgressCallback
  ): Promise<ToolResult<AskQuestionResult>> {
    const { question, session_id, notebook_id, notebook_url, show_browser, browser_options } = args;
  
    log.info(`🔧 [TOOL] ask_question called`);
    log.info(`  Question: "${question.substring(0, 100)}"...`);
    if (session_id) {
      log.info(`  Session ID: ${session_id}`);
    }
    if (notebook_id) {
      log.info(`  Notebook ID: ${notebook_id}`);
    }
    if (notebook_url) {
      log.info(`  Notebook URL: ${notebook_url}`);
    }
  
    try {
      // Resolve notebook URL
      let resolvedNotebookUrl = notebook_url;
  
      if (!resolvedNotebookUrl && notebook_id) {
        const notebook = this.library.incrementUseCount(notebook_id);
        if (!notebook) {
          throw new Error(`Notebook not found in library: ${notebook_id}`);
        }
  
        resolvedNotebookUrl = notebook.url;
        log.info(`  Resolved notebook: ${notebook.name}`);
      } else if (!resolvedNotebookUrl) {
        const active = this.library.getActiveNotebook();
        if (active) {
          const notebook = this.library.incrementUseCount(active.id);
          if (!notebook) {
            throw new Error(`Active notebook not found: ${active.id}`);
          }
          resolvedNotebookUrl = notebook.url;
          log.info(`  Using active notebook: ${notebook.name}`);
        }
      }
  
      // Progress: Getting or creating session
      await sendProgress?.("Getting or creating browser session...", 1, 5);
  
      // Apply browser options temporarily
      const originalConfig = { ...CONFIG };
      const effectiveConfig = applyBrowserOptions(browser_options, show_browser);
      Object.assign(CONFIG, effectiveConfig);
  
      // Calculate overrideHeadless parameter for session manager
      // show_browser takes precedence over browser_options.headless
      let overrideHeadless: boolean | undefined = undefined;
      if (show_browser !== undefined) {
        overrideHeadless = show_browser;
      } else if (browser_options?.show !== undefined) {
        overrideHeadless = browser_options.show;
      } else if (browser_options?.headless !== undefined) {
        overrideHeadless = !browser_options.headless;
      }
  
      try {
        // Get or create session (with headless override to handle mode changes)
        const session = await this.sessionManager.getOrCreateSession(
          session_id,
          resolvedNotebookUrl,
          overrideHeadless
        );
  
      // Progress: Asking question
      await sendProgress?.("Asking question to NotebookLM...", 2, 5);
  
      // Ask the question (pass progress callback)
      const rawAnswer = await session.ask(question, sendProgress);
      const answer = `${rawAnswer.trimEnd()}${FOLLOW_UP_REMINDER}`;
  
      // Get session info
      const sessionInfo = session.getInfo();
  
      const result: AskQuestionResult = {
        status: "success",
        question,
        answer,
        session_id: session.sessionId,
        notebook_url: session.notebookUrl,
        session_info: {
          age_seconds: sessionInfo.age_seconds,
          message_count: sessionInfo.message_count,
          last_activity: sessionInfo.last_activity,
        },
      };
  
        // Progress: Complete
        await sendProgress?.("Question answered successfully!", 5, 5);
  
        log.success(`✅ [TOOL] ask_question completed successfully`);
        return {
          success: true,
          data: result,
        };
      } finally {
        // Restore original CONFIG
        Object.assign(CONFIG, originalConfig);
      }
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
  
      // Special handling for rate limit errors
      if (error instanceof RateLimitError || errorMessage.toLowerCase().includes("rate limit")) {
        log.error(`🚫 [TOOL] Rate limit detected`);
        return {
          success: false,
          error:
            "NotebookLM rate limit reached (50 queries/day for free accounts).\n\n" +
            "You can:\n" +
            "1. Use the 're_auth' tool to login with a different Google account\n" +
            "2. Wait until tomorrow for the quota to reset\n" +
            "3. Upgrade to Google AI Pro/Ultra for 5x higher limits\n\n" +
            `Original error: ${errorMessage}`,
        };
      }
  
      log.error(`❌ [TOOL] ask_question failed: ${errorMessage}`);
      return {
        success: false,
        error: errorMessage,
      };
    }
  }

• src/tools/definitions/ask-question.ts:112-220 (schema)

  Tool definition including input schema (JSON Schema) for the 'ask_question' tool, specifying parameters like question, session_id, notebook options, and browser controls.

  export const askQuestionTool: Tool = {
    name: "ask_question",
    // Description will be set dynamically using buildAskQuestionDescription
    description: "Dynamic description placeholder", 
    inputSchema: {
      type: "object",
      properties: {
        question: {
          type: "string",
          description: "The question to ask NotebookLM",
        },
        session_id: {
          type: "string",
          description:
            "Optional session ID for contextual conversations. If omitted, a new session is created.",
        },
        notebook_id: {
          type: "string",
          description:
            "Optional notebook ID from your library. If omitted, uses the active notebook. " +
            "Use list_notebooks to see available notebooks.",
        },
        notebook_url: {
          type: "string",
          description:
            "Optional notebook URL (overrides notebook_id). Use this for ad-hoc queries to notebooks not in your library.",
        },
        show_browser: {
          type: "boolean",
          description:
            "Show browser window for debugging (simple version). " +
            "For advanced control (typing speed, stealth, etc.), use browser_options instead.",
        },
        browser_options: {
          type: "object",
          description:
            "Optional browser behavior settings. Claude can control everything: " +
            "visibility, typing speed, stealth mode, timeouts. Useful for debugging or fine-tuning.",
          properties: {
            show: {
              type: "boolean",
              description: "Show browser window (default: from ENV or false)",
            },
            headless: {
              type: "boolean",
              description: "Run browser in headless mode (default: true)",
            },
            timeout_ms: {
              type: "number",
              description: "Browser operation timeout in milliseconds (default: 30000)",
            },
            stealth: {
              type: "object",
              description: "Human-like behavior settings to avoid detection",
              properties: {
                enabled: {
                  type: "boolean",
                  description: "Master switch for all stealth features (default: true)",
                },
                random_delays: {
                  type: "boolean",
                  description: "Random delays between actions (default: true)",
                },
                human_typing: {
                  type: "boolean",
                  description: "Human-like typing patterns (default: true)",
                },
                mouse_movements: {
                  type: "boolean",
                  description: "Realistic mouse movements (default: true)",
                },
                typing_wpm_min: {
                  type: "number",
                  description: "Minimum typing speed in WPM (default: 160)",
                },
                typing_wpm_max: {
                  type: "number",
                  description: "Maximum typing speed in WPM (default: 240)",
                },
                delay_min_ms: {
                  type: "number",
                  description: "Minimum delay between actions in ms (default: 100)",
                },
                delay_max_ms: {
                  type: "number",
                  description: "Maximum delay between actions in ms (default: 400)",
                },
              },
            },
            viewport: {
              type: "object",
              description: "Browser viewport size",
              properties: {
                width: {
                  type: "number",
                  description: "Viewport width in pixels (default: 1920)",
                },
                height: {
                  type: "number",
                  description: "Viewport height in pixels (default: 1080)",
                },
              },
            },
          },
        },
      },
      required: ["question"],
    },
  };

• src/tools/definitions.ts:20-33 (registration)

  Function that builds and registers all tool definitions, dynamically setting the description for 'ask_question' based on the current notebook library state.

  export function buildToolDefinitions(library: NotebookLibrary): Tool[] {
    // Update the description for ask_question based on the library state
    const dynamicAskQuestionTool = {
      ...askQuestionTool,
      description: buildAskQuestionDescription(library),
    };
  
    return [
      dynamicAskQuestionTool,
      ...notebookManagementTools,
      ...sessionManagementTools,
      ...systemTools,
    ];
  }

• src/index.ts:158-169 (registration)

  Dispatch/registration in the main MCP server handler: routes 'ask_question' tool calls to the handleAskQuestion method with progress support.

  case "ask_question":
    result = await this.toolHandlers.handleAskQuestion(
      args as {
        question: string;
        session_id?: string;
        notebook_id?: string;
        notebook_url?: string;
        show_browser?: boolean;
      },
      sendProgress
    );
    break;

• src/types.ts:21-33 (schema)

  TypeScript interface defining the structure of the result returned by the 'ask_question' tool.

  export interface AskQuestionResult {
    status: "success" | "error";
    question: string;
    answer?: string;
    error?: string;
    notebook_url: string;
    session_id?: string;
    session_info?: {
      age_seconds: number;
      message_count: number;
      last_activity: number;
    };
  }