@wuyax/mcps 0.1.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,378 @@
+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";
+type McpRemoteTransport = "http" | "sse";
+type McpSourceType = "remote" | "package" | "command";
+interface ParsedMcpSource {
+    type: McpSourceType;
+    value: string;
+    inferredName: string;
+}
+interface McpServerConfig {
+    type?: McpRemoteTransport;
+    url?: string;
+    headers?: Record<string, string>;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+type ServerConfigDialectName = "vscode" | "augment" | "amp" | "trae" | "grok" | "cline" | "goose" | "kimi-code" | "kiro" | "opencode" | "pi" | "qwen-code" | "zed";
+interface ServerConfigDialectOptions {
+    stdioTransport?: "none" | "type-stdio" | "transport-stdio" | "type-local";
+    remoteTransport?: "type-http-sse" | "sse-only-type" | "sse-only-transport" | "none" | "streamable-http" | "streamableHttp" | "streamable_http" | "remote-type" | "qwen";
+    commandArray?: boolean;
+    commandField?: string;
+    argsField?: string;
+    envField?: string;
+    urlField?: string;
+    defaultEnvEmpty?: boolean;
+    defaultHeadersEmpty?: boolean;
+    extraFields?: Record<string, unknown>;
+    includeServerName?: boolean;
+    timeoutSeconds?: number;
+}
+type ServerConfigDialect = ServerConfigDialectName | ServerConfigDialectOptions;
+interface McpAgentConfig {
+    name: McpAgentType;
+    displayName: string;
+    globalConfigPath: string;
+    projectConfigPath?: string;
+    configKey: string;
+    projectConfigKey?: string;
+    format: McpConfigFormat;
+    supportedTransports: readonly McpTransportType[];
+    unsupportedTransportMessage?: string;
+    detectGlobalInstall: () => boolean;
+    detectProjectInstall?: (cwd: string) => boolean;
+    resolveConfigPath?: (options: {
+        global: boolean;
+        cwd: string;
+    }) => string;
+    transformDialect?: ServerConfigDialect;
+    transformConfig?: (serverName: string, config: McpServerConfig, context: {
+        global: boolean;
+    }) => unknown;
+}
+interface McpScopeOptions {
+    global?: boolean;
+    cwd?: string;
+}
+interface InstallMcpServerOptions extends McpScopeOptions {
+    source: string;
+    name?: string;
+    agents?: McpAgentType[];
+    args?: string[];
+    transport?: McpRemoteTransport;
+    headers?: Record<string, string>;
+    env?: Record<string, string>;
+}
+interface McpInstallResultForAgent {
+    agent: McpAgentType;
+    success: boolean;
+    path: string;
+    error?: string;
+}
+interface InstallMcpServerResult {
+    serverName: string;
+    config: McpServerConfig;
+    results: McpInstallResultForAgent[];
+}
+interface ListedMcpServer {
+    serverName: string;
+    agent: McpAgentType;
+    path: string;
+    config: unknown;
+    serverConfig?: McpServerConfig;
+}
+interface RemoveMcpServerOptions extends McpScopeOptions {
+    name: string;
+    agents?: McpAgentType[];
+}
+interface RemoveMcpServerResult {
+    agent: McpAgentType;
+    path: string;
+    removed: boolean;
+    error?: string;
+}
+
+declare const mcpAgents: Record<McpAgentType, McpAgentConfig>;
+declare const mcpAgentAliases: Record<string, McpAgentType>;
+declare const getMcpAgentConfig: (agentType: McpAgentType) => McpAgentConfig;
+declare const getMcpAgentTypes: () => McpAgentType[];
+declare const isMcpAgentType: (value: string) => value is McpAgentType;
+declare const resolveMcpAgentAlias: (input: string) => McpAgentType | null;
+declare const isMcpTransportSupported: (agent: McpAgentConfig, transport: McpTransportType) => boolean;
+declare const detectProjectInstalledMcpAgents: (cwd: string) => McpAgentType[];
+declare const detectGloballyInstalledMcpAgents: () => McpAgentType[];
+declare const getMcpAgentsSupportingProjectScope: () => McpAgentType[];
+
+interface BuildMcpServerConfigOptions {
+    transport?: McpRemoteTransport;
+    headers?: Record<string, string>;
+    env?: Record<string, string>;
+    args?: string[];
+}
+declare const buildMcpServerConfig: (parsed: ParsedMcpSource, options?: BuildMcpServerConfigOptions) => McpServerConfig;
+
+interface McpRemoteServerConfig {
+    type: McpRemoteTransport;
+    url: string;
+    headers?: Record<string, string>;
+}
+interface McpStdioServerConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+/**
+ * Type guard for remote (HTTP/SSE) server configuration.
+ */
+declare const isRemoteServerConfig: (config: McpServerConfig) => config is McpRemoteServerConfig;
+/**
+ * Type guard for local (stdio command/script) server configuration.
+ */
+declare const isStdioServerConfig: (config: McpServerConfig) => config is McpStdioServerConfig;
+/**
+ * Parses and normalizes any unknown raw configuration object from agent config files
+ * into a typed standard McpServerConfig domain model.
+ */
+declare const parseServerConfig: (raw: unknown) => McpServerConfig;
+
+declare const DEFAULT_REMOTE_TRANSPORT: "http";
+declare const NPX_COMMAND = "npx";
+declare const NPX_DASH_Y = "-y";
+
+declare const readConfigFile: (filePath: string, format: McpConfigFormat) => Record<string, unknown>;
+declare const writeServerToConfigFile: (filePath: string, format: McpConfigFormat, dottedKey: string, serverName: string, serverConfig: unknown) => void;
+declare const removeServerFromConfigFile: (filePath: string, format: McpConfigFormat, dottedKey: string, serverName: string) => boolean;
+declare const listServersInConfigFile: (filePath: string, format: McpConfigFormat, dottedKey: string) => Record<string, unknown>;
+
+interface McpConfigTarget {
+    configPath: string;
+    configKey: string;
+}
+interface ResolveMcpConfigTargetOptions {
+    global?: boolean;
+    cwd?: string;
+}
+declare const resolveMcpConfigTarget: (agent: McpAgentConfig, options?: ResolveMcpConfigTargetOptions) => McpConfigTarget;
+
+interface ConfigTargetDescriptor {
+    filePath: string;
+    format: McpConfigFormat;
+    dottedKey?: string;
+}
+interface ConfigStoreAdapter {
+    exists(filePath: string): boolean;
+    read(target: ConfigTargetDescriptor): Record<string, unknown>;
+    writeServer(target: ConfigTargetDescriptor, serverName: string, serverConfig: unknown): void;
+    removeServer(target: ConfigTargetDescriptor, serverName: string): boolean;
+    listServers(target: ConfigTargetDescriptor): Record<string, unknown>;
+}
+interface AgentConfigStoreWriteResult {
+    path: string;
+}
+interface AgentConfigStoreRemoveResult {
+    path: string;
+    removed: boolean;
+}
+interface AgentConfigStoreListResult {
+    path: string;
+    exists: boolean;
+    servers: Record<string, unknown>;
+}
+/**
+ * Deep module: Coordinates Agent config target resolution, file checking,
+ * and format persistence behind a unified seam.
+ */
+declare class AgentConfigStore {
+    private adapter;
+    constructor(adapter?: ConfigStoreAdapter);
+    getAdapter(): ConfigStoreAdapter;
+    resolveTarget(agent: McpAgentType | McpAgentConfig, options?: McpScopeOptions): {
+        agent: McpAgentConfig;
+        target: McpConfigTarget;
+    };
+    resolveDescriptor(agent: McpAgentType | McpAgentConfig, options?: McpScopeOptions): ConfigTargetDescriptor;
+    writeServer(agent: McpAgentType | McpAgentConfig, serverName: string, serverConfig: unknown, options?: McpScopeOptions): AgentConfigStoreWriteResult;
+    removeServer(agent: McpAgentType | McpAgentConfig, serverName: string, options?: McpScopeOptions): AgentConfigStoreRemoveResult;
+    listServers(agent: McpAgentType | McpAgentConfig, options?: McpScopeOptions): AgentConfigStoreListResult;
+    read(agent: McpAgentType | McpAgentConfig, options?: McpScopeOptions): Record<string, unknown>;
+    readServer(agent: McpAgentType | McpAgentConfig, serverName: string, options?: McpScopeOptions): unknown | undefined;
+}
+/**
+ * Singleton AgentConfigStore using standard file system adapter.
+ */
+declare const agentConfigStore: AgentConfigStore;
+
+declare const installMcpServer: (options: InstallMcpServerOptions) => InstallMcpServerResult;
+
+interface TargetResolutionQuery extends McpScopeOptions {
+    requested?: string[] | McpAgentType[];
+    all?: boolean;
+    transport?: McpTransportType;
+}
+interface IncompatibleAgent {
+    agent: McpAgentType;
+    reason: string;
+}
+interface TargetResolutionResult {
+    /** Compatible candidate agents that support the requested transport */
+    agents: McpAgentType[];
+    /** Explicit alias for `agents` */
+    compatibleAgents: McpAgentType[];
+    /** All candidate agents before transport filtering */
+    allAgents: McpAgentType[];
+    /** Explicit alias for `allAgents` */
+    candidateAgents: McpAgentType[];
+    /** All agents detected on system / project */
+    detected: McpAgentType[];
+    /** True when target agents were resolved via auto-detection */
+    isDetected: boolean;
+    /** Incompatible agents and the reason they were filtered out */
+    incompatible: IncompatibleAgent[];
+    /** Diagnostic message when resolution yields zero compatible agents */
+    diagnostic?: string;
+}
+/**
+ * Deep module: Resolves candidate target agents from explicit CLI flags,
+ * wildcards, auto-detection, and transport capability filtering.
+ */
+declare const resolveTargetAgents: (query?: TargetResolutionQuery) => TargetResolutionResult;
+
+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 ListInstalledMcpServersOptions extends McpScopeOptions {
+    agents?: McpAgentType[];
+}
+declare const listInstalledMcpServers: (options?: ListInstalledMcpServersOptions) => ListedMcpServer[];
+
+declare const extractPackageName: (input: string) => string;
+declare const parseMcpSource: (input: string) => ParsedMcpSource;
+declare const isRemoteMcpSource: (parsed: ParsedMcpSource) => boolean;
+
+declare const removeMcpServerFromAgent: (serverName: string, agentType: McpAgentType, options?: {
+    global?: boolean;
+    cwd?: string;
+}) => RemoveMcpServerResult;
+declare const removeMcpServer: (options: RemoveMcpServerOptions) => RemoveMcpServerResult[];
+
+declare const mainMenu: () => Promise<void>;
+
+interface WizardAddOptions extends McpScopeOptions {
+    source?: string;
+    name?: string;
+    agents?: McpAgentType[];
+    args?: string[];
+    transport?: McpRemoteTransport;
+    headers?: Record<string, string>;
+    env?: Record<string, string>;
+}
+declare const wizardAdd: (initial?: WizardAddOptions) => Promise<boolean>;
+
+type WizardManageOptions = McpScopeOptions;
+declare const wizardManage: (options?: WizardManageOptions) => Promise<void>;
+
+interface WizardRemoveOptions extends McpScopeOptions {
+    name?: string;
+    agents?: McpAgentType[];
+}
+declare const wizardRemove: (options?: WizardRemoveOptions) => Promise<boolean>;
+
+/**
+ * Parses multiline .env formatted text into a key-value record.
+ * Supports:
+ * - Empty lines and comments (#)
+ * - `export KEY=VALUE` or `KEY=VALUE`
+ * - Values with `=` inside
+ * - Single/double quoted values
+ */
+declare const parseEnvText: (rawText: string) => Record<string, string>;
+/**
+ * Prompts user for environment variables.
+ * Offers choices:
+ * 1. Skip / No env vars
+ * 2. Paste multiline .env text
+ * 3. Add key-value one by one (with secret mask detection)
+ */
+declare const promptEnvConfig: (initialEnv?: Record<string, string>) => Promise<Record<string, string>>;
+
+/**
+ * Parses multiline HTTP headers text (Key: Value or Key=Value) into a Record<string, string>.
+ */
+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>>;
+
+/**
+ * Parses a command-line argument string into an array of arguments,
+ * respecting single and double quotes for arguments with spaces.
+ */
+declare const parseArgsString: (rawText: string) => string[];
+/**
+ * Prompts the user for additional command-line arguments.
+ */
+declare const promptArgsConfig: (initialArgs?: string[]) => Promise<string[]>;
+
+interface PromptScopeAndAgentsOptions extends McpScopeOptions {
+    defaultGlobal?: boolean;
+    defaultAgents?: McpAgentType[];
+}
+interface ScopeAndAgentsResult {
+    global: boolean;
+    agents: McpAgentType[];
+}
+/**
+ * Interactively prompts for scope (Project vs Global) and target agents.
+ * Auto-detects installed agents and pre-selects them.
+ */
+declare const promptScopeAndAgents: (options?: PromptScopeAndAgentsOptions) => Promise<ScopeAndAgentsResult>;
+
+interface PromptScopeOptions extends McpScopeOptions {
+    defaultGlobal?: boolean;
+    message?: string;
+}
+/**
+ * Prompts user to choose between project and global scope.
+ * Returns true for global, false for project.
+ */
+declare const promptScope: (options?: PromptScopeOptions) => Promise<boolean>;
+
+interface GroupedInstalledServer {
+    serverName: string;
+    agents: McpAgentType[];
+    paths: string[];
+    config: McpServerConfig;
+}
+declare const normalizeServerConfig: (raw: unknown) => McpServerConfig;
+/**
+ * Groups a flat array of ListedMcpServer entries by serverName.
+ */
+declare const groupInstalledServersByName: (installed: ListedMcpServer[]) => Map<string, GroupedInstalledServer>;
+
+/**
+ * Deep module: Transforms standard McpServerConfig into an Agent-specific configuration shape
+ * driven by declarative dialects.
+ */
+declare const transformServerConfig: (serverName: string, config: McpServerConfig, dialect: ServerConfigDialect, _context?: {
+    global?: boolean;
+}) => unknown;
+/**
+ * Factory creating an agent-bound transform function from a declarative dialect.
+ */
+declare const createAgentTransform: (dialect: ServerConfigDialect) => ((serverName: string, config: McpServerConfig, context: {
+    global: boolean;
+}) => unknown);
+/**
+ * Transforms an MCP server config for a given Agent, checking custom transformConfig
+ * or falling back to declarative transformDialect.
+ */
+declare const transformServerConfigForAgent: (agent: McpAgentConfig, serverName: string, config: McpServerConfig, context?: {
+    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 };

package/dist/index.js

@@ -0,0 +1,111 @@
+import {
+  AgentConfigStore,
+  DEFAULT_REMOTE_TRANSPORT,
+  NPX_COMMAND,
+  NPX_DASH_Y,
+  agentConfigStore,
+  buildMcpServerConfig,
+  createAgentTransform,
+  detectGloballyInstalledMcpAgents,
+  detectProjectInstalledMcpAgents,
+  extractPackageName,
+  getMcpAgentConfig,
+  getMcpAgentTypes,
+  getMcpAgentsSupportingProjectScope,
+  groupInstalledServersByName,
+  installMcpServer,
+  installMcpServerForAgent,
+  installMcpServerForAgents,
+  isMcpAgentType,
+  isMcpTransportSupported,
+  isRemoteMcpSource,
+  isRemoteServerConfig,
+  isStdioServerConfig,
+  listInstalledMcpServers,
+  listServersInConfigFile,
+  mainMenu,
+  mcpAgentAliases,
+  mcpAgents,
+  normalizeServerConfig,
+  parseArgsString,
+  parseEnvText,
+  parseHeadersText,
+  parseMcpSource,
+  parseServerConfig,
+  promptArgsConfig,
+  promptEnvConfig,
+  promptHeadersConfig,
+  promptScope,
+  promptScopeAndAgents,
+  readConfigFile,
+  removeMcpServer,
+  removeMcpServerFromAgent,
+  removeServerFromConfigFile,
+  resolveMcpAgentAlias,
+  resolveMcpConfigTarget,
+  resolveTargetAgents,
+  transformServerConfig,
+  transformServerConfigForAgent,
+  wizardAdd,
+  wizardManage,
+  wizardRemove,
+  writeServerToConfigFile
+} from "./chunk-XW2KL6W3.js";
+export {
+  AgentConfigStore,
+  DEFAULT_REMOTE_TRANSPORT,
+  NPX_COMMAND,
+  NPX_DASH_Y,
+  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
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@wuyax/mcps",
+  "version": "0.1.0-beta.1",
+  "description": "Cross-platform MCP (Model Context Protocol) server installer and manager for AI coding agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mcps": "./bin/mcps.mjs"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "@inquirer/prompts": "^8.7.1",
+    "commander": "^14.0.0",
+    "jsonc-parser": "^3.3.1",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.8.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}