notelm-mcp 1.2.1

package/dist/utils/stealth-utils.js

@@ -0,0 +1,396 @@
+/**
+ * Stealth utilities for human-like browser behavior
+ *
+ * This module provides functions to simulate realistic human interactions:
+ * - Human-like typing (speed configurable via CONFIG.typingWpmMin/Max)
+ * - Realistic mouse movements (Bezier curves with jitter)
+ * - Random delays (normal distribution)
+ * - Smooth scrolling
+ * - Reading pauses
+ *
+ * Based on the Python implementation from stealth_utils.py
+ */
+import { CONFIG } from "../config.js";
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Sleep for specified milliseconds
+ */
+export async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Generate random integer between min and max (inclusive)
+ */
+export function randomInt(min, max) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+/**
+ * Generate random float between min and max
+ */
+export function randomFloat(min, max) {
+    return Math.random() * (max - min) + min;
+}
+/**
+ * Generate random character (for typos)
+ */
+export function randomChar() {
+    const chars = "qwertyuiopasdfghjklzxcvbnm";
+    return chars[randomInt(0, chars.length - 1)];
+}
+/**
+ * Generate Gaussian (normal) distributed random number
+ * Uses Box-Muller transform
+ */
+export function gaussian(mean, stdDev) {
+    const u1 = Math.random();
+    const u2 = Math.random();
+    const z0 = Math.sqrt(-2.0 * Math.log(u1)) * Math.cos(2.0 * Math.PI * u2);
+    return z0 * stdDev + mean;
+}
+// ============================================================================
+// Random Delays
+// ============================================================================
+/**
+ * Add a random delay to simulate human thinking/reaction time
+ * Uses normal distribution for more realistic delays
+ *
+ * @param minMs Minimum delay in milliseconds (default: from CONFIG)
+ * @param maxMs Maximum delay in milliseconds (default: from CONFIG)
+ */
+export async function randomDelay(minMs, maxMs) {
+    minMs = minMs ?? CONFIG.minDelayMs;
+    maxMs = maxMs ?? CONFIG.maxDelayMs;
+    if (!CONFIG.stealthEnabled || !CONFIG.stealthRandomDelays) {
+        // Fixed delay (average)
+        const target = minMs === maxMs ? minMs : (minMs + maxMs) / 2;
+        if (target > 0) {
+            await sleep(target);
+        }
+        return;
+    }
+    // Use normal distribution for more realistic delays
+    // Mean at 60% of range, standard deviation of 20% of range
+    const mean = minMs + (maxMs - minMs) * 0.6;
+    const stdDev = (maxMs - minMs) * 0.2;
+    let delay = gaussian(mean, stdDev);
+    delay = Math.max(minMs, Math.min(maxMs, delay)); // Clamp to range
+    await sleep(delay);
+}
+// ============================================================================
+// Human Typing
+// ============================================================================
+/**
+ * Type text in a human-like manner with variable speed and optional typos
+ *
+ * Simulates realistic typing patterns:
+ * - Variable speed (45-65 WPM by default)
+ * - Occasional typos (2% chance)
+ * - Longer pauses after punctuation
+ * - Realistic character delays
+ *
+ * @param page Playwright page instance
+ * @param selector CSS selector of input element
+ * @param text Text to type
+ * @param options Typing options (wpm, withTypos)
+ */
+export async function humanType(page, selector, text, options = {}) {
+    if (!CONFIG.stealthEnabled || !CONFIG.stealthHumanTyping) {
+        // Fast typing without stealth
+        await page.fill(selector, text);
+        return;
+    }
+    const wpm = options.wpm ?? randomInt(CONFIG.typingWpmMin, CONFIG.typingWpmMax);
+    const withTypos = options.withTypos ?? true;
+    // Calculate average delay per character (in ms)
+    // WPM = (characters / 5) / minutes
+    // Average word length ~5 characters
+    const charsPerMinute = wpm * 5;
+    const avgDelayMs = (60 * 1000) / charsPerMinute;
+    // Clear existing text first
+    await page.fill(selector, "");
+    await randomDelay(30, 80);
+    // Click to focus
+    await page.click(selector);
+    await randomDelay(20, 60);
+    // Type each character
+    let currentText = "";
+    let i = 0;
+    while (i < text.length) {
+        const char = text[i];
+        // Simulate very rare typo (0.3% chance) and shorter correction
+        if (withTypos && Math.random() < 0.003 && i > 0) {
+            // Type wrong character
+            const wrongChar = randomChar();
+            currentText += wrongChar;
+            await page.fill(selector, currentText);
+            // Shorter notice window for faster typing
+            const noticeDelay = randomFloat(avgDelayMs * 0.6, avgDelayMs * 1.1);
+            await sleep(noticeDelay);
+            // Backspace
+            currentText = currentText.slice(0, -1);
+            await page.fill(selector, currentText);
+            await randomDelay(20, 60);
+        }
+        // Type correct character
+        currentText += char;
+        await page.fill(selector, currentText);
+        // Variable delay between characters – tuned for faster but still human-like typing
+        let delay;
+        if (char === "." || char === "!" || char === "?") {
+            delay = randomFloat(avgDelayMs * 1.05, avgDelayMs * 1.4);
+        }
+        else if (char === " ") {
+            delay = randomFloat(avgDelayMs * 0.5, avgDelayMs * 0.9);
+        }
+        else if (char === ",") {
+            delay = randomFloat(avgDelayMs * 0.9, avgDelayMs * 1.2);
+        }
+        else {
+            // Normal character
+            const variation = randomFloat(0.5, 0.9);
+            delay = avgDelayMs * variation;
+        }
+        await sleep(delay);
+        i++;
+    }
+    // Small delay after finishing typing
+    await randomDelay(50, 120);
+}
+// ============================================================================
+// Mouse Movement
+// ============================================================================
+/**
+ * Move mouse in a realistic curved path to target coordinates
+ * Uses Bezier-like curves with jitter for natural movement
+ *
+ * @param page Playwright page instance
+ * @param targetX Target X coordinate (default: random)
+ * @param targetY Target Y coordinate (default: random)
+ * @param steps Number of steps in movement (default: random 10-25)
+ */
+export async function randomMouseMovement(page, targetX, targetY, steps) {
+    if (!CONFIG.stealthEnabled || !CONFIG.stealthMouseMovements) {
+        return;
+    }
+    const viewport = page.viewportSize() || CONFIG.viewport;
+    targetX = targetX ?? randomInt(100, viewport.width - 100);
+    targetY = targetY ?? randomInt(100, viewport.height - 100);
+    steps = steps ?? randomInt(10, 25);
+    // Start from a random position (we don't know current position)
+    const startX = randomInt(0, viewport.width);
+    const startY = randomInt(0, viewport.height);
+    // Generate curved path using Bezier-like curve
+    for (let step = 0; step < steps; step++) {
+        const progress = step / steps;
+        // Add some randomness to create a natural curve
+        const curveOffsetX = Math.sin(progress * Math.PI) * randomInt(-50, 50);
+        const curveOffsetY = Math.cos(progress * Math.PI) * randomInt(-30, 30);
+        let currentX = startX + (targetX - startX) * progress + curveOffsetX;
+        let currentY = startY + (targetY - startY) * progress + curveOffsetY;
+        // Add micro-jitter (humans never move in perfectly straight lines)
+        const jitterX = randomFloat(-3, 3);
+        const jitterY = randomFloat(-3, 3);
+        currentX = Math.max(0, Math.min(viewport.width, currentX + jitterX));
+        currentY = Math.max(0, Math.min(viewport.height, currentY + jitterY));
+        await page.mouse.move(currentX, currentY);
+        // Variable delay between movements (faster in middle, slower at ends)
+        const delay = 10 + 20 * Math.abs(0.5 - progress);
+        await sleep(delay);
+    }
+}
+// ============================================================================
+// Realistic Click
+// ============================================================================
+/**
+ * Click an element with realistic human behavior
+ * Includes mouse movement, pause, and click
+ *
+ * @param page Playwright page instance
+ * @param selector CSS selector of element to click
+ * @param withMouseMovement Whether to move mouse first (default: true)
+ */
+export async function realisticClick(page, selector, withMouseMovement = true) {
+    if (!CONFIG.stealthEnabled || !CONFIG.stealthMouseMovements) {
+        await page.click(selector);
+        return;
+    }
+    if (withMouseMovement) {
+        // Move mouse to element
+        const element = await page.$(selector);
+        if (element) {
+            const box = await element.boundingBox();
+            if (box) {
+                // Don't click exactly in center (humans are imperfect)
+                const offsetX = randomFloat(-box.width * 0.2, box.width * 0.2);
+                const offsetY = randomFloat(-box.height * 0.2, box.height * 0.2);
+                const targetX = box.x + box.width / 2 + offsetX;
+                const targetY = box.y + box.height / 2 + offsetY;
+                await randomMouseMovement(page, targetX, targetY);
+            }
+        }
+    }
+    // Small pause before clicking
+    await randomDelay(100, 300);
+    // Click
+    await page.click(selector);
+    // Small pause after clicking
+    await randomDelay(150, 400);
+}
+// ============================================================================
+// Smooth Scrolling
+// ============================================================================
+/**
+ * Scroll the page smoothly like a human
+ * Uses multiple small steps for smooth animation
+ *
+ * @param page Playwright page instance
+ * @param amount Scroll amount in pixels (default: random 100-400)
+ * @param direction Scroll direction ("down" or "up")
+ */
+export async function smoothScroll(page, amount, direction = "down") {
+    amount = amount ?? randomInt(100, 400);
+    amount = Math.abs(amount);
+    if (direction === "up") {
+        amount = -amount;
+    }
+    if (!CONFIG.stealthEnabled || !CONFIG.stealthMouseMovements) {
+        await page.evaluate((scrollAmount) => {
+            window.scrollBy({ top: scrollAmount, behavior: "auto" });
+        }, amount);
+        return;
+    }
+    // Scroll in multiple small steps for smoothness
+    const steps = randomInt(8, 15);
+    const stepAmount = amount / steps;
+    for (let i = 0; i < steps; i++) {
+        await page.evaluate((step) => {
+            window.scrollBy({ top: step, behavior: "smooth" });
+        }, stepAmount);
+        await sleep(randomFloat(20, 50));
+    }
+    // Pause after scrolling (humans look at content)
+    await randomDelay(300, 800);
+}
+// ============================================================================
+// Reading Simulation
+// ============================================================================
+/**
+ * Pause as if reading text, based on length
+ * Calculates realistic reading time based on text length and WPM
+ *
+ * @param textLength Number of characters to "read"
+ * @param wpm Reading speed in words per minute (default: random 200-250)
+ */
+export async function readingPause(textLength, wpm) {
+    if (!CONFIG.stealthEnabled || !CONFIG.stealthRandomDelays) {
+        return;
+    }
+    wpm = wpm ?? randomInt(200, 250);
+    // Calculate reading time
+    // Average word length ~5 characters
+    const wordCount = textLength / 5;
+    const minutes = wordCount / wpm;
+    let seconds = minutes * 60;
+    // Add some randomness (humans don't read at constant speed)
+    seconds *= randomFloat(0.8, 1.2);
+    // Cap at reasonable maximum (3 seconds)
+    seconds = Math.min(seconds, 3.0);
+    await sleep(seconds * 1000);
+}
+// ============================================================================
+// Random Mouse Jitter
+// ============================================================================
+/**
+ * Add small random mouse movements to simulate natural fidgeting
+ *
+ * @param page Playwright page instance
+ * @param iterations Number of small movements (default: 3)
+ */
+export async function randomMouseJitter(page, iterations = 3) {
+    if (!CONFIG.stealthEnabled || !CONFIG.stealthMouseMovements) {
+        return;
+    }
+    const viewport = page.viewportSize() || CONFIG.viewport;
+    for (let i = 0; i < iterations; i++) {
+        const targetX = randomInt(0, viewport.width);
+        const targetY = randomInt(0, viewport.height);
+        await page.mouse.move(targetX, targetY, { steps: randomInt(2, 4) });
+        await sleep(randomFloat(100, 300));
+    }
+}
+// ============================================================================
+// Hover Element
+// ============================================================================
+/**
+ * Hover over an element with realistic mouse movement
+ *
+ * @param page Playwright page instance
+ * @param selector CSS selector of element to hover
+ */
+export async function hoverElement(page, selector) {
+    if (!CONFIG.stealthEnabled || !CONFIG.stealthMouseMovements) {
+        await page.hover(selector);
+        return;
+    }
+    const element = await page.$(selector);
+    if (element) {
+        const box = await element.boundingBox();
+        if (box) {
+            // Move to center of element
+            const targetX = box.x + box.width / 2;
+            const targetY = box.y + box.height / 2;
+            await randomMouseMovement(page, targetX, targetY);
+            await page.hover(selector);
+            await randomDelay(200, 500);
+        }
+    }
+}
+// ============================================================================
+// Simulate Reading Page
+// ============================================================================
+/**
+ * Simulate reading a page with scrolling and pauses
+ * Adds realistic behavior of scrolling and reading content
+ *
+ * @param page Playwright page instance
+ */
+export async function simulateReadingPage(page) {
+    if (!CONFIG.stealthEnabled || !CONFIG.stealthRandomDelays) {
+        return;
+    }
+    // Random number of scroll actions
+    const scrollCount = randomInt(1, 3);
+    for (let i = 0; i < scrollCount; i++) {
+        // Scroll down
+        await smoothScroll(page, undefined, "down");
+        // "Read" the visible content
+        await randomDelay(800, 1500);
+        // Sometimes scroll up a bit (humans do this)
+        if (Math.random() < 0.3) {
+            await smoothScroll(page, randomInt(50, 150), "up");
+            await randomDelay(400, 800);
+        }
+    }
+}
+// ============================================================================
+// Exports
+// ============================================================================
+export default {
+    sleep,
+    randomInt,
+    randomFloat,
+    randomChar,
+    gaussian,
+    randomDelay,
+    humanType,
+    randomMouseMovement,
+    realisticClick,
+    smoothScroll,
+    readingPause,
+    randomMouseJitter,
+    hoverElement,
+    simulateReadingPage,
+};
+//# sourceMappingURL=stealth-utils.js.map

