@xortex/xcode 3.0.0

package/utils/claudeInChrome/mcpServer.ts

@@ -0,0 +1,292 @@
+export type ClaudeForChromeContext = any;
+export const createClaudeForChromeMcpServer = () => null;
+export type Logger = any;
+export type PermissionMode = any;
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { format } from 'util'
+import { shutdownDatadog } from '../../services/analytics/datadog.js'
+import { shutdown1PEventLogging } from '../../services/analytics/firstPartyEventLogger.js'
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../../services/analytics/growthbook.js'
+import {
+  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  logEvent,
+} from '../../services/analytics/index.js'
+import { initializeAnalyticsSink } from '../../services/analytics/sink.js'
+import { getClaudeAIOAuthTokens } from '../auth.js'
+import { enableConfigs, getGlobalConfig, saveGlobalConfig } from '../config.js'
+import { logForDebugging } from '../debug.js'
+import { isEnvTruthy } from '../envUtils.js'
+import { sideQuery } from '../sideQuery.js'
+import { getAllSocketPaths, getSecureSocketPath } from './common.js'
+
+const EXTENSION_DOWNLOAD_URL = 'https://claude.ai/chrome'
+const BUG_REPORT_URL =
+  'https://github.com/anthropics/claude-code/issues/new?labels=bug,claude-in-chrome'
+
+// String metadata keys safe to forward to analytics. Keys like error_message
+// are excluded because they could contain page content or user data.
+const SAFE_BRIDGE_STRING_KEYS = new Set([
+  'bridge_status',
+  'error_type',
+  'tool_name',
+])
+
+const PERMISSION_MODES: readonly PermissionMode[] = [
+  'ask',
+  'skip_all_permission_checks',
+  'follow_a_plan',
+]
+
+function isPermissionMode(raw: string): raw is PermissionMode {
+  return PERMISSION_MODES.some(m => m === raw)
+}
+
+/**
+ * Resolves the Chrome bridge URL based on environment and feature flag.
+ * Bridge is used when the feature flag is enabled; ant users always get
+ * bridge. API key / 3P users fall back to native messaging.
+ */
+function getChromeBridgeUrl(): string | undefined {
+  const bridgeEnabled =
+    process.env.USER_TYPE === 'ant' ||
+    getFeatureValue_CACHED_MAY_BE_STALE('tengu_copper_bridge', false)
+
+  if (!bridgeEnabled) {
+    return undefined
+  }
+
+  if (
+    isEnvTruthy(process.env.USE_LOCAL_OAUTH) ||
+    isEnvTruthy(process.env.LOCAL_BRIDGE)
+  ) {
+    return 'ws://localhost:8765'
+  }
+
+  if (isEnvTruthy(process.env.USE_STAGING_OAUTH)) {
+    return 'wss://bridge-staging.claudeusercontent.com'
+  }
+
+  return 'wss://bridge.claudeusercontent.com'
+}
+
+function isLocalBridge(): boolean {
+  return (
+    isEnvTruthy(process.env.USE_LOCAL_OAUTH) ||
+    isEnvTruthy(process.env.LOCAL_BRIDGE)
+  )
+}
+
+/**
+ * Build the ClaudeForChromeContext used by both the subprocess MCP server
+ * and the in-process path in the MCP client.
+ */
+export function createChromeContext(
+  env?: Record<string, string>,
+): ClaudeForChromeContext {
+  const logger = new DebugLogger()
+  const chromeBridgeUrl = getChromeBridgeUrl()
+  logger.info(`Bridge URL: ${chromeBridgeUrl ?? 'none (using native socket)'}`)
+  const rawPermissionMode =
+    env?.CLAUDE_CHROME_PERMISSION_MODE ??
+    process.env.CLAUDE_CHROME_PERMISSION_MODE
+  let initialPermissionMode: PermissionMode | undefined
+  if (rawPermissionMode) {
+    if (isPermissionMode(rawPermissionMode)) {
+      initialPermissionMode = rawPermissionMode
+    } else {
+      logger.warn(
+        `Invalid CLAUDE_CHROME_PERMISSION_MODE "${rawPermissionMode}". Valid values: ${PERMISSION_MODES.join(', ')}`,
+      )
+    }
+  }
+  return {
+    serverName: 'Claude in Chrome',
+    logger,
+    socketPath: getSecureSocketPath(),
+    getSocketPaths: getAllSocketPaths,
+    clientTypeId: 'claude-code',
+    onAuthenticationError: () => {
+      logger.warn(
+        'Authentication error occurred. Please ensure you are logged into the Claude browser extension with the same claude.ai account as Claude Code.',
+      )
+    },
+    onToolCallDisconnected: () => {
+      return `Browser extension is not connected. Please ensure the Claude browser extension is installed and running (${EXTENSION_DOWNLOAD_URL}), and that you are logged into claude.ai with the same account as Claude Code. If this is your first time connecting to Chrome, you may need to restart Chrome for the installation to take effect. If you continue to experience issues, please report a bug: ${BUG_REPORT_URL}`
+    },
+    onExtensionPaired: (deviceId: string, name: string) => {
+      saveGlobalConfig(config => {
+        if (
+          config.chromeExtension?.pairedDeviceId === deviceId &&
+          config.chromeExtension?.pairedDeviceName === name
+        ) {
+          return config
+        }
+        return {
+          ...config,
+          chromeExtension: {
+            pairedDeviceId: deviceId,
+            pairedDeviceName: name,
+          },
+        }
+      })
+      logger.info(`Paired with "${name}" (${deviceId.slice(0, 8)})`)
+    },
+    getPersistedDeviceId: () => {
+      return getGlobalConfig().chromeExtension?.pairedDeviceId
+    },
+    ...(chromeBridgeUrl && {
+      bridgeConfig: {
+        url: chromeBridgeUrl,
+        getUserId: async () => {
+          return getGlobalConfig().oauthAccount?.accountUuid
+        },
+        getOAuthToken: async () => {
+          return getClaudeAIOAuthTokens()?.accessToken ?? ''
+        },
+        ...(isLocalBridge() && { devUserId: 'dev_user_local' }),
+      },
+    }),
+    ...(initialPermissionMode && { initialPermissionMode }),
+    // Wire inference for the browser_task tool — the chrome-mcp server runs
+    // a lightning-mode agent loop in Node and calls the extension's
+    // lightning_turn tool once per iteration for execution.
+    //
+    // Ant-only: the extension's lightning_turn is build-time-gated via
+    // import.meta.env.ANT_ONLY_BUILD — the whole lightning/ module graph is
+    // tree-shaken from the public extension build (build:prod greps for a
+    // marker to verify). Without this injection, the Node MCP server's
+    // ListTools also filters browser_task + lightning_turn out, so external
+    // users never see the tools advertised. Three independent gates.
+    //
+    // Types inlined: AnthropicMessagesRequest/Response live in
+    // @ant/claude-for-chrome-mcp@0.4.0 which isn't published yet. CI installs
+    // 0.3.0. The callAnthropicMessages field is also 0.4.0-only, but spreading
+    // an extra property into ClaudeForChromeContext is fine against either
+    // version — 0.3.0 sees an unknown field (allowed in spread), 0.4.0 sees a
+    // structurally-matching one. Once 0.4.0 is published, this can switch to
+    // the package's exported types and the dep can be bumped.
+    ...(process.env.USER_TYPE === 'ant' && {
+      callAnthropicMessages: async (req: {
+        model: string
+        max_tokens: number
+        system: string
+        messages: Parameters<typeof sideQuery>[0]['messages']
+        stop_sequences?: string[]
+        signal?: AbortSignal
+      }): Promise<{
+        content: Array<{ type: 'text'; text: string }>
+        stop_reason: string | null
+        usage?: { input_tokens: number; output_tokens: number }
+      }> => {
+        // sideQuery handles OAuth attribution fingerprint, proxy, model betas.
+        // skipSystemPromptPrefix: the lightning prompt is complete on its own;
+        // the CLI prefix would dilute the batching instructions.
+        // tools: [] is load-bearing — without it Sonnet emits
+        // <function_calls> XML before the text commands. Original
+        // lightning-harness.js (apps repo) does the same.
+        const response = await sideQuery({
+          model: req.model,
+          system: req.system,
+          messages: req.messages,
+          max_tokens: req.max_tokens,
+          stop_sequences: req.stop_sequences,
+          signal: req.signal,
+          skipSystemPromptPrefix: true,
+          tools: [],
+          querySource: 'chrome_mcp',
+        })
+        // BetaContentBlock is TextBlock | ThinkingBlock | ToolUseBlock | ...
+        // Only text blocks carry the model's command output.
+        const textBlocks: Array<{ type: 'text'; text: string }> = []
+        for (const b of response.content) {
+          if (b.type === 'text') {
+            textBlocks.push({ type: 'text', text: b.text })
+          }
+        }
+        return {
+          content: textBlocks,
+          stop_reason: response.stop_reason,
+          usage: {
+            input_tokens: response.usage.input_tokens,
+            output_tokens: response.usage.output_tokens,
+          },
+        }
+      },
+    }),
+    trackEvent: (eventName, metadata) => {
+      const safeMetadata: {
+        [key: string]:
+          | boolean
+          | number
+          | AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
+          | undefined
+      } = {}
+      if (metadata) {
+        for (const [key, value] of Object.entries(metadata)) {
+          // Rename 'status' to 'bridge_status' to avoid Datadog's reserved field
+          const safeKey = key === 'status' ? 'bridge_status' : key
+          if (typeof value === 'boolean' || typeof value === 'number') {
+            safeMetadata[safeKey] = value
+          } else if (
+            typeof value === 'string' &&
+            SAFE_BRIDGE_STRING_KEYS.has(safeKey)
+          ) {
+            // Only forward allowlisted string keys — fields like error_message
+            // could contain page content or user data
+            safeMetadata[safeKey] =
+              value as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
+          }
+        }
+      }
+      logEvent(eventName, safeMetadata)
+    },
+  }
+}
+
+export async function runClaudeInChromeMcpServer(): Promise<void> {
+  enableConfigs()
+  initializeAnalyticsSink()
+  const context = createChromeContext()
+
+  const server = createClaudeForChromeMcpServer(context)
+  const transport = new StdioServerTransport()
+
+  // Exit when parent process dies (stdin pipe closes).
+  // Flush analytics before exiting so final-batch events (e.g. disconnect) aren't lost.
+  let exiting = false
+  const shutdownAndExit = async (): Promise<void> => {
+    if (exiting) {
+      return
+    }
+    exiting = true
+    await shutdown1PEventLogging()
+    await shutdownDatadog()
+    // eslint-disable-next-line custom-rules/no-process-exit
+    process.exit(0)
+  }
+  process.stdin.on('end', () => void shutdownAndExit())
+  process.stdin.on('error', () => void shutdownAndExit())
+
+  logForDebugging('[Claude in Chrome] Starting MCP server')
+  await server.connect(transport)
+  logForDebugging('[Claude in Chrome] MCP server started')
+}
+
+class DebugLogger implements Logger {
+  silly(message: string, ...args: unknown[]): void {
+    logForDebugging(format(message, ...args), { level: 'debug' })
+  }
+  debug(message: string, ...args: unknown[]): void {
+    logForDebugging(format(message, ...args), { level: 'debug' })
+  }
+  info(message: string, ...args: unknown[]): void {
+    logForDebugging(format(message, ...args), { level: 'info' })
+  }
+  warn(message: string, ...args: unknown[]): void {
+    logForDebugging(format(message, ...args), { level: 'warn' })
+  }
+  error(message: string, ...args: unknown[]): void {
+    logForDebugging(format(message, ...args), { level: 'error' })
+  }
+}

