@xortex/xcode 3.0.0

package/services/mcp/elicitationHandler.ts

@@ -0,0 +1,313 @@
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import {
+  ElicitationCompleteNotificationSchema,
+  type ElicitRequestParams,
+  ElicitRequestSchema,
+  type ElicitResult,
+} from '@modelcontextprotocol/sdk/types.js'
+import type { AppState } from '../../state/AppState.js'
+import {
+  executeElicitationHooks,
+  executeElicitationResultHooks,
+  executeNotificationHooks,
+} from '../../utils/hooks.js'
+import { logMCPDebug, logMCPError } from '../../utils/log.js'
+import { jsonStringify } from '../../utils/slowOperations.js'
+import {
+  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  logEvent,
+} from '../analytics/index.js'
+
+/** Configuration for the waiting state shown after the user opens a URL. */
+export type ElicitationWaitingState = {
+  /** Button label, e.g. "Retry now" or "Skip confirmation" */
+  actionLabel: string
+  /** Whether to show a visible Cancel button (e.g. for error-based retry flow) */
+  showCancel?: boolean
+}
+
+export type ElicitationRequestEvent = {
+  serverName: string
+  /** The JSON-RPC request ID, unique per server connection. */
+  requestId: string | number
+  params: ElicitRequestParams
+  signal: AbortSignal
+  /**
+   * Resolves the elicitation. For explicit elicitations, all actions are
+   * meaningful. For error-based retry (-32042), 'accept' is a no-op —
+   * the retry is driven by onWaitingDismiss instead.
+   */
+  respond: (response: ElicitResult) => void
+  /** For URL elicitations: shown after user opens the browser. */
+  waitingState?: ElicitationWaitingState
+  /** Called when phase 2 (waiting) is dismissed by user action or completion. */
+  onWaitingDismiss?: (action: 'dismiss' | 'retry' | 'cancel') => void
+  /** Set to true by the completion notification handler when the server confirms completion. */
+  completed?: boolean
+}
+
+function getElicitationMode(params: ElicitRequestParams): 'form' | 'url' {
+  return params.mode === 'url' ? 'url' : 'form'
+}
+
+/** Find a queued elicitation event by server name and elicitationId. */
+function findElicitationInQueue(
+  queue: ElicitationRequestEvent[],
+  serverName: string,
+  elicitationId: string,
+): number {
+  return queue.findIndex(
+    e =>
+      e.serverName === serverName &&
+      e.params.mode === 'url' &&
+      'elicitationId' in e.params &&
+      e.params.elicitationId === elicitationId,
+  )
+}
+
+export function registerElicitationHandler(
+  client: Client,
+  serverName: string,
+  setAppState: (f: (prevState: AppState) => AppState) => void,
+): void {
+  // Register the elicitation request handler.
+  // Wrapped in try/catch because setRequestHandler throws if the client wasn't
+  // created with elicitation capability declared.
+  try {
+    client.setRequestHandler(ElicitRequestSchema, async (request, extra) => {
+      logMCPDebug(
+        serverName,
+        `Received elicitation request: ${jsonStringify(request)}`,
+      )
+
+      const mode = getElicitationMode(request.params)
+
+      logEvent('tengu_mcp_elicitation_shown', {
+        mode: mode as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      })
+
+      try {
+        // Run elicitation hooks first - they can provide a response programmatically
+        const hookResponse = await runElicitationHooks(
+          serverName,
+          request.params,
+          extra.signal,
+        )
+        if (hookResponse) {
+          logMCPDebug(
+            serverName,
+            `Elicitation resolved by hook: ${jsonStringify(hookResponse)}`,
+          )
+          logEvent('tengu_mcp_elicitation_response', {
+            mode: mode as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+            action:
+              hookResponse.action as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+          })
+          return hookResponse
+        }
+
+        const elicitationId =
+          mode === 'url' && 'elicitationId' in request.params
+            ? (request.params.elicitationId as string | undefined)
+            : undefined
+
+        const response = new Promise<ElicitResult>(resolve => {
+          const onAbort = () => {
+            resolve({ action: 'cancel' })
+          }
+
+          if (extra.signal.aborted) {
+            onAbort()
+            return
+          }
+
+          const waitingState: ElicitationWaitingState | undefined =
+            elicitationId ? { actionLabel: 'Skip confirmation' } : undefined
+
+          setAppState(prev => ({
+            ...prev,
+            elicitation: {
+              queue: [
+                ...prev.elicitation.queue,
+                {
+                  serverName,
+                  requestId: extra.requestId,
+                  params: request.params,
+                  signal: extra.signal,
+                  waitingState,
+                  respond: (result: ElicitResult) => {
+                    extra.signal.removeEventListener('abort', onAbort)
+                    logEvent('tengu_mcp_elicitation_response', {
+                      mode: mode as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+                      action:
+                        result.action as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+                    })
+                    resolve(result)
+                  },
+                },
+              ],
+            },
+          }))
+
+          extra.signal.addEventListener('abort', onAbort, { once: true })
+        })
+        const rawResult = await response
+        logMCPDebug(
+          serverName,
+          `Elicitation response: ${jsonStringify(rawResult)}`,
+        )
+        const result = await runElicitationResultHooks(
+          serverName,
+          rawResult,
+          extra.signal,
+          mode,
+          elicitationId,
+        )
+        return result
+      } catch (error) {
+        logMCPError(serverName, `Elicitation error: ${error}`)
+        return { action: 'cancel' as const }
+      }
+    })
+
+    // Register handler for elicitation completion notifications (URL mode).
+    // Sets `completed: true` on the matching queue event; the dialog reacts to this flag.
+    client.setNotificationHandler(
+      ElicitationCompleteNotificationSchema,
+      notification => {
+        const { elicitationId } = notification.params
+        logMCPDebug(
+          serverName,
+          `Received elicitation completion notification: ${elicitationId}`,
+        )
+        void executeNotificationHooks({
+          message: `MCP server "${serverName}" confirmed elicitation ${elicitationId} complete`,
+          notificationType: 'elicitation_complete',
+        })
+        let found = false
+        setAppState(prev => {
+          const idx = findElicitationInQueue(
+            prev.elicitation.queue,
+            serverName,
+            elicitationId,
+          )
+          if (idx === -1) return prev
+          found = true
+          const queue = [...prev.elicitation.queue]
+          queue[idx] = { ...queue[idx]!, completed: true }
+          return { ...prev, elicitation: { queue } }
+        })
+        if (!found) {
+          logMCPDebug(
+            serverName,
+            `Ignoring completion notification for unknown elicitation: ${elicitationId}`,
+          )
+        }
+      },
+    )
+  } catch {
+    // Client wasn't created with elicitation capability - nothing to register
+    return
+  }
+}
+
+export async function runElicitationHooks(
+  serverName: string,
+  params: ElicitRequestParams,
+  signal: AbortSignal,
+): Promise<ElicitResult | undefined> {
+  try {
+    const mode = params.mode === 'url' ? 'url' : 'form'
+    const url = 'url' in params ? (params.url as string) : undefined
+    const elicitationId =
+      'elicitationId' in params
+        ? (params.elicitationId as string | undefined)
+        : undefined
+
+    const { elicitationResponse, blockingError } =
+      await executeElicitationHooks({
+        serverName,
+        message: params.message,
+        requestedSchema:
+          'requestedSchema' in params
+            ? (params.requestedSchema as Record<string, unknown>)
+            : undefined,
+        signal,
+        mode,
+        url,
+        elicitationId,
+      })
+
+    if (blockingError) {
+      return { action: 'decline' }
+    }
+
+    if (elicitationResponse) {
+      return {
+        action: elicitationResponse.action,
+        content: elicitationResponse.content,
+      }
+    }
+
+    return undefined
+  } catch (error) {
+    logMCPError(serverName, `Elicitation hook error: ${error}`)
+    return undefined
+  }
+}
+
+/**
+ * Run ElicitationResult hooks after the user has responded, then fire a
+ * `elicitation_response` notification. Returns a (potentially modified)
+ * ElicitResult — hooks may override the action/content or block the response.
+ */
+export async function runElicitationResultHooks(
+  serverName: string,
+  result: ElicitResult,
+  signal: AbortSignal,
+  mode?: 'form' | 'url',
+  elicitationId?: string,
+): Promise<ElicitResult> {
+  try {
+    const { elicitationResultResponse, blockingError } =
+      await executeElicitationResultHooks({
+        serverName,
+        action: result.action,
+        content: result.content as Record<string, unknown> | undefined,
+        signal,
+        mode,
+        elicitationId,
+      })
+
+    if (blockingError) {
+      void executeNotificationHooks({
+        message: `Elicitation response for server "${serverName}": decline`,
+        notificationType: 'elicitation_response',
+      })
+      return { action: 'decline' }
+    }
+
+    const finalResult = elicitationResultResponse
+      ? {
+          action: elicitationResultResponse.action,
+          content: elicitationResultResponse.content ?? result.content,
+        }
+      : result
+
+    // Fire a notification for observability
+    void executeNotificationHooks({
+      message: `Elicitation response for server "${serverName}": ${finalResult.action}`,
+      notificationType: 'elicitation_response',
+    })
+
+    return finalResult
+  } catch (error) {
+    logMCPError(serverName, `ElicitationResult hook error: ${error}`)
+    // Fire notification even on error
+    void executeNotificationHooks({
+      message: `Elicitation response for server "${serverName}": ${result.action}`,
+      notificationType: 'elicitation_response',
+    })
+    return result
+  }
+}