package/dist/utils/stealth-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stealth-utils.js","sourceRoot":"","sources":["../../src/utils/stealth-utils.ts"],"names":[],"mappings":"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"}

package/dist/utils/stealth-utils.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tests for stealth-utils.ts
+ *
+ * Unit tests for human-like behavior simulation utilities.
+ */
+export {};
+//# sourceMappingURL=stealth-utils.test.d.ts.map

package/dist/utils/stealth-utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stealth-utils.test.d.ts","sourceRoot":"","sources":["../../src/utils/stealth-utils.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/utils/stealth-utils.test.js

@@ -0,0 +1,72 @@
+/**
+ * Tests for stealth-utils.ts
+ *
+ * Unit tests for human-like behavior simulation utilities.
+ */
+import { describe, it, expect } from 'vitest';
+import { randomInt, randomFloat, randomChar, gaussian, sleep, } from './stealth-utils.js';
+describe('stealth-utils', () => {
+    describe('randomInt', () => {
+        it('should return integer within range', () => {
+            for (let i = 0; i < 100; i++) {
+                const result = randomInt(1, 10);
+                expect(result).toBeGreaterThanOrEqual(1);
+                expect(result).toBeLessThanOrEqual(10);
+                expect(Number.isInteger(result)).toBe(true);
+            }
+        });
+        it('should handle same min and max', () => {
+            expect(randomInt(5, 5)).toBe(5);
+        });
+        it('should handle zero range', () => {
+            expect(randomInt(0, 0)).toBe(0);
+        });
+    });
+    describe('randomFloat', () => {
+        it('should return float within range', () => {
+            for (let i = 0; i < 100; i++) {
+                const result = randomFloat(1.0, 10.0);
+                expect(result).toBeGreaterThanOrEqual(1.0);
+                expect(result).toBeLessThanOrEqual(10.0);
+            }
+        });
+        it('should handle same min and max', () => {
+            expect(randomFloat(5.0, 5.0)).toBe(5.0);
+        });
+    });
+    describe('randomChar', () => {
+        it('should return lowercase letter', () => {
+            for (let i = 0; i < 100; i++) {
+                const result = randomChar();
+                expect(result).toMatch(/^[a-z]$/);
+            }
+        });
+    });
+    describe('gaussian', () => {
+        it('should return values around mean', () => {
+            const mean = 100;
+            const stdDev = 10;
+            const values = [];
+            for (let i = 0; i < 1000; i++) {
+                values.push(gaussian(mean, stdDev));
+            }
+            const avg = values.reduce((a, b) => a + b, 0) / values.length;
+            // Average should be close to mean (within 2 std devs)
+            expect(Math.abs(avg - mean)).toBeLessThan(stdDev * 2);
+        });
+    });
+    describe('sleep', () => {
+        it('should delay for specified time', async () => {
+            const start = Date.now();
+            await sleep(50);
+            const elapsed = Date.now() - start;
+            // Allow some tolerance for timing
+            expect(elapsed).toBeGreaterThanOrEqual(45);
+            expect(elapsed).toBeLessThan(100);
+        });
+        it('should resolve without error', async () => {
+            await expect(sleep(10)).resolves.toBeUndefined();
+        });
+    });
+});
+//# sourceMappingURL=stealth-utils.test.js.map

