@ricardochen1996/browser-use-mcp 0.0.0-stage → 0.1.0

package/lib/http.js

@@ -0,0 +1,222 @@
+/**
+ * Streamable HTTP: one endpoint, one browser per MCP session.
+ *
+ * Useful when several agents should call one long-running server instead of each launching its own
+ * stdio process. Each MCP session (its own `initialize`) still gets its own browser session — its own
+ * profile directory, its own DevTools connection, its own tab — so two agents never click on one
+ * page by accident. A session that stops talking for a while is closed, tab and browser included, so
+ * an abandoned client does not leave a Chrome running forever.
+ *
+ * The transport itself is the official SDK's, stateful mode; this module owns the routing, the
+ * per-session lifecycle, and nothing about the protocol.
+ *
+ * @module browser-use-mcp/http
+ */
+
+import { randomUUID } from 'node:crypto'
+import { createServer as createHttpServer } from 'node:http'
+import { rmSync } from 'node:fs'
+import { join, sep } from 'node:path'
+
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+
+import { createServer, createSession, validProfileName } from './server.js'
+
+/**
+ * Serve the MCP protocol over Streamable HTTP until the process is signalled.
+ *
+ * @param {object} config - the resolved configuration.
+ * @param {object} logger - the stderr logger.
+ * @returns {Promise<{url: string, close: () => Promise<void>}>}
+ */
+export async function serveHttp(config, logger) {
+  const entries = new Map()
+  const idleMs = config.httpIdleMs
+  let closing = false
+  let resolveClosed
+  const closed = new Promise(resolve => { resolveClosed = resolve })
+
+  const dispose = async (sessionId, reason) => {
+    const entry = entries.get(sessionId)
+    if (entry === undefined) return
+    entries.delete(sessionId)
+    logger?.info(`MCP session ${sessionId.slice(0, 8)} closed (${reason}); closing its browser`)
+    try {
+      await entry.server.close()
+    } catch (error) {
+      logger?.debug?.(`closing the MCP session failed: ${error?.message ?? error}`)
+    }
+    try {
+      const problem = await entry.session.shutdown()
+      if (problem !== '') logger?.error(`a browser was not shut down cleanly: ${problem}`)
+    } catch (error) {
+      logger?.error(`stopping a browser failed: ${error?.stack ?? error}`)
+    }
+    // An anonymous HTTP session is ephemeral: its client cannot come back to the same profile (the
+    // session id is random), so the directory is removed. A named profile is the opposite — it is
+    // kept, which is what makes its logins survive a reconnect.
+    const profileDir = entry.session.connection.userDataDir
+    const managed = join(config.browserUseMcpHome, 'profiles') + sep
+    if (entry.persistentProfile !== true && profileDir.startsWith(managed)) {
+      try {
+        rmSync(profileDir, { recursive: true, force: true })
+      } catch (error) {
+        logger?.debug?.(`removing ${profileDir} failed: ${error?.message ?? error}`)
+      }
+    }
+  }
+
+  const http = createHttpServer(async (request, response) => {
+    try {
+      const url = new URL(request.url ?? '/', `http://${request.headers.host ?? 'localhost'}`)
+      if (url.pathname !== config.path) {
+        response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' })
+        response.end(`Not found. MCP is served at ${config.path}\n`)
+        return
+      }
+      const header = request.headers['mcp-session-id']
+      const knownId = Array.isArray(header) ? header[0] : header
+      if (knownId !== undefined && knownId !== '') {
+        const entry = entries.get(knownId)
+        if (entry === undefined) {
+          response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' })
+          response.end('Unknown or expired MCP session. Send initialize again.\n')
+          return
+        }
+        entry.lastSeen = Date.now()
+        // A long POST (a browser launch, a goal run) sends no further request while it runs; counting
+        // it in flight keeps the idle sweep from closing the session under its own answer. A GET is
+        // the long-lived server-to-client stream by design and must not count, or a client that keeps
+        // one open would never look idle.
+        const counted = request.method === 'POST'
+        if (counted) entry.inFlight += 1
+        try {
+          await entry.transport.handleRequest(request, response)
+        } finally {
+          if (counted) entry.inFlight -= 1
+          entry.lastSeen = Date.now()
+        }
+        return
+      }
+      if (request.method !== 'POST') {
+        response.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' })
+        response.end('Send an MCP initialize request with POST first.\n')
+        return
+      }
+      // A new MCP session: its own browser session, its own profile, its own sidecar. A client may
+      // name its profile so the directory — and its logins — survive reconnects: either
+      // `/mcp?profile=<name>` or an `X-Browser-Use-Profile: <name>` header on this initialize
+      // request. Without a name the profile is anonymous and removed when the session ends.
+      const requestedProfile = url.searchParams.get('profile')
+        ?? (typeof request.headers['x-browser-use-profile'] === 'string' ? request.headers['x-browser-use-profile'] : null)
+      if (requestedProfile !== null && !validProfileName(requestedProfile)) {
+        response.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' })
+        response.end('Invalid profile name: use 1-32 characters from [A-Za-z0-9_-] (?profile=<name> or X-Browser-Use-Profile).\n')
+        return
+      }
+      const sessionId = randomUUID()
+      const session = createSession(config, {
+        suffix: sessionId,
+        ...(requestedProfile === null ? {} : { profileName: requestedProfile }),
+        logger,
+      })
+      const server = createServer({ config, session, logger })
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => sessionId,
+        onsessioninitialized: initialized => {
+          entries.set(initialized, {
+            transport,
+            server,
+            session,
+            lastSeen: Date.now(),
+            inFlight: 0,
+            persistentProfile: requestedProfile !== null,
+          })
+          logger?.info(`MCP session ${initialized.slice(0, 8)} started (${entries.size} live)`)
+        },
+        onsessionclosed: initialized => {
+          void dispose(initialized, 'the client closed the session')
+        },
+        // Plain JSON answers keep a simple agent's HTTP client working; an SSE-capable client still
+        // gets its standalone stream on GET, which the transport serves itself.
+        enableJsonResponse: true,
+      })
+      transport.onclose = () => {
+        if (!closing) void dispose(sessionId, 'transport closed')
+      }
+      await server.connect(transport)
+      await transport.handleRequest(request, response)
+    } catch (error) {
+      logger?.error(`an HTTP request failed: ${error?.stack ?? error}`)
+      try {
+        if (!response.headersSent) {
+          response.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' })
+        }
+        response.end('Internal server error\n')
+      } catch {
+        // The connection is already gone; nothing left to answer.
+      }
+    }
+  })
+
+  http.on('clientError', (error, socket) => {
+    logger?.debug?.(`an HTTP client connection failed: ${error.message}`)
+    socket.destroy()
+  })
+
+  await new Promise((resolve, reject) => {
+    http.once('error', reject)
+    http.listen(config.port, config.host, () => {
+      http.off('error', reject)
+      resolve()
+    })
+  })
+
+  const shown = config.host === '0.0.0.0' || config.host === '::' ? '127.0.0.1' : config.host
+  const url = `http://${shown}:${config.port}${config.path}`
+  const tools = await import('./tools.js')
+  logger?.info(`serving MCP over Streamable HTTP at ${url}`)
+  const idleText = idleMs < 60_000 ? `${(idleMs / 1000).toFixed(idleMs % 1000 === 0 ? 0 : 1)} seconds` : `${Math.round(idleMs / 60_000)} minutes`
+  logger?.info(`${tools.toolNames(config).length} tools per session; each MCP session gets its own browser; idle sessions close after ${idleText}`)
+  if (config.host !== '127.0.0.1' && config.host !== '::1' && config.host !== 'localhost') {
+    logger?.error(
+      `the HTTP endpoint is bound to ${config.host}: it has no authentication. Use it only on a trusted `
+      + 'network, or bind --host 127.0.0.1 and reach it through a tunnel you control.',
+    )
+  }
+
+  // Sweep often enough that a short test timeout behaves, and never more than once a minute.
+  const sweepEvery = Math.min(60_000, Math.max(1_000, Math.floor(idleMs / 4)))
+  const sweep = setInterval(() => {
+    const now = Date.now()
+    for (const [sessionId, entry] of entries) {
+      if (entry.inFlight > 0) continue
+      if (now - entry.lastSeen > idleMs) void dispose(sessionId, 'idle timeout')
+    }
+  }, sweepEvery)
+  sweep.unref?.()
+
+  const shutdown = async reason => {
+    if (closing) return
+    closing = true
+    clearInterval(sweep)
+    logger?.info(`shutting down the HTTP endpoint (${reason})`)
+    // Stop accepting first, close every session's transport (which ends its SSE streams), and only
+    // then force the sockets shut: a client that never comes back must not keep the process alive
+    // after SIGTERM, which is exactly what an open event stream would otherwise do.
+    const closed = new Promise(resolve => http.close(() => resolve()))
+    await Promise.allSettled([...entries.keys()].map(sessionId => dispose(sessionId, reason)))
+    await Promise.race([closed, new Promise(resolve => setTimeout(resolve, 1_500))])
+    http.closeIdleConnections?.()
+    http.closeAllConnections?.()
+    await Promise.race([closed, new Promise(resolve => setTimeout(resolve, 1_500))])
+    resolveClosed()
+  }
+
+  process.once('SIGINT', () => { void shutdown('SIGINT') })
+  process.once('SIGTERM', () => { void shutdown('SIGTERM') })
+  process.once('SIGHUP', () => { void shutdown('SIGHUP') })
+
+  await closed
+  return { url, close: async () => shutdown('closed') }
+}

