mcpick 0.0.21 → 0.0.23

package/CHANGELOG.md

@@ -1,25 +1,50 @@
 # mcpick
 
+## 0.0.23
+
+### Patch Changes
+
+- 291b1d4: Add config rollback command, scoped Claude removals, author
+  metadata, and rollback backup tests.
+- 92a0d0e: Improve marketplace add validation, authentication checks,
+  and error messages for GitHub repository access failures.
+- 1d191a5: Add safer config writes, non-Claude client mutation
+  commands, shell-free git execution, and adapter tests.
+
+## 0.0.22
+
+### Patch Changes
+
+- 55a46c0: chore: remove outdated documentation and refresh README for
+  vendor-neutral MCPick architecture and current CLI flows
+- f30675a: Add vendor-neutral skills management, client-first TUI
+  refactor, and safer redacted CLI output for agents.
+
 ## 0.0.21
 
 ### Patch Changes
 
-- 47e40be: chore: reorder TUI menu and update README for agent-first usage
+- 47e40be: chore: reorder TUI menu and update README for agent-first
+  usage
 
 ## 0.0.20
 
 ### Patch Changes
 
 - 00ea930: chore: add unit tests and CI workflow with GitHub Actions
-- 37a62e1: feat: auto-show help instead of TUI in non-TTY environments for LLM agents
-- fc1db54: fix: replace exec with execFile to eliminate shell injection on all platforms
+- 37a62e1: feat: auto-show help instead of TUI in non-TTY environments
+  for LLM agents
+- fc1db54: fix: replace exec with execFile to eliminate shell
+  injection on all platforms
 
 ## 0.0.19
 
 ### Patch Changes
 
-- 5ed618e: Migrate build tooling from tsc/prettier to vite-plus, fix all lint warnings
-- 08997dc: feat: rewrite --help for LLM agents with workflow, concepts, and examples sections
+- 5ed618e: Migrate build tooling from tsc/prettier to vite-plus, fix
+  all lint warnings
+- 08997dc: feat: rewrite --help for LLM agents with workflow,
+  concepts, and examples sections
 
 ## 0.0.18
 

package/README.md

