@xortex/xcode 3.0.0

package/utils/plugins/mcpPluginIntegration.ts

@@ -0,0 +1,634 @@
+import { join } from 'path'
+import { expandEnvVarsInString } from '../../services/mcp/envExpansion.js'
+import {
+  type McpServerConfig,
+  McpServerConfigSchema,
+  type ScopedMcpServerConfig,
+} from '../../services/mcp/types.js'
+import type { LoadedPlugin, PluginError } from '../../types/plugin.js'
+import { logForDebugging } from '../debug.js'
+import { errorMessage, isENOENT } from '../errors.js'
+import { getFsImplementation } from '../fsOperations.js'
+import { jsonParse } from '../slowOperations.js'
+import {
+  isMcpbSource,
+  loadMcpbFile,
+  loadMcpServerUserConfig,
+  type McpbLoadResult,
+  type UserConfigSchema,
+  type UserConfigValues,
+  validateUserConfig,
+} from './mcpbHandler.js'
+import { getPluginDataDir } from './pluginDirectories.js'
+import {
+  getPluginStorageId,
+  loadPluginOptions,
+  substitutePluginVariables,
+  substituteUserConfigVariables,
+} from './pluginOptionsStorage.js'
+
+/**
+ * Load MCP servers from an MCPB file
+ * Handles downloading, extracting, and converting DXT manifest to MCP config
+ */
+async function loadMcpServersFromMcpb(
+  plugin: LoadedPlugin,
+  mcpbPath: string,
+  errors: PluginError[],
+): Promise<Record<string, McpServerConfig> | null> {
+  try {
+    logForDebugging(`Loading MCP servers from MCPB: ${mcpbPath}`)
+
+    // Use plugin.repository directly - it's already in "plugin@marketplace" format
+    const pluginId = plugin.repository
+
+    const result = await loadMcpbFile(
+      mcpbPath,
+      plugin.path,
+      pluginId,
+      status => {
+        logForDebugging(`MCPB [${plugin.name}]: ${status}`)
+      },
+    )
+
+    // Check if MCPB needs user configuration
+    if ('status' in result && result.status === 'needs-config') {
+      // User config needed - this is normal for unconfigured plugins
+      // Don't load the MCP server yet - user can configure via /plugin menu
+      logForDebugging(
+        `MCPB ${mcpbPath} requires user configuration. ` +
+          `User can configure via: /plugin → Manage plugins → ${plugin.name} → Configure`,
+      )
+      // Return null to skip this server for now (not an error)
+      return null
+    }
+
+    // Type guard passed - result is success type
+    const successResult = result as McpbLoadResult
+
+    // Use the DXT manifest name as the server name
+    const serverName = successResult.manifest.name
+
+    // Check for server name conflicts with existing servers
+    // This will be checked later when merging all servers, but we log here for debugging
+    logForDebugging(
+      `Loaded MCP server "${serverName}" from MCPB (extracted to ${successResult.extractedPath})`,
+    )
+
+    return { [serverName]: successResult.mcpConfig }
+  } catch (error) {
+    const errorMsg = errorMessage(error)
+    logForDebugging(`Failed to load MCPB ${mcpbPath}: ${errorMsg}`, {
+      level: 'error',
+    })
+
+    // Use plugin@repository as source (consistent with other plugin errors)
+    const source = `${plugin.name}@${plugin.repository}`
+
+    // Determine error type based on error message
+    const isUrl = mcpbPath.startsWith('http')
+    if (
+      isUrl &&
+      (errorMsg.includes('download') || errorMsg.includes('network'))
+    ) {
+      errors.push({
+        type: 'mcpb-download-failed',
+        source,
+        plugin: plugin.name,
+        url: mcpbPath,
+        reason: errorMsg,
+      })
+    } else if (
+      errorMsg.includes('manifest') ||
+      errorMsg.includes('user configuration')
+    ) {
+      errors.push({
+        type: 'mcpb-invalid-manifest',
+        source,
+        plugin: plugin.name,
+        mcpbPath,
+        validationError: errorMsg,
+      })
+    } else {
+      errors.push({
+        type: 'mcpb-extract-failed',
+        source,
+        plugin: plugin.name,
+        mcpbPath,
+        reason: errorMsg,
+      })
+    }
+
+    return null
+  }
+}
+
+/**
+ * Load MCP servers from a plugin's manifest
+ * This function loads MCP server configurations from various sources within the plugin
+ * including manifest entries, .mcp.json files, and .mcpb files
+ */
+export async function loadPluginMcpServers(
+  plugin: LoadedPlugin,
+  errors: PluginError[] = [],
+): Promise<Record<string, McpServerConfig> | undefined> {
+  let servers: Record<string, McpServerConfig> = {}
+
+  // Check for .mcp.json in plugin directory first (lowest priority)
+  const defaultMcpServers = await loadMcpServersFromFile(
+    plugin.path,
+    '.mcp.json',
+  )
+  if (defaultMcpServers) {
+    servers = { ...servers, ...defaultMcpServers }
+  }
+
+  // Handle manifest mcpServers if present (higher priority)
+  if (plugin.manifest.mcpServers) {
+    const mcpServersSpec = plugin.manifest.mcpServers
+
+    // Handle different mcpServers formats
+    if (typeof mcpServersSpec === 'string') {
+      // Check if it's an MCPB file
+      if (isMcpbSource(mcpServersSpec)) {
+        const mcpbServers = await loadMcpServersFromMcpb(
+          plugin,
+          mcpServersSpec,
+          errors,
+        )
+        if (mcpbServers) {
+          servers = { ...servers, ...mcpbServers }
+        }
+      } else {
+        // Path to JSON file
+        const mcpServers = await loadMcpServersFromFile(
+          plugin.path,
+          mcpServersSpec,
+        )
+        if (mcpServers) {
+          servers = { ...servers, ...mcpServers }
+        }
+      }
+    } else if (Array.isArray(mcpServersSpec)) {
+      // Array of paths or inline configs.
+      // Load all specs in parallel, then merge in original order so
+      // last-wins collision semantics are preserved.
+      const results = await Promise.all(
+        mcpServersSpec.map(async spec => {
+          try {
+            if (typeof spec === 'string') {
+              // Check if it's an MCPB file
+              if (isMcpbSource(spec)) {
+                return await loadMcpServersFromMcpb(plugin, spec, errors)
+              }
+              // Path to JSON file
+              return await loadMcpServersFromFile(plugin.path, spec)
+            }
+            // Inline MCP server configs (sync)
+            return spec
+          } catch (e) {
+            // Defensive: if one spec throws, don't lose results from the
+            // others. The previous serial loop implicitly tolerated this.
+            logForDebugging(
+              `Failed to load MCP servers from spec for plugin ${plugin.name}: ${e}`,
+              { level: 'error' },
+            )
+            return null
+          }
+        }),
+      )
+      for (const result of results) {
+        if (result) {
+          servers = { ...servers, ...result }
+        }
+      }
+    } else {
+      // Direct MCP server configs
+      servers = { ...servers, ...mcpServersSpec }
+    }
+  }
+
+  return Object.keys(servers).length > 0 ? servers : undefined
+}
+
+/**
+ * Load MCP servers from a JSON file within a plugin
+ * This is a simplified version that doesn't expand environment variables
+ * and is specifically for plugin MCP configs
+ */
+async function loadMcpServersFromFile(
+  pluginPath: string,
+  relativePath: string,
+): Promise<Record<string, McpServerConfig> | null> {
+  const fs = getFsImplementation()
+  const filePath = join(pluginPath, relativePath)
+
+  let content: string
+  try {
+    content = await fs.readFile(filePath, { encoding: 'utf-8' })
+  } catch (e: unknown) {
+    if (isENOENT(e)) {
+      return null
+    }
+    logForDebugging(`Failed to load MCP servers from ${filePath}: ${e}`, {
+      level: 'error',
+    })
+    return null
+  }
+
+  try {
+    const parsed = jsonParse(content)
+
+    // Check if it's in the .mcp.json format with mcpServers key
+    const mcpServers = parsed.mcpServers || parsed
+
+    // Validate each server config
+    const validatedServers: Record<string, McpServerConfig> = {}
+    for (const [name, config] of Object.entries(mcpServers)) {
+      const result = McpServerConfigSchema().safeParse(config)
+      if (result.success) {
+        validatedServers[name] = result.data
+      } else {
+        logForDebugging(
+          `Invalid MCP server config for ${name} in ${filePath}: ${result.error.message}`,
+          { level: 'error' },
+        )
+      }
+    }
+
+    return validatedServers
+  } catch (error) {
+    logForDebugging(`Failed to load MCP servers from ${filePath}: ${error}`, {
+      level: 'error',
+    })
+    return null
+  }
+}
+
+/**
+ * A channel entry from a plugin's manifest whose userConfig has not yet been
+ * filled in (required fields are missing from saved settings).
+ */
+export type UnconfiguredChannel = {
+  server: string
+  displayName: string
+  configSchema: UserConfigSchema
+}
+
+/**
+ * Find channel entries in a plugin's manifest whose required userConfig
+ * fields are not yet saved. Pure function — no React, no prompting.
+ * ManagePlugins.tsx calls this after a plugin is enabled to decide whether
+ * to show the config dialog.
+ *
+ * Entries without a `userConfig` schema are skipped (nothing to prompt for).
+ * Entries whose saved config already satisfies `validateUserConfig` are
+ * skipped. The `configSchema` in the return value is structurally a
+ * `UserConfigSchema` because the Zod schema in schemas.ts matches
+ * `McpbUserConfigurationOption` field-for-field.
+ */
+export function getUnconfiguredChannels(
+  plugin: LoadedPlugin,
+): UnconfiguredChannel[] {
+  const channels = plugin.manifest.channels
+  if (!channels || channels.length === 0) {
+    return []
+  }
+
+  // plugin.repository is already in "plugin@marketplace" format — same key
+  // loadMcpServerUserConfig / saveMcpServerUserConfig use.
+  const pluginId = plugin.repository
+
+  const unconfigured: UnconfiguredChannel[] = []
+  for (const channel of channels) {
+    if (!channel.userConfig || Object.keys(channel.userConfig).length === 0) {
+      continue
+    }
+    const saved = loadMcpServerUserConfig(pluginId, channel.server) ?? {}
+    const validation = validateUserConfig(saved, channel.userConfig)
+    if (!validation.valid) {
+      unconfigured.push({
+        server: channel.server,
+        displayName: channel.displayName ?? channel.server,
+        configSchema: channel.userConfig,
+      })
+    }
+  }
+  return unconfigured
+}
+
+/**
+ * Look up saved user config for a server, if this server is declared as a
+ * channel in the plugin's manifest. Returns undefined for non-channel servers
+ * or channels without a userConfig schema — resolvePluginMcpEnvironment will
+ * then skip ${user_config.X} substitution for that server.
+ */
+function loadChannelUserConfig(
+  plugin: LoadedPlugin,
+  serverName: string,
+): UserConfigValues | undefined {
+  const channel = plugin.manifest.channels?.find(c => c.server === serverName)
+  if (!channel?.userConfig) {
+    return undefined
+  }
+  return loadMcpServerUserConfig(plugin.repository, serverName) ?? undefined
+}
+
+/**
+ * Add plugin scope to MCP server configs
+ * This adds a prefix to server names to avoid conflicts between plugins
+ */
+export function addPluginScopeToServers(
+  servers: Record<string, McpServerConfig>,
+  pluginName: string,
+  pluginSource: string,
+): Record<string, ScopedMcpServerConfig> {
+  const scopedServers: Record<string, ScopedMcpServerConfig> = {}
+
+  for (const [name, config] of Object.entries(servers)) {
+    // Add plugin prefix to server name to avoid conflicts
+    const scopedName = `plugin:${pluginName}:${name}`
+    const scoped: ScopedMcpServerConfig = {
+      ...config,
+      scope: 'dynamic', // Use dynamic scope for plugin servers
+      pluginSource,
+    }
+    scopedServers[scopedName] = scoped
+  }
+
+  return scopedServers
+}
+
+/**
+ * Extract all MCP servers from loaded plugins
+ * NOTE: Resolves environment variables for all servers before returning
+ */
+export async function extractMcpServersFromPlugins(
+  plugins: LoadedPlugin[],
+  errors: PluginError[] = [],
+): Promise<Record<string, ScopedMcpServerConfig>> {
+  const allServers: Record<string, ScopedMcpServerConfig> = {}
+
+  const scopedResults = await Promise.all(
+    plugins.map(async plugin => {
+      if (!plugin.enabled) return null
+
+      const servers = await loadPluginMcpServers(plugin, errors)
+      if (!servers) return null
+
+      // Resolve environment variables before scoping. When a saved channel
+      // config is missing a key (plugin update added a required field, or a
+      // hand-edited settings.json), substituteUserConfigVariables throws
+      // inside resolvePluginMcpEnvironment — catch per-server so one bad
+      // config doesn't crash the whole plugin load via Promise.all.
+      const resolvedServers: Record<string, McpServerConfig> = {}
+      for (const [name, config] of Object.entries(servers)) {
+        const userConfig = buildMcpUserConfig(plugin, name)
+        try {
+          resolvedServers[name] = resolvePluginMcpEnvironment(
+            config,
+            plugin,
+            userConfig,
+            errors,
+            plugin.name,
+            name,
+          )
+        } catch (err) {
+          errors?.push({
+            type: 'generic-error',
+            source: name,
+            plugin: plugin.name,
+            error: errorMessage(err),
+          })
+        }
+      }
+
+      // Store the UNRESOLVED servers on the plugin for caching
+      // (Environment variables will be resolved fresh each time they're needed)
+      plugin.mcpServers = servers
+
+      logForDebugging(
+        `Loaded ${Object.keys(servers).length} MCP servers from plugin ${plugin.name}`,
+      )
+
+      return addPluginScopeToServers(
+        resolvedServers,
+        plugin.name,
+        plugin.source,
+      )
+    }),
+  )
+
+  for (const scopedServers of scopedResults) {
+    if (scopedServers) {
+      Object.assign(allServers, scopedServers)
+    }
+  }
+
+  return allServers
+}
+
+/**
+ * Build the userConfig map for a single MCP server by merging the plugin's
+ * top-level manifest.userConfig values with the channel-specific per-server
+ * config (assistant-mode channels). Channel-specific wins on collision so
+ * plugins that declare the same key at both levels get the more specific value.
+ *
+ * Returns undefined when neither source has anything — resolvePluginMcpEnvironment
+ * skips substituteUserConfigVariables in that case.
+ */
+function buildMcpUserConfig(
+  plugin: LoadedPlugin,
+  serverName: string,
+): UserConfigValues | undefined {
+  // Gate on manifest.userConfig. loadPluginOptions always returns at least {}
+  // (it spreads two `?? {}` fallbacks), so without this guard topLevel is never
+  // undefined — the `!topLevel` check below is dead, we return {} for
+  // unconfigured plugins, and resolvePluginMcpEnvironment runs
+  // substituteUserConfigVariables against an empty map → throws on any
+  // ${user_config.X} ref. The manifest check also skips the unconditional
+  // keychain read (~50-100ms on macOS) for plugins that don't use options.
+  const topLevel = plugin.manifest.userConfig
+    ? loadPluginOptions(getPluginStorageId(plugin))
+    : undefined
+  const channelSpecific = loadChannelUserConfig(plugin, serverName)
+
+  if (!topLevel && !channelSpecific) return undefined
+  return { ...topLevel, ...channelSpecific }
+}
+
+/**
+ * Resolve environment variables for plugin MCP servers
+ * Handles ${CLAUDE_PLUGIN_ROOT}, ${user_config.X}, and general ${VAR} substitution
+ * Tracks missing environment variables for error reporting
+ */
+export function resolvePluginMcpEnvironment(
+  config: McpServerConfig,
+  plugin: { path: string; source: string },
+  userConfig?: UserConfigValues,
+  errors?: PluginError[],
+  pluginName?: string,
+  serverName?: string,
+): McpServerConfig {
+  const allMissingVars: string[] = []
+
+  const resolveValue = (value: string): string => {
+    // First substitute plugin-specific variables
+    let resolved = substitutePluginVariables(value, plugin)
+
+    // Then substitute user config variables if provided
+    if (userConfig) {
+      resolved = substituteUserConfigVariables(resolved, userConfig)
+    }
+
+    // Finally expand general environment variables
+    // This is done last so plugin-specific and user config vars take precedence
+    const { expanded, missingVars } = expandEnvVarsInString(resolved)
+    allMissingVars.push(...missingVars)
+
+    return expanded
+  }
+
+  let resolved: McpServerConfig
+
+  // Handle different server types
+  switch (config.type) {
+    case undefined:
+    case 'stdio': {
+      const stdioConfig = { ...config }
+
+      // Resolve command path
+      if (stdioConfig.command) {
+        stdioConfig.command = resolveValue(stdioConfig.command)
+      }
+
+      // Resolve args
+      if (stdioConfig.args) {
+        stdioConfig.args = stdioConfig.args.map(arg => resolveValue(arg))
+      }
+
+      // Resolve environment variables and add CLAUDE_PLUGIN_ROOT / CLAUDE_PLUGIN_DATA
+      const resolvedEnv: Record<string, string> = {
+        CLAUDE_PLUGIN_ROOT: plugin.path,
+        CLAUDE_PLUGIN_DATA: getPluginDataDir(plugin.source),
+        ...(stdioConfig.env || {}),
+      }
+      for (const [key, value] of Object.entries(resolvedEnv)) {
+        if (key !== 'CLAUDE_PLUGIN_ROOT' && key !== 'CLAUDE_PLUGIN_DATA') {
+          resolvedEnv[key] = resolveValue(value)
+        }
+      }
+      stdioConfig.env = resolvedEnv
+
+      resolved = stdioConfig
+      break
+    }
+
+    case 'sse':
+    case 'http':
+    case 'ws': {
+      const remoteConfig = { ...config }
+
+      // Resolve URL
+      if (remoteConfig.url) {
+        remoteConfig.url = resolveValue(remoteConfig.url)
+      }
+
+      // Resolve headers
+      if (remoteConfig.headers) {
+        const resolvedHeaders: Record<string, string> = {}
+        for (const [key, value] of Object.entries(remoteConfig.headers)) {
+          resolvedHeaders[key] = resolveValue(value)
+        }
+        remoteConfig.headers = resolvedHeaders
+      }
+
+      resolved = remoteConfig
+      break
+    }
+
+    // For other types (sse-ide, ws-ide, sdk, claudeai-proxy), pass through unchanged
+    case 'sse-ide':
+    case 'ws-ide':
+    case 'sdk':
+    case 'claudeai-proxy':
+      resolved = config
+      break
+  }
+
+  // Log and track missing variables if any were found and errors array provided
+  if (errors && allMissingVars.length > 0) {
+    const uniqueMissingVars = [...new Set(allMissingVars)]
+    const varList = uniqueMissingVars.join(', ')
+
+    logForDebugging(
+      `Missing environment variables in plugin MCP config: ${varList}`,
+      { level: 'warn' },
+    )
+
+    // Add error to the errors array if plugin and server names are provided
+    if (pluginName && serverName) {
+      errors.push({
+        type: 'mcp-config-invalid',
+        source: `plugin:${pluginName}`,
+        plugin: pluginName,
+        serverName,
+        validationError: `Missing environment variables: ${varList}`,
+      })
+    }
+  }
+
+  return resolved
+}
+
+/**
+ * Get MCP servers from a specific plugin with environment variable resolution and scoping
+ * This function is called when the MCP servers need to be activated and ensures they have
+ * the proper environment variables and scope applied
+ */
+export async function getPluginMcpServers(
+  plugin: LoadedPlugin,
+  errors: PluginError[] = [],
+): Promise<Record<string, ScopedMcpServerConfig> | undefined> {
+  if (!plugin.enabled) {
+    return undefined
+  }
+
+  // Use cached servers if available
+  const servers =
+    plugin.mcpServers || (await loadPluginMcpServers(plugin, errors))
+  if (!servers) {
+    return undefined
+  }
+
+  // Resolve environment variables. Same per-server try/catch as
+  // extractMcpServersFromPlugins above: a partial saved channel config
+  // (plugin update added a required field) would make
+  // substituteUserConfigVariables throw inside resolvePluginMcpEnvironment,
+  // and this function runs inside Promise.all at config.ts:911 — one
+  // uncaught throw crashes all plugin MCP loading.
+  const resolvedServers: Record<string, McpServerConfig> = {}
+  for (const [name, config] of Object.entries(servers)) {
+    const userConfig = buildMcpUserConfig(plugin, name)
+    try {
+      resolvedServers[name] = resolvePluginMcpEnvironment(
+        config,
+        plugin,
+        userConfig,
+        errors,
+        plugin.name,
+        name,
+      )
+    } catch (err) {
+      errors?.push({
+        type: 'generic-error',
+        source: name,
+        plugin: plugin.name,
+        error: errorMessage(err),
+      })
+    }
+  }
+
+  // Add plugin scope
+  return addPluginScopeToServers(resolvedServers, plugin.name, plugin.source)
+}