mcpick 0.0.20 → 0.0.21

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.
Files changed (4) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +127 -306
  3. package/dist/index.js +19 -19
  4. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # mcpick
2
2
 
3
+ ## 0.0.21
4
+
5
+ ### Patch Changes
6
+
7
+ - 47e40be: chore: reorder TUI menu and update README for agent-first usage
8
+
3
9
  ## 0.0.20
4
10
 
5
11
  ### Patch Changes
package/README.md CHANGED
@@ -1,366 +1,187 @@
1
1
  # McPick
2
2
 
3
- A CLI tool for managing MCP servers, plugins, and plugin caches in
4
- Claude Code. Toggle servers and plugins on/off, manage stale plugin
5
- caches, and optimise context usage and performance.
3
+ [![built with vite+](https://img.shields.io/badge/built%20with-Vite+-646CFF?logo=vite&logoColor=white)](https://viteplus.dev)
4
+ [![tested with vitest](https://img.shields.io/badge/tested%20with-Vitest-6E9F18?logo=vitest&logoColor=white)](https://vitest.dev)
6
5
 
7
- ## Installation
6
+ Claude Code extension manager — MCP servers, plugins (skills, hooks,
7
+ agents), and marketplaces.
8
8
 
9
- ### One-time Usage (recommended)
9
+ ## Quick Start
10
10
 
11
- ```bash
12
- pnpx mcpick
13
- # or
14
- pnpm dlx mcpick
15
- # or
16
- npx mcpick
17
- ```
18
-
19
- ### Global Installation
11
+ Use mcpick inline in Claude Code sessions. Tell Claude:
20
12
 
21
- ```bash
22
- pnpm install -g mcpick
23
- # or
24
- npm install -g mcpick
25
13
  ```
26
-
27
- ## The Problem
28
-
29
- Using the Claude Code `/doctor` command you may see something like
30
- this if you have many MCP servers configured:
31
-
32
- ```bash
33
- Context Usage Warnings
34
- └ ⚠ Large MCP tools context (~66,687 tokens > 25,000)
35
- └ MCP servers:
36
- └ mcp-omnisearch-testing: 20 tools (~10,494 tokens)
37
- └ mcp-omnisearch: 20 tools (~10,454 tokens)
38
- └ mcp-sqlite-tools-testing: 19 tools (~9,910 tokens)
39
- └ mcp-sqlite-tools: 19 tools (~9,872 tokens)
40
- └ playwright: 21 tools (~9,804 tokens)
41
- └ (7 more servers)
14
+ Use npx mcpick to add the marketplace at spences10/claude-code-toolkit
42
15
  ```
43
16
 
44
- Claude Code loads **all** MCP servers from your `.claude.json` file at
45
- startup, regardless of whether you need them for your current task.
46
- This can lead to:
47
-
48
- - 🐌 Slower Claude Code startup times
49
- - 💾 High context token usage
50
- - 🧠 Cognitive overload from too many available tools
51
-
52
- ## The Solution
53
-
54
- McPick provides an intuitive CLI menu and non-interactive subcommands
55
- to:
56
-
57
- - ✅ **Toggle servers on/off** - Enable only the MCP servers you need
58
- for your current task
59
- - 🔌 **Toggle plugins on/off** - Enable or disable Claude Code
60
- marketplace plugins
61
- - 🗑️ **Manage plugin cache** - Detect stale plugins, clear caches,
62
- clean orphaned versions, refresh marketplaces
63
- - 📁 **Manage server registry** - Keep a database of all your
64
- available MCP servers
65
- - 🔄 **Safe configuration** - Only modifies the `mcpServers` section,
66
- preserving other Claude Code settings
67
- - 💾 **Backup & restore** - Create focused backups of your MCP server
68
- configurations
69
-
70
- ## Features
71
-
72
- ### Interactive Menu
17
+ ```
18
+ Use npx mcpick to list my plugins and disable the ones I'm not using
19
+ ```
73
20
 
74
- ```bash
75
- ┌ McPick - MCP Server Configuration Manager
76
- │
77
- ◆ What would you like to do?
78
- │ ● Enable / Disable MCP servers (Toggle MCP servers on/off)
79
- │ ○ Enable / Disable plugins (Toggle Claude Code plugins on/off)
80
- │ ○ Manage plugin cache (View, clear, or refresh plugin caches)
81
- │ ○ Backup config
82
- │ ○ Add MCP server
83
- │ ○ Restore from backup
84
- │ ○ Load profile
85
- │ ○ Save profile
86
- │ ○ Exit
87
- └
21
+ ```
22
+ Use npx mcpick to enable only the mcp-sqlite-tools server
88
23
  ```
89
24
 
90
- ### Scope Support
25
+ McPick auto-detects non-TTY environments and shows structured help
26
+ instead of launching the interactive TUI — so LLM agents can read
27
+ `npx mcpick --help` and figure out the rest.
91
28
 
92
- MCPick supports the three MCP server scopes used by Claude Code:
29
+ ## Concepts
93
30
 
94
- | Scope | Description | Storage Location |
95
- | ----------- | ------------------------------------ | --------------------------------------------- |
96
- | **Local** | Project-specific servers (default) | `~/.claude.json` → `projects[cwd].mcpServers` |
97
- | **Project** | Shared via `.mcp.json` in repository | `.mcp.json` in project root |
98
- | **User** | Global servers for all projects | `~/.claude.json` → `mcpServers` |
31
+ Marketplaces contain plugins. Plugins contain skills
32
+ (`/slash-commands`), hooks, agents, and MCP servers.
99
33
 
100
- When you select "Enable / Disable MCP servers", MCPick will:
34
+ ```
35
+ Marketplace → Plugin → Skills, Hooks, Agents, MCP Servers
36
+ ```
101
37
 
102
- 1. Ask which scope you want to edit
103
- 2. Show servers already enabled for that scope (pre-checked)
104
- 3. Use `claude mcp add/remove` CLI commands for Local and Project
105
- scopes
38
+ ## Common Workflows
106
39
 
107
- This integration ensures your changes are correctly applied to the
108
- right configuration location.
40
+ ### Install skills from a marketplace
109
41
 
110
- ### Smart Server Management
42
+ ```bash
43
+ # 1. Add the marketplace
44
+ npx mcpick marketplace add spences10/claude-code-toolkit
111
45
 
112
- - **Auto-discovery**: Automatically imports servers from your existing
113
- `.claude.json`
114
- - **Registry sync**: Maintains a registry of available servers for
115
- quick selection
116
- - **Selective enabling**: Choose exactly which servers to enable via
117
- multiselect
118
- - **Configuration safety**: Preserves all non-MCP settings in your
119
- Claude Code config
46
+ # 2. Install a plugin from it
47
+ npx mcpick plugins install my-plugin@claude-code-toolkit
120
48
 
121
- ### Backup System
49
+ # 3. Skills are now available as /slash-commands in Claude Code
50
+ ```
122
51
 
123
- - **Focused backups**: Only backs up MCP server configurations (not
124
- the entire 30k+ line config)
125
- - **Automatic cleanup**: Keeps last 10 backups to prevent storage
126
- bloat
127
- - **Easy restoration**: Restore from any previous backup with a simple
128
- menu
52
+ Marketplace sources can be:
129
53
 
130
- ### Profiles
54
+ - `owner/repo` — GitHub shorthand
55
+ - `https://github.com/owner/repo` — full URL
56
+ - `./local-path` — local directory
131
57
 
132
- Load predefined sets of MCP servers instantly:
58
+ ### Toggle MCP servers
133
59
 
134
60
  ```bash
135
- # Apply a profile
136
- mcpick --profile database
137
- mcpick -p database
138
-
139
- # Save current config as a profile
140
- mcpick --save-profile mysetup
141
- mcpick -s mysetup
142
-
143
- # List available profiles
144
- mcpick --list-profiles
145
- mcpick -l
61
+ npx mcpick list # List servers and status
62
+ npx mcpick enable <server> # Enable a server
63
+ npx mcpick disable <server> # Disable a server
64
+ npx mcpick add --name <n> ... # Add a new server
65
+ npx mcpick remove <server> # Remove a server
146
66
  ```
147
67
 
148
- Profiles are stored in `~/.claude/mcpick/profiles/`. You can also
149
- create them manually:
150
-
151
- ```json
152
- // ~/.claude/mcpick/profiles/database.json
153
- {
154
- "mcp-sqlite-tools": {
155
- "type": "stdio",
156
- "command": "npx",
157
- "args": ["-y", "mcp-sqlite-tools"]
158
- }
159
- }
68
+ ### Manage plugins
69
+
70
+ ```bash
71
+ npx mcpick plugins list # List plugins and status
72
+ npx mcpick plugins install <key> # Install from marketplace
73
+ npx mcpick plugins uninstall <key> # Remove plugin
74
+ npx mcpick plugins update <key> # Update to latest
75
+ npx mcpick plugins enable <key> # Enable plugin
76
+ npx mcpick plugins disable <key> # Disable plugin
160
77
  ```
161
78
 
162
- Or use full format with `mcpServers` wrapper:
79
+ ### Manage marketplaces
163
80
 
164
- ```json
165
- {
166
- "mcpServers": {
167
- "server-name": { ... }
168
- }
169
- }
81
+ ```bash
82
+ npx mcpick marketplace list # List configured marketplaces
83
+ npx mcpick marketplace add <src> # Add a marketplace
84
+ npx mcpick marketplace remove <n> # Remove a marketplace
85
+ npx mcpick marketplace update # Update all marketplaces
170
86
  ```
171
87
 
172
- ### Plugin Cache Management
88
+ ### Manage hooks
173
89
 
174
- Claude Code caches marketplace plugins at `~/.claude/plugins/cache/`.
175
- When marketplace authors update plugins, your cached versions can go
176
- stale. McPick detects this and lets you fix it.
90
+ ```bash
91
+ npx mcpick hooks list # List all hooks
92
+ npx mcpick hooks add # Add a settings hook
93
+ npx mcpick hooks remove # Remove a hook
94
+ ```
177
95
 
178
- #### Interactive
96
+ ### Plugin cache
179
97
 
180
- Select "Manage plugin cache" from the main menu to:
98
+ ```bash
99
+ npx mcpick cache status # Show staleness info
100
+ npx mcpick cache clear [key] # Clear plugin cache
101
+ npx mcpick cache clean-orphaned # Remove orphaned dirs
102
+ npx mcpick cache refresh # Git pull marketplaces
103
+ ```
181
104
 
182
- - **View cache status** - See all cached plugins with staleness
183
- indicators (version mismatch, commits behind, orphaned versions)
184
- - **Clear plugin caches** - Refreshes the marketplace and clears
185
- selected caches so they rebuild with the latest version
186
- - **Clean orphaned versions** - Remove old version directories marked
187
- as orphaned
188
- - **Refresh marketplaces** - Git pull all marketplace clones to get
189
- latest plugin listings
105
+ ### Profiles
190
106
 
191
- #### CLI Subcommands
107
+ Switch between server/plugin configurations instantly:
192
108
 
193
109
  ```bash
194
- # Show cache status for all plugins
195
- npx mcpick cache status
196
- npx mcpick cache status --json
197
-
198
- # Clear a specific plugin cache (refreshes marketplace first)
199
- npx mcpick cache clear plugin-name@marketplace
200
- npx mcpick cache clear --all
110
+ npx mcpick --profile database # Apply a profile
111
+ npx mcpick --save-profile mysetup # Save current config
112
+ npx mcpick --list-profiles # List profiles
113
+ ```
201
114
 
202
- # Remove orphaned version directories
203
- npx mcpick cache clean-orphaned
115
+ ### Backups
204
116
 
205
- # Refresh all marketplace clones
206
- npx mcpick cache refresh
117
+ ```bash
118
+ npx mcpick backup # Create timestamped backup
119
+ npx mcpick restore [file] # Restore from backup
207
120
  ```
208
121
 
209
- ### Plugin Management
122
+ All commands support `--json` for machine-readable output.
210
123
 
211
- Install, update, and toggle Claude Code marketplace plugins:
124
+ ## Interactive TUI
212
125
 
213
- ```bash
214
- # List all plugins and their status
215
- npx mcpick plugins list
216
- npx mcpick plugins list --json
126
+ Running `npx mcpick` in a terminal (TTY) launches the interactive
127
+ menu for human use:
217
128
 
218
- # Install/uninstall a plugin (wraps claude plugin CLI)
219
- npx mcpick plugins install plugin-name@marketplace
220
- npx mcpick plugins uninstall plugin-name@marketplace
129
+ ```
130
+ ┌ MCPick - Claude Code Extension Manager
131
+ │
132
+ ◆ What would you like to do?
133
+ │ ● Enable / Disable MCP servers
134
+ │ ○ Manage plugins
135
+ │ ○ Manage marketplaces
136
+ │ ○ Manage hooks
137
+ │ ○ Manage plugin cache
138
+ │ ○ Backup config
139
+ │ ○ Add MCP server
140
+ │ ○ Restore from backup
141
+ │ ○ Load profile
142
+ │ ○ Save profile
143
+ │ ○ Exit
144
+ └
145
+ ```
221
146
 
222
- # Update a plugin to latest version
223
- npx mcpick plugins update plugin-name@marketplace
147
+ In non-TTY environments (LLM agents, piped output), mcpick
148
+ automatically shows `--help` instead.
224
149
 
225
- # Enable/disable a plugin
226
- npx mcpick plugins enable plugin-name@marketplace
227
- npx mcpick plugins disable plugin-name@marketplace
228
- ```
150
+ ## The Problem
229
151
 
230
- All plugin commands support `--scope` (user, project, local) and
231
- `--json` flags.
152
+ Claude Code loads **all** MCP servers at startup. With many servers
153
+ configured, `/doctor` shows:
232
154
 
233
- ### CLI Subcommands
155
+ ```
156
+ Context Usage Warnings
157
+ └ ⚠ Large MCP tools context (~66,687 tokens > 25,000)
158
+ ```
234
159
 
235
- McPick supports both an interactive menu (default) and non-interactive
236
- CLI subcommands for scripting and LLM tool use:
160
+ This means slower startup, wasted context tokens, and cognitive
161
+ overload from too many tools. McPick lets you toggle servers on/off so
162
+ you only load what you need.
237
163
 
238
- ```bash
239
- # MCP server management
240
- npx mcpick list # List servers
241
- npx mcpick enable <server> # Enable a server
242
- npx mcpick disable <server> # Disable a server
243
- npx mcpick add --name <n> ... # Add a server
244
- npx mcpick remove <server> # Remove a server
245
-
246
- # Backups and profiles
247
- npx mcpick backup # Create backup
248
- npx mcpick restore [file] # Restore from backup
249
- npx mcpick profile list # List profiles
250
- npx mcpick profile load <name> # Load a profile
251
- npx mcpick profile save <name> # Save current config
252
-
253
- # Plugin management
254
- npx mcpick plugins list # List plugins
255
- npx mcpick plugins enable <key> # Enable plugin
256
- npx mcpick plugins disable <key> # Disable plugin
257
- npx mcpick plugins install <key> # Install from marketplace
258
- npx mcpick plugins uninstall <key> # Remove plugin
259
- npx mcpick plugins update <key> # Update to latest version
164
+ ## Scope Support
260
165
 
261
- # Cache management
262
- npx mcpick cache status # Show staleness info
263
- npx mcpick cache clear [key] # Clear plugin cache
264
- npx mcpick cache clean-orphaned # Remove orphaned dirs
265
- npx mcpick cache refresh # Git pull marketplaces
266
- ```
166
+ | Scope | Description | Storage Location |
167
+ | ----------- | ---------------------------------- | --------------------------------------------- |
168
+ | **Local** | Project-specific servers (default) | `~/.claude.json` → `projects[cwd].mcpServers` |
169
+ | **Project** | Shared via `.mcp.json` in repo | `.mcp.json` in project root |
170
+ | **User** | Global servers for all projects | `~/.claude.json` → `mcpServers` |
267
171
 
268
- All subcommands support `--json` for machine-readable output.
269
-
270
- ### Typical Workflow
271
-
272
- 1. **Before a coding session**: Run `mcpick -p <profile>` or use the
273
- interactive menu to enable relevant servers
274
- 2. **Launch Claude Code**: Run `claude` to start with your configured
275
- servers
276
- 3. **Switch contexts**: Run `mcpick -p <other-profile>` to quickly
277
- switch server sets
278
-
279
- ### Adding New Servers
280
-
281
- 1. Select "Add MCP server"
282
- 2. Provide server details:
283
- - Name (e.g., "mcp-sqlite-tools")
284
- - Command (e.g., "npx")
285
- - Arguments (e.g., "-y", "mcp-sqlite-tools")
286
- - Description (optional)
287
- - Environment variables (optional)
288
-
289
- ## Configuration
290
-
291
- MCPick works with the standard Claude Code configuration format:
292
-
293
- ```json
294
- {
295
- "mcpServers": {
296
- "server-name": {
297
- "command": "npx",
298
- "args": ["-y", "mcp-server-package"],
299
- "env": {
300
- "API_KEY": "your-key"
301
- }
302
- }
303
- }
304
- }
305
- ```
172
+ ## File Locations
306
173
 
307
- ### File Locations
308
-
309
- - **Claude Config**: `~/.claude.json` (your main Claude Code
310
- configuration)
311
- - **Project Config**: `.mcp.json` (project-specific shared config,
312
- committed to git)
313
- - **MCPick Registry**: `~/.claude/mcpick/servers.json` (MCPick's
314
- server database)
315
- - **Backups**: `~/.claude/mcpick/backups/` (MCP configuration backups)
316
- - **Profiles**: `~/.claude/mcpick/profiles/` (predefined server sets)
317
- - **Plugin Cache**: `~/.claude/plugins/cache/` (cached plugin files)
318
- - **Installed Plugins**: `~/.claude/plugins/installed_plugins.json`
319
- (plugin install registry)
320
- - **Marketplaces**: `~/.claude/plugins/marketplaces/` (marketplace git
321
- clones)
322
-
323
- #### MCP Server Storage by Scope
324
-
325
- | Scope | Location | Use Case |
326
- | ------- | ------------------------------------------------------------ | ---------------------------------- |
327
- | Local | `~/.claude.json` → `projects["/path/to/project"].mcpServers` | Personal project config |
328
- | Project | `.mcp.json` in project root | Shared team config (commit to git) |
329
- | User | `~/.claude.json` → `mcpServers` | Global servers for all projects |
330
-
331
- > **Note**: MCPick automatically detects servers in parent
332
- > directories. If you have local servers configured at
333
- > `/Users/you/projects` and run MCPick from
334
- > `/Users/you/projects/myapp`, it will find and display them.
335
-
336
- ## Safety Features
337
-
338
- - **Non-destructive**: Only modifies the `mcpServers` section of your
339
- Claude Code config
340
- - **Backup integration**: Automatically creates backups before major
341
- changes
342
- - **Validation**: Ensures all server configurations are valid before
343
- writing
344
- - **Error handling**: Graceful failure modes with helpful error
345
- messages
346
-
347
- ## Future Features
348
-
349
- McPick is actively being developed with new features planned. See the
350
- [roadmap](./docs/ROADMAP.md) for details on:
351
-
352
- - **Settings Validation** - Validate your Claude Code settings files
353
- using the
354
- [claude-code-settings-schema](https://github.com/spences10/claude-code-settings-schema)
355
- - **Permissions Management** - Interactive tool permission
356
- configuration with presets (Safe Mode, Dev Mode, Review Mode)
357
-
358
- Have ideas for other features?
359
- [Open an issue](https://github.com/spences10/mcpick/issues) or check
360
- out the [contribution guide](./docs/ROADMAP.md)!
174
+ | File | Purpose |
175
+ | ------------------------------------------ | ---------------------------- |
176
+ | `~/.claude.json` | Claude Code configuration |
177
+ | `.mcp.json` | Project-specific shared config |
178
+ | `~/.claude/mcpick/servers.json` | Server registry |
179
+ | `~/.claude/mcpick/backups/` | Configuration backups |
180
+ | `~/.claude/mcpick/profiles/` | Saved profiles |
181
+ | `~/.claude/plugins/cache/` | Cached plugin files |
182
+ | `~/.claude/plugins/marketplaces/` | Marketplace git clones |
361
183
 
362
184
  ## Requirements
363
185
 
364
186
  - Node.js 22+
365
187
  - Claude Code installed and configured
366
- - pnpm (for building from source)
package/dist/index.js CHANGED
@@ -1108,14 +1108,19 @@ async function main() {
1108
1108
  hint: "Toggle MCP servers on/off"
1109
1109
  },
1110
1110
  {
1111
- value: "edit-plugins",
1112
- label: "Manage plugins",
1113
- hint: "Toggle, install, uninstall, or update plugins"
1111
+ value: "add-server",
1112
+ label: "Add MCP server",
1113
+ hint: "Register a new MCP server"
1114
1114
  },
1115
1115
  {
1116
1116
  value: "manage-marketplace",
1117
1117
  label: "Manage marketplaces",
1118
- hint: "Add, remove, or update plugin marketplaces"
1118
+ hint: "Add a marketplace, then install plugins from it"
1119
+ },
1120
+ {
1121
+ value: "edit-plugins",
1122
+ label: "Manage plugins",
1123
+ hint: "Toggle, install, uninstall, or update plugins"
1119
1124
  },
1120
1125
  {
1121
1126
  value: "manage-hooks",
@@ -1127,21 +1132,6 @@ async function main() {
1127
1132
  label: "Manage plugin cache",
1128
1133
  hint: "View, clear, or refresh plugin caches"
1129
1134
  },
1130
- {
1131
- value: "backup",
1132
- label: "Backup config",
1133
- hint: "Create a timestamped backup"
1134
- },
1135
- {
1136
- value: "add-server",
1137
- label: "Add MCP server",
1138
- hint: "Register a new MCP server"
1139
- },
1140
- {
1141
- value: "restore",
1142
- label: "Restore from backup",
1143
- hint: "Restore from a previous backup"
1144
- },
1145
1135
  {
1146
1136
  value: "load-profile",
1147
1137
  label: "Load profile",
@@ -1152,6 +1142,16 @@ async function main() {
1152
1142
  label: "Save profile",
1153
1143
  hint: "Save current config as profile"
1154
1144
  },
1145
+ {
1146
+ value: "backup",
1147
+ label: "Backup config",
1148
+ hint: "Create a timestamped backup"
1149
+ },
1150
+ {
1151
+ value: "restore",
1152
+ label: "Restore from backup",
1153
+ hint: "Restore from a previous backup"
1154
+ },
1155
1155
  {
1156
1156
  value: "exit",
1157
1157
  label: "Exit",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mcpick",
3
- "version": "0.0.20",
3
+ "version": "0.0.21",
4
4
  "description": "Claude Code extension manager — MCP servers, plugins (skills, hooks, agents), and marketplaces",
5
5
  "keywords": [
6
6
  "claude",