@wuyax/mcps 0.1.0-beta.2 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wuyax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -12,8 +12,9 @@ Cross-platform Model Context Protocol (MCP) server manager, synchronizer, and co
 - **Multi-Format Storage**: Native read and write engines for JSON, JSONC (preserving existing comments and AST structure via `jsonc-parser`), YAML, and TOML.
 - **Declarative Dialect Transforms**: Intelligent transformation layer adapting standard `McpServerConfig` models into agent-specific field shapes (`command` array vs binary string, `cmd` vs `command`, `envs` vs `env` vs `environment`, `uri` vs `url`, transport indicators, timeouts, and metadata flags).
 - **Intelligent Source Resolution**: Accepts npm package specs, remote HTTP/SSE endpoints, local CLI commands, and Docker containers. Automatically strips npm scopes, package affixes, script extensions, and URL host clutter to infer clean server names.
-- **Cross-Agent Synchronization**: Inspect installed MCP servers across project and global scopes, view parsed details, and sync/clone configurations to other agents with automatic dialect and format translation.
-- **Dual Mode (Interactive TTY + Headless CLI)**: Rich interactive terminal wizards with multiline `.env`/header pasting, `$EDITOR` launching, and password masking for secrets, combined with robust CLI flags and standard exit codes for CI/CD and autonomous agents.
+- **Config Clustering & Co-Hosted Deduplication**: Automatically detects agents sharing the same physical configuration target (such as Claude Code, GitHub Copilot CLI, and Qoder sharing `.mcp.json`). Deduplicates filesystem writes, keeps interactive selection synchronized via linked checkboxes, and reports co-configured and co-affected agents.
+- **Cross-Agent Synchronization & In-Place Editing**: Inspect installed MCP servers across project and global scopes, view parsed details with secret masking, edit configurations in-place with protocol switching (stdio <-> remote), and sync/clone configurations to other agents with automatic dialect and format translation.
+- **Dual Mode (Interactive TTY + Headless CLI)**: Rich interactive terminal wizards with multiline `.env`/header pasting, `$EDITOR` launching, and password masking for secrets, combined with robust CLI commands (`add`, `manage`, `list`, `remove`) and standard exit codes for CI/CD and autonomous agents.
 - **Pluggable Architecture**: Decoupled deep modules including `AgentConfigStore` (supporting filesystem and in-memory test adapters), `resolveTargetAgents` (capability and transport filtering), and declarative transform dialects.
 
 ---
@@ -73,6 +74,18 @@ List installed MCP servers in the current project:
 mcps list
 ```
 
+Inspect an installed MCP server's configuration details:
+
+```bash
+mcps manage server-filesystem
+```
+
+Update command arguments or environment variables non-interactively:
+
+```bash
+mcps manage server-filesystem --args "/workspace" "/data" -y
+```
+
 Remove an MCP server from all agents globally without prompting:
 
 ```bash
@@ -104,7 +117,7 @@ When launched with no arguments, the main menu offers:
 4. **Scope & Agent Selection**:
    - Choose between **Project** (`.`) and **Global** (user home directory).
    - Scans filesystem to auto-detect installed agents in the chosen scope.
-   - Presents a checkbox list where detected agents are labeled with `[detected]` and pre-selected by default.
+   - Presents a synchronized linked checkbox list (`linkedCheckbox`): detected agents carry `[detected]` tags and are pre-selected by default. Agents sharing the same physical configuration file (e.g. `claude-code`, `github-copilot-cli`, and `qoder` in project scope) are grouped and labeled with `[shared: <agents>]`. Selecting or deselecting any agent automatically updates its linked co-hosted peers.
 5. **Arguments**: Configure optional CLI arguments (quote-aware parsing for paths with spaces).
 6. **Environment Variables & Secrets**:
    - `Skip / None`: Proceed without environment variables.
@@ -113,30 +126,32 @@ When launched with no arguments, the main menu offers:
    - `Enter key-value pairs one by one`: Prompts for individual variables. Automatically detects sensitive keys (`token`, `key`, `secret`, `password`, `auth`, `credential`) and masks input using password prompts.
 7. **HTTP Headers** (for remote servers):
    - Supports multiline terminal pasting (`Key: Value` or `Key=Value`), `$EDITOR` entry, or step-by-step entry with secret masking for authorization tokens.
-8. **Configuration Preview & Confirmation**: Displays normalized parameters before writing to disk.
+8. **Configuration Preview & Confirmation**: Displays normalized parameters before writing to disk, deduplicating writes across co-hosted config files and highlighting `(co-configured: <agents>)` on completion.
 