package/utils/claudeInChrome/prompt.ts

@@ -0,0 +1,83 @@
+export const BASE_CHROME_PROMPT = `# Claude in Chrome browser automation
+
+You have access to browser automation tools (mcp__claude-in-chrome__*) for interacting with web pages in Chrome. Follow these guidelines for effective browser automation.
+
+## GIF recording
+
+When performing multi-step browser interactions that the user may want to review or share, use mcp__claude-in-chrome__gif_creator to record them.
+
+You must ALWAYS:
+* Capture extra frames before and after taking actions to ensure smooth playback
+* Name the file meaningfully to help the user identify it later (e.g., "login_process.gif")
+
+## Console log debugging
+
+You can use mcp__claude-in-chrome__read_console_messages to read console output. Console output may be verbose. If you are looking for specific log entries, use the 'pattern' parameter with a regex-compatible pattern. This filters results efficiently and avoids overwhelming output. For example, use pattern: "[MyApp]" to filter for application-specific logs rather than reading all console output.
+
+## Alerts and dialogs
+
+IMPORTANT: Do not trigger JavaScript alerts, confirms, prompts, or browser modal dialogs through your actions. These browser dialogs block all further browser events and will prevent the extension from receiving any subsequent commands. Instead, when possible, use console.log for debugging and then use the mcp__claude-in-chrome__read_console_messages tool to read those log messages. If a page has dialog-triggering elements:
+1. Avoid clicking buttons or links that may trigger alerts (e.g., "Delete" buttons with confirmation dialogs)
+2. If you must interact with such elements, warn the user first that this may interrupt the session
+3. Use mcp__claude-in-chrome__javascript_tool to check for and dismiss any existing dialogs before proceeding
+
+If you accidentally trigger a dialog and lose responsiveness, inform the user they need to manually dismiss it in the browser.
+
+## Avoid rabbit holes and loops
+
+When using browser automation tools, stay focused on the specific task. If you encounter any of the following, stop and ask the user for guidance:
+- Unexpected complexity or tangential browser exploration
+- Browser tool calls failing or returning errors after 2-3 attempts
+- No response from the browser extension
+- Page elements not responding to clicks or input
+- Pages not loading or timing out
+- Unable to complete the browser task despite multiple approaches
+
+Explain what you attempted, what went wrong, and ask how the user would like to proceed. Do not keep retrying the same failing browser action or explore unrelated pages without checking in first.
+
+## Tab context and session startup
+
+IMPORTANT: At the start of each browser automation session, call mcp__claude-in-chrome__tabs_context_mcp first to get information about the user's current browser tabs. Use this context to understand what the user might want to work with before creating new tabs.
+
+Never reuse tab IDs from a previous/other session. Follow these guidelines:
+1. Only reuse an existing tab if the user explicitly asks to work with it
+2. Otherwise, create a new tab with mcp__claude-in-chrome__tabs_create_mcp
+3. If a tool returns an error indicating the tab doesn't exist or is invalid, call tabs_context_mcp to get fresh tab IDs
+4. When a tab is closed by the user or a navigation error occurs, call tabs_context_mcp to see what tabs are available`
+
+/**
+ * Additional instructions for chrome tools when tool search is enabled.
+ * These instruct the model to load chrome tools via ToolSearch before using them.
+ * Only injected when tool search is actually enabled (not just optimistically possible).
+ */
+export const CHROME_TOOL_SEARCH_INSTRUCTIONS = `**IMPORTANT: Before using any chrome browser tools, you MUST first load them using ToolSearch.**
+
+Chrome browser tools are MCP tools that require loading before use. Before calling any mcp__claude-in-chrome__* tool:
+1. Use ToolSearch with \`select:mcp__claude-in-chrome__<tool_name>\` to load the specific tool
+2. Then call the tool
+
+For example, to get tab context:
+1. First: ToolSearch with query "select:mcp__claude-in-chrome__tabs_context_mcp"
+2. Then: Call mcp__claude-in-chrome__tabs_context_mcp`
+
+/**
+ * Get the base chrome system prompt (without tool search instructions).
+ * Tool search instructions are injected separately at request time in claude.ts
+ * based on the actual tool search enabled state.
+ */
+export function getChromeSystemPrompt(): string {
+  return BASE_CHROME_PROMPT
+}
+
+/**
+ * Minimal hint about Claude in Chrome skill availability. This is injected at startup when the extension is installed
+ * to guide the model to invoke the skill before using the MCP tools.
+ */
+export const CLAUDE_IN_CHROME_SKILL_HINT = `**Browser Automation**: Chrome browser tools are available via the "claude-in-chrome" skill. CRITICAL: Before using any mcp__claude-in-chrome__* tools, invoke the skill by calling the Skill tool with skill: "claude-in-chrome". The skill provides browser automation instructions and enables the tools.`
+
+/**
+ * Variant when the built-in WebBrowser tool is also available — steer
+ * dev-loop tasks to WebBrowser and reserve the extension for the user's
+ * authenticated Chrome (logged-in sites, OAuth, computer-use).
+ */
+export const CLAUDE_IN_CHROME_SKILL_HINT_WITH_WEBBROWSER = `**Browser Automation**: Use WebBrowser for development (dev servers, JS eval, console, screenshots). Use claude-in-chrome for the user's real Chrome when you need logged-in sessions, OAuth, or computer-use — invoke Skill(skill: "claude-in-chrome") before any mcp__claude-in-chrome__* tool.`