@wuyax/mcps 0.1.0-beta.1 → 0.1.0-beta.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +554 -114
- package/dist/{chunk-XW2KL6W3.js → chunk-BUKA3NPJ.js} +1488 -203
- package/dist/cli.cjs +1425 -246
- package/dist/cli.js +9 -22
- package/dist/index.cjs +1485 -188
- package/dist/index.d.cts +248 -9
- package/dist/index.d.ts +248 -9
- package/dist/index.js +56 -1
- package/package.json +3 -1
package/README.md
CHANGED
|
@@ -1,25 +1,27 @@
|
|
|
1
1
|
# mcps (@wuyax/mcps)
|
|
2
2
|
|
|
3
|
-
Cross-platform
|
|
3
|
+
Cross-platform Model Context Protocol (MCP) server manager, synchronizer, and configuration orchestrator for AI coding agents.
|
|
4
4
|
|
|
5
|
-
`mcps` bridges configuration divergence across AI coding tools. It
|
|
5
|
+
`mcps` bridges configuration divergence across AI coding tools. It classifies MCP server sources, auto-detects installed coding agents, converts configuration shapes into agent-specific dialects, and persists settings into native configuration files across multiple formats (`json`, `jsonc`, `yaml`, `toml`).
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## Key Features
|
|
10
10
|
|
|
11
|
-
- **23 Supported Agents**:
|
|
12
|
-
- **Multi-Format
|
|
13
|
-
- **Dialect Transforms**:
|
|
14
|
-
- **Source
|
|
15
|
-
- **
|
|
16
|
-
- **
|
|
11
|
+
- **23 Supported Agents**: First-class support for Amp, Antigravity, Antigravity CLI, Augment, Claude Code, Claude Desktop, Cline (VS Code extension), Cline CLI, Codex, Cursor, Gemini CLI, GitHub Copilot CLI, Goose, Grok, Kimi Code CLI, Kiro, OpenCode, Pi, Qoder, Qwen Code, Trae, VS Code, and Zed.
|
|
12
|
+
- **Multi-Format Storage**: Native read and write engines for JSON, JSONC (preserving existing comments and AST structure via `jsonc-parser`), YAML, and TOML.
|
|
13
|
+
- **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).
|
|
14
|
+
- **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.
|
|
15
|
+
- **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.
|
|
16
|
+
- **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.
|
|
17
|
+
- **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.
|
|
18
|
+
- **Pluggable Architecture**: Decoupled deep modules including `AgentConfigStore` (supporting filesystem and in-memory test adapters), `resolveTargetAgents` (capability and transport filtering), and declarative transform dialects.
|
|
17
19
|
|
|
18
20
|
---
|
|
19
21
|
|
|
20
22
|
## Installation
|
|
21
23
|
|
|
22
|
-
Run directly
|
|
24
|
+
Run directly using `npx`:
|
|
23
25
|
|
|
24
26
|
```bash
|
|
25
27
|
npx @wuyax/mcps
|
|
@@ -37,24 +39,22 @@ pnpm add -g @wuyax/mcps
|
|
|
37
39
|
|
|
38
40
|
## Quick Start
|
|
39
41
|
|
|
40
|
-
|
|
42
|
+
Execute directly via `npx @wuyax/mcps [command]` or `mcps [command]` when installed globally.
|
|
41
43
|
|
|
42
|
-
### Interactive Wizard (Default)
|
|
44
|
+
### 1. Interactive Terminal Wizard (Default)
|
|
43
45
|
|
|
44
|
-
|
|
46
|
+
Running `mcps` without arguments in an interactive terminal launches the main menu wizard:
|
|
45
47
|
|
|
46
48
|
```bash
|
|
47
|
-
npx @wuyax/mcps
|
|
48
|
-
# or if installed globally:
|
|
49
49
|
mcps
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
-
The interactive
|
|
53
|
-
1. **Add MCP Server**: Step-by-step
|
|
54
|
-
2. **Manage & Sync Installed MCP Servers**: Inspect installed servers in project or global scope, view parsed
|
|
55
|
-
3. **Remove MCP Server**: Select and remove MCP servers from target agent configs.
|
|
52
|
+
The interactive menu provides three workflows:
|
|
53
|
+
1. **Add MCP Server**: Step-by-step installation guiding source selection, protocol detection, scope and agent selection with auto-detection tags, command arguments, and environment variables.
|
|
54
|
+
2. **Manage & Sync Installed MCP Servers**: Inspect installed servers in project or global scope, view parsed server configurations, and clone/sync configurations across agents with automatic format and schema conversion.
|
|
55
|
+
3. **Remove MCP Server**: Select and remove MCP servers from target agent configs with safety confirmations.
|
|
56
56
|
|
|
57
|
-
### Non-Interactive CLI
|
|
57
|
+
### 2. Non-Interactive CLI Automation
|
|
58
58
|
|
|
59
59
|
Install an npm MCP server into auto-detected project agents:
|
|
60
60
|
|
|
@@ -62,84 +62,147 @@ Install an npm MCP server into auto-detected project agents:
|
|
|
62
62
|
mcps add @modelcontextprotocol/server-filesystem
|
|
63
63
|
```
|
|
64
64
|
|
|
65
|
-
Install a remote SSE server
|
|
65
|
+
Install a remote SSE server into specific agents with an authorization header:
|
|
66
66
|
|
|
67
67
|
```bash
|
|
68
68
|
mcps add https://mcp.example.com/sse --transport sse --header "Authorization: Bearer token123" -a cursor vscode
|
|
69
69
|
```
|
|
70
70
|
|
|
71
|
-
List installed servers in the current project:
|
|
71
|
+
List installed MCP servers in the current project:
|
|
72
72
|
|
|
73
73
|
```bash
|
|
74
74
|
mcps list
|
|
75
75
|
```
|
|
76
76
|
|
|
77
|
-
|
|
77
|
+
Inspect an installed MCP server's configuration details:
|
|
78
78
|
|
|
79
79
|
```bash
|
|
80
|
-
mcps
|
|
80
|
+
mcps manage server-filesystem
|
|
81
81
|
```
|
|
82
82
|
|
|
83
|
-
|
|
83
|
+
Update command arguments or environment variables non-interactively:
|
|
84
84
|
|
|
85
|
-
|
|
85
|
+
```bash
|
|
86
|
+
mcps manage server-filesystem --args "/workspace" "/data" -y
|
|
87
|
+
```
|
|
86
88
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
89
|
+
Remove an MCP server from all agents globally without prompting:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
mcps remove server-filesystem -g -a '*' -y
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Interactive Wizards
|
|
98
|
+
|
|
99
|
+
When running in an interactive terminal (TTY), `mcps` provides interactive wizards built with `@inquirer/prompts`.
|
|
100
|
+
|
|
101
|
+
### Main Menu (`mcps`)
|
|
102
|
+
|
|
103
|
+
When launched with no arguments, the main menu offers:
|
|
104
|
+
- **Add MCP Server**: Launches `wizardAdd`.
|
|
105
|
+
- **Manage & Sync Installed MCP Servers**: Launches `wizardManage`.
|
|
106
|
+
- **Remove MCP Server**: Launches `wizardRemove`.
|
|
107
|
+
- **Exit**: Cleanly exits the wizard.
|
|
108
|
+
|
|
109
|
+
### Add Wizard (`mcps add` without source)
|
|
110
|
+
|
|
111
|
+
1. **Source Type Selection**:
|
|
112
|
+
- `npm package (run via npx)`: Enter package identifier (e.g. `@modelcontextprotocol/server-postgres`).
|
|
113
|
+
- `Remote MCP server (via HTTP / SSE URL)`: Enter HTTP/HTTPS URL (e.g. `https://mcp.example.com/sse`).
|
|
114
|
+
- `Local command / script / Docker (stdio)`: Enter command string (e.g. `python -m my_mcp_server`).
|
|
115
|
+
2. **Server Name**: Automatically inferred from the source with an editable default.
|
|
116
|
+
3. **Transport & Protocol** (for remote servers): Select between `HTTP` and `SSE (Server-Sent Events)`. Defaults to `sse` if URL contains `/sse`.
|
|
117
|
+
4. **Scope & Agent Selection**:
|
|
118
|
+
- Choose between **Project** (`.`) and **Global** (user home directory).
|
|
119
|
+
- Scans filesystem to auto-detect installed agents in the chosen scope.
|
|
120
|
+
- 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.
|
|
121
|
+
5. **Arguments**: Configure optional CLI arguments (quote-aware parsing for paths with spaces).
|
|
122
|
+
6. **Environment Variables & Secrets**:
|
|
123
|
+
- `Skip / None`: Proceed without environment variables.
|
|
124
|
+
- `Paste multiline .env text into terminal`: Supports `KEY=VALUE`, `export KEY=VALUE`, comments (`#`), and quoted values.
|
|
125
|
+
- `Open in system default editor ($EDITOR)`: Opens temporary `.env` file in user's configured editor.
|
|
126
|
+
- `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.
|
|
127
|
+
7. **HTTP Headers** (for remote servers):
|
|
128
|
+
- Supports multiline terminal pasting (`Key: Value` or `Key=Value`), `$EDITOR` entry, or step-by-step entry with secret masking for authorization tokens.
|
|
129
|
+
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.
|
|
130
|
+
|
|
131
|
+
### Manage & Sync Wizard (`mcps` -> Manage, or `mcps manage [server-name]`)
|
|
132
|
+
|
|
133
|
+
1. Prompts for scope (**Project** or **Global**), or accepts scope flag (`-g, --global`).
|
|
134
|
+
2. Lists all configured MCP servers grouped by server name along with configuring agents. Directly passing `[server-name]` skips the server selection step.
|
|
135
|
+
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.
|
|
136
|
+
4. Allows triggering **Edit server configuration**:
|
|
137
|
+
- **Switch Server Type**: Convert a local command (stdio) to a remote endpoint (HTTP/SSE) or vice versa in-place with interactive input prompts.
|
|
138
|
+
- **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.
|
|
139
|
+
- **Command Arguments (`args`)**: Edit arguments in-place with existing arguments pre-filled.
|
|
140
|
+
- **Command (`command`)**: Update executable name or binary path.
|
|
141
|
+
- **Remote Endpoints (`url`, `type`, `headers`)**: Modify remote URLs, toggle between HTTP and SSE transport, and manage HTTP headers.
|
|
142
|
+
- **Reset & Discard**: Reset working changes back to the original values or cancel to discard edits without saving.
|
|
143
|
+
- Saves and persists updated configurations to target agent files using native formats and schema dialects, displaying `(co-configured: <agents>)` feedback for shared configuration targets.
|
|
144
|
+
5. Allows triggering **Sync / clone to other agents**:
|
|
145
|
+
- Identifies candidate agents that do not currently have the server configured.
|
|
146
|
+
- Filters candidate agents by scope and transport capability.
|
|
147
|
+
- Uses linked checkbox selection for candidate agents, keeping co-hosted targets in sync.
|
|
148
|
+
- Writes the server configuration to selected targets using their respective native config formats and schema dialects, displaying `(co-configured: <agents>)` feedback.
|
|
149
|
+
|
|
150
|
+
### Remove Wizard (`mcps remove` without name)
|
|
151
|
+
|
|
152
|
+
1. Prompts for scope (**Project** or **Global**).
|
|
153
|
+
2. Lists configured servers for selection.
|
|
154
|
+
3. Removes the selected server from target agent configuration files with safety confirmation, displaying `(co-affected: <agents>)` feedback when removing from shared configuration targets.
|
|
112
155
|
|
|
113
156
|
---
|
|
114
157
|
|
|
115
|
-
## CLI Reference
|
|
158
|
+
## CLI Command Reference
|
|
116
159
|
|
|
117
|
-
###
|
|
160
|
+
### Exit Codes & Completion Criteria
|
|
118
161
|
|
|
119
|
-
-
|
|
120
|
-
-
|
|
162
|
+
- `0`: Operation completed successfully. Target configuration files were modified or queried as requested.
|
|
163
|
+
- `1`: Operation failed. Caused by missing required arguments in non-TTY mode, unresolvable or incompatible agents, invalid source syntax, or file system permission errors.
|
|
164
|
+
|
|
165
|
+
---
|
|
121
166
|
|
|
122
167
|
### `mcps add [source]`
|
|
123
168
|
|
|
124
|
-
|
|
169
|
+
Installs an MCP server into one or more agent configuration files.
|
|
125
170
|
|
|
126
171
|
```bash
|
|
127
172
|
mcps add [source] [options]
|
|
128
173
|
```
|
|
129
174
|
|
|
130
175
|
#### Arguments
|
|
131
|
-
|
|
176
|
+
|
|
177
|
+
- `[source]`: MCP server source. Can be an npm package (`@modelcontextprotocol/server-git`), a remote endpoint (`https://mcp.example.com/sse`), or a shell command (`python -m my_server`). If omitted in TTY mode, starts the interactive Add Wizard.
|
|
132
178
|
|
|
133
179
|
#### Options
|
|
134
|
-
|
|
135
|
-
-
|
|
136
|
-
-
|
|
137
|
-
- `-
|
|
138
|
-
-
|
|
139
|
-
- `--
|
|
180
|
+
|
|
181
|
+
- `-a, --agent <agents...>`: Target specific agents by identifier or alias (e.g. `-a cursor vscode`). Pass `'*'` to target all agents.
|
|
182
|
+
- `--all`: Target all supported agents that support the chosen scope.
|
|
183
|
+
- `-g, --global`: Install to user-level global configuration instead of current project directory.
|
|
184
|
+
- `-t, --transport <type>`: Explicit transport type for remote servers (`http` or `sse`). Defaults to `sse` if URL contains `/sse`, otherwise `http`.
|
|
185
|
+
- `--header <header...>`: HTTP header formatted as `Key: Value`. Repeatable.
|
|
186
|
+
- `--env <env...>`: Environment variable formatted as `KEY=VALUE`. Repeatable.
|
|
140
187
|
- `--args <args...>`: Additional command-line arguments for stdio/package servers.
|
|
141
188
|
- `-n, --name <name>`: Explicit override for server name.
|
|
142
|
-
- `-y, --yes`: Non-interactive mode
|
|
189
|
+
- `-y, --yes`: Non-interactive mode; skips confirmation prompts.
|
|
190
|
+
|
|
191
|
+
#### Target Resolution & Auto-Detection
|
|
192
|
+
|
|
193
|
+
When neither `-a` nor `--all` is specified:
|
|
194
|
+
1. `mcps` scans the project root or global home directories for installed agents.
|
|
195
|
+
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).
|
|
196
|
+
3. If no agents are detected, logs a diagnostic warning and exits with code `1`.
|
|
197
|
+
|
|
198
|
+
#### Co-Hosted Agent Deduplication
|
|
199
|
+
|
|
200
|
+
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:
|
|
201
|
+
|
|
202
|
+
```text
|
|
203
|
+
claude-code .mcp.json
|
|
204
|
+
Note: Also configured for co-hosted agent(s): github-copilot-cli, qoder
|
|
205
|
+
```
|
|
143
206
|
|
|
144
207
|
#### Examples
|
|
145
208
|
|
|
@@ -147,21 +210,29 @@ mcps add [source] [options]
|
|
|
147
210
|
# Auto-detect project agents and install npm package
|
|
148
211
|
mcps add @modelcontextprotocol/server-postgres
|
|
149
212
|
|
|
150
|
-
# Install with
|
|
213
|
+
# Install npm package with environment variables and custom arguments to specific agents
|
|
151
214
|
mcps add @modelcontextprotocol/server-github \
|
|
152
|
-
--env "GITHUB_PERSONAL_ACCESS_TOKEN=
|
|
215
|
+
--env "GITHUB_PERSONAL_ACCESS_TOKEN=ghp_secret" \
|
|
153
216
|
-a cursor claude-code
|
|
154
217
|
|
|
155
|
-
# Install custom python command with name
|
|
218
|
+
# Install custom python command with explicit name
|
|
156
219
|
mcps add "python -m my_mcp_server" -n custom-server -a vscode
|
|
157
220
|
|
|
158
|
-
# Install
|
|
159
|
-
mcps add
|
|
221
|
+
# Install Docker container stdio command
|
|
222
|
+
mcps add "docker run -i --rm mcp/fetch" -n fetch -a cursor
|
|
223
|
+
|
|
224
|
+
# Install remote SSE server globally with authorization header
|
|
225
|
+
mcps add https://mcp.internal.net/sse \
|
|
160
226
|
-t sse \
|
|
161
|
-
--header "Authorization: Bearer
|
|
162
|
-
-g -a cursor
|
|
227
|
+
--header "Authorization: Bearer token_xyz" \
|
|
228
|
+
-g -a cursor vscode
|
|
229
|
+
|
|
230
|
+
# Install to all supported global agents non-interactively
|
|
231
|
+
mcps add @modelcontextprotocol/server-memory -g --all -y
|
|
163
232
|
```
|
|
164
233
|
|
|
234
|
+
---
|
|
235
|
+
|
|
165
236
|
### `mcps list` (alias: `mcps ls`)
|
|
166
237
|
|
|
167
238
|
Lists installed MCP servers across agents.
|
|
@@ -172,23 +243,106 @@ mcps ls [options]
|
|
|
172
243
|
```
|
|
173
244
|
|
|
174
245
|
#### Options
|
|
175
|
-
|
|
246
|
+
|
|
247
|
+
- `-g, --global`: Query global user-level configurations instead of current project directory.
|
|
176
248
|
- `-a, --agent <agents...>`: Filter listing by specific agent identifiers or aliases.
|
|
177
249
|
- `--json`: Output server configurations as structured JSON.
|
|
178
250
|
|
|
179
251
|
#### Examples
|
|
180
252
|
|
|
181
253
|
```bash
|
|
182
|
-
# List
|
|
254
|
+
# List servers configured in the current project
|
|
183
255
|
mcps list
|
|
184
256
|
|
|
185
|
-
# List
|
|
186
|
-
mcps list -g
|
|
257
|
+
# List servers configured globally across Cursor and VS Code
|
|
258
|
+
mcps list -g -a cursor vscode
|
|
259
|
+
|
|
260
|
+
# Output all project-configured servers in JSON format
|
|
261
|
+
mcps list --json
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
---
|
|
187
265
|
|
|
188
|
-
|
|
189
|
-
|
|
266
|
+
### `mcps manage [server-name]`
|
|
267
|
+
|
|
268
|
+
Inspects, modifies in-place, or synchronizes installed MCP server configurations across coding agents.
|
|
269
|
+
|
|
270
|
+
```bash
|
|
271
|
+
mcps manage [server-name] [options]
|
|
190
272
|
```
|
|
191
273
|
|
|
274
|
+
#### Arguments
|
|
275
|
+
|
|
276
|
+
- `[server-name]`: Name of the MCP server to inspect or manage.
|
|
277
|
+
- 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.
|
|
278
|
+
- 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.
|
|
279
|
+
|
|
280
|
+
#### Options
|
|
281
|
+
|
|
282
|
+
- `-a, --agent <agents...>`: Target specific agents for inspection or update. When omitted during updates, defaults to all agents currently configuring the server.
|
|
283
|
+
- `-g, --global`: Target global user-level configurations instead of current project directory.
|
|
284
|
+
- `-t, --transport <type>`: Transport type for remote servers (`http` or `sse`).
|
|
285
|
+
- `--header <header...>`: HTTP header formatted as `Key: Value`. Repeatable.
|
|
286
|
+
- `--clear-headers`: Clear all HTTP headers for remote servers.
|
|
287
|
+
- `--env <env...>`: Environment variable formatted as `KEY=VALUE`. Repeatable.
|
|
288
|
+
- `--clear-env`: Clear all environment variables for stdio servers.
|
|
289
|
+
- `--args <args...>`: CLI arguments for stdio/package servers.
|
|
290
|
+
- `--clear-args`: Clear all arguments for stdio/package servers.
|
|
291
|
+
- `--command <command>`: Executable command for stdio servers.
|
|
292
|
+
- `--url <url>`: Remote endpoint URL.
|
|
293
|
+
- `-y, --yes`: Non-interactive mode; skips confirmation and interactive prompts.
|
|
294
|
+
|
|
295
|
+
#### Protocol Switching & Sanitization
|
|
296
|
+
|
|
297
|
+
`mcps manage` automatically handles protocol transitions and prevents configuration pollution:
|
|
298
|
+
- **Mutual Exclusion**: `--url` (remote) and `--command` (stdio) cannot be specified simultaneously.
|
|
299
|
+
- **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.
|
|
300
|
+
- **Switching to Stdio**: Supplying `--command` strips existing remote fields (`url`, `type`, `headers`) and applies stdio parameters (`command`, `args`, `env`).
|
|
301
|
+
- **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).
|
|
302
|
+
- **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.
|
|
303
|
+
|
|
304
|
+
#### Co-Hosted Agent Synchronization
|
|
305
|
+
|
|
306
|
+
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:
|
|
307
|
+
|
|
308
|
+
```text
|
|
309
|
+
claude-code: Successfully updated in .mcp.json
|
|
310
|
+
Note: Also configured for co-hosted agent(s): github-copilot-cli, qoder
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
#### Examples
|
|
314
|
+
|
|
315
|
+
```bash
|
|
316
|
+
# Inspect server configuration and configured agents in current project
|
|
317
|
+
mcps manage postgres
|
|
318
|
+
|
|
319
|
+
# Inspect a globally configured server
|
|
320
|
+
mcps manage memory -g
|
|
321
|
+
|
|
322
|
+
# Update command arguments for an existing stdio server
|
|
323
|
+
mcps manage postgres --args --read-only --port 5432 -y
|
|
324
|
+
|
|
325
|
+
# Merge additional environment variables into an existing stdio server
|
|
326
|
+
mcps manage postgres --env "DB_POOL=10" -y
|
|
327
|
+
|
|
328
|
+
# Replace all environment variables with a new set using --clear-env
|
|
329
|
+
mcps manage postgres --clear-env --env "POSTGRES_URL=postgresql://localhost:5432/db" -y
|
|
330
|
+
|
|
331
|
+
# Clear all CLI arguments from a stdio server
|
|
332
|
+
mcps manage postgres --clear-args -y
|
|
333
|
+
|
|
334
|
+
# Switch an existing stdio server to a remote SSE server
|
|
335
|
+
mcps manage github --url https://api.github.com/mcp/sse -t sse --header "Authorization: Bearer ghp_token" -y
|
|
336
|
+
|
|
337
|
+
# Switch an existing remote server to a local command
|
|
338
|
+
mcps manage github --command "npx -y @modelcontextprotocol/server-github" -y
|
|
339
|
+
|
|
340
|
+
# Update server configuration on specific target agents only
|
|
341
|
+
mcps manage postgres --args --timeout 60 -a cursor vscode -y
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
---
|
|
345
|
+
|
|
192
346
|
### `mcps remove [name]` (alias: `mcps rm`)
|
|
193
347
|
|
|
194
348
|
Removes an MCP server from agent configuration files.
|
|
@@ -199,104 +353,390 @@ mcps rm [name] [options]
|
|
|
199
353
|
```
|
|
200
354
|
|
|
201
355
|
#### Arguments
|
|
202
|
-
|
|
356
|
+
|
|
357
|
+
- `[name]`: Name of the MCP server to remove. If omitted in TTY mode, starts the interactive Remove Wizard.
|
|
203
358
|
|
|
204
359
|
#### Options
|
|
360
|
+
|
|
205
361
|
- `-g, --global`: Remove from global user-level configurations.
|
|
206
|
-
- `-a, --agent <agents...>`: Filter removal to specific agents. Pass `'*'`
|
|
207
|
-
- `-y, --yes`: Skip confirmation
|
|
362
|
+
- `-a, --agent <agents...>`: Filter removal to specific agents. Pass `'*'` to target all agents.
|
|
363
|
+
- `-y, --yes`: Skip confirmation prompts.
|
|
364
|
+
|
|
365
|
+
#### Co-Affected Agent Reporting
|
|
366
|
+
|
|
367
|
+
When removing a server from a configuration file shared by multiple agents, `mcps` performs a single file mutation and reports all co-affected agents:
|
|
368
|
+
|
|
369
|
+
```text
|
|
370
|
+
claude-code removed postgres .mcp.json
|
|
371
|
+
Note: Also affects co-hosted agent(s): github-copilot-cli, qoder
|
|
372
|
+
```
|
|
208
373
|
|
|
209
374
|
#### Examples
|
|
210
375
|
|
|
211
376
|
```bash
|
|
212
|
-
# Remove from all configured project
|
|
377
|
+
# Remove server from all configured agents in current project
|
|
213
378
|
mcps remove postgres
|
|
214
379
|
|
|
215
|
-
# Remove from Cursor
|
|
380
|
+
# Remove server from Cursor global config without prompting
|
|
216
381
|
mcps remove github -a cursor -g -y
|
|
382
|
+
|
|
383
|
+
# Remove server from all agents globally
|
|
384
|
+
mcps remove memory -g -a '*' -y
|
|
217
385
|
```
|
|
218
386
|
|
|
219
387
|
---
|
|
220
388
|
|
|
221
389
|
## Source Parsing Mechanics
|
|
222
390
|
|
|
223
|
-
When a source string is provided to `mcps add`, `mcps`
|
|
391
|
+
When a source string is provided to `mcps add`, `mcps` parses and normalizes it into a `ParsedMcpSource`:
|
|
392
|
+
|
|
393
|
+
### 1. Remote URLs (`type: "remote"`)
|
|
394
|
+
|
|
395
|
+
- Identified when string matches `^https?:\/\/` pattern.
|
|
396
|
+
- **Transport Inference**: Defaults to `sse` if the URL pathname contains `/sse`, otherwise `http`.
|
|
397
|
+
- **Name Inference**: Extracts meaningful domain labels, stripping generic prefixes (`api`, `mcp`, `app`) and common TLDs (`com`, `org`, `io`, `net`, `dev`, etc.). Example: `https://api.github.com/mcp/sse` -> `github`.
|
|
398
|
+
|
|
399
|
+
### 2. npm Packages (`type: "package"`)
|
|
224
400
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
401
|
+
- Matches npm package naming conventions (e.g. `@scope/name`, `package-name`).
|
|
402
|
+
- Normalized to `command: "npx"`, `args: ["-y", "<package>"]`.
|
|
403
|
+
- **Name Inference**:
|
|
404
|
+
- Strips version tags (e.g. `@1.0.0`).
|
|
405
|
+
- Strips npm scope prefixes (e.g. `@modelcontextprotocol/`).
|
|
406
|
+
- Strips path prefixes and script extensions (`.js`, `.mjs`, `.cjs`, `.ts`, `.py`).
|
|
407
|
+
- Strips common package prefixes (`mcp-server-`, `mcp-`, `server-`) and suffixes (`-mcp-server`, `-server`, `-mcp`).
|
|
408
|
+
- Example: `@modelcontextprotocol/server-postgres` -> `postgres`.
|
|
409
|
+
|
|
410
|
+
### 3. Shell Commands (`type: "command"`)
|
|
411
|
+
|
|
412
|
+
- Identified when string contains whitespace or known runner prefixes (`python`, `python3`, `node`, `uvx`, `docker`).
|
|
413
|
+
- Tokenizes binary and arguments.
|
|
414
|
+
- **Name Inference**: Inspects tokens following the runner binary, ignoring flags, and extracts the target script or package name.
|
|
415
|
+
- Example: `python -m my_mcp_server` -> `my_mcp_server`.
|
|
416
|
+
- Example: `uvx mcp-server-sqlite` -> `sqlite`.
|
|
417
|
+
- Example: `docker run -i --rm mcp/fetch` -> `fetch`.
|
|
233
418
|
|
|
234
419
|
---
|
|
235
420
|
|
|
236
|
-
##
|
|
421
|
+
## Supported Agents Matrix
|
|
237
422
|
|
|
238
|
-
`mcps`
|
|
423
|
+
`mcps` supports 23 AI coding agents and tools:
|
|
424
|
+
|
|
425
|
+
| Agent | Identifier | Aliases | Scopes | Transports | Format | Config Path (Project / Global) |
|
|
426
|
+
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
|
|
427
|
+
| **Amp** | `amp` | `amp-cli`, `amp-code`, `ampcode` | Project, Global | stdio, http, sse | `jsonc` | `.amp/settings.json` / `~/.config/amp/settings.jsonc` |
|
|
428
|
+
| **Antigravity** | `antigravity` | - | Project, Global | stdio, http, sse | `jsonc` | `.agents/mcp_config.json` / `~/.gemini/config/mcp_config.json` |
|
|
429
|
+
| **Antigravity CLI** | `antigravity-cli` | `agy` | Project, Global | stdio, http, sse | `jsonc` | `.agents/mcp_config.json` / `~/.gemini/config/mcp_config.json` |
|
|
430
|
+
| **Augment** | `augment` | `auggie`, `augment-code`, `augmentcode` | Project, Global | stdio, http, sse | `jsonc` | `.augment/settings.json` / `~/.augment/settings.jsonc` |
|
|
431
|
+
| **Claude Code** | `claude-code` | - | Project, Global | stdio, http, sse | `jsonc` | `.mcp.json` / `~/.claude.json` |
|
|
432
|
+
| **Claude Desktop** | `claude-desktop` | - | Global | stdio | `jsonc` | User Application Support / Roaming `claude_desktop_config.json` |
|
|
433
|
+
| **Cline (VS Code)** | `cline` | `cline-vscode` | Project, Global | stdio, http, sse | `jsonc` | `.cline/mcp.json` / VS Code global storage `cline_mcp_settings.json` |
|
|
434
|
+
| **Cline CLI** | `cline-cli` | - | Project, Global | stdio, http, sse | `jsonc` | `.cline/mcp.json` / `~/.cline/mcp.json` |
|
|
435
|
+
| **Codex** | `codex` | - | Project, Global | stdio, http, sse | `toml` | `.codex/config.toml` / `~/.codex/config.toml` |
|
|
436
|
+
| **Cursor** | `cursor` | - | Project, Global | stdio, http, sse | `jsonc` | `.cursor/mcp.json` / `~/.cursor/mcp.json` |
|
|
437
|
+
| **Gemini CLI** | `gemini-cli` | `gemini` | Project, Global | stdio, http, sse | `jsonc` | `.gemini/settings.json` / `~/.gemini/settings.json` |
|
|
438
|
+
| **GitHub Copilot CLI** | `github-copilot-cli` | - | Project, Global | stdio, http, sse | `jsonc` | `.mcp.json` / `~/.copilot/mcp-config.json` |
|
|
439
|
+
| **Goose** | `goose` | - | Project, Global | stdio, http, sse | `yaml` | `.goose/config.yaml` / `~/.config/goose/config.yaml` |
|
|
440
|
+
| **Grok** | `grok` | `grok-cli`, `xai`, `xai-grok` | Project, Global | stdio, http, sse | `toml` | `.grok/config.toml` / `~/.grok/config.toml` |
|
|
441
|
+
| **Kimi Code CLI** | `kimi-code-cli` | `kimi`, `kimi-cli`, `kimi-code` | Project, Global | stdio, http, sse | `jsonc` | `.kimi-code/mcp.json` / `~/.kimi-code/mcp.json` |
|
|
442
|
+
| **Kiro** | `kiro` | `kiro-cli`, `kiro-ide` | Project, Global | stdio, http, sse | `jsonc` | `.kiro/settings/mcp.json` / `~/.kiro/settings/mcp.json` |
|
|
443
|
+
| **OpenCode** | `opencode` | - | Project, Global | stdio, http, sse | `jsonc` | `opencode.json` / `~/.config/opencode/opencode.json` |
|
|
444
|
+
| **Pi** | `pi` | `pi-agent` | Project, Global | stdio, http, sse | `jsonc` | `.pi/mcp.json` / `~/.pi/agent/mcp.json` |
|
|
445
|
+
| **Qoder** | `qoder` | `qoder-cli` | Project, Global | stdio, http, sse | `jsonc` | `.mcp.json` / `~/.qoder/settings.json` |
|
|
446
|
+
| **Qwen Code** | `qwen-code` | `qwen`, `qwen-cli`, `qwencode` | Project, Global | stdio, http, sse | `jsonc` | `.qwen/settings.json` / `~/.qwen/settings.json` |
|
|
447
|
+
| **Trae** | `trae` | `trae-code`, `traecode`, `trae-ide` | Project, Global | stdio, http, sse | `jsonc` | `.trae/mcp.json` / `~/.trae/mcp.json` |
|
|
448
|
+
| **VS Code** | `vscode` | `github-copilot` | Project, Global | stdio, http, sse | `jsonc` | `.vscode/mcp.json` / User `mcp.json` |
|
|
449
|
+
| **Zed** | `zed` | - | Project, Global | stdio, http, sse | `jsonc` | `.zed/settings.json` / `~/.config/zed/settings.json` |
|
|
450
|
+
|
|
451
|
+
### Co-Hosted Agent Configurations
|
|
452
|
+
|
|
453
|
+
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:
|
|
454
|
+
|
|
455
|
+
| Configuration Path | Key | Co-Hosted Agents | Scope |
|
|
456
|
+
| :--- | :--- | :--- | :--- |
|
|
457
|
+
| `.mcp.json` | `mcpServers` | `claude-code`, `github-copilot-cli`, `qoder` | Project |
|
|
458
|
+
| `.cline/mcp.json` | `mcpServers` | `cline`, `cline-cli` | Project |
|
|
459
|
+
| `.agents/mcp_config.json` | `mcpServers` | `antigravity`, `antigravity-cli` | Project |
|
|
460
|
+
| `~/.gemini/config/mcp_config.json` | `mcpServers` | `antigravity`, `antigravity-cli` | Global |
|
|
461
|
+
|
|
462
|
+
### Environment Variable Overrides
|
|
463
|
+
|
|
464
|
+
For headless environments, Docker containers, and non-standard filesystem layouts, `mcps` respects environment variables for agent directories:
|
|
465
|
+
|
|
466
|
+
| Environment Variable | Target Agent | Description |
|
|
467
|
+
| :--- | :--- | :--- |
|
|
468
|
+
| `AMP_HOME` | Amp | Overrides global config directory (defaults to `~/.config/amp` or `~/.amp`). |
|
|
469
|
+
| `AUGMENT_HOME` | Augment | Overrides global config directory (defaults to `~/.augment`). |
|
|
470
|
+
| `CLINE_DIR` | Cline CLI | Overrides global directory (defaults to `~/.cline`). |
|
|
471
|
+
| `CODEX_HOME` | Codex | Overrides global directory (defaults to `~/.codex`). |
|
|
472
|
+
| `COPILOT_HOME` | GitHub Copilot CLI | Overrides global directory (defaults to `~/.copilot`). |
|
|
473
|
+
| `GROK_HOME` | Grok | Overrides global directory (defaults to `~/.grok`). |
|
|
474
|
+
| `KIMI_CODE_HOME` | Kimi Code CLI | Overrides global directory (defaults to `~/.kimi-code`). |
|
|
475
|
+
| `KIRO_HOME` | Kiro | Overrides global directory (defaults to `~/.kiro`). |
|
|
476
|
+
| `QODER_HOME` | Qoder | Overrides global directory (defaults to `~/.qoder`). |
|
|
477
|
+
| `QWEN_CODE_HOME` / `QWEN_HOME` | Qwen Code | Overrides global directory (defaults to `~/.qwen`). |
|
|
478
|
+
| `XDG_CONFIG_HOME` | Linux/macOS defaults | Sets standard XDG base directory for tools adhering to XDG (`amp`, `opencode`, `goose`, `zed`). |
|
|
479
|
+
|
|
480
|
+
---
|
|
481
|
+
|
|
482
|
+
## Server Config Dialects
|
|
483
|
+
|
|
484
|
+
Agent configurations diverge significantly in syntax and structure. `mcps` maps the normalized domain model (`McpServerConfig`) into each agent's native dialect via declarative presets:
|
|
485
|
+
|
|
486
|
+
- **VS Code (`vscode`, `github-copilot-cli`)**:
|
|
487
|
+
- Root key: `servers`.
|
|
488
|
+
- stdio transport: `type: "stdio"`, `command`, `args`.
|
|
489
|
+
- remote transport: `type: "http" | "sse"`, `url`, `headers`.
|
|
490
|
+
- **Goose (`goose`)**:
|
|
491
|
+
- Root key: `extensions`.
|
|
492
|
+
- stdio transport: `cmd` (instead of `command`), `args`, `envs` (instead of `env`), `type: "stdio"`, `timeout: 30`, `description: ""`, `enabled: true`.
|
|
493
|
+
- remote transport: `uri` (instead of `url`), `type: "streamable_http" | "sse"`, `headers`, `timeout: 30`, `description: ""`, `enabled: true`.
|
|
494
|
+
- **OpenCode (`opencode`)**:
|
|
495
|
+
- Root key: `mcp`.
|
|
496
|
+
- stdio transport: `command: [command, ...args]` (array format), `environment` (instead of `env`), `type: "local"`, `enabled: true`.
|
|
497
|
+
- remote transport: `type: "remote"`, `url`, `headers`, `enabled: true`.
|
|
498
|
+
- **Pi (`pi`)**:
|
|
499
|
+
- stdio transport: `transport: "stdio"`.
|
|
500
|
+
- remote transport: `transport: "streamable-http" | "sse"`.
|
|
501
|
+
- **Qwen Code (`qwen-code`)**:
|
|
502
|
+
- remote transport: Uses `url` for SSE and `httpUrl` for standard HTTP.
|
|
503
|
+
- **Cline (`cline`, `cline-cli`)**:
|
|
504
|
+
- remote transport: `type: "sse" | "streamableHttp"`.
|
|
505
|
+
- **Grok & Trae (`grok`, `trae`)**:
|
|
506
|
+
- remote transport: Sets `type: "sse"` only when SSE transport is active.
|
|
507
|
+
- **Zed (`zed`)**:
|
|
508
|
+
- Root key: `context_servers`.
|
|
509
|
+
- **Codex (`codex`)**:
|
|
510
|
+
- Format: TOML under `[mcp_servers.<name>]`.
|
|
511
|
+
- **Claude Desktop (`claude-desktop`)**:
|
|
512
|
+
- Enforces stdio-only transport. Remote URLs trigger diagnostic warnings and are prevented from persisting.
|
|
513
|
+
|
|
514
|
+
---
|
|
515
|
+
|
|
516
|
+
## Programmatic Node / TypeScript API
|
|
517
|
+
|
|
518
|
+
`mcps` exports a strongly-typed API for ESM and CommonJS.
|
|
519
|
+
|
|
520
|
+
### Server Lifecycle: Install, Update, List & Remove
|
|
239
521
|
|
|
240
522
|
```typescript
|
|
241
523
|
import {
|
|
242
524
|
installMcpServer,
|
|
525
|
+
updateMcpServer,
|
|
243
526
|
listInstalledMcpServers,
|
|
244
527
|
removeMcpServer,
|
|
245
528
|
parseMcpSource,
|
|
246
529
|
resolveTargetAgents,
|
|
247
|
-
|
|
248
|
-
getMcpAgentConfig,
|
|
249
|
-
} from "mcps";
|
|
530
|
+
} from "@wuyax/mcps";
|
|
250
531
|
|
|
251
532
|
// 1. Install an MCP server
|
|
252
533
|
const installResult = installMcpServer({
|
|
253
534
|
source: "@modelcontextprotocol/server-postgres",
|
|
254
|
-
agents: ["cursor", "vscode", "
|
|
535
|
+
agents: ["cursor", "vscode", "goose"],
|
|
255
536
|
env: {
|
|
256
|
-
POSTGRES_CONNECTION_STRING: "postgresql://localhost/db",
|
|
537
|
+
POSTGRES_CONNECTION_STRING: "postgresql://localhost:5432/db",
|
|
257
538
|
},
|
|
539
|
+
args: ["--read-only"],
|
|
258
540
|
global: false,
|
|
259
541
|
});
|
|
260
542
|
|
|
261
543
|
console.log(`Configured ${installResult.serverName}:`);
|
|
262
|
-
for (const
|
|
263
|
-
|
|
544
|
+
for (const record of installResult.results) {
|
|
545
|
+
if (record.success) {
|
|
546
|
+
const coHosted = record.coConfiguredAgents
|
|
547
|
+
? ` (co-configured: ${record.coConfiguredAgents.join(", ")})`
|
|
548
|
+
: "";
|
|
549
|
+
console.log(` ${record.agent}: OK -> ${record.path}${coHosted}`);
|
|
550
|
+
} else {
|
|
551
|
+
console.error(` ${record.agent}: Error -> ${record.error}`);
|
|
552
|
+
}
|
|
264
553
|
}
|
|
265
554
|
|
|
266
|
-
// 2.
|
|
267
|
-
const
|
|
555
|
+
// 2. Update an MCP server (with automatic protocol sanitization and capability filtering)
|
|
556
|
+
const updateResult = updateMcpServer({
|
|
557
|
+
serverName: "postgres",
|
|
558
|
+
config: {
|
|
559
|
+
command: "npx",
|
|
560
|
+
args: ["-y", "@modelcontextprotocol/server-postgres", "--max-connections", "20"],
|
|
561
|
+
env: {
|
|
562
|
+
POSTGRES_CONNECTION_STRING: "postgresql://localhost:5432/production",
|
|
563
|
+
},
|
|
564
|
+
},
|
|
565
|
+
agents: ["cursor", "vscode"],
|
|
268
566
|
global: false,
|
|
269
|
-
agents: ["cursor"],
|
|
270
567
|
});
|
|
271
568
|
|
|
272
|
-
|
|
273
|
-
const
|
|
274
|
-
|
|
569
|
+
console.log(`Updated ${updateResult.serverName}:`);
|
|
570
|
+
for (const record of updateResult.results) {
|
|
571
|
+
if (record.success) {
|
|
572
|
+
console.log(` ${record.agent}: OK -> ${record.path}`);
|
|
573
|
+
} else {
|
|
574
|
+
console.error(` ${record.agent}: Error -> ${record.error}`);
|
|
575
|
+
}
|
|
576
|
+
}
|
|
577
|
+
|
|
578
|
+
// 3. List installed MCP servers
|
|
579
|
+
const servers = listInstalledMcpServers({
|
|
580
|
+
global: false,
|
|
581
|
+
agents: ["cursor", "vscode"],
|
|
582
|
+
});
|
|
583
|
+
|
|
584
|
+
for (const s of servers) {
|
|
585
|
+
console.log(`${s.serverName} on ${s.agent} (${s.path})`);
|
|
586
|
+
}
|
|
275
587
|
|
|
276
588
|
// 4. Remove an MCP server
|
|
277
589
|
const removeResults = removeMcpServer({
|
|
278
590
|
name: "postgres",
|
|
279
|
-
agents: ["cursor"],
|
|
591
|
+
agents: ["cursor", "vscode"],
|
|
592
|
+
global: false,
|
|
593
|
+
});
|
|
594
|
+
|
|
595
|
+
for (const record of removeResults) {
|
|
596
|
+
const coAffected = record.coAffectedAgents
|
|
597
|
+
? ` (also affects: ${record.coAffectedAgents.join(", ")})`
|
|
598
|
+
: "";
|
|
599
|
+
console.log(`Removed from ${record.agent} at ${record.path}${coAffected}`);
|
|
600
|
+
}
|
|
601
|
+
```
|
|
602
|
+
|
|
603
|
+
### Parsing Sources & Resolving Agents
|
|
604
|
+
|
|
605
|
+
```typescript
|
|
606
|
+
import { parseMcpSource, resolveTargetAgents } from "@wuyax/mcps";
|
|
607
|
+
|
|
608
|
+
// Parse any source string
|
|
609
|
+
const parsed = parseMcpSource("https://api.github.com/mcp/sse");
|
|
610
|
+
// { type: "remote", value: "https://api.github.com/mcp/sse", inferredName: "github" }
|
|
611
|
+
|
|
612
|
+
// Resolve target agents with capability checks
|
|
613
|
+
const targets = resolveTargetAgents({
|
|
614
|
+
requested: ["cursor", "claude-desktop"],
|
|
615
|
+
transport: "sse",
|
|
616
|
+
global: true,
|
|
617
|
+
});
|
|
618
|
+
|
|
619
|
+
console.log("Compatible:", targets.compatibleAgents); // ['cursor']
|
|
620
|
+
console.log("Incompatible:", targets.incompatible);
|
|
621
|
+
// [{ agent: 'claude-desktop', reason: 'Claude Desktop currently supports only stdio MCP servers...' }]
|
|
622
|
+
```
|
|
623
|
+
|
|
624
|
+
### Pluggable AgentConfigStore
|
|
625
|
+
|
|
626
|
+
`AgentConfigStore` decouples file persistence, allowing in-memory testing:
|
|
627
|
+
|
|
628
|
+
```typescript
|
|
629
|
+
import {
|
|
630
|
+
AgentConfigStore,
|
|
631
|
+
MemoryConfigStoreAdapter,
|
|
632
|
+
agentConfigStore, // Default singleton using FsConfigStoreAdapter
|
|
633
|
+
} from "@wuyax/mcps";
|
|
634
|
+
|
|
635
|
+
// Use memory adapter for isolated testing
|
|
636
|
+
const memoryStore = new AgentConfigStore(new MemoryConfigStoreAdapter());
|
|
637
|
+
|
|
638
|
+
memoryStore.writeServer("cursor", "test-server", {
|
|
639
|
+
command: "npx",
|
|
640
|
+
args: ["-y", "test-mcp"],
|
|
641
|
+
});
|
|
642
|
+
|
|
643
|
+
const server = memoryStore.readServer("cursor", "test-server");
|
|
644
|
+
console.log(server);
|
|
645
|
+
```
|
|
646
|
+
|
|
647
|
+
### Config Clusters & Co-Hosted Agent Resolution
|
|
648
|
+
|
|
649
|
+
Query and resolve agents sharing underlying physical configuration files:
|
|
650
|
+
|
|
651
|
+
```typescript
|
|
652
|
+
import {
|
|
653
|
+
resolveConfigClusters,
|
|
654
|
+
getCoHostedAgents,
|
|
655
|
+
getCandidateAgentsForScope,
|
|
656
|
+
sortAgentsWithClusters,
|
|
657
|
+
installToCompatibleAgents,
|
|
658
|
+
} from "@wuyax/mcps";
|
|
659
|
+
|
|
660
|
+
// 1. Find agents sharing configuration with Claude Code in project scope
|
|
661
|
+
const coHosted = getCoHostedAgents("claude-code", { global: false });
|
|
662
|
+
// ['github-copilot-cli', 'qoder']
|
|
663
|
+
|
|
664
|
+
// 2. Resolve deduplicated clusters for a batch of agents
|
|
665
|
+
const clusters = resolveConfigClusters(
|
|
666
|
+
["claude-code", "github-copilot-cli", "cursor", "cline"],
|
|
667
|
+
{ global: false },
|
|
668
|
+
);
|
|
669
|
+
for (const cluster of clusters) {
|
|
670
|
+
console.log(`Target: ${cluster.configPath} [${cluster.configKey}]`);
|
|
671
|
+
console.log(` Target agents: ${cluster.targetAgents.join(", ")}`);
|
|
672
|
+
console.log(` Unselected co-hosted: ${cluster.coHostedAgents.join(", ")}`);
|
|
673
|
+
}
|
|
674
|
+
|
|
675
|
+
// 3. Sort agents so cluster peers appear adjacent in lists
|
|
676
|
+
const sorted = sortAgentsWithClusters(["github-copilot-cli", "cursor", "claude-code"]);
|
|
677
|
+
// ['github-copilot-cli', 'claude-code', 'cursor']
|
|
678
|
+
|
|
679
|
+
// 4. Batch-install to compatible agents with cluster deduplication
|
|
680
|
+
const results = installToCompatibleAgents("my-server", serverConfig, {
|
|
681
|
+
allAgents: ["claude-code", "cursor", "claude-desktop"],
|
|
682
|
+
incompatible: [
|
|
683
|
+
{ agent: "claude-desktop", reason: "Claude Desktop currently supports only stdio MCP servers." },
|
|
684
|
+
],
|
|
280
685
|
global: false,
|
|
281
686
|
});
|
|
282
687
|
```
|
|
283
688
|
|
|
689
|
+
### Exported Utilities & Interactive Prompts
|
|
690
|
+
|
|
691
|
+
The interactive wizard flows, prompt components, and inspection/sanitization utilities are also exported for programmatic embedding:
|
|
692
|
+
|
|
693
|
+
```typescript
|
|
694
|
+
import {
|
|
695
|
+
mainMenu,
|
|
696
|
+
wizardAdd,
|
|
697
|
+
wizardManage,
|
|
698
|
+
wizardRemove,
|
|
699
|
+
linkedCheckbox,
|
|
700
|
+
buildLinkedAgentChoices,
|
|
701
|
+
groupInstalledServersByName,
|
|
702
|
+
normalizeServerConfig,
|
|
703
|
+
formatCoHostedBadge,
|
|
704
|
+
logCoHostedNotice,
|
|
705
|
+
displayServerDetails,
|
|
706
|
+
resolveTransport,
|
|
707
|
+
maskSecretValue,
|
|
708
|
+
maskSecretHeader,
|
|
709
|
+
sanitizeUpdatedServerConfig,
|
|
710
|
+
detectUpdateTransition,
|
|
711
|
+
promptSwitchServerType,
|
|
712
|
+
promptScopeAndAgents,
|
|
713
|
+
promptEnvConfig,
|
|
714
|
+
promptHeadersConfig,
|
|
715
|
+
promptArgsConfig,
|
|
716
|
+
parseEnvText,
|
|
717
|
+
parseHeadersText,
|
|
718
|
+
} from "@wuyax/mcps";
|
|
719
|
+
```
|
|
720
|
+
|
|
284
721
|
---
|
|
285
722
|
|
|
286
723
|
## Architecture & Seams
|
|
287
724
|
|
|
288
|
-
`mcps` is
|
|
725
|
+
`mcps` is organized around decoupled deep modules:
|
|
289
726
|
|
|
290
|
-
- **CLI Commands (`src/cli/`)**: Built
|
|
291
|
-
- **Interactive Wizards (`src/interactive/`)**: Terminal
|
|
292
|
-
- **
|
|
293
|
-
- **
|
|
294
|
-
- **
|
|
295
|
-
- **
|
|
727
|
+
- **CLI Commands (`src/cli/`)**: Built with `commander`. Provides non-interactive execution with full flags and TTY wizard fallbacks.
|
|
728
|
+
- **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.
|
|
729
|
+
- **Linked Checkbox Prompt (`src/interactive/prompts/linked-checkbox.ts`)**: Extensible interactive checkbox prompt supporting linked peer selection and custom descriptive metadata.
|
|
730
|
+
- **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.
|
|
731
|
+
- **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.
|
|
732
|
+
- **Target Agent Resolver (`src/resolve-target-agents.ts`)**: Resolves target agents from CLI arguments, wildcards, auto-detection, and transport capability constraints.
|
|
733
|
+
- **Agent Config Store (`src/config-store.ts`)**: Unified persistence engine behind a pluggable storage seam (`ConfigStoreAdapter`), handling path resolution, existence checks, and file serialization.
|
|
734
|
+
- **Format Adapters (`src/formats/`)**: Isolated adapters for `json`, comment-preserving `jsonc` (via `jsonc-parser`), `yaml`, and `toml`.
|
|
735
|
+
- **Server Config Dialects (`src/transforms/`)**: Declarative dialect transformations mapping standard `McpServerConfig` records into native agent schema variations.
|
|
296
736
|
|
|
297
737
|
---
|
|
298
738
|
|
|
299
|
-
##
|
|
739
|
+
## Quality Gates & Verification
|
|
300
740
|
|
|
301
741
|
Every change must pass all three gates:
|
|
302
742
|
|