package/lib/jev.js

@@ -0,0 +1,105 @@
+/**
+ * Jev: the policy behind `browser_goal` and `browser_act`'s intent, and where its endpoints come from.
+ *
+ * In `dsh-browser-use` these values are resolved from the harness configuration and inherited from
+ * the conversation's model route. An MCP server has no conversation to inherit from, so the values
+ * come from the server's own configuration (flags and environment), and are handed to the sidecar
+ * with each call that spends model quota — never left in the server's environment, where a goal run
+ * could read a stale key.
+ *
+ * @module browser-use-mcp/jev
+ */
+
+/** Variables the engine reads for one model-calling request; nothing else may leak into a sidecar. */
+export const ENGINE_VARIABLES = [
+  'JEV_DECIDER',
+  'TYPESAFE_API_KEY', 'TYPESAFE_BASE_URL', 'TYPESAFE_MODEL', 'TYPESAFE_FALLBACK_URL',
+  'TEXT_MODEL_API_KEY', 'TEXT_MODEL_BASE_URL', 'TEXT_MODEL', 'TEXT_MODEL_REASONING', 'TEXT_MODEL_HEADERS',
+]
+
+/**
+ * The engine environment for the next model-spending request, or `{}` when none is configured.
+ *
+ * With `jev-decider chat` the sidecar serves the engine's chat-model endpoint on loopback and points
+ * the engine's TypeSafe variables at it, so the TypeSafe values are deliberately not sent: the text
+ * model is the only model that run resolves.
+ * @param {object} config - the resolved configuration.
+ */
+export function jevEnvironment(config) {
+  if (!config.jev.enabled) return {}
+  const env = {}
+  const set = (name, value) => {
+    if (value !== undefined && value !== null && String(value) !== '') env[name] = String(value)
+  }
+  if (config.jev.decider === 'chat') {
+    env.JEV_DECIDER = 'chat'
+  } else {
+    set('TYPESAFE_BASE_URL', config.jev.typesafe.baseURL)
+    set('TYPESAFE_MODEL', config.jev.typesafe.model)
+    set('TYPESAFE_FALLBACK_URL', config.jev.typesafe.fallbackURL)
+    set('TYPESAFE_API_KEY', config.jev.typesafe.apiKey)
+  }
+  set('TEXT_MODEL_API_KEY', config.jev.textModel.apiKey)
+  set('TEXT_MODEL_BASE_URL', config.jev.textModel.baseURL)
+  set('TEXT_MODEL', config.jev.textModel.model)
+  set('TEXT_MODEL_REASONING', config.jev.textModel.reasoning)
+  if (Object.keys(config.jev.textModel.headers).length > 0) {
+    set('TEXT_MODEL_HEADERS', JSON.stringify(config.jev.textModel.headers))
+  }
+  return env
+}
+
+/**
+ * Whether a policy call can run at all with this configuration, and what is missing if not.
+ *
+ * This is the question the tool asks *before* it reaches the engine, so a misconfigured server gets
+ * one sentence naming the variable to set instead of an engine stack trace. It is not a promise that
+ * a configured endpoint answers: only a real call can know that.
+ * @param {object} config - the resolved configuration.
+ * @returns {{ready: boolean, missing: string[], description: string}}
+ */
+export function jevReadiness(config) {
+  if (!config.jev.enabled) {
+    return { ready: false, missing: [], description: 'Jev is off (--no-jev): browser_goal and browser_act intents are not offered.' }
+  }
+  if (config.jev.decider === 'chat') {
+    const missing = []
+    if (config.jev.textModel.baseURL === '') missing.push('TEXT_MODEL_BASE_URL')
+    if (config.jev.textModel.model === '') missing.push('TEXT_MODEL')
+    return {
+      ready: missing.length === 0,
+      missing,
+      description: missing.length === 0
+        ? `the text model ${config.jev.textModel.model} at ${config.jev.textModel.baseURL} decides (--jev-decider chat)`
+        : `--jev-decider chat needs ${missing.join(' and ')} so the text model can decide`,
+    }
+  }
+  const missing = []
+  if (config.jev.typesafe.apiKey === '') missing.push('TYPESAFE_API_KEY')
+  // The text helper writes a TYPE_TEXT value; a goal with only clicks needs no text model, so this
+  // is reported but does not make the policy unusable.
+  const textNote = config.jev.textModel.apiKey === '' && config.jev.textModel.baseURL === ''
+    ? '; TYPE_TEXT values need TEXT_MODEL_API_KEY/TEXT_MODEL_BASE_URL/TEXT_MODEL, or write them yourself with browser_act'
+    : ''
+  return {
+    ready: missing.length === 0,
+    missing,
+    description: missing.length === 0
+      ? `Jev at ${config.jev.typesafe.baseURL || 'the default TypeSafe endpoint'} (model ${config.jev.typesafe.model || 'default'}) decides${textNote}`
+      : `${missing.join(' and ')} is required for browser_goal and browser_act intents, or pass --jev-decider chat with TEXT_MODEL_*`,
+  }
+}
+
+/**
+ * Where the Jev credentials come from, in one line the doctor can print — never a key itself.
+ * @param {object} config - the resolved configuration.
+ * @returns {string}
+ */
+export function jevDescribe(config) {
+  if (!config.jev.enabled) return 'off (--no-jev)'
+  const key = value => (String(value ?? '').trim() === '' ? 'unset' : 'set')
+  if (config.jev.decider === 'chat') {
+    return `on, chat decider: text model ${config.jev.textModel.model || '(unset)'} at ${config.jev.textModel.baseURL || '(unset)'}, key ${key(config.jev.textModel.apiKey)}`
+  }
+  return `on, typesafe decider: ${config.jev.typesafe.baseURL || 'default endpoint'} (model ${config.jev.typesafe.model || 'default'}), key ${key(config.jev.typesafe.apiKey)}; text model ${config.jev.textModel.model || '(unset)'} at ${config.jev.textModel.baseURL || '(unset)'}, key ${key(config.jev.textModel.apiKey)}`
+}