package/services/mcp/envExpansion.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared utilities for expanding environment variables in MCP server configurations
+ */
+
+/**
+ * Expand environment variables in a string value
+ * Handles ${VAR} and ${VAR:-default} syntax
+ * @returns Object with expanded string and list of missing variables
+ */
+export function expandEnvVarsInString(value: string): {
+  expanded: string
+  missingVars: string[]
+} {
+  const missingVars: string[] = []
+
+  const expanded = value.replace(/\$\{([^}]+)\}/g, (match, varContent) => {
+    // Split on :- to support default values (limit to 2 parts to preserve :- in defaults)
+    const [varName, defaultValue] = varContent.split(':-', 2)
+    const envValue = process.env[varName]
+
+    if (envValue !== undefined) {
+      return envValue
+    }
+    if (defaultValue !== undefined) {
+      return defaultValue
+    }
+
+    // Track missing variable for error reporting
+    missingVars.push(varName)
+    // Return original if not found (allows debugging but will be reported as error)
+    return match
+  })
+
+  return {
+    expanded,
+    missingVars,
+  }
+}

package/services/mcp/headersHelper.ts

@@ -0,0 +1,138 @@
+import { getIsNonInteractiveSession } from '../../bootstrap/state.js'
+import { checkHasTrustDialogAccepted } from '../../utils/config.js'
+import { logAntError } from '../../utils/debug.js'
+import { errorMessage } from '../../utils/errors.js'
+import { execFileNoThrowWithCwd } from '../../utils/execFileNoThrow.js'
+import { logError, logMCPDebug, logMCPError } from '../../utils/log.js'
+import { jsonParse } from '../../utils/slowOperations.js'
+import { logEvent } from '../analytics/index.js'
+import type {
+  McpHTTPServerConfig,
+  McpSSEServerConfig,
+  McpWebSocketServerConfig,
+  ScopedMcpServerConfig,
+} from './types.js'
+
+/**
+ * Check if the MCP server config comes from project settings (projectSettings or localSettings)
+ * This is important for security checks
+ */
+function isMcpServerFromProjectOrLocalSettings(
+  config: ScopedMcpServerConfig,
+): boolean {
+  return config.scope === 'project' || config.scope === 'local'
+}
+
+/**
+ * Get dynamic headers for an MCP server using the headersHelper script
+ * @param serverName The name of the MCP server
+ * @param config The MCP server configuration
+ * @returns Headers object or null if not configured or failed
+ */
+export async function getMcpHeadersFromHelper(
+  serverName: string,
+  config: McpSSEServerConfig | McpHTTPServerConfig | McpWebSocketServerConfig,
+): Promise<Record<string, string> | null> {
+  if (!config.headersHelper) {
+    return null
+  }
+
+  // Security check for project/local settings
+  // Skip trust check in non-interactive mode (e.g., CI/CD, automation)
+  if (
+    'scope' in config &&
+    isMcpServerFromProjectOrLocalSettings(config as ScopedMcpServerConfig) &&
+    !getIsNonInteractiveSession()
+  ) {
+    // Check if trust has been established for this project
+    const hasTrust = checkHasTrustDialogAccepted()
+    if (!hasTrust) {
+      const error = new Error(
+        `Security: headersHelper for MCP server '${serverName}' executed before workspace trust is confirmed. If you see this message, post in ${MACRO.FEEDBACK_CHANNEL}.`,
+      )
+      logAntError('MCP headersHelper invoked before trust check', error)
+      logEvent('tengu_mcp_headersHelper_missing_trust', {})
+      return null
+    }
+  }
+
+  try {
+    logMCPDebug(serverName, 'Executing headersHelper to get dynamic headers')
+    const execResult = await execFileNoThrowWithCwd(config.headersHelper, [], {
+      shell: true,
+      timeout: 10000,
+      // Pass server context so one helper script can serve multiple MCP servers
+      // (git credential-helper style). See deshaw/anthropic-issues#28.
+      env: {
+        ...process.env,
+        CLAUDE_CODE_MCP_SERVER_NAME: serverName,
+        CLAUDE_CODE_MCP_SERVER_URL: config.url,
+      },
+    })
+    if (execResult.code !== 0 || !execResult.stdout) {
+      throw new Error(
+        `headersHelper for MCP server '${serverName}' did not return a valid value`,
+      )
+    }
+    const result = execResult.stdout.trim()
+
+    const headers = jsonParse(result)
+    if (
+      typeof headers !== 'object' ||
+      headers === null ||
+      Array.isArray(headers)
+    ) {
+      throw new Error(
+        `headersHelper for MCP server '${serverName}' must return a JSON object with string key-value pairs`,
+      )
+    }
+
+    // Validate all values are strings
+    for (const [key, value] of Object.entries(headers)) {
+      if (typeof value !== 'string') {
+        throw new Error(
+          `headersHelper for MCP server '${serverName}' returned non-string value for key "${key}": ${typeof value}`,
+        )
+      }
+    }
+
+    logMCPDebug(
+      serverName,
+      `Successfully retrieved ${Object.keys(headers).length} headers from headersHelper`,
+    )
+    return headers as Record<string, string>
+  } catch (error) {
+    logMCPError(
+      serverName,
+      `Error getting headers from headersHelper: ${errorMessage(error)}`,
+    )
+    logError(
+      new Error(
+        `Error getting MCP headers from headersHelper for server '${serverName}': ${errorMessage(error)}`,
+      ),
+    )
+    // Return null instead of throwing to avoid blocking the connection
+    return null
+  }
+}
+
+/**
+ * Get combined headers for an MCP server (static + dynamic)
+ * @param serverName The name of the MCP server
+ * @param config The MCP server configuration
+ * @returns Combined headers object
+ */
+export async function getMcpServerHeaders(
+  serverName: string,
+  config: McpSSEServerConfig | McpHTTPServerConfig | McpWebSocketServerConfig,
+): Promise<Record<string, string>> {
+  const staticHeaders = config.headers || {}
+  const dynamicHeaders =
+    (await getMcpHeadersFromHelper(serverName, config)) || {}
+
+  // Dynamic headers override static headers if both are present
+  return {
+    ...staticHeaders,
+    ...dynamicHeaders,
+  }
+}

