mcpbrowser 0.3.31 → 0.3.33

package/README.md

@@ -31,6 +31,7 @@ Example workflow for AI assistant to use MCPBrowser
   - [npm Package](#option-4-npm-package)
 - [MCP Tools](#mcp-tools)
   - [fetch_webpage](#fetch_webpage)
+  - [execute_javascript](#execute_javascript)
   - [click_element](#click_element)
   - [type_text](#type_text)
   - [get_current_html](#get_current_html)
@@ -165,6 +166,33 @@ Fetches web pages using your Chrome/Edge browser. Handles authentication, CAPTCH
 
 ---
 
+### `execute_javascript`
+
+Executes a JavaScript snippet in the active page context and returns the result with metadata (execution time, truncation flag, URL-change flag). Use this for structured extraction (e.g., inbox rows) or JS-driven UI actions that are unreliable via protocol clicks.
+
+**⚠️ Note:** Page must be already loaded via `fetch_webpage` first.
+
+**Parameters:**
+- `url` (string, required) - The URL of the page (must match a previously fetched page)
+- `script` (string, required) - JavaScript source to execute in the page context
+- `timeoutMs` (number, optional, default: `30000`, max: `60000`) - Execution timeout
+- `returnType` (string, optional, default: `json`) - `json` | `text` | `void`
+
+**Returns:** Serialized result (`outerHTML` for DOM nodes), `type`, `executionTimeMs`, `truncated`, `urlChanged`, `currentUrl`, and structured `error` when the script throws or times out.
+
+**Example:**
+```json
+{
+  "action": "execute_javascript",
+  "url": "https://mail.google.com/",
+  "script": "[...document.querySelectorAll('tr.zA')].slice(0,5).map((row,i)=>({index:i+1,sender:row.querySelector('.zF,.yP')?.textContent,subject:row.querySelector('.bog')?.textContent}))",
+  "timeoutMs": 30000,
+  "returnType": "json"
+}
+```
+
+---
+
 ### `click_element`
 
 Clicks on any clickable element (buttons, links, divs with onclick handlers, etc.). Can target by CSS selector or visible text content. Automatically scrolls element into view and waits for page stability after clicking.
@@ -195,6 +223,8 @@ Clicks on any clickable element (buttons, links, divs with onclick handlers, etc
 { url: "https://example.com", text: "Load More", postClickWait: 2000 }
 ```
 
+**Fallback behavior:** If the native click times out after locating the element, MCPBrowser automatically retries with a JavaScript-based click and returns `fallbackUsed`, `nativeAttempt`, and `fallbackAttempt` metadata. If both attempts fail, the response lists both errors so you can choose another strategy.
+
 ---
 
 ### `type_text`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpbrowser",
-  "version": "0.3.31",
+  "version": "0.3.33",
   "mcpName": "io.github.cherchyk/mcpbrowser",
   "type": "module",
   "description": "MCP browser server - fetch web pages using real Chrome/Edge/Brave browser. Handles authentication, SSO, CAPTCHAs, and anti-bot protection. Browser automation for AI assistants.",

package/src/actions/click-element.js

@@ -33,48 +33,38 @@ import logger from '../core/logger.js';
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
  */
 
-// ============================================================================
-// RESPONSE CLASS
-// ============================================================================
-
 /**
- * Response for successful click_element operations
+ * Structured response for click_element with JS fallback metadata
  */
-export class ClickElementSuccessResponse extends MCPResponse {
-  /**
-   * @param {string} currentUrl - URL after click
-   * @param {string} message - Success message
-   * @param {string|null} html - Page HTML if returnHtml was true
-   * @param {string[]} nextSteps - Suggested next actions
-   */
-  constructor(currentUrl, message, html, nextSteps) {
+export class ClickWithFallbackResponse extends MCPResponse {
+  constructor({ status, fallbackUsed = false, nativeAttempt, fallbackAttempt, postClickWait, currentUrl, html = null, message, nextSteps = [] }) {
     super(nextSteps);
-    
-    if (typeof currentUrl !== 'string') {
-      throw new TypeError('currentUrl must be a string');
-    }
-    if (typeof message !== 'string') {
-      throw new TypeError('message must be a string');
-    }
-    if (html !== null && typeof html !== 'string') {
-      throw new TypeError('html must be a string or null');
-    }
-    
+    this.status = status;
+    this.fallbackUsed = fallbackUsed;
+    this.nativeAttempt = nativeAttempt;
+    this.fallbackAttempt = fallbackAttempt;
+    this.postClickWait = postClickWait;
     this.currentUrl = currentUrl;
-    this.message = message;
     this.html = html;
+    this.message = message;
   }
 
   _getAdditionalFields() {
     return {
+      status: this.status,
+      fallbackUsed: this.fallbackUsed,
+      nativeAttempt: this.nativeAttempt,
+      fallbackAttempt: this.fallbackAttempt,
+      postClickWait: this.postClickWait,
       currentUrl: this.currentUrl,
-      message: this.message,
-      html: this.html
+      html: this.html,
+      message: this.message
     };
   }
 
   getTextSummary() {
-    return this.message || "Element clicked successfully";
+    const base = this.message || 'Click completed';
+    return this.fallbackUsed ? `${base} (JS fallback used)` : base;
   }
 }
 
@@ -106,8 +96,38 @@ export const CLICK_ELEMENT_TOOL = {
   outputSchema: {
     type: "object",
     properties: {
+      status: { type: "string", enum: ["success", "failed"], description: "Overall click status after native and fallback attempts" },
+      fallbackUsed: { type: "boolean", description: "True when native click timed out and JS fallback ran" },
+      nativeAttempt: { 
+        type: "object",
+        properties: {
+          status: { type: "string", enum: ["success", "timeout", "error"] },
+          durationMs: { type: "number" },
+          error: { type: ["string", "null"] }
+        },
+        required: ["status", "durationMs"]
+      },
+      fallbackAttempt: {
+        type: ["object", "null"],
+        properties: {
+          status: { type: "string", enum: ["success", "timeout", "error"] },
+          durationMs: { type: "number" },
+          error: { type: ["string", "null"] }
+        },
+        required: ["status", "durationMs"],
+        description: "Present when fallbackUsed is true"
+      },
+      postClickWait: {
+        type: "object",
+        properties: {
+          applied: { type: "boolean" },
+          waitedMs: { type: "number" }
+        },
+        required: ["applied", "waitedMs"],
+        description: "Post-click wait metadata"
+      },
       currentUrl: { type: "string", description: "URL after click" },
-      message: { type: "string", description: "Success message" },
+      message: { type: "string", description: "Status message" },
       html: { 
         type: ["string", "null"], 
         description: "Page HTML if returnHtml was true, null otherwise" 
@@ -118,7 +138,7 @@ export const CLICK_ELEMENT_TOOL = {
         description: "Suggested next actions"
       }
     },
-    required: ["currentUrl", "message", "html", "nextSteps"],
+    required: ["status", "fallbackUsed", "nativeAttempt", "currentUrl", "message", "html", "nextSteps"],
     additionalProperties: false
   }
 };
@@ -252,28 +272,60 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
     }
 
     // Scroll element into view and click
-    // For automation, use instant scroll instead of smooth animation to avoid delays
     await page.evaluate(el => el.scrollIntoView({ behavior: 'auto', block: 'center' }), elementHandle);
-    // original:
-    // Smooth scroll (commented out for performance):
-    // await page.evaluate(el => el.scrollIntoView({ behavior: 'smooth', block: 'center' }), elementHandle);
-    // await new Promise(r => setTimeout(r, 300)); // Brief delay after scroll
-    
+
+    const attemptClick = async (label, fn, timeoutMs) => {
+      const start = Date.now();
+      let timeoutId;
+      const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+      });
+
+      try {
+        await Promise.race([fn(), timeoutPromise]);
+        return { status: 'success', durationMs: Date.now() - start };
+      } catch (error) {
+        const status = /timeout|timed.out/i.test(error?.message || '') ? 'timeout' : 'error';
+        return { status, durationMs: Date.now() - start, error: error?.message || 'Unknown error' };
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    };
+
+    const clickTimeout = Math.min(Math.max(waitForElementTimeout, 500), 60000);
     logger.debug(`Clicking: ${selector || `text="${text}"`}`);
-    await elementHandle.click();
-    
-    // Wait for page to stabilize (handles both navigation and SPA content updates)
-    logger.debug(`Waiting for page to be ready${returnHtml ? '' : ' (fast mode)'}...`);
-    await waitForPageReady(page, { afterInteraction: true });
-    
-    // Wait for SPAs to render dynamic content after click
-    if (postClickWait > 0) {
-      await new Promise(resolve => setTimeout(resolve, postClickWait));
+    const nativeAttempt = await attemptClick('native click', () => elementHandle.click(), clickTimeout);
+
+    let fallbackUsed = false;
+    let fallbackAttempt = null;
+
+    if (nativeAttempt.status === 'timeout') {
+      fallbackUsed = true;
+      fallbackAttempt = await attemptClick('fallback click', () => page.evaluate(el => el.click(), elementHandle), clickTimeout);
     }
-    
+
+    const finalStatus = nativeAttempt.status === 'success' || (fallbackAttempt && fallbackAttempt.status === 'success')
+      ? 'success'
+      : 'failed';
+
+    if (finalStatus === 'success') {
+      logger.debug(`Waiting for page to be ready${returnHtml ? '' : ' (fast mode)'}...`);
+      await waitForPageReady(page, { afterInteraction: true });
+
+      if (postClickWait > 0) {
+        await new Promise(resolve => setTimeout(resolve, postClickWait));
+      }
+    }
+
     const currentUrl = page.url();
-    const clickMessage = selector ? `Clicked element: ${selector}` : `Clicked element with text: "${text}"`;
-    const html = returnHtml ? await extractAndProcessHtml(page, removeUnnecessaryHTML) : null;
+    const html = finalStatus === 'success' && returnHtml ? await extractAndProcessHtml(page, removeUnnecessaryHTML) : null;
+    const baseMessage = selector ? `Clicked element: ${selector}` : `Clicked element with text: "${text}"`;
+    const message = finalStatus === 'success'
+      ? baseMessage
+      : fallbackUsed
+        ? `Click failed after fallback. Native: ${nativeAttempt.error || nativeAttempt.status}. Fallback: ${fallbackAttempt?.error || fallbackAttempt?.status}`
+        : `Click failed. Native: ${nativeAttempt.error || nativeAttempt.status}`;
+
     const nextSteps = returnHtml
       ? [
           "Use MCPBrowser's click_element again to navigate further",
@@ -288,10 +340,20 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
           "Use MCPBrowser's click_element or MCPBrowser's type_text for more interactions",
           "Use MCPBrowser's close_tab when finished"
         ];
-    
-    logger.info(`click_element completed: ${selector || `text="${text}"`}`);
-    
-    return new ClickElementSuccessResponse(currentUrl, clickMessage, html, nextSteps);
+
+    logger.info(`click_element completed: ${selector || `text="${text}"`}${fallbackUsed ? ' (fallback used)' : ''}`);
+
+    return new ClickWithFallbackResponse({
+      status: finalStatus,
+      fallbackUsed,
+      nativeAttempt,
+      fallbackAttempt,
+      postClickWait: { applied: finalStatus === 'success', waitedMs: finalStatus === 'success' ? postClickWait : 0 },
+      currentUrl,
+      html,
+      message,
+      nextSteps
+    });
   } catch (err) {
     logger.error(`click_element failed: ${err.message}`);
     return new InformationalResponse(

package/src/actions/execute-javascript.js

@@ -0,0 +1,244 @@
+/**
+ * execute-javascript.js - Run arbitrary JavaScript in the current page context
+ */
+
+import { getBrowser, getValidatedPage } from '../core/browser.js';
+import { waitForPageReady } from '../core/page.js';
+import { MCPResponse, InformationalResponse } from '../core/responses.js';
+import logger from '../core/logger.js';
+import { serializeExecutionResult } from '../utils.js';
+
+// Shared execution defaults for script actions
+export const EXECUTION_TIMEOUT_DEFAULT_MS = 30_000;
+export const EXECUTION_TIMEOUT_MAX_MS = 60_000;
+export const EXECUTION_RESULT_MAX_BYTES = 100_000;
+
+/**
+ * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
+ */
+
+/**
+ * Structured response for execute_javascript action
+ */
+export class ExecuteJavascriptResponse extends MCPResponse {
+  constructor({ result, type, executionTimeMs, truncated = false, urlChanged = false, currentUrl = '', error = null, nextSteps = [] }) {
+    super(nextSteps);
+
+    this.result = result;
+    this.type = type;
+    this.executionTimeMs = executionTimeMs;
+    this.truncated = truncated;
+    this.urlChanged = urlChanged;
+    this.currentUrl = currentUrl;
+    this.error = error;
+  }
+
+  _getAdditionalFields() {
+    return {
+      result: this.result,
+      type: this.type,
+      executionTimeMs: this.executionTimeMs,
+      truncated: this.truncated,
+      urlChanged: this.urlChanged,
+      currentUrl: this.currentUrl,
+      error: this.error || undefined
+    };
+  }
+
+  getTextSummary() {
+    const outcome = this.error ? `Script error: ${this.error.message || 'Unknown error'}` : 'Script executed';
+    const timing = typeof this.executionTimeMs === 'number' ? ` in ${this.executionTimeMs}ms` : '';
+    const nav = this.urlChanged ? ' (navigation detected)' : '';
+    return `${outcome}${timing}${nav}`;
+  }
+}
+
+export const EXECUTE_JAVASCRIPT_TOOL = {
+  name: 'execute_javascript',
+  title: 'Execute JavaScript',
+  description: '**BROWSER INTERACTION** - Executes a JavaScript snippet in the active page and returns the result with metadata (execution time, truncation, navigation detection). Use for structured extraction or UI actions that are unreliable via protocol clicks.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: 'The URL of the page (must match a previously fetched page)' },
+      script: { type: 'string', description: 'JavaScript source code to execute in page context' },
+      timeoutMs: { type: 'number', description: 'Maximum execution time in milliseconds', default: EXECUTION_TIMEOUT_DEFAULT_MS },
+      returnType: { type: 'string', description: "How to interpret the result: 'json' | 'text' | 'void'", enum: ['json', 'text', 'void'], default: 'json' }
+    },
+    required: ['url', 'script'],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: 'object',
+    properties: {
+      result: { description: 'Serialized result of the script', nullable: true },
+      type: { type: 'string', description: 'Type of the returned result' },
+      executionTimeMs: { type: 'number', description: 'Script execution duration' },
+      truncated: { type: 'boolean', description: 'True if result was capped to size limit' },
+      urlChanged: { type: 'boolean', description: 'True if page URL changed during execution' },
+      currentUrl: { type: 'string', description: 'URL after execution' },
+      nextSteps: { type: 'array', items: { type: 'string' } },
+      error: { type: ['object', 'null'], description: 'Error object when script throws or times out' }
+    },
+    required: ['type', 'executionTimeMs', 'truncated', 'urlChanged', 'currentUrl', 'nextSteps'],
+    additionalProperties: false
+  }
+};
+
+function clampTimeout(timeoutMs) {
+  const numeric = typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) ? timeoutMs : EXECUTION_TIMEOUT_DEFAULT_MS;
+  return Math.min(Math.max(numeric, 1), EXECUTION_TIMEOUT_MAX_MS);
+}
+
+function buildErrorResponse(message, reason, nextSteps) {
+  return new InformationalResponse(message, reason, nextSteps);
+}
+
+export async function executeJavascript({ url, script, timeoutMs = EXECUTION_TIMEOUT_DEFAULT_MS, returnType = 'json' }) {
+  logger.info(`execute_javascript called: ${url}`);
+
+  if (!url) throw new Error('url parameter is required');
+  if (!script || typeof script !== 'string' || !script.trim()) throw new Error('script parameter is required');
+
+  let hostname;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+
+  try {
+    await getBrowser();
+  } catch (err) {
+    logger.error(`execute_javascript: Failed to connect to browser: ${err.message}`);
+    return buildErrorResponse(
+      `Browser connection failed: ${err.message}`,
+      'The browser must be running with remote debugging enabled.',
+      [
+        'Ensure the browser is installed and running',
+        'Check that remote debugging is enabled (--remote-debugging-port)',
+        'Try restarting the MCP server'
+      ]
+    );
+  }
+
+  const { page, error: pageError } = await getValidatedPage(hostname);
+  if (!page) {
+    const isConnectionLost = pageError && pageError.includes('connection');
+    logger.debug(`execute_javascript: ${pageError || 'No page found for ' + hostname}`);
+    return buildErrorResponse(
+      isConnectionLost ? `Page connection lost for ${hostname}` : `No open page found for ${hostname}`,
+      isConnectionLost
+        ? 'The browser tab was closed or the connection was lost. The page needs to be reloaded.'
+        : 'The page must be loaded before you can run scripts on it.',
+      [
+        "Use MCPBrowser's fetch_webpage tool to load the page first",
+        "Then retry MCPBrowser's execute_javascript with the same URL"
+      ]
+    );
+  }
+
+  const effectiveTimeout = clampTimeout(timeoutMs);
+  const beforeUrl = page.url();
+  const start = Date.now();
+
+  const evalPromise = page.evaluate(async ({ userScript, mode }) => {
+    const wrap = async () => {
+      const fn = new Function(`return (async () => { ${userScript} })();`);
+      return await fn();
+    };
+
+    try {
+      const value = await wrap();
+      const isDom = typeof Element !== 'undefined' && value instanceof Element;
+      if (mode === 'void') {
+        return { value: null, type: 'void' };
+      }
+      if (mode === 'text') {
+        return { value: String(value), type: 'string' };
+      }
+      if (isDom) {
+        return { value: value.outerHTML, type: 'dom-html' };
+      }
+      const valueType = Array.isArray(value) ? 'array' : (value === null ? 'null' : typeof value);
+      return { value, type: valueType };
+    } catch (error) {
+      return { error: { name: error?.name || 'Error', message: error?.message || 'Script error', stack: error?.stack || '' } };
+    }
+  }, { userScript: script, mode: returnType });
+
+  let evalResult;
+  try {
+    evalResult = await Promise.race([
+      evalPromise,
+      new Promise((_, reject) => setTimeout(() => reject(new Error(`Execution timed out after ${effectiveTimeout}ms`)), effectiveTimeout))
+    ]);
+  } catch (err) {
+    const executionTimeMs = Date.now() - start;
+    let currentUrl = page.url();
+    try {
+      currentUrl = await page.evaluate(() => location.href);
+    } catch {
+      // ignore evaluation failures when the page is gone
+    }
+    return new ExecuteJavascriptResponse({
+      result: null,
+      type: 'error',
+      executionTimeMs,
+      truncated: false,
+      urlChanged: currentUrl !== beforeUrl,
+      currentUrl,
+      error: { name: 'TimeoutError', message: err.message }
+    });
+  }
+
+  const executionTimeMs = Date.now() - start;
+  let currentUrl = page.url();
+  try {
+    currentUrl = await page.evaluate(() => location.href);
+  } catch {
+    // If we can't read location (e.g., cross-origin), fall back to page.url()
+  }
+  const urlChanged = currentUrl !== beforeUrl;
+
+  if (evalResult?.error) {
+    return new ExecuteJavascriptResponse({
+      result: null,
+      type: 'error',
+      executionTimeMs,
+      truncated: false,
+      urlChanged,
+      currentUrl,
+      error: evalResult.error
+    });
+  }
+
+  const serialization = serializeExecutionResult(evalResult?.value, { maxBytes: EXECUTION_RESULT_MAX_BYTES });
+
+  return new ExecuteJavascriptResponse({
+    result: serialization.result,
+    type: evalResult?.type || serialization.type,
+    executionTimeMs,
+    truncated: serialization.truncated,
+    urlChanged,
+    currentUrl,
+    nextSteps: [
+      'Use click_element or type_text for follow-up actions',
+      'Inspect urlChanged to decide if navigation occurred',
+      serialization.truncated ? 'Narrow your selector or reduce returned fields to avoid truncation' : 'Proceed with the returned data'
+    ]
+  });
+}
+
+export async function executeJavascriptWithReady(params) {
+  const response = await executeJavascript(params);
+  try {
+    if (!response.error) {
+      const { page } = await getValidatedPage(new URL(params.url).hostname);
+      if (page) await waitForPageReady(page, { afterInteraction: true });
+    }
+  } catch (err) {
+    logger.debug(`execute_javascript post-wait skipped: ${err.message}`);
+  }
+  return response;
+}

package/src/mcp-browser.js

@@ -27,6 +27,7 @@ import { closeTab, CLOSE_TAB_TOOL } from './actions/close-tab.js';
 import { getCurrentHtml, GET_CURRENT_HTML_TOOL } from './actions/get-current-html.js';
 import { takeScreenshot, TAKE_SCREENSHOT_TOOL } from './actions/take-screenshot.js';
 import { scrollPage, SCROLL_PAGE_TOOL } from './actions/scroll-page.js';
+import { executeJavascript, EXECUTE_JAVASCRIPT_TOOL } from './actions/execute-javascript.js';
 
 // Import functions for testing exports
 import { getBrowser, closeBrowser } from './core/browser.js';
@@ -60,6 +61,7 @@ async function main() {
   const tools = [
     // ACCEPT_EULA_TOOL,
     FETCH_WEBPAGE_TOOL,
+    EXECUTE_JAVASCRIPT_TOOL,
     CLICK_ELEMENT_TOOL,
     TYPE_TEXT_TOOL,
     CLOSE_TAB_TOOL,
@@ -91,6 +93,10 @@ async function main() {
         case "fetch_webpage":
           result = await fetchPage(safeArgs);
           break;
+
+        case "execute_javascript":
+          result = await executeJavascript(safeArgs);
+          break;
           
         case "click_element":
           result = await clickElement(safeArgs);
@@ -158,6 +164,7 @@ export {
   extractAndProcessHtml,
   getBaseDomain,
   isLikelyAuthUrl,
+  executeJavascript,
   clickElement,
   typeText,
   closeTab,

package/src/utils.js

@@ -72,6 +72,71 @@ export function truncate(str, max) {
   return str.length > max ? `${str.slice(0, max)}... [truncated]` : str;
 }
 
+function byteLength(str) {
+  return new TextEncoder().encode(str).length;
+}
+
+function safeStringify(value) {
+  const seen = new WeakSet();
+  return JSON.stringify(value, (key, val) => {
+    if (typeof val === 'function' || typeof val === 'symbol') return undefined;
+    if (typeof val === 'bigint') return val.toString();
+    if (val && typeof val === 'object') {
+      if (seen.has(val)) return '[Circular]';
+      seen.add(val);
+    }
+    return val;
+  });
+}
+
+/**
+ * Serialize a JS value for MCP responses with size and safety guards.
+ * Returns JSON-safe payload, detected type, and truncation flag.
+ * @param {any} value
+ * @param {object} options
+ * @param {number} [options.maxBytes=100000]
+ * @returns {{ result: any, type: string, truncated: boolean }}
+ */
+export function serializeExecutionResult(value, { maxBytes = 100_000 } = {}) {
+  let type = Array.isArray(value) ? 'array' : (value === null ? 'null' : typeof value);
+  let jsonString;
+
+  if (type === 'string') {
+    jsonString = String(value);
+  } else {
+    try {
+      jsonString = safeStringify(value);
+    } catch (err) {
+      jsonString = String(value);
+      type = 'string';
+    }
+  }
+
+  let truncated = false;
+  if (byteLength(jsonString) > maxBytes) {
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder();
+    const sliced = encoder.encode(jsonString).slice(0, maxBytes);
+    jsonString = `${decoder.decode(sliced)}...[truncated]`;
+    truncated = true;
+    type = 'string';
+  }
+
+  let parsed = value;
+  if (type === 'object' || type === 'array' || type === 'null') {
+    try {
+      parsed = JSON.parse(jsonString);
+    } catch {
+      parsed = jsonString;
+      type = 'string';
+    }
+  } else if (type === 'string') {
+    parsed = jsonString;
+  }
+
+  return { result: parsed, type, truncated };
+}
+
 /**
  * Extract base domain from hostname (e.g., "mail.google.com" → "google.com")
  * @param {string} hostname - The hostname to parse