@@ -1,187 +1,210 @@
-# McPick
+# MCPick
 
 [![built with vite+](https://img.shields.io/badge/built%20with-Vite+-646CFF?logo=vite&logoColor=white)](https://viteplus.dev)
 [![tested with vitest](https://img.shields.io/badge/tested%20with-Vitest-6E9F18?logo=vitest&logoColor=white)](https://vitest.dev)
 
-Claude Code extension manager — MCP servers, plugins (skills, hooks,
-agents), and marketplaces.
+Vendor-neutral MCP configuration manager with first-class Claude Code
+support.
 
-## Quick Start
+MCPick helps humans and LLM agents inspect, toggle, and back up MCP
+server configuration across multiple AI clients. Claude Code-specific
+plugins, hooks, marketplaces, and cache commands remain available, but
+they are no longer the core product model.
 
-Use mcpick inline in Claude Code sessions. Tell Claude:
+## Install
 
-```
-Use npx mcpick to add the marketplace at spences10/claude-code-toolkit
+```bash
+npm install -g mcpick
+# or run without installing
+npx mcpick --help
 ```
 
-```
-Use npx mcpick to list my plugins and disable the ones I'm not using
-```
+Requirements:
 
-```
-Use npx mcpick to enable only the mcp-sqlite-tools server
-```
+- Node.js 22+
+- Claude Code is required only for Claude Code-specific commands
+- The external `skills` CLI is used through `npx -y skills@latest` for
+  portable skills commands
 
-McPick auto-detects non-TTY environments and shows structured help
-instead of launching the interactive TUI — so LLM agents can read
-`npx mcpick --help` and figure out the rest.
+## Agent-first CLI
 
-## Concepts
+In non-TTY environments, MCPick shows help instead of launching the
+interactive TUI. This makes it safer for prompts like:
 
-Marketplaces contain plugins. Plugins contain skills
-(`/slash-commands`), hooks, agents, and MCP servers.
+> “Use mcpick to work out how to enable this MCP server.”
 
-```
-Marketplace → Plugin → Skills, Hooks, Agents, MCP Servers
-```
-
-## Common Workflows
-
-### Install skills from a marketplace
+Start with:
 
 ```bash
-# 1. Add the marketplace
-npx mcpick marketplace add spences10/claude-code-toolkit
+npx mcpick --help
+npx mcpick clients
+npx mcpick list --json
+```
 
-# 2. Install a plugin from it
-npx mcpick plugins install my-plugin@claude-code-toolkit
+MCPick redacts known secret patterns before printing output. MCP
+configs often contain env vars and authorization headers, so `env` and
+`headers` values are shown as `***` in JSON output.
 
-# 3. Skills are now available as /slash-commands in Claude Code
-```
+## MCP clients
 
-Marketplace sources can be:
+Supported client adapters:
 
-- `owner/repo` — GitHub shorthand
-- `https://github.com/owner/repo` — full URL
-- `./local-path` — local directory
+| Client                | Scopes               | Command examples                                  |
+| --------------------- | -------------------- | ------------------------------------------------- |
+| Claude Code           | local, project, user | `mcpick list`, `mcpick enable <server>`           |
+| Gemini CLI            | project, user        | `mcpick list --client gemini-cli --scope project` |
+| VS Code / Copilot     | project              | `mcpick list --client vscode --scope project`     |
+| Cursor                | project, user        | `mcpick list --client cursor --scope user`        |
+| Windsurf              | user                 | `mcpick list --client windsurf --scope user`      |
+| OpenCode              | project, user        | `mcpick list --client opencode --scope project`   |
+| Pi via pi-mcp-adapter | project, user        | `mcpick list --client pi --scope user`            |
 
-### Toggle MCP servers
+Show known config locations:
 
 ```bash
-npx mcpick list                    # List servers and status
-npx mcpick enable <server>        # Enable a server
-npx mcpick disable <server>       # Disable a server
-npx mcpick add --name <n> ...     # Add a new server
-npx mcpick remove <server>        # Remove a server
+npx mcpick clients
+npx mcpick clients --json
 ```
 
-### Manage plugins
+## MCP server commands
 
 ```bash
-npx mcpick plugins list            # List plugins and status
-npx mcpick plugins install <key>   # Install from marketplace
-npx mcpick plugins uninstall <key> # Remove plugin
-npx mcpick plugins update <key>    # Update to latest
-npx mcpick plugins enable <key>    # Enable plugin
-npx mcpick plugins disable <key>   # Disable plugin
-```
+# List Claude Code registry/status
+npx mcpick list
+npx mcpick list --json
 
-### Manage marketplaces
+# List another client
+npx mcpick list --client pi --scope user --json
+npx mcpick list --client opencode --scope project
 
-```bash
-npx mcpick marketplace list       # List configured marketplaces
-npx mcpick marketplace add <src>  # Add a marketplace
-npx mcpick marketplace remove <n> # Remove a marketplace
-npx mcpick marketplace update     # Update all marketplaces
+# Claude Code enable/disable
+npx mcpick enable <server> --scope local
+npx mcpick disable <server> --scope local
+
+# Add/remove Claude Code server definitions
+npx mcpick add --name <server> --command npx --args "-y,package-name"
+npx mcpick add-json <name> '{"command":"npx","args":["-y","package-name"]}'
+npx mcpick remove <server>
 ```
 
-### Manage hooks
+For secret-backed servers, prefer environment variable references and
+secret-safe loading tools. MCPick redacts printed values, but MCP
+client config files may still store secrets in plain text because that
+is how many clients currently load MCP credentials.
 
-```bash
-npx mcpick hooks list             # List all hooks
-npx mcpick hooks add              # Add a settings hook
-npx mcpick hooks remove           # Remove a hook
-```
+## Portable skills
 
-### Plugin cache
+MCPick delegates portable SKILL.md management to the external `skills`
+CLI.
 
 ```bash
-npx mcpick cache status           # Show staleness info
-npx mcpick cache clear [key]      # Clear plugin cache
-npx mcpick cache clean-orphaned   # Remove orphaned dirs
-npx mcpick cache refresh          # Git pull marketplaces
-```
+# List installed skills for a client
+npx mcpick skills list --agent pi --json
 
-### Profiles
+# See available skills from a source without installing
+npx mcpick skills add spences10/skills --list
 
-Switch between server/plugin configurations instantly:
+# Install one skill
+npx mcpick skills add spences10/skills --agent pi --skill svelte-runes --yes
 
-```bash
-npx mcpick --profile database     # Apply a profile
-npx mcpick --save-profile mysetup # Save current config
-npx mcpick --list-profiles        # List profiles
+# Install all skills for a client globally
+npx mcpick skills add spences10/skills --agent opencode --skill '*' --global --yes
+
+# Update/remove
+npx mcpick skills update --global --yes
+npx mcpick skills remove svelte-runes --agent pi --yes
 ```
 
-### Backups
+## Claude Code-specific tools
+
+These commands wrap Claude Code concepts and are intentionally
+client-specific:
 
 ```bash
-npx mcpick backup                 # Create timestamped backup
-npx mcpick restore [file]         # Restore from backup
+# Plugins
+npx mcpick plugins list
+npx mcpick plugins install <name>@<marketplace>
+npx mcpick plugins enable <name>@<marketplace>
+npx mcpick plugins disable <name>@<marketplace>
+
+# Marketplaces
+npx mcpick marketplace list
+npx mcpick marketplace add <source>
+npx mcpick marketplace update
+npx mcpick marketplace remove <name>
+
+# Hooks and plugin cache
+npx mcpick hooks list
+npx mcpick cache status
+npx mcpick cache refresh
 ```
 
-All commands support `--json` for machine-readable output.
+## Profiles and backups
 
-## Interactive TUI
+Profiles and backups currently preserve MCP server and Claude Code
+plugin state.
 
-Running `npx mcpick` in a terminal (TTY) launches the interactive
-menu for human use:
+```bash
+npx mcpick --profile database
+npx mcpick --save-profile mysetup
+npx mcpick --list-profiles
 
-```
-┌  MCPick - Claude Code Extension Manager
-│
-◆  What would you like to do?
-│  ● Enable / Disable MCP servers
-│  ○ Manage plugins
-│  ○ Manage marketplaces
-│  ○ Manage hooks
-│  ○ Manage plugin cache
-│  ○ Backup config
-│  ○ Add MCP server
-│  ○ Restore from backup
-│  ○ Load profile
-│  ○ Save profile
-│  ○ Exit
-└
+npx mcpick backup
+npx mcpick restore [file]
+
+# Safe-write rollback backups created before config mutations
+npx mcpick rollback --list
+npx mcpick rollback [file]
 ```
 
-In non-TTY environments (LLM agents, piped output), mcpick
-automatically shows `--help` instead.
+## Interactive TUI
 
-## The Problem
+Running `npx mcpick` in a terminal launches the human-facing menu:
 
-Claude Code loads **all** MCP servers at startup. With many servers
-configured, `/doctor` shows:
+```text
+MCPick - MCP Configuration Manager
 
-```
- Context Usage Warnings
- └ ⚠ Large MCP tools context (~66,687 tokens > 25,000)
+What would you like to do?
+  Enable / Disable MCP servers
+  Skills
+  Client-specific tools
+  Load profile
+  Save profile
+  Backup config
+  Restore from backup
+  Exit
 ```
 
-This means slower startup, wasted context tokens, and cognitive
-overload from too many tools. McPick lets you toggle servers on/off so
-you only load what you need.
+The primary TUI flow is client-first: choose a client, then toggle its
+MCP servers. Claude Code plugins, hooks, marketplaces, and cache live
+under “Client-specific tools”.
 
-## Scope Support
+## Config locations
 
-| Scope       | Description                        | Storage Location                              |
-| ----------- | ---------------------------------- | --------------------------------------------- |
-| **Local**   | Project-specific servers (default) | `~/.claude.json` → `projects[cwd].mcpServers` |
-| **Project** | Shared via `.mcp.json` in repo     | `.mcp.json` in project root                   |
-| **User**    | Global servers for all projects    | `~/.claude.json` → `mcpServers`               |
+MCPick reads the standard locations used by each client adapter.
+Common paths include:
 
-## File Locations
+| Path                     | Purpose                                         |
+| ------------------------ | ----------------------------------------------- |
+| `~/.claude.json`         | Claude Code local/user MCP config               |
+| `.mcp.json`              | Shared project MCP config                       |
+| `.gemini/settings.json`  | Gemini CLI project config                       |
+| `.vscode/mcp.json`       | VS Code / Copilot project config                |
+| `.cursor/mcp.json`       | Cursor project config                           |
+| `opencode.json`          | OpenCode project config                         |
+| `~/.config/mcp/mcp.json` | Shared global MCP config used by pi-mcp-adapter |
+| `.pi/mcp.json`           | Pi project override                             |
 
-| File                                       | Purpose                      |
-| ------------------------------------------ | ---------------------------- |
-| `~/.claude.json`                           | Claude Code configuration    |
-| `.mcp.json`                                | Project-specific shared config |
-| `~/.claude/mcpick/servers.json`            | Server registry              |
-| `~/.claude/mcpick/backups/`                | Configuration backups        |
-| `~/.claude/mcpick/profiles/`               | Saved profiles               |
-| `~/.claude/plugins/cache/`                 | Cached plugin files          |
-| `~/.claude/plugins/marketplaces/`          | Marketplace git clones       |
+MCPick-owned state lives under `~/.claude/mcpick/` for historical
+compatibility.
 
-## Requirements
+## Development
 
-- Node.js 22+
-- Claude Code installed and configured
+```bash
+pnpm install
+pnpm test
+pnpm run check
+pnpm build
+```
+
+See `docs/VENDOR_NEUTRAL_ARCHITECTURE.md` for architecture notes.

package/dist/add-LJQa2my2.js

@@ -0,0 +1,164 @@
+import { n as validate_mcp_server } from "./validation-xMlbgGCF.js";
+import { A as add_client_server, F as resolve_client_location, M as get_client_adapter, d as add_mcp_via_cli, w as add_server_to_registry } from "./index.js";
+import { n as output, t as error } from "./output-HtT5HCof.js";
+import { defineCommand } from "citty";
+//#region src/cli/commands/add.ts
+var add_default = defineCommand({
+	meta: {
+		name: "add",
+		description: "Add a new MCP server to the registry and enable it"
+	},
+	args: {
+		name: {
+			type: "string",
+			description: "Server name",
+			required: true
+		},
+		command: {
+			type: "string",
+			description: "Command to run (for stdio transport)"
+		},
+		args: {
+			type: "string",
+			description: "Comma-separated arguments (e.g. \"npx,-y,mcp-sqlite\")"
+		},
+		url: {
+			type: "string",
+			description: "URL (for sse or http transport)"
+		},
+		type: {
+			type: "string",
+			description: "Transport type: stdio, sse, or http (default: stdio)",
+			default: "stdio"
+		},
+		env: {
+			type: "string",
+			description: "Environment variables as KEY=val,KEY=val"
+		},
+		headers: {
+			type: "string",
+			description: "HTTP headers as KEY=val,KEY=val"
+		},
+		description: {
+			type: "string",
+			description: "Server description"
+		},
+		client: {
+			type: "string",
+			description: "Client to edit: claude-code, gemini-cli, vscode, cursor, windsurf, opencode, or pi",
+			default: "claude-code"
+		},
+		scope: {
+			type: "string",
+			description: "Scope: local, project, or user (default: local for Claude Code)"
+		},
+		location: {
+			type: "string",
+			description: "Exact config path when a client has multiple matching locations"
+		},
+		json: {
+			type: "boolean",
+			description: "Output as JSON",
+			default: false
+		}
+	},
+	async run({ args }) {
+		const transport = args.type;
+		if (![
+			"stdio",
+			"sse",
+			"http"
+		].includes(transport)) error(`Invalid type: ${transport}. Use stdio, sse, or http.`);
+		const add_args = args;
+		const portable = build_portable_server(add_args, transport);
+		if (add_args.client && add_args.client !== "claude-code") {
+			await add_to_client(add_args.client, portable, add_args.scope, add_args.location, add_args.json);
+			return;
+		}
+		const scope = add_args.scope || "local";
+		if (![
+			"local",
+			"project",
+			"user"
+		].includes(scope)) error(`Invalid scope: ${scope}. Use local, project, or user.`);
+		const server_data = {
+			name: portable.name,
+			...transport !== "stdio" ? { type: transport } : {},
+			...portable.command ? { command: portable.command } : {},
+			...portable.args ? { args: portable.args } : {},
+			...portable.url ? { url: portable.url } : {},
+			...portable.env ? { env: portable.env } : {},
+			...portable.headers ? { headers: portable.headers } : {},
+			...portable.description ? { description: portable.description } : {}
+		};
+		let server;
+		try {
+			server = validate_mcp_server(server_data);
+		} catch (err) {
+			error(`Invalid server config: ${err instanceof Error ? err.message : "validation failed"}`);
+		}
+		await add_server_to_registry(server);
+		const result = await add_mcp_via_cli(server, scope);
+		if (add_args.json) output({
+			added: server.name,
+			client: "claude-code",
+			scope,
+			cli: result.success,
+			error: result.error
+		}, true);
+		else if (result.success) console.log(`Added '${server.name}' and enabled (scope: ${scope})`);
+		else console.log(`Added '${server.name}' to registry but CLI failed: ${result.error}`);
+	}
+});
+function build_portable_server(args, transport) {
+	const server = {
+		name: args.name,
+		transport
+	};
+	if (transport === "stdio") {
+		if (!args.command) error("--command is required for stdio transport");
+		server.command = args.command;
+		if (args.args) server.args = args.args.split(",");
+	} else {
+		if (!args.url) error(`--url is required for ${transport} transport`);
+		server.url = args.url;
+		if (args.headers) server.headers = parse_key_value_pairs(args.headers);
+	}
+	if (args.env) server.env = parse_key_value_pairs(args.env);
+	if (args.description) server.description = args.description;
+	return server;
+}
+async function add_to_client(client, server, scope, location_path, json) {
+	const adapter = get_client_adapter(client);
+	if (!adapter) error(`Invalid client: ${client}. Use claude-code, gemini-cli, vscode, cursor, windsurf, opencode, or pi.`);
+	if (scope && ![
+		"local",
+		"project",
+		"user"
+	].includes(scope)) error(`Invalid scope: ${scope}. Use local, project, or user.`);
+	try {
+		const location = resolve_client_location(adapter, scope, location_path);
+		await add_client_server(adapter, location, server);
+		if (json) output({
+			added: server.name,
+			client: adapter.id,
+			scope: location.scope,
+			location: location.path
+		}, true);
+		else console.log(`Added '${server.name}' (${adapter.id}:${location.scope})`);
+	} catch (err) {
+		error(err instanceof Error ? err.message : "Failed to add server");
+	}
+}
+function parse_key_value_pairs(input) {
+	const result = {};
+	for (const pair of input.split(",")) {
+		const eq = pair.indexOf("=");
+		if (eq > 0) result[pair.substring(0, eq)] = pair.substring(eq + 1);
+	}
+	return result;
+}
+//#endregion
+export { add_default as default };
+
+//# sourceMappingURL=add-LJQa2my2.js.map

package/dist/add-json-TEdYweZ5.js

@@ -0,0 +1,95 @@
+import { F as resolve_client_location, M as get_client_adapter, _ as mcp_add_json_via_cli, j as add_client_server_config } from "./index.js";
+import { n as output, t as error } from "./output-HtT5HCof.js";
+import { defineCommand } from "citty";
+//#region src/cli/commands/add-json.ts
+var add_json_default = defineCommand({
+	meta: {
+		name: "add-json",
+		description: "Add an MCP server from a JSON configuration string"
+	},
+	args: {
+		name: {
+			type: "positional",
+			description: "Server name",
+			required: true
+		},
+		config: {
+			type: "positional",
+			description: "JSON configuration string",
+			required: true
+		},
+		client: {
+			type: "string",
+			description: "Client to edit: claude-code, gemini-cli, vscode, cursor, windsurf, opencode, or pi",
+			default: "claude-code"
+		},
+		scope: {
+			type: "string",
+			description: "Scope: local, project, or user (default: local for Claude Code)"
+		},
+		location: {
+			type: "string",
+			description: "Exact config path when a client has multiple matching locations"
+		},
+		json: {
+			type: "boolean",
+			description: "Output as JSON",
+			default: false
+		}
+	},
+	async run({ args }) {
+		let parsed;
+		try {
+			parsed = JSON.parse(args.config);
+		} catch {
+			error("Invalid JSON configuration. Provide a valid JSON string.");
+		}
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) error("JSON configuration must be an object.");
+		if (args.client && args.client !== "claude-code") {
+			await add_json_to_client(args.client, args.name, parsed, args.scope, args.location, args.json);
+			return;
+		}
+		const scope = args.scope || "local";
+		if (![
+			"local",
+			"project",
+			"user"
+		].includes(scope)) error(`Invalid scope: ${scope}. Use local, project, or user.`);
+		const result = await mcp_add_json_via_cli(args.name, args.config, scope);
+		if (args.json) output({
+			added: args.name,
+			client: "claude-code",
+			scope,
+			success: result.success,
+			error: result.error
+		}, true);
+		else if (result.success) console.log(`Added '${args.name}' from JSON (scope: ${scope})`);
+		else error(result.error || "Unknown error");
+	}
+});
+async function add_json_to_client(client, name, config, scope, location_path, json) {
+	const adapter = get_client_adapter(client);
+	if (!adapter) error(`Invalid client: ${client}. Use claude-code, gemini-cli, vscode, cursor, windsurf, opencode, or pi.`);
+	if (scope && ![
+		"local",
+		"project",
+		"user"
+	].includes(scope)) error(`Invalid scope: ${scope}. Use local, project, or user.`);
+	try {
+		const location = resolve_client_location(adapter, scope, location_path);
+		await add_client_server_config(adapter, location, name, config);
+		if (json) output({
+			added: name,
+			client: adapter.id,
+			scope: location.scope,
+			location: location.path
+		}, true);
+		else console.log(`Added '${name}' from JSON (${adapter.id}:${location.scope})`);
+	} catch (err) {
+		error(err instanceof Error ? err.message : "Failed to add server");
+	}
+}
+//#endregion
+export { add_json_default as default };
+
+//# sourceMappingURL=add-json-TEdYweZ5.js.map

package/dist/{backup-DSDhHI5f.js → backup-kyS5IVIr.js}

@@ -1,7 +1,7 @@
 import { m as get_plugin_backup_filename, n as get_backup_filename, r as get_backups_dir, t as ensure_directory_exists } from "./paths-BPISiJi4.js";
-import { s as read_claude_config } from "./config-DijVdEFn.js";
-import { a as read_claude_settings } from "./settings-DEcWtzLE.js";
-import { n as output } from "./output-BchYq0mR.js";
+import { s as read_claude_config } from "./config-DzMmTJYL.js";
+import { V as read_claude_settings } from "./index.js";
+import { n as output } from "./output-HtT5HCof.js";
 import { readdir, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { defineCommand } from "citty";
@@ -61,4 +61,4 @@ var backup_default = defineCommand({
 //#endregion
 export { backup_default as default };
 
-//# sourceMappingURL=backup-DSDhHI5f.js.map
+//# sourceMappingURL=backup-kyS5IVIr.js.map