@wuyax/mcps 0.1.0-beta.1 → 0.1.0-beta.2
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 +339 -115
- package/dist/{chunk-XW2KL6W3.js → chunk-7V5XL4RI.js} +728 -144
- package/dist/cli.cjs +735 -179
- package/dist/cli.js +5 -17
- package/dist/index.cjs +743 -145
- package/dist/index.d.cts +78 -2
- package/dist/index.d.ts +78 -2
- package/dist/index.js +25 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,25 +1,26 @@
|
|
|
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
|
-
- **Cross-Agent Synchronization**: Inspect installed MCP servers and clone configurations
|
|
16
|
-
- **Dual Mode (Interactive TTY +
|
|
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
|
+
- **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.
|
|
16
|
+
- **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.
|
|
17
|
+
- **Pluggable Architecture**: Decoupled deep modules including `AgentConfigStore` (supporting filesystem and in-memory test adapters), `resolveTargetAgents` (capability and transport filtering), and declarative transform dialects.
|
|
17
18
|
|
|
18
19
|
---
|
|
19
20
|
|
|
20
21
|
## Installation
|
|
21
22
|
|
|
22
|
-
Run directly
|
|
23
|
+
Run directly using `npx`:
|
|
23
24
|
|
|
24
25
|
```bash
|
|
25
26
|
npx @wuyax/mcps
|
|
@@ -37,24 +38,22 @@ pnpm add -g @wuyax/mcps
|
|
|
37
38
|
|
|
38
39
|
## Quick Start
|
|
39
40
|
|
|
40
|
-
|
|
41
|
+
Execute directly via `npx @wuyax/mcps [command]` or `mcps [command]` when installed globally.
|
|
41
42
|
|
|
42
|
-
### Interactive Wizard (Default)
|
|
43
|
+
### 1. Interactive Terminal Wizard (Default)
|
|
43
44
|
|
|
44
|
-
|
|
45
|
+
Running `mcps` without arguments in an interactive terminal launches the main menu wizard:
|
|
45
46
|
|
|
46
47
|
```bash
|
|
47
|
-
npx @wuyax/mcps
|
|
48
|
-
# or if installed globally:
|
|
49
48
|
mcps
|
|
50
49
|
```
|
|
51
50
|
|
|
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.
|
|
51
|
+
The interactive menu provides three workflows:
|
|
52
|
+
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.
|
|
53
|
+
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.
|
|
54
|
+
3. **Remove MCP Server**: Select and remove MCP servers from target agent configs with safety confirmations.
|
|
56
55
|
|
|
57
|
-
### Non-Interactive CLI
|
|
56
|
+
### 2. Non-Interactive CLI Automation
|
|
58
57
|
|
|
59
58
|
Install an npm MCP server into auto-detected project agents:
|
|
60
59
|
|
|
@@ -62,84 +61,124 @@ Install an npm MCP server into auto-detected project agents:
|
|
|
62
61
|
mcps add @modelcontextprotocol/server-filesystem
|
|
63
62
|
```
|
|
64
63
|
|
|
65
|
-
Install a remote SSE server
|
|
64
|
+
Install a remote SSE server into specific agents with an authorization header:
|
|
66
65
|
|
|
67
66
|
```bash
|
|
68
67
|
mcps add https://mcp.example.com/sse --transport sse --header "Authorization: Bearer token123" -a cursor vscode
|
|
69
68
|
```
|
|
70
69
|
|
|
71
|
-
List installed servers in the current project:
|
|
70
|
+
List installed MCP servers in the current project:
|
|
72
71
|
|
|
73
72
|
```bash
|
|
74
73
|
mcps list
|
|
75
74
|
```
|
|
76
75
|
|
|
77
|
-
Remove
|
|
76
|
+
Remove an MCP server from all agents globally without prompting:
|
|
78
77
|
|
|
79
78
|
```bash
|
|
80
|
-
mcps remove server-filesystem -g
|
|
79
|
+
mcps remove server-filesystem -g -a '*' -y
|
|
81
80
|
```
|
|
82
81
|
|
|
83
82
|
---
|
|
84
83
|
|
|
85
|
-
##
|
|
86
|
-
|
|
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
|
-
|
|
84
|
+
## Interactive Wizards
|
|
85
|
+
|
|
86
|
+
When running in an interactive terminal (TTY), `mcps` provides interactive wizards built with `@inquirer/prompts`.
|
|
87
|
+
|
|
88
|
+
### Main Menu (`mcps`)
|
|
89
|
+
|
|
90
|
+
When launched with no arguments, the main menu offers:
|
|
91
|
+
- **Add MCP Server**: Launches `wizardAdd`.
|
|
92
|
+
- **Manage & Sync Installed MCP Servers**: Launches `wizardManage`.
|
|
93
|
+
- **Remove MCP Server**: Launches `wizardRemove`.
|
|
94
|
+
- **Exit**: Cleanly exits the wizard.
|
|
95
|
+
|
|
96
|
+
### Add Wizard (`mcps add` without source)
|
|
97
|
+
|
|
98
|
+
1. **Source Type Selection**:
|
|
99
|
+
- `npm package (run via npx)`: Enter package identifier (e.g. `@modelcontextprotocol/server-postgres`).
|
|
100
|
+
- `Remote MCP server (via HTTP / SSE URL)`: Enter HTTP/HTTPS URL (e.g. `https://mcp.example.com/sse`).
|
|
101
|
+
- `Local command / script / Docker (stdio)`: Enter command string (e.g. `python -m my_mcp_server`).
|
|
102
|
+
2. **Server Name**: Automatically inferred from the source with an editable default.
|
|
103
|
+
3. **Transport & Protocol** (for remote servers): Select between `HTTP` and `SSE (Server-Sent Events)`. Defaults to `sse` if URL contains `/sse`.
|
|
104
|
+
4. **Scope & Agent Selection**:
|
|
105
|
+
- Choose between **Project** (`.`) and **Global** (user home directory).
|
|
106
|
+
- Scans filesystem to auto-detect installed agents in the chosen scope.
|
|
107
|
+
- Presents a checkbox list where detected agents are labeled with `[detected]` and pre-selected by default.
|
|
108
|
+
5. **Arguments**: Configure optional CLI arguments (quote-aware parsing for paths with spaces).
|
|
109
|
+
6. **Environment Variables & Secrets**:
|
|
110
|
+
- `Skip / None`: Proceed without environment variables.
|
|
111
|
+
- `Paste multiline .env text into terminal`: Supports `KEY=VALUE`, `export KEY=VALUE`, comments (`#`), and quoted values.
|
|
112
|
+
- `Open in system default editor ($EDITOR)`: Opens temporary `.env` file in user's configured editor.
|
|
113
|
+
- `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.
|
|
114
|
+
7. **HTTP Headers** (for remote servers):
|
|
115
|
+
- Supports multiline terminal pasting (`Key: Value` or `Key=Value`), `$EDITOR` entry, or step-by-step entry with secret masking for authorization tokens.
|
|
116
|
+
8. **Configuration Preview & Confirmation**: Displays normalized parameters before writing to disk.
|
|
117
|
+
|
|
118
|
+
### Manage & Sync Wizard (`mcps` -> Manage)
|
|
119
|
+
|
|
120
|
+
1. Prompts for scope (**Project** or **Global**).
|
|
121
|
+
2. Lists all configured MCP servers grouped by server name along with the agents that currently configure them.
|
|
122
|
+
3. Inspects selected server details: transport type, URL or command, arguments, environment variables, and headers (with secret masking).
|
|
123
|
+
4. Allows triggering **Edit server configuration**:
|
|
124
|
+
- **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.
|
|
125
|
+
- **Command Arguments (`args`)**: Edit arguments in-place with existing arguments pre-filled.
|
|
126
|
+
- **Command (`command`)**: Update executable name or binary path.
|
|
127
|
+
- **Remote Endpoints (`url`, `type`, `headers`)**: Modify remote URLs, toggle HTTP/SSE transport, and manage HTTP headers.
|
|
128
|
+
- Saves and persists updated configurations to target agent files using native formats and schema dialects.
|
|
129
|
+
5. Allows triggering **Sync / clone to other agents**:
|
|
130
|
+
- Identifies candidate agents that do not currently have the server configured.
|
|
131
|
+
- Filters candidate agents by scope and transport capability.
|
|
132
|
+
- Writes the server configuration to selected targets using their respective native config formats and schema dialects.
|
|
133
|
+
|
|
134
|
+
### Remove Wizard (`mcps remove` without name)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
1. Prompts for scope (**Project** or **Global**).
|
|
138
|
+
2. Lists configured servers for selection.
|
|
139
|
+
3. Removes the selected server from target agent configuration files with safety confirmation.
|
|
112
140
|
|
|
113
141
|
---
|
|
114
142
|
|
|
115
|
-
## CLI Reference
|
|
143
|
+
## CLI Command Reference
|
|
144
|
+
|
|
145
|
+
### Exit Codes & Completion Criteria
|
|
116
146
|
|
|
117
|
-
|
|
147
|
+
- `0`: Operation completed successfully. Target configuration files were modified or queried as requested.
|
|
148
|
+
- `1`: Operation failed. Caused by missing required arguments in non-TTY mode, unresolvable or incompatible agents, invalid source syntax, or file system permission errors.
|
|
118
149
|
|
|
119
|
-
|
|
120
|
-
- `-h, --help`: Display command-line help.
|
|
150
|
+
---
|
|
121
151
|
|
|
122
152
|
### `mcps add [source]`
|
|
123
153
|
|
|
124
|
-
|
|
154
|
+
Installs an MCP server into one or more agent configuration files.
|
|
125
155
|
|
|
126
156
|
```bash
|
|
127
157
|
mcps add [source] [options]
|
|
128
158
|
```
|
|
129
159
|
|
|
130
160
|
#### Arguments
|
|
131
|
-
|
|
161
|
+
|
|
162
|
+
- `[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
163
|
|
|
133
164
|
#### Options
|
|
134
|
-
|
|
135
|
-
-
|
|
136
|
-
-
|
|
137
|
-
- `-
|
|
138
|
-
-
|
|
139
|
-
- `--
|
|
165
|
+
|
|
166
|
+
- `-a, --agent <agents...>`: Target specific agents by identifier or alias (e.g. `-a cursor vscode`). Pass `'*'` to target all agents.
|
|
167
|
+
- `--all`: Target all supported agents that support the chosen scope.
|
|
168
|
+
- `-g, --global`: Install to user-level global configuration instead of current project directory.
|
|
169
|
+
- `-t, --transport <type>`: Explicit transport type for remote servers (`http` or `sse`). Defaults to `sse` if URL contains `/sse`, otherwise `http`.
|
|
170
|
+
- `--header <header...>`: HTTP header formatted as `Key: Value`. Repeatable.
|
|
171
|
+
- `--env <env...>`: Environment variable formatted as `KEY=VALUE`. Repeatable.
|
|
140
172
|
- `--args <args...>`: Additional command-line arguments for stdio/package servers.
|
|
141
173
|
- `-n, --name <name>`: Explicit override for server name.
|
|
142
|
-
- `-y, --yes`: Non-interactive mode
|
|
174
|
+
- `-y, --yes`: Non-interactive mode; skips confirmation prompts.
|
|
175
|
+
|
|
176
|
+
#### Target Resolution & Auto-Detection
|
|
177
|
+
|
|
178
|
+
When neither `-a` nor `--all` is specified:
|
|
179
|
+
1. `mcps` scans the project root or global home directories for installed agents.
|
|
180
|
+
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).
|
|
181
|
+
3. If no agents are detected, logs a diagnostic warning and exits with code `1`.
|
|
143
182
|
|
|
144
183
|
#### Examples
|
|
145
184
|
|
|
@@ -147,21 +186,29 @@ mcps add [source] [options]
|
|
|
147
186
|
# Auto-detect project agents and install npm package
|
|
148
187
|
mcps add @modelcontextprotocol/server-postgres
|
|
149
188
|
|
|
150
|
-
# Install with
|
|
189
|
+
# Install npm package with environment variables and custom arguments to specific agents
|
|
151
190
|
mcps add @modelcontextprotocol/server-github \
|
|
152
|
-
--env "GITHUB_PERSONAL_ACCESS_TOKEN=
|
|
191
|
+
--env "GITHUB_PERSONAL_ACCESS_TOKEN=ghp_secret" \
|
|
153
192
|
-a cursor claude-code
|
|
154
193
|
|
|
155
|
-
# Install custom python command with name
|
|
194
|
+
# Install custom python command with explicit name
|
|
156
195
|
mcps add "python -m my_mcp_server" -n custom-server -a vscode
|
|
157
196
|
|
|
158
|
-
# Install
|
|
159
|
-
mcps add
|
|
197
|
+
# Install Docker container stdio command
|
|
198
|
+
mcps add "docker run -i --rm mcp/fetch" -n fetch -a cursor
|
|
199
|
+
|
|
200
|
+
# Install remote SSE server globally with authorization header
|
|
201
|
+
mcps add https://mcp.internal.net/sse \
|
|
160
202
|
-t sse \
|
|
161
|
-
--header "Authorization: Bearer
|
|
162
|
-
-g -a cursor
|
|
203
|
+
--header "Authorization: Bearer token_xyz" \
|
|
204
|
+
-g -a cursor vscode
|
|
205
|
+
|
|
206
|
+
# Install to all supported global agents non-interactively
|
|
207
|
+
mcps add @modelcontextprotocol/server-memory -g --all -y
|
|
163
208
|
```
|
|
164
209
|
|
|
210
|
+
---
|
|
211
|
+
|
|
165
212
|
### `mcps list` (alias: `mcps ls`)
|
|
166
213
|
|
|
167
214
|
Lists installed MCP servers across agents.
|
|
@@ -172,23 +219,26 @@ mcps ls [options]
|
|
|
172
219
|
```
|
|
173
220
|
|
|
174
221
|
#### Options
|
|
175
|
-
|
|
222
|
+
|
|
223
|
+
- `-g, --global`: Query global user-level configurations instead of current project directory.
|
|
176
224
|
- `-a, --agent <agents...>`: Filter listing by specific agent identifiers or aliases.
|
|
177
225
|
- `--json`: Output server configurations as structured JSON.
|
|
178
226
|
|
|
179
227
|
#### Examples
|
|
180
228
|
|
|
181
229
|
```bash
|
|
182
|
-
# List
|
|
230
|
+
# List servers configured in the current project
|
|
183
231
|
mcps list
|
|
184
232
|
|
|
185
|
-
# List
|
|
186
|
-
mcps list -g
|
|
233
|
+
# List servers configured globally across Cursor and VS Code
|
|
234
|
+
mcps list -g -a cursor vscode
|
|
187
235
|
|
|
188
|
-
#
|
|
189
|
-
mcps list
|
|
236
|
+
# Output all project-configured servers in JSON format
|
|
237
|
+
mcps list --json
|
|
190
238
|
```
|
|
191
239
|
|
|
240
|
+
---
|
|
241
|
+
|
|
192
242
|
### `mcps remove [name]` (alias: `mcps rm`)
|
|
193
243
|
|
|
194
244
|
Removes an MCP server from agent configuration files.
|
|
@@ -199,43 +249,151 @@ mcps rm [name] [options]
|
|
|
199
249
|
```
|
|
200
250
|
|
|
201
251
|
#### Arguments
|
|
202
|
-
|
|
252
|
+
|
|
253
|
+
- `[name]`: Name of the MCP server to remove. If omitted in TTY mode, starts the interactive Remove Wizard.
|
|
203
254
|
|
|
204
255
|
#### Options
|
|
256
|
+
|
|
205
257
|
- `-g, --global`: Remove from global user-level configurations.
|
|
206
|
-
- `-a, --agent <agents...>`: Filter removal to specific agents. Pass `'*'`
|
|
207
|
-
- `-y, --yes`: Skip confirmation
|
|
258
|
+
- `-a, --agent <agents...>`: Filter removal to specific agents. Pass `'*'` to target all agents.
|
|
259
|
+
- `-y, --yes`: Skip confirmation prompts.
|
|
208
260
|
|
|
209
261
|
#### Examples
|
|
210
262
|
|
|
211
263
|
```bash
|
|
212
|
-
# Remove from all configured project
|
|
264
|
+
# Remove server from all configured agents in current project
|
|
213
265
|
mcps remove postgres
|
|
214
266
|
|
|
215
|
-
# Remove from Cursor
|
|
267
|
+
# Remove server from Cursor global config without prompting
|
|
216
268
|
mcps remove github -a cursor -g -y
|
|
269
|
+
|
|
270
|
+
# Remove server from all agents globally
|
|
271
|
+
mcps remove memory -g -a '*' -y
|
|
217
272
|
```
|
|
218
273
|
|
|
219
274
|
---
|
|
220
275
|
|
|
221
276
|
## Source Parsing Mechanics
|
|
222
277
|
|
|
223
|
-
When a source string is provided to `mcps add`, `mcps`
|
|
278
|
+
When a source string is provided to `mcps add`, `mcps` parses and normalizes it into a `ParsedMcpSource`:
|
|
279
|
+
|
|
280
|
+
### 1. Remote URLs (`type: "remote"`)
|
|
281
|
+
|
|
282
|
+
- Identified when string matches `^https?:\/\/` pattern.
|
|
283
|
+
- **Transport Inference**: Defaults to `sse` if the URL pathname contains `/sse`, otherwise `http`.
|
|
284
|
+
- **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`.
|
|
285
|
+
|
|
286
|
+
### 2. npm Packages (`type: "package"`)
|
|
287
|
+
|
|
288
|
+
- Matches npm package naming conventions (e.g. `@scope/name`, `package-name`).
|
|
289
|
+
- Normalized to `command: "npx"`, `args: ["-y", "<package>"]`.
|
|
290
|
+
- **Name Inference**:
|
|
291
|
+
- Strips version tags (e.g. `@1.0.0`).
|
|
292
|
+
- Strips npm scope prefixes (e.g. `@modelcontextprotocol/`).
|
|
293
|
+
- Strips path prefixes and script extensions (`.js`, `.mjs`, `.cjs`, `.ts`, `.py`).
|
|
294
|
+
- Strips common package prefixes (`mcp-server-`, `mcp-`, `server-`) and suffixes (`-mcp-server`, `-server`, `-mcp`).
|
|
295
|
+
- Example: `@modelcontextprotocol/server-postgres` -> `postgres`.
|
|
296
|
+
|
|
297
|
+
### 3. Shell Commands (`type: "command"`)
|
|
298
|
+
|
|
299
|
+
- Identified when string contains whitespace or known runner prefixes (`python`, `python3`, `node`, `uvx`, `docker`).
|
|
300
|
+
- Tokenizes binary and arguments.
|
|
301
|
+
- **Name Inference**: Inspects tokens following the runner binary, ignoring flags, and extracts the target script or package name.
|
|
302
|
+
- Example: `python -m my_mcp_server` -> `my_mcp_server`.
|
|
303
|
+
- Example: `uvx mcp-server-sqlite` -> `sqlite`.
|
|
304
|
+
- Example: `docker run -i --rm mcp/fetch` -> `fetch`.
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
308
|
+
## Supported Agents Matrix
|
|
309
|
+
|
|
310
|
+
`mcps` supports 23 AI coding agents and tools:
|
|
311
|
+
|
|
312
|
+
| Agent | Identifier | Aliases | Scopes | Transports | Format | Config Path (Project / Global) |
|
|
313
|
+
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
|
|
314
|
+
| **Amp** | `amp` | `amp-cli`, `amp-code`, `ampcode` | Project, Global | stdio, http, sse | `jsonc` | `.amp/settings.json` / `~/.config/amp/settings.jsonc` |
|
|
315
|
+
| **Antigravity** | `antigravity` | - | Project, Global | stdio, http, sse | `jsonc` | `.agents/mcp_config.json` / `~/.gemini/config/mcp_config.json` |
|
|
316
|
+
| **Antigravity CLI** | `antigravity-cli` | `agy` | Project, Global | stdio, http, sse | `jsonc` | `.agents/mcp_config.json` / `~/.gemini/config/mcp_config.json` |
|
|
317
|
+
| **Augment** | `augment` | `auggie`, `augment-code`, `augmentcode` | Project, Global | stdio, http, sse | `jsonc` | `.augment/settings.json` / `~/.augment/settings.jsonc` |
|
|
318
|
+
| **Claude Code** | `claude-code` | - | Project, Global | stdio, http, sse | `jsonc` | `.mcp.json` / `~/.claude.json` |
|
|
319
|
+
| **Claude Desktop** | `claude-desktop` | - | Global | stdio | `jsonc` | User Application Support / Roaming `claude_desktop_config.json` |
|
|
320
|
+
| **Cline (VS Code)** | `cline` | `cline-vscode` | Project, Global | stdio, http, sse | `jsonc` | `.cline/mcp.json` / VS Code global storage `cline_mcp_settings.json` |
|
|
321
|
+
| **Cline CLI** | `cline-cli` | - | Project, Global | stdio, http, sse | `jsonc` | `.cline/mcp.json` / `~/.cline/mcp.json` |
|
|
322
|
+
| **Codex** | `codex` | - | Project, Global | stdio, http, sse | `toml` | `.codex/config.toml` / `~/.codex/config.toml` |
|
|
323
|
+
| **Cursor** | `cursor` | - | Project, Global | stdio, http, sse | `jsonc` | `.cursor/mcp.json` / `~/.cursor/mcp.json` |
|
|
324
|
+
| **Gemini CLI** | `gemini-cli` | `gemini` | Project, Global | stdio, http, sse | `jsonc` | `.gemini/settings.json` / `~/.gemini/settings.json` |
|
|
325
|
+
| **GitHub Copilot CLI** | `github-copilot-cli` | - | Project, Global | stdio, http, sse | `jsonc` | `.mcp.json` / `~/.copilot/mcp-config.json` |
|
|
326
|
+
| **Goose** | `goose` | - | Project, Global | stdio, http, sse | `yaml` | `.goose/config.yaml` / `~/.config/goose/config.yaml` |
|
|
327
|
+
| **Grok** | `grok` | `grok-cli`, `xai`, `xai-grok` | Project, Global | stdio, http, sse | `toml` | `.grok/config.toml` / `~/.grok/config.toml` |
|
|
328
|
+
| **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` |
|
|
329
|
+
| **Kiro** | `kiro` | `kiro-cli`, `kiro-ide` | Project, Global | stdio, http, sse | `jsonc` | `.kiro/settings/mcp.json` / `~/.kiro/settings/mcp.json` |
|
|
330
|
+
| **OpenCode** | `opencode` | - | Project, Global | stdio, http, sse | `jsonc` | `opencode.json` / `~/.config/opencode/opencode.json` |
|
|
331
|
+
| **Pi** | `pi` | `pi-agent` | Project, Global | stdio, http, sse | `jsonc` | `.pi/mcp.json` / `~/.pi/agent/mcp.json` |
|
|
332
|
+
| **Qoder** | `qoder` | `qoder-cli` | Project, Global | stdio, http, sse | `jsonc` | `.mcp.json` / `~/.qoder/settings.json` |
|
|
333
|
+
| **Qwen Code** | `qwen-code` | `qwen`, `qwen-cli`, `qwencode` | Project, Global | stdio, http, sse | `jsonc` | `.qwen/settings.json` / `~/.qwen/settings.json` |
|
|
334
|
+
| **Trae** | `trae` | `trae-code`, `traecode`, `trae-ide` | Project, Global | stdio, http, sse | `jsonc` | `.trae/mcp.json` / `~/.trae/mcp.json` |
|
|
335
|
+
| **VS Code** | `vscode` | `github-copilot` | Project, Global | stdio, http, sse | `jsonc` | `.vscode/mcp.json` / User `mcp.json` |
|
|
336
|
+
| **Zed** | `zed` | - | Project, Global | stdio, http, sse | `jsonc` | `.zed/settings.json` / `~/.config/zed/settings.json` |
|
|
337
|
+
|
|
338
|
+
### Environment Variable Overrides
|
|
339
|
+
|
|
340
|
+
For headless environments, Docker containers, and non-standard filesystem layouts, `mcps` respects environment variables for agent directories:
|
|
224
341
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
342
|
+
| Environment Variable | Target Agent | Description |
|
|
343
|
+
| :--- | :--- | :--- |
|
|
344
|
+
| `AMP_HOME` | Amp | Overrides global config directory (defaults to `~/.config/amp` or `~/.amp`). |
|
|
345
|
+
| `AUGMENT_HOME` | Augment | Overrides global config directory (defaults to `~/.augment`). |
|
|
346
|
+
| `CLINE_DIR` | Cline CLI | Overrides global directory (defaults to `~/.cline`). |
|
|
347
|
+
| `CODEX_HOME` | Codex | Overrides global directory (defaults to `~/.codex`). |
|
|
348
|
+
| `COPILOT_HOME` | GitHub Copilot CLI | Overrides global directory (defaults to `~/.copilot`). |
|
|
349
|
+
| `GROK_HOME` | Grok | Overrides global directory (defaults to `~/.grok`). |
|
|
350
|
+
| `KIMI_CODE_HOME` | Kimi Code CLI | Overrides global directory (defaults to `~/.kimi-code`). |
|
|
351
|
+
| `KIRO_HOME` | Kiro | Overrides global directory (defaults to `~/.kiro`). |
|
|
352
|
+
| `QODER_HOME` | Qoder | Overrides global directory (defaults to `~/.qoder`). |
|
|
353
|
+
| `QWEN_CODE_HOME` / `QWEN_HOME` | Qwen Code | Overrides global directory (defaults to `~/.qwen`). |
|
|
354
|
+
| `XDG_CONFIG_HOME` | Linux/macOS defaults | Sets standard XDG base directory for tools adhering to XDG (`amp`, `opencode`, `goose`, `zed`). |
|
|
233
355
|
|
|
234
356
|
---
|
|
235
357
|
|
|
236
|
-
##
|
|
358
|
+
## Server Config Dialects
|
|
359
|
+
|
|
360
|
+
Agent configurations diverge significantly in syntax and structure. `mcps` maps the normalized domain model (`McpServerConfig`) into each agent's native dialect via declarative presets:
|
|
361
|
+
|
|
362
|
+
- **VS Code (`vscode`, `github-copilot-cli`)**:
|
|
363
|
+
- Root key: `servers`.
|
|
364
|
+
- stdio transport: `type: "stdio"`, `command`, `args`.
|
|
365
|
+
- remote transport: `type: "http" | "sse"`, `url`, `headers`.
|
|
366
|
+
- **Goose (`goose`)**:
|
|
367
|
+
- Root key: `extensions`.
|
|
368
|
+
- stdio transport: `cmd` (instead of `command`), `args`, `envs` (instead of `env`), `type: "stdio"`, `timeout: 30`, `description: ""`, `enabled: true`.
|
|
369
|
+
- remote transport: `uri` (instead of `url`), `type: "streamable_http" | "sse"`, `headers`, `timeout: 30`, `description: ""`, `enabled: true`.
|
|
370
|
+
- **OpenCode (`opencode`)**:
|
|
371
|
+
- Root key: `mcp`.
|
|
372
|
+
- stdio transport: `command: [command, ...args]` (array format), `environment` (instead of `env`), `type: "local"`, `enabled: true`.
|
|
373
|
+
- remote transport: `type: "remote"`, `url`, `headers`, `enabled: true`.
|
|
374
|
+
- **Pi (`pi`)**:
|
|
375
|
+
- stdio transport: `transport: "stdio"`.
|
|
376
|
+
- remote transport: `transport: "streamable-http" | "sse"`.
|
|
377
|
+
- **Qwen Code (`qwen-code`)**:
|
|
378
|
+
- remote transport: Uses `url` for SSE and `httpUrl` for standard HTTP.
|
|
379
|
+
- **Cline (`cline`, `cline-cli`)**:
|
|
380
|
+
- remote transport: `type: "sse" | "streamableHttp"`.
|
|
381
|
+
- **Grok & Trae (`grok`, `trae`)**:
|
|
382
|
+
- remote transport: Sets `type: "sse"` only when SSE transport is active.
|
|
383
|
+
- **Zed (`zed`)**:
|
|
384
|
+
- Root key: `context_servers`.
|
|
385
|
+
- **Codex (`codex`)**:
|
|
386
|
+
- Format: TOML under `[mcp_servers.<name>]`.
|
|
387
|
+
- **Claude Desktop (`claude-desktop`)**:
|
|
388
|
+
- Enforces stdio-only transport. Remote URLs trigger diagnostic warnings and are prevented from persisting.
|
|
389
|
+
|
|
390
|
+
---
|
|
237
391
|
|
|
238
|
-
|
|
392
|
+
## Programmatic Node / TypeScript API
|
|
393
|
+
|
|
394
|
+
`mcps` exports a strongly-typed API for ESM and CommonJS.
|
|
395
|
+
|
|
396
|
+
### Installation & Removal
|
|
239
397
|
|
|
240
398
|
```typescript
|
|
241
399
|
import {
|
|
@@ -244,59 +402,125 @@ import {
|
|
|
244
402
|
removeMcpServer,
|
|
245
403
|
parseMcpSource,
|
|
246
404
|
resolveTargetAgents,
|
|
247
|
-
|
|
248
|
-
getMcpAgentConfig,
|
|
249
|
-
} from "mcps";
|
|
405
|
+
} from "@wuyax/mcps";
|
|
250
406
|
|
|
251
407
|
// 1. Install an MCP server
|
|
252
408
|
const installResult = installMcpServer({
|
|
253
409
|
source: "@modelcontextprotocol/server-postgres",
|
|
254
|
-
agents: ["cursor", "vscode", "
|
|
410
|
+
agents: ["cursor", "vscode", "goose"],
|
|
255
411
|
env: {
|
|
256
|
-
POSTGRES_CONNECTION_STRING: "postgresql://localhost/db",
|
|
412
|
+
POSTGRES_CONNECTION_STRING: "postgresql://localhost:5432/db",
|
|
257
413
|
},
|
|
414
|
+
args: ["--read-only"],
|
|
258
415
|
global: false,
|
|
259
416
|
});
|
|
260
417
|
|
|
261
418
|
console.log(`Configured ${installResult.serverName}:`);
|
|
262
|
-
for (const
|
|
263
|
-
|
|
419
|
+
for (const record of installResult.results) {
|
|
420
|
+
if (record.success) {
|
|
421
|
+
console.log(` ${record.agent}: OK -> ${record.path}`);
|
|
422
|
+
} else {
|
|
423
|
+
console.error(` ${record.agent}: Error -> ${record.error}`);
|
|
424
|
+
}
|
|
264
425
|
}
|
|
265
426
|
|
|
266
|
-
// 2. List installed servers
|
|
267
|
-
const
|
|
427
|
+
// 2. List installed MCP servers
|
|
428
|
+
const servers = listInstalledMcpServers({
|
|
268
429
|
global: false,
|
|
269
|
-
agents: ["cursor"],
|
|
430
|
+
agents: ["cursor", "vscode"],
|
|
270
431
|
});
|
|
271
432
|
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
433
|
+
for (const s of servers) {
|
|
434
|
+
console.log(`${s.serverName} on ${s.agent} (${s.path})`);
|
|
435
|
+
}
|
|
275
436
|
|
|
276
|
-
//
|
|
437
|
+
// 3. Remove an MCP server
|
|
277
438
|
const removeResults = removeMcpServer({
|
|
278
439
|
name: "postgres",
|
|
279
|
-
agents: ["cursor"],
|
|
440
|
+
agents: ["cursor", "vscode"],
|
|
280
441
|
global: false,
|
|
281
442
|
});
|
|
282
443
|
```
|
|
283
444
|
|
|
445
|
+
### Parsing Sources & Resolving Agents
|
|
446
|
+
|
|
447
|
+
```typescript
|
|
448
|
+
import { parseMcpSource, resolveTargetAgents } from "@wuyax/mcps";
|
|
449
|
+
|
|
450
|
+
// Parse any source string
|
|
451
|
+
const parsed = parseMcpSource("https://api.github.com/mcp/sse");
|
|
452
|
+
// { type: "remote", value: "https://api.github.com/mcp/sse", inferredName: "github" }
|
|
453
|
+
|
|
454
|
+
// Resolve target agents with capability checks
|
|
455
|
+
const targets = resolveTargetAgents({
|
|
456
|
+
requested: ["cursor", "claude-desktop"],
|
|
457
|
+
transport: "sse",
|
|
458
|
+
global: true,
|
|
459
|
+
});
|
|
460
|
+
|
|
461
|
+
console.log("Compatible:", targets.compatibleAgents); // ['cursor']
|
|
462
|
+
console.log("Incompatible:", targets.incompatible);
|
|
463
|
+
// [{ agent: 'claude-desktop', reason: 'Claude Desktop currently supports only stdio MCP servers...' }]
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
### Pluggable AgentConfigStore
|
|
467
|
+
|
|
468
|
+
`AgentConfigStore` decouples file persistence, allowing in-memory testing:
|
|
469
|
+
|
|
470
|
+
```typescript
|
|
471
|
+
import {
|
|
472
|
+
AgentConfigStore,
|
|
473
|
+
MemoryConfigStoreAdapter,
|
|
474
|
+
agentConfigStore, // Default singleton using FsConfigStoreAdapter
|
|
475
|
+
} from "@wuyax/mcps";
|
|
476
|
+
|
|
477
|
+
// Use memory adapter for isolated testing
|
|
478
|
+
const memoryStore = new AgentConfigStore(new MemoryConfigStoreAdapter());
|
|
479
|
+
|
|
480
|
+
memoryStore.writeServer("cursor", "test-server", {
|
|
481
|
+
command: "npx",
|
|
482
|
+
args: ["-y", "test-mcp"],
|
|
483
|
+
});
|
|
484
|
+
|
|
485
|
+
const server = memoryStore.readServer("cursor", "test-server");
|
|
486
|
+
console.log(server);
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
### Exported Interactive Utilities
|
|
490
|
+
|
|
491
|
+
The interactive wizard flows and prompt components are also exported for programmatic embedding:
|
|
492
|
+
|
|
493
|
+
```typescript
|
|
494
|
+
import {
|
|
495
|
+
mainMenu,
|
|
496
|
+
wizardAdd,
|
|
497
|
+
wizardManage,
|
|
498
|
+
wizardRemove,
|
|
499
|
+
promptScopeAndAgents,
|
|
500
|
+
promptEnvConfig,
|
|
501
|
+
promptHeadersConfig,
|
|
502
|
+
promptArgsConfig,
|
|
503
|
+
parseEnvText,
|
|
504
|
+
parseHeadersText,
|
|
505
|
+
} from "@wuyax/mcps";
|
|
506
|
+
```
|
|
507
|
+
|
|
284
508
|
---
|
|
285
509
|
|
|
286
510
|
## Architecture & Seams
|
|
287
511
|
|
|
288
|
-
`mcps` is
|
|
512
|
+
`mcps` is organized around decoupled deep modules:
|
|
289
513
|
|
|
290
|
-
- **CLI Commands (`src/cli/`)**: Built
|
|
291
|
-
- **Interactive Wizards (`src/interactive/`)**: Terminal
|
|
292
|
-
- **Target Agent Resolver (`src/resolve-target-agents.ts`)**: Resolves target agents
|
|
293
|
-
- **Agent Config Store (`src/config-store.ts`)**: Unified persistence engine
|
|
294
|
-
- **Format Adapters (`src/formats/`)**: Isolated adapters for `json`, `jsonc` (
|
|
295
|
-
- **Server Config Dialects (`src/transforms/`)**: Declarative transformations
|
|
514
|
+
- **CLI Commands (`src/cli/`)**: Built with `commander`. Provides non-interactive execution with full flags and TTY wizard fallbacks.
|
|
515
|
+
- **Interactive Wizards (`src/interactive/`)**: Terminal UI built with `@inquirer/prompts`. Handles scope selection, credential masking, multiline terminal and `$EDITOR` input, and cross-agent synchronization.
|
|
516
|
+
- **Target Agent Resolver (`src/resolve-target-agents.ts`)**: Resolves target agents from CLI arguments, wildcards, auto-detection, and transport capability constraints.
|
|
517
|
+
- **Agent Config Store (`src/config-store.ts`)**: Unified persistence engine behind a pluggable storage seam (`ConfigStoreAdapter`), handling path resolution, existence checks, and file serialization.
|
|
518
|
+
- **Format Adapters (`src/formats/`)**: Isolated adapters for `json`, comment-preserving `jsonc` (via `jsonc-parser`), `yaml`, and `toml`.
|
|
519
|
+
- **Server Config Dialects (`src/transforms/`)**: Declarative dialect transformations mapping standard `McpServerConfig` records into native agent schema variations.
|
|
296
520
|
|
|
297
521
|
---
|
|
298
522
|
|
|
299
|
-
##
|
|
523
|
+
## Quality Gates & Verification
|
|
300
524
|
|
|
301
525
|
Every change must pass all three gates:
|
|
302
526
|
|