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)

}