package/services/mcp/mcpStringUtils.ts

@@ -0,0 +1,106 @@
+/**
+ * Pure string utility functions for MCP tool/server name parsing.
+ * This file has no heavy dependencies to keep it lightweight for
+ * consumers that only need string parsing (e.g., permissionValidation).
+ */
+
+import { normalizeNameForMCP } from './normalization.js'
+
+/*
+ * Extracts MCP server information from a tool name string
+ * @param toolString The string to parse. Expected format: "mcp__serverName__toolName"
+ * @returns An object containing server name and optional tool name, or null if not a valid MCP rule
+ *
+ * Known limitation: If a server name contains "__", parsing will be incorrect.
+ * For example, "mcp__my__server__tool" would parse as server="my" and tool="server__tool"
+ * instead of server="my__server" and tool="tool". This is rare in practice since server
+ * names typically don't contain double underscores.
+ */
+export function mcpInfoFromString(toolString: string): {
+  serverName: string
+  toolName: string | undefined
+} | null {
+  const parts = toolString.split('__')
+  const [mcpPart, serverName, ...toolNameParts] = parts
+  if (mcpPart !== 'mcp' || !serverName) {
+    return null
+  }
+  // Join all parts after server name to preserve double underscores in tool names
+  const toolName =
+    toolNameParts.length > 0 ? toolNameParts.join('__') : undefined
+  return { serverName, toolName }
+}
+
+/**
+ * Generates the MCP tool/command name prefix for a given server
+ * @param serverName Name of the MCP server
+ * @returns The prefix string
+ */
+export function getMcpPrefix(serverName: string): string {
+  return `mcp__${normalizeNameForMCP(serverName)}__`
+}
+
+/**
+ * Builds a fully qualified MCP tool name from server and tool names.
+ * Inverse of mcpInfoFromString().
+ * @param serverName Name of the MCP server (unnormalized)
+ * @param toolName Name of the tool (unnormalized)
+ * @returns The fully qualified name, e.g., "mcp__server__tool"
+ */
+export function buildMcpToolName(serverName: string, toolName: string): string {
+  return `${getMcpPrefix(serverName)}${normalizeNameForMCP(toolName)}`
+}
+
+/**
+ * Returns the name to use for permission rule matching.
+ * For MCP tools, uses the fully qualified mcp__server__tool name so that
+ * deny rules targeting builtins (e.g., "Write") don't match unprefixed MCP
+ * replacements that share the same display name. Falls back to `tool.name`.
+ */
+export function getToolNameForPermissionCheck(tool: {
+  name: string
+  mcpInfo?: { serverName: string; toolName: string }
+}): string {
+  return tool.mcpInfo
+    ? buildMcpToolName(tool.mcpInfo.serverName, tool.mcpInfo.toolName)
+    : tool.name
+}
+
+/*
+ * Extracts the display name from an MCP tool/command name
+ * @param fullName The full MCP tool/command name (e.g., "mcp__server_name__tool_name")
+ * @param serverName The server name to remove from the prefix
+ * @returns The display name without the MCP prefix
+ */
+export function getMcpDisplayName(
+  fullName: string,
+  serverName: string,
+): string {
+  const prefix = `mcp__${normalizeNameForMCP(serverName)}__`
+  return fullName.replace(prefix, '')
+}
+
+/**
+ * Extracts just the tool/command display name from a userFacingName
+ * @param userFacingName The full user-facing name (e.g., "github - Add comment to issue (MCP)")
+ * @returns The display name without server prefix and (MCP) suffix
+ */
+export function extractMcpToolDisplayName(userFacingName: string): string {
+  // This is really ugly but our current Tool type doesn't make it easy to have different display names for different purposes.
+
+  // First, remove the (MCP) suffix if present
+  let withoutSuffix = userFacingName.replace(/\s*\(MCP\)\s*$/, '')
+
+  // Trim the result
+  withoutSuffix = withoutSuffix.trim()
+
+  // Then, remove the server prefix (everything before " - ")
+  const dashIndex = withoutSuffix.indexOf(' - ')
+  if (dashIndex !== -1) {
+    const displayName = withoutSuffix.substring(dashIndex + 3).trim()
+    return displayName
+  }
+
+  // If no dash found, return the string without (MCP)
+  return withoutSuffix
+}

