@cosmocoder/mcp-web-docs 1.0.0 → 1.1.0

package/README.md

@@ -1,5 +1,11 @@
 # MCP Web Docs
 
+[![npm version](https://img.shields.io/npm/v/@cosmocoder/mcp-web-docs.svg)](https://www.npmjs.com/package/@cosmocoder/mcp-web-docs)
+[![npm downloads](https://img.shields.io/npm/dm/@cosmocoder/mcp-web-docs.svg)](https://www.npmjs.com/package/@cosmocoder/mcp-web-docs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.19.0-brightgreen.svg)](https://nodejs.org/)
+[![CI](https://github.com/cosmocoder/mcp-web-docs/actions/workflows/release.yml/badge.svg)](https://github.com/cosmocoder/mcp-web-docs/actions/workflows/release.yml)
+
 **Index Any Documentation. Search Locally. Stay Private.**
 
 A self-hosted Model Context Protocol (MCP) server that crawls, indexes, and searches documentation from *any* website. Unlike remote MCP servers limited to GitHub repos or pre-indexed libraries, web-docs gives you full control over what gets indexed — including private documentation behind authentication.
@@ -32,6 +38,7 @@ AI assistants struggle with documentation:
 
 - **🌐 Universal Crawler** - Works with any documentation site, not just GitHub
 - **🔍 Hybrid Search** - Combines full-text search (FTS) with semantic vector search
+- **🏷️ Tags & Categories** - Organize docs with tags and filter searches by project, team, or category
 - **🔐 Authentication Support** - Crawl private/protected docs with interactive browser login (auto-detects your default browser)
 - **📊 Smart Extraction** - Automatically extracts code blocks, props tables, and structured content
 - **⚡ Local Embeddings** - Uses FastEmbed for fast, private embedding generation (no API keys)
@@ -46,11 +53,21 @@ AI assistants struggle with documentation:
 
 - Node.js >= 22.19.0
 
-### Setup
+### Option 1: Install from NPM (Recommended)
+
+```bash
+npm install -g @cosmocoder/mcp-web-docs
+```
+
+### Option 2: Run with npx
+
+No installation required - just configure your MCP client to use npx (see below).
+
+### Option 3: Build from Source
 
 ```bash
 # Clone the repository
-git clone https://github.com/user/mcp-web-docs.git
+git clone https://github.com/cosmocoder/mcp-web-docs.git
 cd mcp-web-docs
 
 # Install dependencies (automatically installs Playwright browsers)
@@ -67,6 +84,30 @@ npm run build
 
 Add to your Cursor MCP settings (`~/.cursor/mcp.json`):
 
+**Using npx (no install required):**
+```json
+{
+  "mcpServers": {
+    "web-docs": {
+      "command": "npx",
+      "args": ["-y", "@cosmocoder/mcp-web-docs"]
+    }
+  }
+}
+```
+
+**Using global install:**
+```json
+{
+  "mcpServers": {
+    "web-docs": {
+      "command": "mcp-web-docs"
+    }
+  }
+}
+```
+
+**Using local build:**
 ```json
 {
   "mcpServers": {
@@ -85,12 +126,24 @@ Add to your Cursor MCP settings (`~/.cursor/mcp.json`):
 
 Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
+**Using npx:**
 ```json
 {
   "mcpServers": {
     "web-docs": {
-      "command": "node",
-      "args": ["/path/to/mcp-web-docs/build/index.js"]
+      "command": "npx",
+      "args": ["-y", "@cosmocoder/mcp-web-docs"]
+    }
+  }
+}
+```
+
+**Using global install:**
+```json
+{
+  "mcpServers": {
+    "web-docs": {
+      "command": "mcp-web-docs"
     }
   }
 }
@@ -103,12 +156,24 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 
 Add to `.vscode/mcp.json` in your workspace:
 
+**Using npx:**
 ```json
 {
   "servers": {
     "web-docs": {
-      "command": "node",
-      "args": ["/path/to/mcp-web-docs/build/index.js"]
+      "command": "npx",
+      "args": ["-y", "@cosmocoder/mcp-web-docs"]
+    }
+  }
+}
+```
+
+**Using global install:**
+```json
+{
+  "servers": {
+    "web-docs": {
+      "command": "mcp-web-docs"
     }
   }
 }
@@ -121,12 +186,24 @@ Add to `.vscode/mcp.json` in your workspace:
 
 Add to `~/.codeium/windsurf/mcp_config.json`:
 
+**Using npx:**
 ```json
 {
   "mcpServers": {
     "web-docs": {
-      "command": "node",
-      "args": ["/path/to/mcp-web-docs/build/index.js"]
+      "command": "npx",
+      "args": ["-y", "@cosmocoder/mcp-web-docs"]
+    }
+  }
+}
+```
+
+**Using global install:**
+```json
+{
+  "mcpServers": {
+    "web-docs": {
+      "command": "mcp-web-docs"
     }
   }
 }
@@ -139,12 +216,26 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 
 Add to `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`:
 
+**Using npx:**
 ```json
 {
   "mcpServers": {
     "web-docs": {
-      "command": "node",
-      "args": ["/path/to/mcp-web-docs/build/index.js"],
+      "command": "npx",
+      "args": ["-y", "@cosmocoder/mcp-web-docs"],
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+**Using global install:**
+```json
+{
+  "mcpServers": {
+    "web-docs": {
+      "command": "mcp-web-docs",
       "disabled": false,
       "autoApprove": []
     }
@@ -154,6 +245,38 @@ Add to `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude
 
 </details>
 
+<details>
+<summary><b>RooCode</b></summary>
+
+**Global configuration:** Open RooCode → Click MCP icon → "Edit Global MCP"
+
+**Project-level configuration:** Create `.roo/mcp.json` at your project root
+
+**Using npx:**
+```json
+{
+  "mcpServers": {
+    "web-docs": {
+      "command": "npx",
+      "args": ["-y", "@cosmocoder/mcp-web-docs"]
+    }
+  }
+}
+```
+
+**Using global install:**
+```json
+{
+  "mcpServers": {
+    "web-docs": {
+      "command": "mcp-web-docs"
+    }
+  }
+}
+```
+
+</details>
+
 ---
 
 ## ⚡ Quick Start
@@ -194,9 +317,10 @@ Add a new documentation site for indexing.
 ```typescript
 add_documentation({
   url: "https://docs.example.com/",
-  title: "Example Docs",        // Optional
-  id: "example-docs",           // Optional custom ID
-  auth: {                       // Optional authentication
+  title: "Example Docs",              // Optional
+  id: "example-docs",                 // Optional custom ID
+  tags: ["frontend", "mycompany"],    // Optional tags for categorization
+  auth: {                             // Optional authentication
     requiresAuth: true,
     // browser auto-detected from OS settings if omitted
     loginTimeoutSecs: 300
@@ -211,8 +335,9 @@ Search through indexed documentation using hybrid search (FTS + semantic).
 ```typescript
 search_documentation({
   query: "how to configure authentication",
-  url: "https://docs.example.com/",  // Optional: filter to specific site
-  limit: 10                           // Optional: max results
+  url: "https://docs.example.com/",    // Optional: filter to specific site
+  tags: ["frontend", "mycompany"],     // Optional: filter by tags
+  limit: 10                            // Optional: max results
 })
 ```
 
@@ -230,7 +355,22 @@ authenticate({
 
 ### `list_documentation`
 
-List all indexed documentation sites.
+List all indexed documentation sites with their metadata including tags.
+
+### `set_tags`
+
+Set or update tags for a documentation site. Tags help categorize and filter documentation.
+
+```typescript
+set_tags({
+  url: "https://docs.example.com/",
+  tags: ["frontend", "react", "mycompany"]  // Replaces existing tags
+})
+```
+
+### `list_tags`
+
+List all available tags with usage counts. Useful to see what tags exist across your indexed docs.
 
 ### `reindex_documentation`
 
@@ -285,15 +425,50 @@ API references, configuration, or library usage.
 
 ### Scoping Searches
 
-If you have multiple sites indexed, filter by URL to search within a specific site:
+If you have multiple sites indexed, filter by URL or tags:
 
 ```typescript
+// Filter by specific site URL
 search_documentation({
   query: "routing",
-  url: "https://nextjs.org/docs/"  // Only search Next.js docs
+  url: "https://nextjs.org/docs/"
+})
+
+// Filter by tags (searches all docs with matching tags)
+search_documentation({
+  query: "Button component",
+  tags: ["frontend", "mycompany"]  // Only docs tagged with BOTH tags
+})
+```
+
+### Organizing with Tags
+
+Tags help organize documentation when you have multiple related sites. Add tags when indexing:
+
+```typescript
+// Index frontend package docs
+add_documentation({
+  url: "https://docs.mycompany.com/ui-components/",
+  tags: ["frontend", "mycompany", "react"]
+})
+
+// Index backend API docs
+add_documentation({
+  url: "https://docs.mycompany.com/api/",
+  tags: ["backend", "mycompany", "api"]
 })
 ```
 
+Later, search across all frontend docs:
+```typescript
+search_documentation({
+  query: "authentication",
+  tags: ["frontend"]  // Searches all frontend-tagged docs
+})
+```
+
+You can also add tags to existing documentation with `set_tags`.
+
 ---
 
 ## 🚨 Troubleshooting

package/build/crawler/auth.d.ts

@@ -55,13 +55,21 @@ export declare class AuthManager {
      */
     clearSession(url: string): Promise<void>;
     /**
-     * Validate that a stored session is still valid by making a test request.
-     * This detects expired sessions by checking for:
-     * 1. Redirects to login/auth pages
-     * 2. Login page content in the response
+     * Check if stored cookies have expired based on their expiration timestamps.
+     * This is a fast check that doesn't require launching a browser.
+     *
+     * @param storageStateJson - The decrypted storage state JSON
+     * @param domain - The domain to check cookies for
+     * @returns Object with expiration status and details
+     */
+    private checkCookieExpiration;
+    /**
+     * Validate that a stored session is still valid.
+     * First checks cookie expiration timestamps (fast, no network).
+     * Falls back to browser-based validation for edge cases.
      *
      * @param url - The protected URL to validate against
-     * @param browserType - Browser type to use for validation
+     * @param browserType - Browser type to use for browser-based validation (if needed)
      * @returns Validation result indicating if session is still valid
      */
     validateSession(url: string, browserType?: BrowserType): Promise<{
@@ -111,7 +119,10 @@ export declare class AuthManager {
      * Detection methods (in order of priority):
      * 1. If successPattern is provided: wait for URL to match the regex
      * 2. If successSelector is provided: wait for the CSS selector to appear
-     * 3. Default: poll for common login success indicators (logout button, user menu, URL change)
+     * 3. Default: poll for common login success indicators or return to target domain
+     *
+     * For multi-step OAuth flows (e.g., GitHub Pages → GitHub Login → Okta → back),
+     * the method tracks when the user returns to the original target domain.
      */
     private waitForLogin;
     /**

package/build/crawler/auth.js

@@ -164,13 +164,72 @@ export class AuthManager {
         }
     }
     /**
-     * Validate that a stored session is still valid by making a test request.
-     * This detects expired sessions by checking for:
-     * 1. Redirects to login/auth pages
-     * 2. Login page content in the response
+     * Check if stored cookies have expired based on their expiration timestamps.
+     * This is a fast check that doesn't require launching a browser.
+     *
+     * @param storageStateJson - The decrypted storage state JSON
+     * @param domain - The domain to check cookies for
+     * @returns Object with expiration status and details
+     */
+    checkCookieExpiration(storageStateJson, domain) {
+        try {
+            const storageState = safeJsonParse(storageStateJson, StorageStateSchema);
+            const cookies = storageState.cookies || [];
+            const now = Date.now() / 1000; // Convert to seconds (cookie expires is in seconds)
+            // Filter cookies relevant to this domain
+            const domainLower = domain.toLowerCase();
+            const relevantCookies = cookies.filter((cookie) => {
+                const cookieDomain = cookie.domain.toLowerCase().replace(/^\./, ''); // Remove leading dot
+                return domainLower === cookieDomain || domainLower.endsWith('.' + cookieDomain);
+            });
+            if (relevantCookies.length === 0) {
+                // No domain-specific cookies, check all cookies
+                // This handles cases where auth cookies are on a different domain (e.g., github.com for github.io)
+                logger.debug(`[AuthManager] No cookies found for ${domain}, checking all ${cookies.length} cookies`);
+            }
+            const cookiesToCheck = relevantCookies.length > 0 ? relevantCookies : cookies;
+            let expiredCount = 0;
+            const details = [];
+            for (const cookie of cookiesToCheck) {
+                // Skip cookies without expiration (session cookies)
+                if (cookie.expires === undefined || cookie.expires === -1 || cookie.expires === 0) {
+                    continue;
+                }
+                if (cookie.expires < now) {
+                    expiredCount++;
+                    const expiredAgo = Math.round((now - cookie.expires) / 3600); // Hours ago
+                    details.push(`Cookie "${cookie.name}" expired ${expiredAgo}h ago`);
+                }
+            }
+            // Consider session expired if ANY auth-related cookies are expired
+            // Common auth cookie names
+            const authCookiePatterns = /session|auth|token|jwt|sid|login|user|identity|sso|saml|oauth/i;
+            const expiredAuthCookies = cookiesToCheck.filter((cookie) => {
+                if (!cookie.expires || cookie.expires === -1 || cookie.expires === 0)
+                    return false;
+                return cookie.expires < now && authCookiePatterns.test(cookie.name);
+            });
+            return {
+                hasExpiredCookies: expiredCount > 0,
+                expiredCount,
+                totalCount: cookiesToCheck.length,
+                details: expiredAuthCookies.length > 0
+                    ? details.filter((d) => expiredAuthCookies.some((c) => d.includes(c.name)))
+                    : details.slice(0, 3), // Limit details
+            };
+        }
+        catch (error) {
+            logger.debug(`[AuthManager] Error checking cookie expiration:`, error);
+            return { hasExpiredCookies: false, expiredCount: 0, totalCount: 0, details: [] };
+        }
+    }
+    /**
+     * Validate that a stored session is still valid.
+     * First checks cookie expiration timestamps (fast, no network).
+     * Falls back to browser-based validation for edge cases.
      *
      * @param url - The protected URL to validate against
-     * @param browserType - Browser type to use for validation
+     * @param browserType - Browser type to use for browser-based validation (if needed)
      * @returns Validation result indicating if session is still valid
      */
     async validateSession(url, browserType = 'chromium') {
@@ -181,6 +240,25 @@ export class AuthManager {
             logger.info(`[AuthManager] No stored session found for ${domain}`);
             return { isValid: false, reason: 'No stored session found' };
         }
+        // Fast check: Look at cookie expiration timestamps
+        const cookieCheck = this.checkCookieExpiration(storageStateJson, domain);
+        logger.debug(`[AuthManager] Cookie check: ${cookieCheck.expiredCount}/${cookieCheck.totalCount} expired`);
+        if (cookieCheck.hasExpiredCookies) {
+            const reason = `Session cookies have expired (${cookieCheck.expiredCount} expired). ${cookieCheck.details.join('; ')}`;
+            logger.warn(`[AuthManager] Session expired based on cookie timestamps: ${reason}`);
+            return {
+                isValid: false,
+                reason,
+                loginDetection: {
+                    isLoginPage: false,
+                    confidence: 1.0,
+                    reasons: [`Cookie expiration check: ${cookieCheck.details.join(', ')}`],
+                },
+            };
+        }
+        // If no cookies have explicit expiration, or all have valid timestamps,
+        // do a quick browser-based check to be sure
+        logger.debug(`[AuthManager] Cookie timestamps look valid, performing browser-based validation...`);
         let browser = null;
         let context = null;
         try {
@@ -200,17 +278,26 @@ export class AuthManager {
                 waitUntil: 'domcontentloaded',
                 timeout: 30000,
             });
+            // Wait for potential JavaScript redirects
+            await page.waitForLoadState('networkidle', { timeout: 10000 }).catch(() => { });
+            // Additional wait for JS-based auth redirects (GitHub Pages, etc.)
+            await page.waitForTimeout(2000);
             const finalUrl = page.url();
             logger.debug(`[AuthManager] Final URL after navigation: ${finalUrl}`);
-            // Check 1: Were we redirected to a login page?
-            if (isLoginPageUrl(finalUrl) && finalUrl !== url) {
-                logger.warn(`[AuthManager] Session appears expired - redirected to login page: ${finalUrl}`);
-                return {
-                    isValid: false,
-                    reason: 'Redirected to login page - session has expired',
-                    finalUrl,
-                    loginDetection: { isLoginPage: true, confidence: 1.0, reasons: ['Redirected to login URL'] },
-                };
+            // Check 1: Were we redirected to a different domain (likely auth)?
+            const finalDomain = new URL(finalUrl).hostname.toLowerCase();
+            const expectedDomain = domain.toLowerCase();
+            if (finalDomain !== expectedDomain && !finalDomain.endsWith('.' + expectedDomain)) {
+                // Redirected to a different domain - check if it's a login page
+                if (isLoginPageUrl(finalUrl)) {
+                    logger.warn(`[AuthManager] Session appears expired - redirected to login page: ${finalUrl}`);
+                    return {
+                        isValid: false,
+                        reason: `Redirected to login page on different domain (${finalDomain})`,
+                        finalUrl,
+                        loginDetection: { isLoginPage: true, confidence: 1.0, reasons: ['Redirected to external login URL'] },
+                    };
+                }
             }
             // Check 2: Did we get an auth-related HTTP status?
             const status = response?.status();
@@ -223,8 +310,6 @@ export class AuthManager {
                 };
             }
             // Check 3: Does the page content look like a login page?
-            // Wait for content to load
-            await page.waitForLoadState('networkidle', { timeout: 10000 }).catch(() => { });
             const pageContent = await page.content();
             const bodyText = await page.evaluate(() => document.body?.textContent || '');
             const loginDetection = detectLoginPage(bodyText + pageContent, finalUrl);
@@ -378,6 +463,7 @@ export class AuthManager {
             logger.info(`[AuthManager] ⏳ You have ${loginTimeoutSecs} seconds to complete login.`);
             // Wait for successful login
             const loginSuccess = await this.waitForLogin(page, {
+                targetUrl: url, // The original target URL to return to
                 successPattern: loginSuccessPattern,
                 successSelector: loginSuccessSelector,
                 timeoutSecs: loginTimeoutSecs,
@@ -405,17 +491,28 @@ export class AuthManager {
      * Detection methods (in order of priority):
      * 1. If successPattern is provided: wait for URL to match the regex
      * 2. If successSelector is provided: wait for the CSS selector to appear
-     * 3. Default: poll for common login success indicators (logout button, user menu, URL change)
+     * 3. Default: poll for common login success indicators or return to target domain
+     *
+     * For multi-step OAuth flows (e.g., GitHub Pages → GitHub Login → Okta → back),
+     * the method tracks when the user returns to the original target domain.
      */
     async waitForLogin(page, options) {
-        const { successPattern, successSelector, timeoutSecs } = options;
+        const { targetUrl, successPattern, successSelector, timeoutSecs } = options;
         const startTime = Date.now();
         const timeoutMs = timeoutSecs * 1000;
+        // Extract target domain for multi-step OAuth flow detection
+        let targetDomain;
+        try {
+            targetDomain = new URL(targetUrl).hostname.toLowerCase();
+        }
+        catch {
+            targetDomain = '';
+        }
         logger.debug(`[AuthManager] Login detection method: ${successPattern
             ? `URL pattern: ${successPattern}`
             : successSelector
                 ? `CSS selector: ${successSelector}`
-                : 'auto-detect (looking for logout button, user menu, or URL change)'}`);
+                : `auto-detect (target domain: ${targetDomain})`}`);
         // If we have specific success criteria, wait for them
         if (successPattern) {
             // Validate the regex pattern to prevent ReDoS attacks
@@ -450,53 +547,90 @@ export class AuthManager {
         // Default: wait for navigation away from login page or for page to show logged-in state
         // Poll for changes that indicate successful login
         logger.info(`[AuthManager] Using auto-detection for login success...`);
+        logger.info(`[AuthManager] Target domain: ${targetDomain}`);
         logger.info(`[AuthManager] The browser will stay open until you login or ${timeoutSecs} seconds pass.`);
         let lastLogTime = 0;
         // Track the initial URL to detect navigation
         const initialUrl = page.url();
         let hasNavigatedAway = false;
         let wasOnLoginPage = false;
+        const visitedDomains = new Set();
+        // Enhanced login page URL pattern including common IdPs
+        const loginPagePattern = /login|signin|sign-in|auth|sso|oauth|session|okta|oktapreview|auth0|onelogin|pingone|pingidentity|pingfederate|duosecurity|adfs|saml|idp/i;
         while (Date.now() - startTime < timeoutMs) {
             try {
                 const currentUrl = page.url();
                 const elapsed = Math.round((Date.now() - startTime) / 1000);
+                // Extract current domain
+                let currentDomain;
+                try {
+                    currentDomain = new URL(currentUrl).hostname.toLowerCase();
+                }
+                catch {
+                    currentDomain = '';
+                }
+                // Track visited domains for debugging
+                if (currentDomain && !visitedDomains.has(currentDomain)) {
+                    visitedDomains.add(currentDomain);
+                    logger.debug(`[AuthManager] Visited new domain: ${currentDomain}`);
+                }
                 // Log status every 10 seconds
                 if (elapsed - lastLogTime >= 10) {
                     logger.info(`[AuthManager] Still waiting for login... (${elapsed}s elapsed, current URL: ${currentUrl})`);
                     lastLogTime = elapsed;
                 }
-                // Check if we're on a login-like page
-                const isLoginPage = /login|signin|sign-in|auth|sso|oauth|session/i.test(currentUrl);
+                // Check if we're on a login-like page (URL-based detection)
+                const isLoginPageUrl = loginPagePattern.test(currentUrl);
+                // Check if we're on a known identity provider domain
+                const isIdpDomain = /okta|auth0|onelogin|pingidentity|duosecurity|microsoftonline|accounts\.google/i.test(currentDomain);
+                const isLoginPage = isLoginPageUrl || isIdpDomain;
                 // Track if we've been to a login page (to know when we've successfully logged in)
                 if (isLoginPage) {
                     wasOnLoginPage = true;
-                    logger.debug(`[AuthManager] Detected login page: ${currentUrl}`);
+                    logger.debug(`[AuthManager] Detected login/IdP page: ${currentUrl}`);
                 }
                 // Track navigation away from initial URL
                 if (currentUrl !== initialUrl && !hasNavigatedAway) {
                     hasNavigatedAway = true;
                     logger.debug(`[AuthManager] Navigation detected: ${initialUrl} → ${currentUrl}`);
                 }
+                // Check if we've returned to the target domain after visiting login pages
+                const isBackAtTargetDomain = targetDomain && (currentDomain === targetDomain || currentDomain.endsWith('.' + targetDomain));
                 // Check for common logged-in indicators
                 const hasLogoutButton = (await page.locator('text=/log\\s*out|sign\\s*out/i').count()) > 0;
                 const hasUserMenu = (await page.locator('[class*="user"], [class*="avatar"], [class*="profile"]').count()) > 0;
-                // Only consider login successful if:
-                // 1. We're not on a login page, AND
-                // 2. We have logged-in indicators OR we were on a login page and navigated away
+                // Success condition 1: Found logout button or user menu (and not on login page)
                 if (!isLoginPage && (hasLogoutButton || hasUserMenu)) {
                     logger.info(`[AuthManager] ✓ Login indicators found (logout button or user menu)`);
                     await page.waitForTimeout(1000);
                     return true;
                 }
-                // For GitHub Pages: only consider successful if we were on login page and came back
-                if (currentUrl.includes('github.io') && wasOnLoginPage && !isLoginPage) {
-                    // We were redirected to login and now we're back on the github.io page
+                // Success condition 2: Returned to target domain after visiting login page(s)
+                // This handles multi-step OAuth flows (GitHub Pages → GitHub → Okta → back to GitHub Pages)
+                if (isBackAtTargetDomain && wasOnLoginPage && !isLoginPage) {
+                    // We were redirected to login/IdP and now we're back on the target domain
                     const bodyText = (await page.locator('body').textContent()) || '';
                     // Make sure it's not an error page
                     if (bodyText.length > 100 && !bodyText.includes('404') && !bodyText.includes('not found')) {
-                        logger.info(`[AuthManager] ✓ Returned to GitHub Pages after login`);
-                        await page.waitForTimeout(1000);
-                        return true;
+                        logger.info(`[AuthManager] ✓ Returned to target domain (${currentDomain}) after login. Visited ${visitedDomains.size} domains during auth flow.`);
+                        // Wait a bit longer for any post-login redirects to settle
+                        await page.waitForTimeout(2000);
+                        // Double-check we're still on target domain after waiting
+                        const finalUrl = page.url();
+                        let finalDomain;
+                        try {
+                            finalDomain = new URL(finalUrl).hostname.toLowerCase();
+                        }
+                        catch {
+                            finalDomain = '';
+                        }
+                        if (finalDomain === targetDomain || finalDomain.endsWith('.' + targetDomain)) {
+                            logger.info(`[AuthManager] ✓ Confirmed on target domain: ${finalUrl}`);
+                            return true;
+                        }
+                        else {
+                            logger.debug(`[AuthManager] Redirected away from target domain after waiting, continuing...`);
+                        }
                     }
                 }
                 // Wait a bit before checking again
@@ -509,6 +643,7 @@ export class AuthManager {
             }
         }
         logger.warn(`[AuthManager] Login detection timed out after ${timeoutSecs} seconds`);
+        logger.debug(`[AuthManager] Visited ${visitedDomains.size} domains during auth flow`);
         return false;
     }
     /**