package/dist/utils/stealth-utils.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stealth-utils.test.js","sourceRoot":"","sources":["../../src/utils/stealth-utils.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EACH,SAAS,EACT,WAAW,EACX,UAAU,EACV,QAAQ,EACR,KAAK,GACR,MAAM,oBAAoB,CAAC;AAE5B,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC3B,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;QACvB,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;YAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC3B,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAChC,MAAM,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;gBACzC,MAAM,CAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;gBACvC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChD,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;YACtC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;YAChC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;QACzB,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;YACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC3B,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBACtC,MAAM,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC;gBAC3C,MAAM,CAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;YAC7C,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;YACtC,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;QACxB,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;YACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC3B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;gBAC5B,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YACtC,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;QACtB,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;YACxC,MAAM,IAAI,GAAG,GAAG,CAAC;YACjB,MAAM,MAAM,GAAG,EAAE,CAAC;YAClB,MAAM,MAAM,GAAa,EAAE,CAAC;YAE5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC5B,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;YACxC,CAAC;YAED,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;YAC9D,sDAAsD;YACtD,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC1D,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE;QACnB,EAAE,CAAC,iCAAiC,EAAE,KAAK,IAAI,EAAE;YAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACzB,MAAM,KAAK,CAAC,EAAE,CAAC,CAAC;YAChB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;YACnC,kCAAkC;YAClC,MAAM,CAAC,OAAO,CAAC,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAAC;YAC3C,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,8BAA8B,EAAE,KAAK,IAAI,EAAE;YAC1C,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;QACrD,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC"}