-### Manage & Sync Wizard (`mcps` -> Manage)
+### Manage & Sync Wizard (`mcps` -> Manage, or `mcps manage [server-name]`)
 
-1. Prompts for scope (**Project** or **Global**).
-2. Lists all configured MCP servers grouped by server name along with the agents that currently configure them.
-3. Inspects selected server details: transport type, URL or command, arguments, environment variables, and headers (with secret masking).
+1. Prompts for scope (**Project** or **Global**), or accepts scope flag (`-g, --global`).
+2. Lists all configured MCP servers grouped by server name along with configuring agents. Directly passing `[server-name]` skips the server selection step.
+3. Inspects server details: transport type, URL or command, arguments, environment variables, and headers (with password and token masking). If configurations diverge across agents, displays a divergence warning.
 4. Allows triggering **Edit server configuration**:
+   - **Switch Server Type**: Convert a local command (stdio) to a remote endpoint (HTTP/SSE) or vice versa in-place with interactive input prompts.
    - **Environment Variables (`env`)**: Inspect masked secrets, modify or add variables one-by-one, open in `$EDITOR` with pre-filled `.env` format, paste multiline `.env` definitions (merge or replace), or delete variables.
    - **Command Arguments (`args`)**: Edit arguments in-place with existing arguments pre-filled.
    - **Command (`command`)**: Update executable name or binary path.
-   - **Remote Endpoints (`url`, `type`, `headers`)**: Modify remote URLs, toggle HTTP/SSE transport, and manage HTTP headers.
-   - Saves and persists updated configurations to target agent files using native formats and schema dialects.
+   - **Remote Endpoints (`url`, `type`, `headers`)**: Modify remote URLs, toggle between HTTP and SSE transport, and manage HTTP headers.
+   - **Reset & Discard**: Reset working changes back to the original values or cancel to discard edits without saving.
+   - Saves and persists updated configurations to target agent files using native formats and schema dialects, displaying `(co-configured: <agents>)` feedback for shared configuration targets.
 5. Allows triggering **Sync / clone to other agents**:
    - Identifies candidate agents that do not currently have the server configured.
    - Filters candidate agents by scope and transport capability.
-   - Writes the server configuration to selected targets using their respective native config formats and schema dialects.
+   - Uses linked checkbox selection for candidate agents, keeping co-hosted targets in sync.
+   - Writes the server configuration to selected targets using their respective native config formats and schema dialects, displaying `(co-configured: <agents>)` feedback.
 
 ### Remove Wizard (`mcps remove` without name)
 
-
 1. Prompts for scope (**Project** or **Global**).
 2. Lists configured servers for selection.
-3. Removes the selected server from target agent configuration files with safety confirmation.
+3. Removes the selected server from target agent configuration files with safety confirmation, displaying `(co-affected: <agents>)` feedback when removing from shared configuration targets.
 
 ---
 
@@ -180,6 +195,15 @@ When neither `-a` nor `--all` is specified:
 2. If agents are detected, filters them by transport capability (e.g. stdio-only agents like Claude Desktop are excluded when adding remote HTTP/SSE servers).
 3. If no agents are detected, logs a diagnostic warning and exits with code `1`.
 