package/services/mcp/normalization.ts

@@ -0,0 +1,23 @@
+/**
+ * Pure utility functions for MCP name normalization.
+ * This file has no dependencies to avoid circular imports.
+ */
+
+// Claude.ai server names are prefixed with this string
+const CLAUDEAI_SERVER_PREFIX = 'claude.ai '
+
+/**
+ * Normalize server names to be compatible with the API pattern ^[a-zA-Z0-9_-]{1,64}$
+ * Replaces any invalid characters (including dots and spaces) with underscores.
+ *
+ * For claude.ai servers (names starting with "claude.ai "), also collapses
+ * consecutive underscores and strips leading/trailing underscores to prevent
+ * interference with the __ delimiter used in MCP tool names.
+ */
+export function normalizeNameForMCP(name: string): string {
+  let normalized = name.replace(/[^a-zA-Z0-9_-]/g, '_')
+  if (name.startsWith(CLAUDEAI_SERVER_PREFIX)) {
+    normalized = normalized.replace(/_+/g, '_').replace(/^_|_$/g, '')
+  }
+  return normalized
+}

package/services/mcp/oauthPort.ts

@@ -0,0 +1,78 @@
+/**
+ * OAuth redirect port helpers — extracted from auth.ts to break the
+ * auth.ts ↔ xaaIdpLogin.ts circular dependency.
+ */
+import { createServer } from 'http'
+import { getPlatform } from '../../utils/platform.js'
+
+// Windows dynamic port range 49152-65535 is reserved
+const REDIRECT_PORT_RANGE =
+  getPlatform() === 'windows'
+    ? { min: 39152, max: 49151 }
+    : { min: 49152, max: 65535 }
+const REDIRECT_PORT_FALLBACK = 3118
+
+/**
+ * Builds a redirect URI on localhost with the given port and a fixed `/callback` path.
+ *
+ * RFC 8252 Section 7.3 (OAuth for Native Apps): loopback redirect URIs match any
+ * port as long as the path matches.
+ */
+export function buildRedirectUri(
+  port: number = REDIRECT_PORT_FALLBACK,
+): string {
+  return `http://localhost:${port}/callback`
+}
+
+function getMcpOAuthCallbackPort(): number | undefined {
+  const port = parseInt(process.env.MCP_OAUTH_CALLBACK_PORT || '', 10)
+  return port > 0 ? port : undefined
+}
+
+/**
+ * Finds an available port in the specified range for OAuth redirect
+ * Uses random selection for better security
+ */
+export async function findAvailablePort(): Promise<number> {
+  // First, try the configured port if specified
+  const configuredPort = getMcpOAuthCallbackPort()
+  if (configuredPort) {
+    return configuredPort
+  }
+
+  const { min, max } = REDIRECT_PORT_RANGE
+  const range = max - min + 1
+  const maxAttempts = Math.min(range, 100) // Don't try forever
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const port = min + Math.floor(Math.random() * range)
+
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const testServer = createServer()
+        testServer.once('error', reject)
+        testServer.listen(port, () => {
+          testServer.close(() => resolve())
+        })
+      })
+      return port
+    } catch {
+      // Port in use, try another random port
+      continue
+    }
+  }
+
+  // If random selection failed, try the fallback port
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const testServer = createServer()
+      testServer.once('error', reject)
+      testServer.listen(REDIRECT_PORT_FALLBACK, () => {
+        testServer.close(() => resolve())
+      })
+    })
+    return REDIRECT_PORT_FALLBACK
+  } catch {
+    throw new Error(`No available ports for OAuth redirect`)
+  }
+}