package/lib/log.js

@@ -0,0 +1,32 @@
+/**
+ * Logging for a protocol whose stdout belongs to the transport.
+ *
+ * An MCP stdio server's stdout carries JSON-RPC frames, so every log line here goes to stderr.
+ * A line that landed on stdout would corrupt the protocol rather than merely spoil the output.
+ *
+ * @module browser-use-mcp/log
+ */
+
+const LEVELS = { silent: 0, error: 1, info: 2, debug: 3 }
+const PREFIX = 'browser-use-mcp'
+
+/** One stderr logger bound to a level; `debug` is silent unless the level asks for it. */
+export function createLogger(level = 'info') {
+  const threshold = LEVELS[level] ?? LEVELS.info
+  const write = (kind, args) => {
+    if (threshold < LEVELS[kind]) return
+    const text = args
+      .map(value => (value instanceof Error ? (value.stack ?? value.message) : typeof value === 'string' ? value : JSON.stringify(value)))
+      .join(' ')
+    process.stderr.write(`${PREFIX} ${text}\n`)
+  }
+  return {
+    level,
+    error: (...args) => write('error', args),
+    info: (...args) => write('info', args),
+    debug: (...args) => write('debug', args),
+  }
+}
+
+/** A logger that throws everything away, for library callers and tests. */
+export const silentLogger = createLogger('silent')