+#### Co-Hosted Agent Deduplication
+
+When target agents share the same physical configuration file (e.g. Claude Code, GitHub Copilot CLI, and Qoder sharing project `.mcp.json`), `mcps` automatically clusters the targets, executes a single file write, and logs co-hosted feedback:
+
+```text
+claude-code .mcp.json
+  Note: Also configured for co-hosted agent(s): github-copilot-cli, qoder
+```
+
 #### Examples
 
 ```bash
@@ -239,6 +263,86 @@ mcps list --json
 
 ---
 
+### `mcps manage [server-name]`
+
+Inspects, modifies in-place, or synchronizes installed MCP server configurations across coding agents.
+
+```bash
+mcps manage [server-name] [options]
+```
+
+#### Arguments
+
+- `[server-name]`: Name of the MCP server to inspect or manage.
+  - In an interactive terminal (TTY): If omitted, launches the interactive Manage & Sync Wizard. If provided without modification flags, displays server details and opens the interactive edit/sync menu.
+  - In non-interactive mode (`--yes` or non-TTY): Required when passing modification flags. When passed without modification flags, prints server configuration details (with masked secrets) and exits.
+
+#### Options
+
+- `-a, --agent <agents...>`: Target specific agents for inspection or update. When omitted during updates, defaults to all agents currently configuring the server.
+- `-g, --global`: Target global user-level configurations instead of current project directory.
+- `-t, --transport <type>`: Transport type for remote servers (`http` or `sse`).
+- `--header <header...>`: HTTP header formatted as `Key: Value`. Repeatable.
+- `--clear-headers`: Clear all HTTP headers for remote servers.
+- `--env <env...>`: Environment variable formatted as `KEY=VALUE`. Repeatable.
+- `--clear-env`: Clear all environment variables for stdio servers.
+- `--args <args...>`: CLI arguments for stdio/package servers.
+- `--clear-args`: Clear all arguments for stdio/package servers.
+- `--command <command>`: Executable command for stdio servers.
+- `--url <url>`: Remote endpoint URL.
+- `-y, --yes`: Non-interactive mode; skips confirmation and interactive prompts.
+
+#### Protocol Switching & Sanitization
+
+`mcps manage` automatically handles protocol transitions and prevents configuration pollution:
+- **Mutual Exclusion**: `--url` (remote) and `--command` (stdio) cannot be specified simultaneously.
+- **Switching to Remote**: Supplying `--url` strips existing stdio fields (`command`, `args`, `env`) and applies remote parameters (`url`, `type`, `headers`). Target agents that only support stdio (e.g. Claude Desktop) are skipped with diagnostic warnings.
+- **Switching to Stdio**: Supplying `--command` strips existing remote fields (`url`, `type`, `headers`) and applies stdio parameters (`command`, `args`, `env`).
+- **Clear Flags**: `--clear-env`, `--clear-args`, and `--clear-headers` strip their respective configuration fields. They can also be paired with replacement values (for instance, `--clear-env --env "NEW_VAR=1"` replaces all previous environment variables).
+- **Mismatched Flag Warnings**: Providing stdio flags (`--env`, `--args`) when configuring a remote server or remote flags (`--header`, `--transport`) when configuring a stdio server outputs warnings and safely ignores incompatible flags.
+
+#### Co-Hosted Agent Synchronization
+
+When updating a server on an agent that shares a physical configuration file with other agents, `mcps` deduplicates the operation to a single write and reports co-configured agents:
+
+```text
+claude-code: Successfully updated in .mcp.json
+  Note: Also configured for co-hosted agent(s): github-copilot-cli, qoder
+```
+
+#### Examples
+
+```bash
+# Inspect server configuration and configured agents in current project
+mcps manage postgres
+
+# Inspect a globally configured server
+mcps manage memory -g
+
+# Update command arguments for an existing stdio server
+mcps manage postgres --args --read-only --port 5432 -y
+
+# Merge additional environment variables into an existing stdio server
+mcps manage postgres --env "DB_POOL=10" -y
+
+# Replace all environment variables with a new set using --clear-env
+mcps manage postgres --clear-env --env "POSTGRES_URL=postgresql://localhost:5432/db" -y
+
+# Clear all CLI arguments from a stdio server
+mcps manage postgres --clear-args -y
+
+# Switch an existing stdio server to a remote SSE server
+mcps manage github --url https://api.github.com/mcp/sse -t sse --header "Authorization: Bearer ghp_token" -y
+
+# Switch an existing remote server to a local command
+mcps manage github --command "npx -y @modelcontextprotocol/server-github" -y
+
+# Update server configuration on specific target agents only
+mcps manage postgres --args --timeout 60 -a cursor vscode -y
+```
+
+---
+
 ### `mcps remove [name]` (alias: `mcps rm`)
 
 Removes an MCP server from agent configuration files.
@@ -258,6 +362,15 @@ mcps rm [name] [options]
 - `-a, --agent <agents...>`: Filter removal to specific agents. Pass `'*'` to target all agents.
 - `-y, --yes`: Skip confirmation prompts.
 
+#### Co-Affected Agent Reporting
+
+When removing a server from a configuration file shared by multiple agents, `mcps` performs a single file mutation and reports all co-affected agents:
+
+```text
+claude-code removed postgres .mcp.json
+  Note: Also affects co-hosted agent(s): github-copilot-cli, qoder
+```
+
 #### Examples
 
 ```bash
@@ -335,6 +448,17 @@ When a source string is provided to `mcps add`, `mcps` parses and normalizes it
 | **VS Code** | `vscode` | `github-copilot` | Project, Global | stdio, http, sse | `jsonc` | `.vscode/mcp.json` / User `mcp.json` |
 | **Zed** | `zed` | - | Project, Global | stdio, http, sse | `jsonc` | `.zed/settings.json` / `~/.config/zed/settings.json` |
 
