rird 2.1.231 → 2.3.0

package/src/mcp/index.ts

@@ -0,0 +1,1117 @@
+import { dynamicTool, type Tool, jsonSchema, type JSONSchema7 } from "ai"
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js"
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js"
+import { type Tool as MCPToolDef, ToolListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js"
+import { Config } from "../config/config"
+import { Log } from "../util/log"
+import { NamedError } from "@opencode-ai/util/error"
+import z from "zod"
+import { Instance } from "../project/instance"
+import { Installation } from "../installation"
+import { withTimeout } from "@/util/timeout"
+import { McpOAuthProvider } from "./oauth-provider"
+import { McpOAuthCallback } from "./oauth-callback"
+import { McpAuth } from "./auth"
+import { BusEvent } from "../bus/bus-event"
+import { Bus } from "@/bus"
+import { TuiEvent } from "@/cli/cmd/tui/event"
+import open from "open"
+import { validateTask, logBlockedAttempt } from "../security"
+import { analyzeIntent, isSimpleTask } from "./intent-analyzer"
+import { Session } from "../session"
+
+export namespace MCP {
+  const log = Log.create({ service: "mcp" })
+
+  export function init() {
+    Bus.subscribe(Session.Event.Deleted, (evt) => {
+      resetSectionTracking(evt.properties.info.id)
+    })
+  }
+
+  export const ToolsChanged = BusEvent.define(
+    "mcp.tools.changed",
+    z.object({
+      server: z.string(),
+    }),
+  )
+
+  export const Failed = NamedError.create(
+    "MCPFailed",
+    z.object({
+      name: z.string(),
+    }),
+  )
+
+  type MCPClient = Client
+
+  export const Status = z
+    .discriminatedUnion("status", [
+      z
+        .object({
+          status: z.literal("connected"),
+        })
+        .meta({
+          ref: "MCPStatusConnected",
+        }),
+      z
+        .object({
+          status: z.literal("disabled"),
+        })
+        .meta({
+          ref: "MCPStatusDisabled",
+        }),
+      z
+        .object({
+          status: z.literal("failed"),
+          error: z.string(),
+        })
+        .meta({
+          ref: "MCPStatusFailed",
+        }),
+      z
+        .object({
+          status: z.literal("needs_auth"),
+        })
+        .meta({
+          ref: "MCPStatusNeedsAuth",
+        }),
+      z
+        .object({
+          status: z.literal("needs_client_registration"),
+          error: z.string(),
+        })
+        .meta({
+          ref: "MCPStatusNeedsClientRegistration",
+        }),
+    ])
+    .meta({
+      ref: "MCPStatus",
+    })
+  export type Status = z.infer<typeof Status>
+
+  // Register notification handlers for MCP client
+  function registerNotificationHandlers(client: MCPClient, serverName: string) {
+    client.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+      log.info("tools list changed notification received", { server: serverName })
+      Bus.publish(ToolsChanged, { server: serverName })
+    })
+  }
+
+  // Convert MCP tool definition to AI SDK Tool type
+  function convertMcpTool(mcpTool: MCPToolDef, client: MCPClient): Tool {
+    const inputSchema = mcpTool.inputSchema
+
+    // Spread first, then override type to ensure it's always "object"
+    const schema: JSONSchema7 = {
+      ...(inputSchema as JSONSchema7),
+      type: "object",
+      properties: (inputSchema.properties ?? {}) as JSONSchema7["properties"],
+      additionalProperties: false,
+    }
+
+    return dynamicTool({
+      description: mcpTool.description ?? "",
+      inputSchema: jsonSchema(schema),
+      execute: async (args: unknown) => {
+        // Security guardrail: validate MCP tool arguments
+        const argsRecord = args as Record<string, unknown>
+        const taskCheck = validateTask({
+          description: mcpTool.description,
+          url: typeof argsRecord.url === "string" ? argsRecord.url : undefined,
+          command: typeof argsRecord.command === "string" ? argsRecord.command : undefined,
+        })
+        if (taskCheck.blocked) {
+          logBlockedAttempt(taskCheck, {
+            task: `MCP tool: ${mcpTool.name}`,
+            url: typeof argsRecord.url === "string" ? argsRecord.url : undefined,
+            command: typeof argsRecord.command === "string" ? argsRecord.command : undefined,
+            timestamp: new Date(),
+          })
+          throw new Error(`MCP tool blocked by security guardrails: ${taskCheck.reason}`)
+        }
+
+        return client.callTool({
+          name: mcpTool.name,
+          arguments: argsRecord,
+        })
+      },
+    })
+  }
+
+  // Store transports for OAuth servers to allow finishing auth
+  type TransportWithAuth = StreamableHTTPClientTransport | SSEClientTransport
+  const pendingOAuthTransports = new Map<string, TransportWithAuth>()
+
+  const state = Instance.state(
+    async () => {
+      const cfg = await Config.get()
+      const config = cfg.mcp ?? {}
+      const clients: Record<string, MCPClient> = {}
+      const status: Record<string, Status> = {}
+
+      await Promise.all(
+        Object.entries(config).map(async ([key, mcp]) => {
+          // If disabled by config, mark as disabled without trying to connect
+          if (mcp.enabled === false) {
+            status[key] = { status: "disabled" }
+            return
+          }
+
+          const result = await create(key, mcp).catch(() => undefined)
+          if (!result) return
+
+          status[key] = result.status
+
+          if (result.mcpClient) {
+            clients[key] = result.mcpClient
+          }
+        }),
+      )
+      return {
+        status,
+        clients,
+      }
+    },
+    async (state) => {
+      await Promise.all(
+        Object.values(state.clients).map((client) =>
+          client.close().catch((error) => {
+            log.error("Failed to close MCP client", {
+              error,
+            })
+          }),
+        ),
+      )
+      pendingOAuthTransports.clear()
+    },
+  )
+
+  export async function add(name: string, mcp: Config.Mcp) {
+    const s = await state()
+    const result = await create(name, mcp)
+    if (!result) {
+      const status = {
+        status: "failed" as const,
+        error: "unknown error",
+      }
+      s.status[name] = status
+      return {
+        status,
+      }
+    }
+    if (!result.mcpClient) {
+      s.status[name] = result.status
+      return {
+        status: s.status,
+      }
+    }
+    s.clients[name] = result.mcpClient
+    s.status[name] = result.status
+
+    return {
+      status: s.status,
+    }
+  }
+
+  async function create(key: string, mcp: Config.Mcp) {
+    if (mcp.enabled === false) {
+      log.info("mcp server disabled", { key })
+      return {
+        mcpClient: undefined,
+        status: { status: "disabled" as const },
+      }
+    }
+    log.info("found", { key, type: mcp.type })
+    let mcpClient: MCPClient | undefined
+    let status: Status | undefined = undefined
+
+    if (mcp.type === "remote") {
+      const url = new URL(mcp.url)
+      const oauthDisabled = mcp.oauth === false
+      const oauthConfig = typeof mcp.oauth === "object" ? mcp.oauth : undefined
+      let authProvider: McpOAuthProvider | undefined
+
+      if (!oauthDisabled) {
+        authProvider = new McpOAuthProvider(
+          key,
+          mcp.url,
+          {
+            clientId: oauthConfig?.clientId,
+            clientSecret: oauthConfig?.clientSecret,
+            scope: oauthConfig?.scope,
+          },
+          {
+            onRedirect: async (url) => {
+              log.info("oauth redirect requested", { key, url: url.toString() })
+            },
+          },
+        )
+      }
+
+      const transports: Array<{ name: string; transport: TransportWithAuth }> = [
+        {
+          name: "StreamableHTTP",
+          transport: new StreamableHTTPClientTransport(url, {
+            authProvider,
+            requestInit: mcp.headers ? { headers: mcp.headers } : undefined,
+          }),
+        },
+        {
+          name: "SSE",
+          transport: new SSEClientTransport(url, {
+            authProvider,
+            requestInit: mcp.headers ? { headers: mcp.headers } : undefined,
+          }),
+        },
+      ]
+
+      let lastError: Error | undefined
+      for (const { name, transport } of transports) {
+        try {
+          const client = new Client({
+            name: "rird",
+            version: Installation.VERSION,
+          })
+          await client.connect(transport)
+          registerNotificationHandlers(client, key)
+          mcpClient = client
+          log.info("connected", { key, transport: name })
+          status = { status: "connected" }
+          break
+        } catch (error) {
+          lastError = error instanceof Error ? error : new Error(String(error))
+
+          // Handle OAuth-specific errors
+          if (error instanceof UnauthorizedError) {
+            log.info("mcp server requires authentication", { key, transport: name })
+
+            // Check if this is a "needs registration" error
+            if (lastError.message.includes("registration") || lastError.message.includes("client_id")) {
+              status = {
+                status: "needs_client_registration" as const,
+                error: "Server does not support dynamic client registration. Please provide clientId in config.",
+              }
+              // Show toast for needs_client_registration
+              Bus.publish(TuiEvent.ToastShow, {
+                title: "MCP Authentication Required",
+                message: `Server "${key}" requires a pre-registered client ID. Add clientId to your config.`,
+                variant: "warning",
+                duration: 8000,
+              }).catch((e) => log.debug("failed to show toast", { error: e }))
+            } else {
+              // Store transport for later finishAuth call
+              pendingOAuthTransports.set(key, transport)
+              status = { status: "needs_auth" as const }
+              // Show toast for needs_auth
+              Bus.publish(TuiEvent.ToastShow, {
+                title: "MCP Authentication Required",
+                message: `Server "${key}" requires authentication. Run: rird mcp auth ${key}`,
+                variant: "warning",
+                duration: 8000,
+              }).catch((e) => log.debug("failed to show toast", { error: e }))
+            }
+            break
+          }
+
+          log.debug("transport connection failed", {
+            key,
+            transport: name,
+            url: mcp.url,
+            error: lastError.message,
+          })
+          status = {
+            status: "failed" as const,
+            error: lastError.message,
+          }
+        }
+      }
+    }
+
+    if (mcp.type === "local") {
+      const [cmd, ...args] = mcp.command
+
+      // Check if script file exists for python/node commands
+      const interpreters = ["python", "python3", "node", "bun", "npx"]
+      if (interpreters.includes(cmd) && args.length > 0) {
+        const scriptPath = args[0]
+        // Skip check for npx packages (e.g., "npx -y mcp-desktop-automation")
+        if (!scriptPath.startsWith("-") && !scriptPath.startsWith("@")) {
+          try {
+            const fs = await import("fs/promises")
+            await fs.access(scriptPath)
+          } catch {
+            log.error("MCP script not found", { key, scriptPath })
+            status = {
+              status: "failed" as const,
+              error: `Script not found: ${scriptPath}. Run postinstall or check your config.`,
+            }
+            return { mcpClient: undefined, status }
+          }
+        }
+      }
+
+      const transport = new StdioClientTransport({
+        stderr: "ignore",
+        command: cmd,
+        args,
+        env: {
+          ...process.env,
+          ...(cmd === "rird" ? { BUN_BE_BUN: "1" } : {}),
+          ...mcp.environment,
+        },
+      })
+
+      try {
+        const client = new Client({
+          name: "rird",
+          version: Installation.VERSION,
+        })
+        await client.connect(transport)
+        registerNotificationHandlers(client, key)
+        mcpClient = client
+        status = {
+          status: "connected",
+        }
+      } catch (error) {
+        log.error("local mcp startup failed", {
+          key,
+          command: mcp.command,
+          error: error instanceof Error ? error.message : String(error),
+        })
+        status = {
+          status: "failed" as const,
+          error: error instanceof Error ? error.message : String(error),
+        }
+      }
+    }
+
+    if (!status) {
+      status = {
+        status: "failed" as const,
+        error: "Unknown error",
+      }
+    }
+
+    if (!mcpClient) {
+      return {
+        mcpClient: undefined,
+        status,
+      }
+    }
+
+    const result = await withTimeout(mcpClient.listTools(), mcp.timeout ?? 5000).catch((err) => {
+      log.error("failed to get tools from client", { key, error: err })
+      return undefined
+    })
+    if (!result) {
+      await mcpClient.close().catch((error) => {
+        log.error("Failed to close MCP client", {
+          error,
+        })
+      })
+      status = {
+        status: "failed",
+        error: "Failed to get tools",
+      }
+      return {
+        mcpClient: undefined,
+        status: {
+          status: "failed" as const,
+          error: "Failed to get tools",
+        },
+      }
+    }
+
+    log.info("create() successfully created client", { key, toolCount: result.tools.length })
+    return {
+      mcpClient,
+      status,
+    }
+  }
+
+  export async function status() {
+    const s = await state()
+    const cfg = await Config.get()
+    const config = cfg.mcp ?? {}
+    const result: Record<string, Status> = {}
+
+    // Include all MCPs from config, not just connected ones
+    for (const key of Object.keys(config)) {
+      result[key] = s.status[key] ?? { status: "disabled" }
+    }
+
+    return result
+  }
+
+  export async function clients() {
+    return state().then((state) => state.clients)
+  }
+
+  export async function connect(name: string) {
+    const cfg = await Config.get()
+    const config = cfg.mcp ?? {}
+    const mcp = config[name]
+    if (!mcp) {
+      log.error("MCP config not found", { name })
+      return
+    }
+
+    const result = await create(name, { ...mcp, enabled: true })
+
+    if (!result) {
+      const s = await state()
+      s.status[name] = {
+        status: "failed",
+        error: "Unknown error during connection",
+      }
+      return
+    }
+
+    const s = await state()
+    s.status[name] = result.status
+    if (result.mcpClient) {
+      s.clients[name] = result.mcpClient
+    }
+  }
+
+  export async function disconnect(name: string) {
+    const s = await state()
+    const client = s.clients[name]
+    if (client) {
+      await client.close().catch((error) => {
+        log.error("Failed to close MCP client", { name, error })
+      })
+      delete s.clients[name]
+    }
+    s.status[name] = { status: "disabled" }
+  }
+
+  export async function tools() {
+    const result: Record<string, Tool> = {}
+    const s = await state()
+    const clientsSnapshot = await clients()
+
+    const BROWSER_MCP_NAMES = new Set(["chrome-browser", "stealth-browser"])
+
+    for (const [clientName, client] of Object.entries(clientsSnapshot)) {
+      // Only include tools from connected MCPs (skip disabled ones)
+      if (s.status[clientName]?.status !== "connected") {
+        continue
+      }
+
+      const toolsResult = await client.listTools().catch((e) => {
+        log.error("failed to get tools", { clientName, error: e.message })
+        const failedStatus = {
+          status: "failed" as const,
+          error: e instanceof Error ? e.message : String(e),
+        }
+        s.status[clientName] = failedStatus
+        delete s.clients[clientName]
+        return undefined
+      })
+      if (!toolsResult) {
+        continue
+      }
+      for (const mcpTool of toolsResult.tools) {
+        const sanitizedClientName = (BROWSER_MCP_NAMES.has(clientName) ? "chrome" : clientName).replace(
+          /[^a-zA-Z0-9_-]/g,
+          "_",
+        )
+        const sanitizedToolName = mcpTool.name.replace(/[^a-zA-Z0-9_-]/g, "_")
+        result[sanitizedClientName + "_" + sanitizedToolName] = convertMcpTool(mcpTool, client)
+      }
+    }
+    return result
+  }
+
+  /**
+   * Start OAuth authentication flow for an MCP server.
+   * Returns the authorization URL that should be opened in a browser.
+   */
+  export async function startAuth(mcpName: string): Promise<{ authorizationUrl: string }> {
+    const cfg = await Config.get()
+    const mcpConfig = cfg.mcp?.[mcpName]
+
+    if (!mcpConfig) {
+      throw new Error(`MCP server not found: ${mcpName}`)
+    }
+
+    if (mcpConfig.type !== "remote") {
+      throw new Error(`MCP server ${mcpName} is not a remote server`)
+    }
+
+    if (mcpConfig.oauth === false) {
+      throw new Error(`MCP server ${mcpName} has OAuth explicitly disabled`)
+    }
+
+    // Start the callback server
+    await McpOAuthCallback.ensureRunning()
+
+    // Generate and store a cryptographically secure state parameter BEFORE creating the provider
+    // The SDK will call provider.state() to read this value
+    const oauthState = Array.from(crypto.getRandomValues(new Uint8Array(32)))
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("")
+    await McpAuth.updateOAuthState(mcpName, oauthState)
+
+    // Create a new auth provider for this flow
+    // OAuth config is optional - if not provided, we'll use auto-discovery
+    const oauthConfig = typeof mcpConfig.oauth === "object" ? mcpConfig.oauth : undefined
+    let capturedUrl: URL | undefined
+    const authProvider = new McpOAuthProvider(
+      mcpName,
+      mcpConfig.url,
+      {
+        clientId: oauthConfig?.clientId,
+        clientSecret: oauthConfig?.clientSecret,
+        scope: oauthConfig?.scope,
+      },
+      {
+        onRedirect: async (url) => {
+          capturedUrl = url
+        },
+      },
+    )
+
+    // Create transport with auth provider
+    const transport = new StreamableHTTPClientTransport(new URL(mcpConfig.url), {
+      authProvider,
+    })
+
+    // Try to connect - this will trigger the OAuth flow
+    try {
+      const client = new Client({
+        name: "rird",
+        version: Installation.VERSION,
+      })
+      await client.connect(transport)
+      // If we get here, we're already authenticated
+      return { authorizationUrl: "" }
+    } catch (error) {
+      if (error instanceof UnauthorizedError && capturedUrl) {
+        // Store transport for finishAuth
+        pendingOAuthTransports.set(mcpName, transport)
+        return { authorizationUrl: capturedUrl.toString() }
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Complete OAuth authentication after user authorizes in browser.
+   * Opens the browser and waits for callback.
+   */
+  export async function authenticate(mcpName: string): Promise<Status> {
+    const { authorizationUrl } = await startAuth(mcpName)
+
+    if (!authorizationUrl) {
+      // Already authenticated
+      const s = await state()
+      return s.status[mcpName] ?? { status: "connected" }
+    }
+
+    // Get the state that was already generated and stored in startAuth()
+    const oauthState = await McpAuth.getOAuthState(mcpName)
+    if (!oauthState) {
+      throw new Error("OAuth state not found - this should not happen")
+    }
+
+    // The SDK has already added the state parameter to the authorization URL
+    // We just need to open the browser
+    log.info("opening browser for oauth", { mcpName, url: authorizationUrl, state: oauthState })
+    await open(authorizationUrl)
+
+    // Wait for callback using the OAuth state parameter
+    const code = await McpOAuthCallback.waitForCallback(oauthState)
+
+    // Validate and clear the state
+    const storedState = await McpAuth.getOAuthState(mcpName)
+    if (storedState !== oauthState) {
+      await McpAuth.clearOAuthState(mcpName)
+      throw new Error("OAuth state mismatch - potential CSRF attack")
+    }
+
+    await McpAuth.clearOAuthState(mcpName)
+
+    // Finish auth
+    return finishAuth(mcpName, code)
+  }
+
+  /**
+   * Complete OAuth authentication with the authorization code.
+   */
+  export async function finishAuth(mcpName: string, authorizationCode: string): Promise<Status> {
+    const transport = pendingOAuthTransports.get(mcpName)
+
+    if (!transport) {
+      throw new Error(`No pending OAuth flow for MCP server: ${mcpName}`)
+    }
+
+    try {
+      // Call finishAuth on the transport
+      await transport.finishAuth(authorizationCode)
+
+      // Clear the code verifier after successful auth
+      await McpAuth.clearCodeVerifier(mcpName)
+
+      // Now try to reconnect
+      const cfg = await Config.get()
+      const mcpConfig = cfg.mcp?.[mcpName]
+
+      if (!mcpConfig) {
+        throw new Error(`MCP server not found: ${mcpName}`)
+      }
+
+      // Re-add the MCP server to establish connection
+      pendingOAuthTransports.delete(mcpName)
+      const result = await add(mcpName, mcpConfig)
+
+      const statusRecord = result.status as Record<string, Status>
+      return statusRecord[mcpName] ?? { status: "failed", error: "Unknown error after auth" }
+    } catch (error) {
+      log.error("failed to finish oauth", { mcpName, error })
+      return {
+        status: "failed",
+        error: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+
+  /**
+   * Remove OAuth credentials for an MCP server.
+   */
+  export async function removeAuth(mcpName: string): Promise<void> {
+    await McpAuth.remove(mcpName)
+    McpOAuthCallback.cancelPending(mcpName)
+    pendingOAuthTransports.delete(mcpName)
+    await McpAuth.clearOAuthState(mcpName)
+    log.info("removed oauth credentials", { mcpName })
+  }
+
+  /**
+   * Check if an MCP server supports OAuth (remote servers support OAuth by default unless explicitly disabled).
+   */
+  export async function supportsOAuth(mcpName: string): Promise<boolean> {
+    const cfg = await Config.get()
+    const mcpConfig = cfg.mcp?.[mcpName]
+    return mcpConfig?.type === "remote" && mcpConfig.oauth !== false
+  }
+
+  /**
+   * Check if an MCP server has stored OAuth tokens.
+   */
+  export async function hasStoredTokens(mcpName: string): Promise<boolean> {
+    const entry = await McpAuth.get(mcpName)
+    return !!entry?.tokens
+  }
+
+  export type AuthStatus = "authenticated" | "expired" | "not_authenticated"
+
+  /**
+   * Get the authentication status for an MCP server.
+   */
+  export async function getAuthStatus(mcpName: string): Promise<AuthStatus> {
+    const hasTokens = await hasStoredTokens(mcpName)
+    if (!hasTokens) return "not_authenticated"
+    const expired = await McpAuth.isTokenExpired(mcpName)
+    return expired ? "expired" : "authenticated"
+  }
+
+  // =============================================================================
+  // SECTION LOADING: Dynamic tool section management for browser MCP
+  // =============================================================================
+
+  /** Browser MCP server names (config keys) */
+  const BROWSER_MCP_NAMES = ["chrome-browser", "stealth-browser"] as const
+
+  /** Name of the stealth browser MCP for tool notification events */
+  const STEALTH_BROWSER_MCP_NAME = "stealth-browser"
+
+  function resolveBrowserMcpName(status: Record<string, Status>): string | undefined {
+    for (const name of BROWSER_MCP_NAMES) {
+      if (status[name]?.status === "connected") return name
+    }
+    return undefined
+  }
+
+  // Track which MCP sections are loaded per-session to avoid race conditions
+  // Key: sessionID, Value: Set of section names loaded for that session
+  const sessionSections: Map<string, Set<string>> = new Map()
+
+  // Track global loaded sections (MCP server state is shared across sessions)
+  let globalLoadedSections: Set<string> = new Set()
+
+  /** Get or create section tracking for a session */
+  function getSessionSections(sessionID?: string): Set<string> {
+    if (!sessionID) return globalLoadedSections
+    if (!sessionSections.has(sessionID)) {
+      sessionSections.set(sessionID, new Set())
+    }
+    return sessionSections.get(sessionID)!
+  }
+
+  /** Clean up section tracking for a session */
+  function clearSessionSections(sessionID: string): void {
+    sessionSections.delete(sessionID)
+  }
+
+  /**
+   * Get the browser MCP client if connected.
+   * Returns undefined if not connected or not configured.
+   */
+  async function getBrowserClient(): Promise<Client | undefined> {
+    const s = await state()
+    const name = resolveBrowserMcpName(s.status)
+    if (!name) return undefined
+    const clientStatus = s.status[name]
+
+    if (!clientStatus || clientStatus.status !== "connected") {
+      log.debug("browser MCP not connected", {
+        status: clientStatus?.status ?? "not_configured",
+      })
+      return undefined
+    }
+
+    return s.clients[name]
+  }
+
+  /**
+   * Load tool sections dynamically via browser MCP meta-tools.
+   * Calls load_tool_section for each section to enable those tools.
+   *
+   * @param sections - Array of section names to load
+   * @param sessionID - Optional session ID for per-session tracking
+   * @returns Promise resolving to results of each load operation
+   *
+   * Valid sections:
+   * - browser-management: Core browser lifecycle (spawn, close, status)
+   * - element-interaction: Clicking, typing, scrolling
+   * - element-extraction: Scraping element data
+   * - file-extraction: File downloads, screenshots
+   * - network-debugging: Network requests, responses
+   * - cdp-functions: Chrome DevTools Protocol access
+   * - cookies-storage: Cookie and storage management
+   * - tabs: Multi-tab workflows
+   * - debugging: Console logs, errors
+   * - dynamic-hooks: Request interception
+   * - progressive-cloning: Page state cloning
+   */
+  export async function loadSections(sections: string[], sessionID?: string): Promise<{ section: string; success: boolean; error?: string }[]> {
+    const client = await getBrowserClient()
+    const results: { section: string; success: boolean; error?: string }[] = []
+    const sessionTracking = getSessionSections(sessionID)
+
+    if (!client) {
+      log.warn("cannot load sections - browser MCP not connected")
+      // Return failure for all requested sections
+      for (const section of sections) {
+        results.push({ section, success: false, error: "browser MCP not connected" })
+      }
+      return results
+    }
+
+    // Load each section via MCP meta-tool
+    for (const section of sections) {
+      try {
+        const result = await client.callTool({
+          name: "load_tool_section",
+          arguments: { section },
+        })
+
+        // Parse the response
+        const content = result.content
+        let success = true
+        let errorMsg: string | undefined
+
+        if (Array.isArray(content) && content.length > 0) {
+          const firstContent = content[0]
+          if (firstContent && typeof firstContent === "object" && "text" in firstContent) {
+            const text = firstContent.text as string
+            try {
+              const parsed = JSON.parse(text)
+              if (parsed.error) {
+                success = false
+                errorMsg = parsed.error
+              } else {
+                log.info("loaded tool section via MCP", {
+                  section,
+                  sessionID,
+                  toolsLoaded: parsed.tools_loaded ?? parsed.tool_count ?? "unknown",
+                })
+              }
+            } catch {
+              // Non-JSON response, assume success
+            }
+          }
+        }
+
+        if (success) {
+          sessionTracking.add(section)
+          globalLoadedSections.add(section)
+        }
+        results.push({ section, success, error: errorMsg })
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error)
+        log.error("error loading section via MCP", { section, sessionID, error: errorMsg })
+        results.push({ section, success: false, error: errorMsg })
+      }
+    }
+
+    // Notify that tools have changed so UI/tool list can refresh
+    const s = await state()
+    const browserName = resolveBrowserMcpName(s.status) ?? "chrome-browser"
+    Bus.publish(ToolsChanged, { server: browserName }).catch((e) =>
+      log.debug("failed to publish tools changed event", { error: e })
+    )
+
+    return results
+  }
+
+  /**
+   * Unload tool sections to save context tokens.
+   *
+   * When sessionID is provided: Only clears local tracking for that session (does NOT call MCP).
+   * This prevents one session's cancel from affecting other sessions.
+   *
+   * When sessionID is NOT provided: Actually calls unload_tool_section on MCP server.
+   *
+   * @param sections - Array of section names to unload (if empty, unloads all loaded sections)
+   * @param sessionID - Optional session ID - if provided, only clears local tracking
+   * @returns Promise resolving to results of each unload operation
+   */
+  export async function unloadSections(sections?: string[], sessionID?: string): Promise<{ section: string; success: boolean; error?: string }[]> {
+    const results: { section: string; success: boolean; error?: string }[] = []
+
+    // If sessionID is provided, just clear that session's tracking (don't actually unload from MCP)
+    // This prevents one session's cancel from affecting other sessions' loaded sections
+    if (sessionID) {
+      const sessionTracking = sessionSections.get(sessionID)
+      if (sessionTracking) {
+        const sectionsToRemove = sections ?? Array.from(sessionTracking)
+        for (const section of sectionsToRemove) {
+          sessionTracking.delete(section)
+          results.push({ section, success: true })
+        }
+        // Clean up if session has no more sections
+        if (sessionTracking.size === 0) {
+          clearSessionSections(sessionID)
+        }
+        log.debug("cleared session section tracking", { sessionID, cleared: sectionsToRemove })
+      }
+      return results
+    }
+
+    // No sessionID - actually unload from MCP server
+    const client = await getBrowserClient()
+
+    // If no sections specified, unload all currently loaded sections
+    const sectionsToUnload = sections ?? Array.from(globalLoadedSections)
+
+    if (sectionsToUnload.length === 0) {
+      log.debug("no sections to unload")
+      return results
+    }
+
+    if (!client) {
+      log.warn("cannot unload sections - browser MCP not connected")
+      // Still clear local tracking
+      for (const section of sectionsToUnload) {
+        globalLoadedSections.delete(section)
+        results.push({ section, success: false, error: "browser MCP not connected" })
+      }
+      return results
+    }
+
+    // Unload each section via MCP meta-tool
+    for (const section of sectionsToUnload) {
+      try {
+        const result = await client.callTool({
+          name: "unload_tool_section",
+          arguments: { section },
+        })
+
+        // Parse the response
+        const content = result.content
+        let success = true
+        let errorMsg: string | undefined
+
+        if (Array.isArray(content) && content.length > 0) {
+          const firstContent = content[0]
+          if (firstContent && typeof firstContent === "object" && "text" in firstContent) {
+            const text = firstContent.text as string
+            try {
+              const parsed = JSON.parse(text)
+              if (parsed.error) {
+                success = false
+                errorMsg = parsed.error
+              } else {
+                log.info("unloaded tool section via MCP", {
+                  section,
+                  toolsDisabled: parsed.tools_disabled?.length ?? parsed.tool_count ?? "unknown",
+                })
+              }
+            } catch {
+              // Non-JSON response, assume success
+            }
+          }
+        }
+
+        if (success) {
+          globalLoadedSections.delete(section)
+        }
+        results.push({ section, success, error: errorMsg })
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error)
+        log.error("error unloading section via MCP", { section, error: errorMsg })
+        // Still remove from local tracking
+        globalLoadedSections.delete(section)
+        results.push({ section, success: false, error: errorMsg })
+      }
+    }
+
+    // Notify that tools have changed so UI/tool list can refresh
+    Bus.publish(ToolsChanged, { server: STEALTH_BROWSER_MCP_NAME }).catch((e) =>
+      log.debug("failed to publish tools changed event", { error: e })
+    )
+
+    return results
+  }
+
+  /**
+   * Analyze user prompt and prepare/load relevant MCP tool sections.
+   * This enables automatic section loading based on user intent.
+   *
+   * @param userPrompt - The user's message/prompt text
+   * @param sessionID - Optional session ID for per-session tracking
+   * @returns Promise resolving to the sections that were loaded
+   */
+  export async function prepareToolsForPrompt(userPrompt: string, sessionID?: string): Promise<string[]> {
+    if (!userPrompt || typeof userPrompt !== "string") return []
+
+    // Check if browser MCP is even connected
+    const client = await getBrowserClient()
+    if (!client) {
+      log.debug("skipping tool preparation - browser MCP not connected")
+      return []
+    }
+
+    // Check if this is a simple task that doesn't need extra tools
+    if (isSimpleTask(userPrompt)) {
+      log.debug("simple task detected - using default tools only", { promptLength: userPrompt.length, sessionID })
+      return []
+    }
+
+    // Use the intent analyzer to determine which sections to load
+    const neededSections = analyzeIntent(userPrompt)
+
+    // Filter to only sections not already loaded (check both global and session tracking)
+    const sessionTracking = getSessionSections(sessionID)
+    const newSections = neededSections.filter(
+      (section) => !globalLoadedSections.has(section) && !sessionTracking.has(section)
+    )
+
+    if (newSections.length === 0) {
+      log.debug("all needed sections already loaded", {
+        needed: neededSections,
+        loaded: Array.from(globalLoadedSections),
+        sessionID,
+      })
+      return neededSections
+    }
+
+    // Load the new sections via MCP meta-tools
+    log.info("preparing MCP sections for prompt", {
+      newSections,
+      alreadyLoaded: Array.from(globalLoadedSections),
+      sessionID,
+    })
+
+    const results = await loadSections(newSections, sessionID)
+
+    // Log summary
+    const successful = results.filter((r) => r.success).map((r) => r.section)
+    const failed = results.filter((r) => !r.success).map((r) => r.section)
+
+    if (failed.length > 0) {
+      log.warn("some sections failed to load", { successful, failed, sessionID })
+    } else {
+      log.info("prepared MCP sections for prompt", {
+        sectionsLoaded: successful,
+        totalLoaded: Array.from(globalLoadedSections),
+        sessionID,
+      })
+    }
+
+    return neededSections
+  }
+
+  /**
+   * Get currently loaded sections (global MCP server state).
+   * @param sessionID - Optional session ID to get session-specific tracking
+   */
+  export function getLoadedSections(sessionID?: string): string[] {
+    if (sessionID) {
+      const sessionTracking = sessionSections.get(sessionID)
+      return sessionTracking ? Array.from(sessionTracking) : []
+    }
+    return Array.from(globalLoadedSections)
+  }
+
+  /**
+   * Query the MCP server for its list of loaded sections.
+   * Returns undefined if browser MCP is not connected.
+   */
+  export async function queryLoadedSections(): Promise<string[] | undefined> {
+    const client = await getBrowserClient()
+    if (!client) {
+      return undefined
+    }
+
+    try {
+      const result = await client.callTool({
+        name: "list_tool_sections",
+        arguments: {},
+      })
+
+      const content = result.content
+      if (Array.isArray(content) && content.length > 0) {
+        const firstContent = content[0]
+        if (firstContent && typeof firstContent === "object" && "text" in firstContent) {
+          const text = firstContent.text as string
+          const parsed = JSON.parse(text)
+          // Extract loaded sections from the response
+          if (parsed.sections) {
+            return parsed.sections
+              .filter((s: { status: string }) => s.status === "loaded" || s.status === "always_loaded")
+              .map((s: { name: string }) => s.name)
+          }
+        }
+      }
+      return []
+    } catch (error) {
+      log.error("failed to query loaded sections", {
+        error: error instanceof Error ? error.message : String(error),
+      })
+      return undefined
+    }
+  }
+
+  /**
+   * Reset local section tracking (useful for session reset).
+   * @param sessionID - Optional session ID to reset only that session's tracking
+   */
+  export function resetSectionTracking(sessionID?: string): void {
+    if (sessionID) {
+      clearSessionSections(sessionID)
+      log.debug("reset section tracking for session", { sessionID })
+    } else {
+      globalLoadedSections.clear()
+      sessionSections.clear()
+      log.debug("reset all section tracking")
+    }
+  }
+}