package/docs/01_configuration.md

@@ -0,0 +1,94 @@
+## Configuration
+
+**No config files needed!** The server works out of the box with sensible defaults.
+
+### Configuration Priority (highest to lowest):
+1. **Tool Parameters** - Claude passes settings like `browser_options` at runtime
+2. **Environment Variables** - Optional overrides for advanced users
+3. **Hardcoded Defaults** - Sensible defaults that work for most users
+
+---
+
+## Tool Parameters (Runtime Configuration)
+
+Claude can control browser behavior via the `browser_options` parameter in tools like `ask_question`, `setup_auth`, and `re_auth`:
+
+```typescript
+browser_options: {
+  show: boolean,              // Show browser window (overrides headless)
+  headless: boolean,          // Run in headless mode (default: true)
+  timeout_ms: number,         // Browser timeout in ms (default: 30000)
+
+  stealth: {
+    enabled: boolean,         // Master switch (default: true)
+    random_delays: boolean,   // Random delays between actions (default: true)
+    human_typing: boolean,    // Human-like typing (default: true)
+    mouse_movements: boolean, // Realistic mouse movements (default: true)
+    typing_wpm_min: number,   // Min typing speed (default: 160)
+    typing_wpm_max: number,   // Max typing speed (default: 240)
+    delay_min_ms: number,     // Min delay between actions (default: 100)
+    delay_max_ms: number,     // Max delay between actions (default: 400)
+  },
+
+  viewport: {
+    width: number,            // Viewport width (default: 1024)
+    height: number,           // Viewport height (default: 768)
+  }
+}
+```
+
+**Example usage:**
+- "Research this and show me the browser" → Sets `show: true`
+- "Use slow typing for this query" → Adjusts typing WPM via stealth settings
+
+---
+
+## Environment Variables (Optional)
+
+For advanced users who want to set global defaults:
+- Auth
+  - `AUTO_LOGIN_ENABLED` — `true|false` (default `false`)
+  - `LOGIN_EMAIL`, `LOGIN_PASSWORD` — for auto‑login if enabled
+  - `AUTO_LOGIN_TIMEOUT_MS` (default `120000`)
+- Stealth / Human-like behavior
+  - `STEALTH_ENABLED` — `true|false` (default `true`) — Master switch for all stealth features
+  - `STEALTH_RANDOM_DELAYS` — `true|false` (default `true`)
+  - `STEALTH_HUMAN_TYPING` — `true|false` (default `true`)
+  - `STEALTH_MOUSE_MOVEMENTS` — `true|false` (default `true`)
+- Typing speed (human‑like)
+  - `TYPING_WPM_MIN` (default 160), `TYPING_WPM_MAX` (default 240)
+- Delays (human‑like)
+  - `MIN_DELAY_MS` (default 100), `MAX_DELAY_MS` (default 400)
+- Browser
+  - `HEADLESS` (default `true`), `BROWSER_TIMEOUT` (ms, default `30000`)
+- Sessions
+  - `MAX_SESSIONS` (default 10), `SESSION_TIMEOUT` (s, default 900)
+- Multi‑instance profile strategy
+  - `NOTEBOOK_PROFILE_STRATEGY` — `auto|single|isolated` (default `auto`)
+  - `NOTEBOOK_CLONE_PROFILE` — clone base profile into isolated dir (default `false`)
+- Cleanup (to prevent disk bloat)
+  - `NOTEBOOK_CLEANUP_ON_STARTUP` (default `true`)
+  - `NOTEBOOK_CLEANUP_ON_SHUTDOWN` (default `true`)
+  - `NOTEBOOK_INSTANCE_TTL_HOURS` (default `72`)
+  - `NOTEBOOK_INSTANCE_MAX_COUNT` (default `20`)
+- Library metadata (optional hints)
+  - `NOTEBOOK_DESCRIPTION`, `NOTEBOOK_TOPICS`, `NOTEBOOK_CONTENT_TYPES`, `NOTEBOOK_USE_CASES`
+  - `NOTEBOOK_URL` — optional; leave empty and manage notebooks via the library
+
+---
+
+## Storage Paths
+
+The server uses platform-specific paths via [env-paths](https://github.com/sindresorhus/env-paths)
+- **Linux**: `~/.local/share/notebooklm-mcp/`
+- **macOS**: `~/Library/Application Support/notebooklm-mcp/`
+- **Windows**: `%LOCALAPPDATA%\notebooklm-mcp\`
+
+**What's stored:**
+- `chrome_profile/` - Persistent Chrome browser profile with login session
+- `browser_state/` - Browser context state and cookies
+- `library.json` - Your notebook library with metadata
+- `chrome_profile_instances/` - Isolated Chrome profiles for concurrent sessions
+
+**No config.json file** - Configuration is purely via environment variables or tool parameters!
+

package/docs/02_tools.md

@@ -0,0 +1,34 @@
+## Tools
+
+### Core
+- `ask_question`
+  - Parameters: `question` (string, required), optional `session_id`, `notebook_id`, `notebook_url`, `show_browser`.
+  - Returns NotebookLM's answer plus the follow-up reminder.
+- `list_sessions`, `close_session`, `reset_session`
+  - Inspect or manage active browser sessions.
+- `get_health`
+  - Summaries auth status, active sessions, and configuration.
+- `setup_auth`
+  - Opens the persistent Chrome profile so you can log in manually.
+- `re_auth`
+  - Switch to a different Google account or re-authenticate.
+  - Use when NotebookLM rate limit is reached (50 queries/day for free accounts).
+  - Closes all sessions, clears auth data, and opens browser for fresh login.
+
+### Notebook library
+- `add_notebook` – Safe conversational add; expects confirmation before writing.
+- `list_notebooks` – Returns id, name, topics, URL, metadata for every entry.
+- `get_notebook` – Fetch a single notebook by id.
+- `select_notebook` – Set the active default notebook.
+- `update_notebook` – Modify metadata fields.
+- `remove_notebook` – Removes entries from the library (not the original NotebookLM notebook).
+- `search_notebooks` – Simple query across name/description/topics/tags.
+- `get_library_stats` – Aggregate statistics (total notebooks, usage counts, etc.).
+
+### Resources
+- `notebooklm://library`
+  - JSON representation of the full library: active notebook, stats, individual notebooks.
+- `notebooklm://library/{id}`
+  - Fetch metadata for a specific notebook. The `{id}` completion pulls from the library automatically.
+
+**Remember:** Every `ask_question` response ends with a reminder that nudges your agent to keep asking until the user’s task is fully addressed.