+### Co-Hosted Agent Configurations
+
+Several agents share identical configuration files and root keys. `mcps` automatically groups these agents into configuration clusters to deduplicate disk mutations and keep states synchronized:
+
+| Configuration Path | Key | Co-Hosted Agents | Scope |
+| :--- | :--- | :--- | :--- |
+| `.mcp.json` | `mcpServers` | `claude-code`, `github-copilot-cli`, `qoder` | Project |
+| `.cline/mcp.json` | `mcpServers` | `cline`, `cline-cli` | Project |
+| `.agents/mcp_config.json` | `mcpServers` | `antigravity`, `antigravity-cli` | Project |
+| `~/.gemini/config/mcp_config.json` | `mcpServers` | `antigravity`, `antigravity-cli` | Global |
+
 ### Environment Variable Overrides
 
 For headless environments, Docker containers, and non-standard filesystem layouts, `mcps` respects environment variables for agent directories:
@@ -393,11 +517,12 @@ Agent configurations diverge significantly in syntax and structure. `mcps` maps
 
 `mcps` exports a strongly-typed API for ESM and CommonJS.
 
-### Installation & Removal
+### Server Lifecycle: Install, Update, List & Remove
 
 ```typescript
 import {
   installMcpServer,
+  updateMcpServer,
   listInstalledMcpServers,
   removeMcpServer,
   parseMcpSource,
@@ -417,6 +542,32 @@ const installResult = installMcpServer({
 
 console.log(`Configured ${installResult.serverName}:`);
 for (const record of installResult.results) {
+  if (record.success) {
+    const coHosted = record.coConfiguredAgents
+      ? ` (co-configured: ${record.coConfiguredAgents.join(", ")})`
+      : "";
+    console.log(`  ${record.agent}: OK -> ${record.path}${coHosted}`);
+  } else {
+    console.error(`  ${record.agent}: Error -> ${record.error}`);
+  }
+}
+
+// 2. Update an MCP server (with automatic protocol sanitization and capability filtering)
+const updateResult = updateMcpServer({
+  serverName: "postgres",
+  config: {
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-postgres", "--max-connections", "20"],
+    env: {
+      POSTGRES_CONNECTION_STRING: "postgresql://localhost:5432/production",
+    },
+  },
+  agents: ["cursor", "vscode"],
+  global: false,
+});
+
+console.log(`Updated ${updateResult.serverName}:`);
+for (const record of updateResult.results) {
   if (record.success) {
     console.log(`  ${record.agent}: OK -> ${record.path}`);
   } else {
@@ -424,7 +575,7 @@ for (const record of installResult.results) {
   }
 }
 
-// 2. List installed MCP servers
+// 3. List installed MCP servers
 const servers = listInstalledMcpServers({
   global: false,
   agents: ["cursor", "vscode"],
@@ -434,12 +585,19 @@ for (const s of servers) {
   console.log(`${s.serverName} on ${s.agent} (${s.path})`);
 }
 
-// 3. Remove an MCP server
+// 4. Remove an MCP server
 const removeResults = removeMcpServer({
   name: "postgres",
   agents: ["cursor", "vscode"],
   global: false,
 });
+
+for (const record of removeResults) {
+  const coAffected = record.coAffectedAgents
+    ? ` (also affects: ${record.coAffectedAgents.join(", ")})`
+    : "";
+  console.log(`Removed from ${record.agent} at ${record.path}${coAffected}`);
+}
 ```
 
 ### Parsing Sources & Resolving Agents
