@wuyax/mcps 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/index.d.cts

@@ -1,3 +1,7 @@
+import { Separator, Theme } from '@inquirer/core';
+import { Context } from '@inquirer/type';
+import { Command } from 'commander';
+
 type McpAgentType = "amp" | "antigravity" | "antigravity-cli" | "augment" | "cline" | "cline-cli" | "claude-code" | "claude-desktop" | "codex" | "cursor" | "gemini-cli" | "grok" | "goose" | "github-copilot-cli" | "kimi-code-cli" | "kiro" | "opencode" | "pi" | "qoder" | "qwen-code" | "trae" | "vscode" | "zed";
 type McpConfigFormat = "json" | "jsonc" | "yaml" | "toml";
 type McpTransportType = "http" | "sse" | "stdio";
@@ -70,6 +74,7 @@ interface McpInstallResultForAgent {
     agent: McpAgentType;
     success: boolean;
     path: string;
+    coConfiguredAgents?: McpAgentType[];
     error?: string;
 }
 interface InstallMcpServerResult {
@@ -92,8 +97,30 @@ interface RemoveMcpServerResult {
     agent: McpAgentType;
     path: string;
     removed: boolean;
+    coAffectedAgents?: McpAgentType[];
     error?: string;
 }
+interface ConfigCluster {
+    configPath: string;
+    configKey: string;
+    targetAgents: McpAgentType[];
+    coHostedAgents: McpAgentType[];
+}
+interface UpdateMcpServerOptions extends McpScopeOptions {
+    serverName: string;
+    config: McpServerConfig;
+    previousConfig?: McpServerConfig;
+    agents?: McpAgentType[];
+}
+interface UpdateMcpServerResult {
+    serverName: string;
+    config: McpServerConfig;
+    results: McpInstallResultForAgent[];
+    incompatible: {
+        agent: McpAgentType;
+        reason: string;
+    }[];
+}
 
 declare const mcpAgents: Record<McpAgentType, McpAgentConfig>;
 declare const mcpAgentAliases: Record<string, McpAgentType>;
@@ -243,6 +270,35 @@ declare const resolveTargetAgents: (query?: TargetResolutionQuery) => TargetReso
 type InstallMcpServerForAgentOptions = McpScopeOptions;
 declare const installMcpServerForAgent: (serverName: string, serverConfig: McpServerConfig, agentType: McpAgentType, options?: InstallMcpServerForAgentOptions) => McpInstallResultForAgent;
 declare const installMcpServerForAgents: (serverName: string, serverConfig: McpServerConfig, agentTypes: McpAgentType[], options?: InstallMcpServerForAgentOptions) => McpInstallResultForAgent[];
+interface InstallToCompatibleAgentsOptions extends McpScopeOptions {
+    allAgents: McpAgentType[];
+    incompatible?: Array<{
+        agent: McpAgentType;
+        reason: string;
+    }>;
+}
+declare const installToCompatibleAgents: (serverName: string, serverConfig: McpServerConfig, options: InstallToCompatibleAgentsOptions) => McpInstallResultForAgent[];
+
+/**
+ * Returns candidate agent types relevant for the given scope.
+ */
+declare const getCandidateAgentsForScope: (options?: McpScopeOptions) => McpAgentType[];
+/**
+ * Returns all other agents sharing the exact same physical configuration target
+ * (same configPath and configKey) for the given scope.
+ */
+declare const getCoHostedAgents: (agentType: McpAgentType, options?: McpScopeOptions) => McpAgentType[];
+/**
+ * Resolves configuration clusters for a given list of requested agents.
+ * Groups requested agents sharing the same physical config path, and tracks
+ * any remaining co-hosted agents sharing the same target that were not in the request.
+ */
+declare const resolveConfigClusters: (agentTypes: McpAgentType[], options?: McpScopeOptions) => ConfigCluster[];
+/**
+ * Sorts agent types so that agents sharing the same physical config target
+ * appear adjacent to each other in the returned array.
+ */
+declare const sortAgentsWithClusters: (agentTypes: McpAgentType[], options?: McpScopeOptions) => McpAgentType[];
 
 interface ListInstalledMcpServersOptions extends McpScopeOptions {
     agents?: McpAgentType[];
@@ -259,6 +315,33 @@ declare const removeMcpServerFromAgent: (serverName: string, agentType: McpAgent
 }) => RemoveMcpServerResult;
 declare const removeMcpServer: (options: RemoveMcpServerOptions) => RemoveMcpServerResult[];
 
+/**
+ * Transforms a server configuration into a clean remote configuration,
+ * stripping stdio-exclusive fields (command, args, env).
+ */
+declare const toRemoteServerConfig: (config: McpServerConfig, defaultTransport?: McpRemoteTransport) => McpServerConfig;
+/**
+ * Transforms a server configuration into a clean stdio configuration,
+ * stripping remote-exclusive fields (url, type, headers).
+ */
+declare const toStdioServerConfig: (config: McpServerConfig) => McpServerConfig;
+type UpdateTransitionType = "switch-to-remote" | "switch-to-stdio" | "merge-remote" | "merge-stdio";
+/**
+ * Determines the transition category when updating an MCP server configuration.
+ */
+declare const detectUpdateTransition: (incoming: McpServerConfig, previous?: McpServerConfig) => UpdateTransitionType;
+/**
+ * Strips obsolete fields when switching between stdio and remote protocols.
+ * When switching to remote (url is provided), stdio fields (command, args, env) are removed.
+ * When switching to stdio (command is provided), remote fields (url, type, headers) are removed.
+ */
+declare const sanitizeUpdatedServerConfig: (incoming: McpServerConfig, previous?: McpServerConfig) => McpServerConfig;
+/**
+ * Core Orchestration: Updates an existing MCP server across specified or installed coding agents,
+ * sanitizing protocol dirty fields and validating transport capabilities.
+ */
+declare const updateMcpServer: (options: UpdateMcpServerOptions) => UpdateMcpServerResult;
+
 declare const mainMenu: () => Promise<void>;
 
 interface WizardAddOptions extends McpScopeOptions {
@@ -272,7 +355,57 @@ interface WizardAddOptions extends McpScopeOptions {
 }
 declare const wizardAdd: (initial?: WizardAddOptions) => Promise<boolean>;
 
-type WizardManageOptions = McpScopeOptions;
+interface DisplayServerDetailsOptions extends McpScopeOptions {
+    serverName: string;
+    config: McpServerConfig;
+    agents?: McpAgentType[];
+    hasDivergence?: boolean;
+    titlePrefix?: string;
+}
+/**
+ * Reusable display function for server details with secret masking.
+ */
+declare const displayServerDetails: ({ serverName, config, agents, hasDivergence, global: isGlobal, titlePrefix, }: DisplayServerDetailsOptions) => void;
+
+/**
+ * Validates and resolves remote transport string into McpRemoteTransport.
+ */
+declare const resolveTransport: (input: string | undefined) => McpRemoteTransport | undefined;
+
+declare const SECRET_KEY_PATTERN: RegExp;
+/**
+ * Masks sensitive values for secure CLI display.
+ */
+declare const maskSecretValue: (key: string, value: string) => string;
+declare const SECRET_HEADER_PATTERN: RegExp;
+/**
+ * Masks sensitive HTTP header values for secure CLI display.
+ */
+declare const maskSecretHeader: (key: string, value: string) => string;
+
+interface GroupedInstalledServer {
+    serverName: string;
+    agents: McpAgentType[];
+    paths: string[];
+    config: McpServerConfig;
+    hasDivergence?: boolean;
+}
+declare const normalizeServerConfig: (raw: unknown) => McpServerConfig;
+/**
+ * Groups a flat array of ListedMcpServer entries by serverName.
+ */
+declare const groupInstalledServersByName: (installed: ListedMcpServer[]) => Map<string, GroupedInstalledServer>;
+
+interface WizardManageOptions extends McpScopeOptions {
+    serverName?: string;
+}
+interface EditServerConfigOptions extends McpScopeOptions {
+    targetGroup: GroupedInstalledServer;
+}
+/**
+ * Interactive prompt flow to switch an MCP server between stdio and remote protocols.
+ */
+declare const promptSwitchServerType: (currentConfig: McpServerConfig, serverName: string) => Promise<McpServerConfig>;
 declare const wizardManage: (options?: WizardManageOptions) => Promise<void>;
 
 interface WizardRemoveOptions extends McpScopeOptions {
@@ -281,6 +414,35 @@ interface WizardRemoveOptions extends McpScopeOptions {
 }
 declare const wizardRemove: (options?: WizardRemoveOptions) => Promise<boolean>;
 
+interface PromptEditKeyValueOptions {
+    title: string;
+    itemNoun: string;
+    itemsNoun: string;
+    maskValue: (key: string, value: string) => string;
+    isSecretKey: (key: string) => boolean;
+    formatText: (items: Record<string, string>) => string;
+    parseText: (text: string) => Record<string, string>;
+    editorPostfix?: string;
+    editorMessage: string;
+    pasteMessage: string;
+    keyPromptMessage: string;
+    valuePromptMessage: string;
+    separator: "=" | ":";
+}
+/**
+ * Generic reusable interactive key-value editing loop supporting:
+ * - Editor launch with pre-filled content ($EDITOR)
+ * - Single item upsert (with secret detection & password masking)
+ * - Single item deletion
+ * - Multiline paste (with merge or replace choices)
+ * - Clear all items
+ */
+declare const promptEditKeyValueConfig: (currentItems: Record<string, string> | undefined, options: PromptEditKeyValueOptions) => Promise<Record<string, string>>;
+
+/**
+ * Formats a key-value env record into .env formatted multiline string.
+ */
+declare const formatEnvText: (env: Record<string, string>) => string;
 /**
  * Parses multiline .env formatted text into a key-value record.
  * Supports:
@@ -298,7 +460,16 @@ declare const parseEnvText: (rawText: string) => Record<string, string>;
  * 3. Add key-value one by one (with secret mask detection)
  */
 declare const promptEnvConfig: (initialEnv?: Record<string, string>) => Promise<Record<string, string>>;
+/**
+ * Dedicated prompt loop for inspecting, modifying, adding, and removing
+ * environment variables of an existing MCP server configuration.
+ */
+declare const promptEditEnvConfig: (currentEnv?: Record<string, string>) => Promise<Record<string, string>>;
 
+/**
+ * Formats a key-value headers record into multiline Key: Value text.
+ */
+declare const formatHeadersText: (headers: Record<string, string>) => string;
 /**
  * Parses multiline HTTP headers text (Key: Value or Key=Value) into a Record<string, string>.
  */
@@ -307,6 +478,11 @@ declare const parseHeadersText: (rawText: string) => Record<string, string>;
  * Interactively prompts user for HTTP headers.
  */
 declare const promptHeadersConfig: (initialHeaders?: Record<string, string>) => Promise<Record<string, string>>;
+/**
+ * Dedicated prompt loop for inspecting, modifying, adding, and removing
+ * HTTP headers of an existing MCP server configuration.
+ */
+declare const promptEditHeadersConfig: (currentHeaders?: Record<string, string>) => Promise<Record<string, string>>;
 
 /**
  * Parses a command-line argument string into an array of arguments,
@@ -317,6 +493,15 @@ declare const parseArgsString: (rawText: string) => string[];
  * Prompts the user for additional command-line arguments.
  */
 declare const promptArgsConfig: (initialArgs?: string[]) => Promise<string[]>;
+/**
+ * Formats an array of argument strings into a space-separated CLI string,
+ * quoting arguments containing spaces or quotes.
+ */
+declare const formatArgsString: (args: string[]) => string;
+/**
+ * Dedicated prompt for editing command arguments with current arguments pre-filled.
+ */
+declare const promptEditArgs: (currentArgs?: string[]) => Promise<string[]>;
 
 interface PromptScopeAndAgentsOptions extends McpScopeOptions {
     defaultGlobal?: boolean;
@@ -342,17 +527,71 @@ interface PromptScopeOptions extends McpScopeOptions {
  */
 declare const promptScope: (options?: PromptScopeOptions) => Promise<boolean>;
 
-interface GroupedInstalledServer {
-    serverName: string;
+interface LinkedChoice<Value> {
+    value: Value;
+    name?: string;
+    checkedName?: string;
+    description?: string;
+    short?: string;
+    disabled?: boolean | string;
+    checked?: boolean;
+    linkedValues?: Value[];
+}
+interface NormalizedLinkedChoice<Value> {
+    value: Value;
+    name: string;
+    checkedName: string;
+    description?: string;
+    short: string;
+    disabled: boolean | string;
+    checked: boolean;
+    linkedValues: Value[];
+}
+interface LinkedCheckboxTheme {
+    icon: {
+        checked: string;
+        unchecked: string;
+        cursor: string;
+        disabledChecked: string;
+        disabledUnchecked: string;
+    };
+    style: {
+        disabled: (text: string) => string;
+        renderSelectedChoices: <T>(selectedChoices: ReadonlyArray<NormalizedLinkedChoice<T>>, allChoices: ReadonlyArray<NormalizedLinkedChoice<T> | Separator>) => string;
+        description: (text: string) => string;
+        keysHelpTip: (keys: [key: string, action: string][]) => string;
+        highlight: (text: string) => string;
+    };
+    i18n: {
+        disabledError: string;
+    };
+}
+interface LinkedCheckboxConfig<Value = string> {
+    message: string;
+    prefix?: string;
+    pageSize?: number;
+    choices: ReadonlyArray<Separator | Value | LinkedChoice<Value>>;
+    loop?: boolean;
+    required?: boolean;
+    validate?: (choices: readonly NormalizedLinkedChoice<Value>[]) => boolean | string | Promise<string | boolean>;
+    theme?: Partial<Theme<LinkedCheckboxTheme>>;
+}
+type LinkedCheckboxPrompt = <Value>(config: LinkedCheckboxConfig<Value>, context?: Context) => Promise<Value[]>;
+declare const linkedCheckbox: LinkedCheckboxPrompt;
+
+declare const mcpManageCommand: Command;
+
+interface BuildLinkedAgentChoicesOptions {
     agents: McpAgentType[];
-    paths: string[];
-    config: McpServerConfig;
+    checkedAgents: McpAgentType[];
+    detectedAgents?: McpAgentType[];
+    scopeOptions?: McpScopeOptions;
 }
-declare const normalizeServerConfig: (raw: unknown) => McpServerConfig;
 /**
- * Groups a flat array of ListedMcpServer entries by serverName.
+ * Builds normalized LinkedChoice items for an interactive agent list,
+ * calculating co-hosted agents and attaching link indicators.
  */
-declare const groupInstalledServersByName: (installed: ListedMcpServer[]) => Map<string, GroupedInstalledServer>;
+declare const buildLinkedAgentChoices: (options: BuildLinkedAgentChoicesOptions) => LinkedChoice<McpAgentType>[];
 
 /**
  * Deep module: Transforms standard McpServerConfig into an Agent-specific configuration shape
@@ -375,4 +614,4 @@ declare const transformServerConfigForAgent: (agent: McpAgentConfig, serverName:
     global: boolean;
 }) => unknown;
 
-export { AgentConfigStore, type AgentConfigStoreListResult, type AgentConfigStoreRemoveResult, type AgentConfigStoreWriteResult, type ConfigStoreAdapter, type ConfigTargetDescriptor, DEFAULT_REMOTE_TRANSPORT, type GroupedInstalledServer, type IncompatibleAgent, type InstallMcpServerOptions, type InstallMcpServerResult, type ListedMcpServer, type McpAgentConfig, type McpAgentType, type McpConfigFormat, type McpInstallResultForAgent, type McpRemoteServerConfig, type McpRemoteTransport, type McpScopeOptions, type McpServerConfig, type McpSourceType, type McpStdioServerConfig, type McpTransportType, NPX_COMMAND, NPX_DASH_Y, type ParsedMcpSource, type RemoveMcpServerOptions, type RemoveMcpServerResult, type ServerConfigDialect, type ServerConfigDialectName, type ServerConfigDialectOptions, type TargetResolutionQuery, type TargetResolutionResult, installMcpServer as add, agentConfigStore, buildMcpServerConfig, createAgentTransform, detectGloballyInstalledMcpAgents, detectProjectInstalledMcpAgents, extractPackageName, getMcpAgentConfig, getMcpAgentTypes, getMcpAgentsSupportingProjectScope, groupInstalledServersByName, installMcpServer as install, installMcpServer, installMcpServerForAgent, installMcpServerForAgents, isMcpAgentType, isMcpTransportSupported, isRemoteMcpSource, isRemoteServerConfig, isStdioServerConfig, listInstalledMcpServers as list, listInstalledMcpServers, listServersInConfigFile, mainMenu, mcpAgentAliases, mcpAgents, normalizeServerConfig, parseArgsString, parseEnvText, parseHeadersText, parseMcpSource, parseServerConfig, parseMcpSource as parseSource, promptArgsConfig, promptEnvConfig, promptHeadersConfig, promptScope, promptScopeAndAgents, readConfigFile, removeMcpServer as remove, removeMcpServer, removeMcpServerFromAgent, removeServerFromConfigFile, resolveMcpAgentAlias, resolveMcpConfigTarget, resolveTargetAgents, transformServerConfig, transformServerConfigForAgent, wizardAdd, wizardManage, wizardRemove, writeServerToConfigFile };
+export { AgentConfigStore, type AgentConfigStoreListResult, type AgentConfigStoreRemoveResult, type AgentConfigStoreWriteResult, type BuildLinkedAgentChoicesOptions, type ConfigCluster, type ConfigStoreAdapter, type ConfigTargetDescriptor, DEFAULT_REMOTE_TRANSPORT, type DisplayServerDetailsOptions, type EditServerConfigOptions, type GroupedInstalledServer, type IncompatibleAgent, type InstallMcpServerOptions, type InstallMcpServerResult, type InstallToCompatibleAgentsOptions, type LinkedCheckboxPrompt, type LinkedChoice, type ListedMcpServer, type McpAgentConfig, type McpAgentType, type McpConfigFormat, type McpInstallResultForAgent, type McpRemoteServerConfig, type McpRemoteTransport, type McpScopeOptions, type McpServerConfig, type McpSourceType, type McpStdioServerConfig, type McpTransportType, NPX_COMMAND, NPX_DASH_Y, type ParsedMcpSource, type PromptEditKeyValueOptions, type RemoveMcpServerOptions, type RemoveMcpServerResult, SECRET_HEADER_PATTERN, SECRET_KEY_PATTERN, type ServerConfigDialect, type ServerConfigDialectName, type ServerConfigDialectOptions, type TargetResolutionQuery, type TargetResolutionResult, type UpdateMcpServerOptions, type UpdateMcpServerResult, type UpdateTransitionType, type WizardManageOptions, installMcpServer as add, agentConfigStore, buildLinkedAgentChoices, buildMcpServerConfig, createAgentTransform, detectGloballyInstalledMcpAgents, detectProjectInstalledMcpAgents, detectUpdateTransition, displayServerDetails, extractPackageName, formatArgsString, formatEnvText, formatHeadersText, getCandidateAgentsForScope, getCoHostedAgents, getMcpAgentConfig, getMcpAgentTypes, getMcpAgentsSupportingProjectScope, groupInstalledServersByName, installMcpServer as install, installMcpServer, installMcpServerForAgent, installMcpServerForAgents, installToCompatibleAgents, isMcpAgentType, isMcpTransportSupported, isRemoteMcpSource, isRemoteServerConfig, isStdioServerConfig, linkedCheckbox, listInstalledMcpServers as list, listInstalledMcpServers, listServersInConfigFile, mainMenu, maskSecretHeader, maskSecretValue, mcpAgentAliases, mcpAgents, mcpManageCommand, normalizeServerConfig, parseArgsString, parseEnvText, parseHeadersText, parseMcpSource, parseServerConfig, parseMcpSource as parseSource, promptArgsConfig, promptEditArgs, promptEditEnvConfig, promptEditHeadersConfig, promptEditKeyValueConfig, promptEnvConfig, promptHeadersConfig, promptScope, promptScopeAndAgents, promptSwitchServerType, readConfigFile, removeMcpServer as remove, removeMcpServer, removeMcpServerFromAgent, removeServerFromConfigFile, resolveConfigClusters, resolveMcpAgentAlias, resolveMcpConfigTarget, resolveTargetAgents, resolveTransport, sanitizeUpdatedServerConfig, sortAgentsWithClusters, toRemoteServerConfig, toStdioServerConfig, transformServerConfig, transformServerConfigForAgent, updateMcpServer as update, updateMcpServer, wizardAdd, wizardManage, wizardRemove, writeServerToConfigFile };