@@ -486,9 +644,69 @@ const server = memoryStore.readServer("cursor", "test-server");
 console.log(server);
 ```
 
-### Exported Interactive Utilities
+### Config Clusters & Co-Hosted Agent Resolution
+
+Query and resolve agents sharing underlying physical configuration files:
+
+```typescript
+import {
+  resolveConfigClusters,
+  getCoHostedAgents,
+  getCandidateAgentsForScope,
+  sortAgentsByClusters,
+  installToCompatibleAgents,
+} from "@wuyax/mcps";
+
+// 1. Find agents sharing configuration with Claude Code in project scope
+const coHosted = getCoHostedAgents("claude-code", { global: false });
+// ['github-copilot-cli', 'qoder']
+
+// 2. Resolve deduplicated clusters for a batch of agents
+const clusters = resolveConfigClusters(
+  ["claude-code", "github-copilot-cli", "cursor", "cline"],
+  { global: false },
+);
+for (const cluster of clusters) {
+  console.log(`Target: ${cluster.configPath} [${cluster.configKey}]`);
+  console.log(`  Target agents: ${cluster.targetAgents.join(", ")}`);
+  console.log(`  Unselected co-hosted: ${cluster.coHostedAgents.join(", ")}`);
+}
+
+// 3. Sort agents so cluster peers appear adjacent in lists
+const sorted = sortAgentsByClusters(["github-copilot-cli", "cursor", "claude-code"]);
+// ['github-copilot-cli', 'claude-code', 'cursor']
+
+// 4. Batch-install to compatible agents with cluster deduplication
+const results = installToCompatibleAgents("my-server", serverConfig, {
+  allAgents: ["claude-code", "cursor", "claude-desktop"],
+  incompatible: [
+    { agent: "claude-desktop", reason: "Claude Desktop currently supports only stdio MCP servers." },
+  ],
+  global: false,
+});
+```
+
+### Exported Utilities & Interactive Prompts
 
-The interactive wizard flows and prompt components are also exported for programmatic embedding:
+`mcps` provides two dedicated export surfaces:
+1. **Headless Programmatic SDK (`@wuyax/mcps`)**: Clean, dependency-light API for servers, clusters, protocols, and security masking.
+2. **Interactive UI Wizards & Prompts (`@wuyax/mcps/interactive`)**: Terminal UI wizards and Inquirer prompts for custom CLI integrations.
+
+#### Headless Utilities (`@wuyax/mcps`)
+
+```typescript
+import {
+  parseServerConfig,
+  buildMcpServerConfig,
+  applyServerConfigDelta,
+  detectUpdateTransition,
+  sanitizeUpdatedServerConfig,
+  maskSecretValue,
+  maskSecretHeader,
+} from "@wuyax/mcps";
+```
+
+#### Interactive Terminal UI & Wizards (`@wuyax/mcps/interactive`)
 
 ```typescript
 import {
@@ -496,13 +714,16 @@ import {
   wizardAdd,
   wizardManage,
   wizardRemove,
+  linkedCheckbox,
+  buildLinkedAgentChoices,
+  promptSwitchServerType,
   promptScopeAndAgents,
   promptEnvConfig,
   promptHeadersConfig,
   promptArgsConfig,
   parseEnvText,
   parseHeadersText,
-} from "@wuyax/mcps";
+} from "@wuyax/mcps/interactive";
 ```
 
 ---
@@ -512,7 +733,10 @@ import {
 `mcps` is organized around decoupled deep modules:
 
 - **CLI Commands (`src/cli/`)**: Built with `commander`. Provides non-interactive execution with full flags and TTY wizard fallbacks.
-- **Interactive Wizards (`src/interactive/`)**: Terminal UI built with `@inquirer/prompts`. Handles scope selection, credential masking, multiline terminal and `$EDITOR` input, and cross-agent synchronization.
+- **Interactive Wizards (`src/interactive/`)**: Terminal UI built with `@inquirer/prompts`. Handles scope selection, credential masking, multiline terminal and `$EDITOR` input, in-place configuration editing, and cross-agent synchronization.
+- **Linked Checkbox Prompt (`src/interactive/prompts/linked-checkbox.ts`)**: Extensible interactive checkbox prompt supporting linked peer selection and custom descriptive metadata.
+- **Core Orchestration (`src/install-mcp-server.ts`, `src/update-mcp-server.ts`, `src/installer.ts`, `src/remove.ts`, `src/list.ts`)**: Pure functions orchestrating agent detection, protocol sanitization, config transformation, and persistence.
+- **Config Clusters & Co-Hosted Deduplication (`src/resolve-config-clusters.ts`)**: Identifies agents sharing identical configuration files and keys, deduplicating physical disk operations and synchronizing interactive selection states.
 - **Target Agent Resolver (`src/resolve-target-agents.ts`)**: Resolves target agents from CLI arguments, wildcards, auto-detection, and transport capability constraints.
 - **Agent Config Store (`src/config-store.ts`)**: Unified persistence engine behind a pluggable storage seam (`ConfigStoreAdapter`), handling path resolution, existence checks, and file serialization.
 - **Format Adapters (`src/formats/`)**: Isolated adapters for `json`, comment-preserving `jsonc` (via `jsonc-parser`), `yaml`, and `toml`.