mcpick 0.0.21 → 0.0.22

package/.github/copilot-instructions.md

@@ -1,32 +1,50 @@
-# McPick Development Instructions
+# MCPick Development Instructions
 
-**Always reference these instructions first and fallback to search or
-bash commands only when you encounter unexpected information that does
-not match the info here.**
+## Project shape
 
-## Working Effectively
+MCPick is a vendor-neutral MCP configuration manager with first-class
+Claude Code support.
 
-### Prerequisites and Setup
+- Keep MCP server functionality client-neutral where possible.
+- Keep Claude Code plugins, hooks, marketplaces, and cache commands
+  clearly Claude-specific.
+- Prefer CLI flows that work well for LLM agents: non-interactive
+  flags, `--json`, useful help text, and redacted output.
 
-- Install Node.js >=22.0.0
-- Install pnpm globally: `npm install -g pnpm` (takes ~2 seconds)
+## Prerequisites
 
-### Development Commands
+- Node.js >=22.0.0
+- pnpm
 
-- **Format code**: `pnpm run format`
-- **Build**: `pnpm run build`
+## Common commands
 
-## Validation Requirements
+```bash
+pnpm install
+pnpm test
+pnpm run check
+pnpm build
+```
 
-### ALWAYS run these before submitting changes:
+## Validation before finishing
 
-1. `pnpm run format` - Auto-format all code
-2. `pnpm run build` - Check for build issues
+Always run:
 
-#### Add changeset once you're done
+```bash
+pnpm run check
+pnpm test
+pnpm build
+```
 
-Run `pnpm changeset` then follow the prompts. Use this after having
-finished the task. Most of the time this is a patch release for
-`mcpick`. Use a short and descriptive message. Always prefix the
-message with either `fix`, `feat`, `breaking`, or `chore` (most likely
-`fix` since you're mostly working on bugfixes).
+`pnpm run check` validates formatting, lint, and types through
+vite-plus.
+
+## Changesets
+
+For user-facing changes, add a changeset:
+
+```bash
+pnpm changeset
+```
+
+Use a short message prefixed with `feat`, `fix`, `chore`, or
+`breaking`.

package/CHANGELOG.md

@@ -1,25 +1,39 @@
 # mcpick
 
+## 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/CONTEXT.md

@@ -0,0 +1,49 @@
+# MCPick
+
+MCPick manages Model Context Protocol configuration across AI
+development tools without making one vendor's config format the
+product model.
+
+## Language
+
+**MCP Server**: A runnable or remote tool provider exposed through the
+Model Context Protocol. _Avoid_: Claude server, plugin server
+
+**MCP Client**: An AI application that loads MCP Server configuration
+and exposes those tools to a model. _Avoid_: Vendor, app, host
+
+**Client Adapter**: A module that translates between MCPick's portable
+MCP Server shape and one MCP Client's config file shape. _Avoid_:
+Provider, integration, plugin
+
+**Portable Server**: MCPick's canonical representation of an MCP
+Server independent of any MCP Client config file. _Avoid_: Claude
+config, raw config
+
+**Config Location**: A file path and scope where an MCP Client reads
+MCP Server configuration. _Avoid_: path helper, config target
+
+**Profile**: A saved set of Portable Servers intended to be applied to
+one or more MCP Clients. _Avoid_: Claude profile
+
+## Relationships
+
+- An **MCP Client** reads one or more **Config Locations**.
+- A **Client Adapter** translates between a **Config Location** and
+  **Portable Servers**.
+- A **Profile** contains **Portable Servers**.
+- An **MCP Server** may appear in multiple **MCP Clients** with
+  client-specific options.
+
+## Example dialogue
+
+> **Dev:** "Can we enable the Google docs MCP server in Gemini and
+> Cursor without rewriting the JSON twice?" **Domain expert:** "Yes —
+> keep it as a **Portable Server**, then let each **Client Adapter**
+> write the right **Config Location**."
+
+## Flagged ambiguities
+
+- "server config" used to mean both MCPick registry entries and
+  client-specific JSON. Resolved: **Portable Server** for MCPick's
+  shape, **Config Location** for client-owned files.

package/README.md

@@ -1,187 +1,206 @@
-# 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]
 ```
 
-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-BDyaBew0.js → add-Bok0qbXi.js}

@@ -1,7 +1,6 @@
-import { n as validate_mcp_server } from "./validation-xMlbgGCF.js";
-import { t as add_server_to_registry } from "./registry-CfUKT7_C.js";
-import { t as add_mcp_via_cli } from "./claude-cli-DnmBJrjg.js";
-import { n as output, t as error } from "./output-BchYq0mR.js";
+import { n as validate_mcp_server } from "./validation-qWlF51fw.js";
+import { d as add_mcp_via_cli, w as add_server_to_registry } from "./index.js";
+import { n as output, t as error } from "./output-BgN9Uuxf.js";
 import { defineCommand } from "citty";
 //#region src/cli/commands/add.ts
 var add_default = defineCommand({
@@ -110,4 +109,4 @@ function parse_key_value_pairs(input) {
 //#endregion
 export { add_default as default };
 
-//# sourceMappingURL=add-BDyaBew0.js.map
+//# sourceMappingURL=add-Bok0qbXi.js.map

package/dist/{add-json-BjgzdeG-.js → add-json-C44vy2A_.js}

@@ -1,5 +1,5 @@
-import { u as mcp_add_json_via_cli } from "./claude-cli-DnmBJrjg.js";
-import { n as output, t as error } from "./output-BchYq0mR.js";
+import { _ as mcp_add_json_via_cli } from "./index.js";
+import { n as output, t as error } from "./output-BgN9Uuxf.js";
 import { defineCommand } from "citty";
 //#region src/cli/commands/add-json.ts
 var add_json_default = defineCommand({
@@ -55,4 +55,4 @@ var add_json_default = defineCommand({
 //#endregion
 export { add_json_default as default };
 
-//# sourceMappingURL=add-json-BjgzdeG-.js.map
+//# sourceMappingURL=add-json-C44vy2A_.js.map

package/dist/{atomic-write-BqEykHp9.js → atomic-write-4lANmzsO.js}

@@ -23,4 +23,4 @@ async function atomic_json_write(file_path, merge) {
 //#endregion
 export { atomic_json_write as t };
 
-//# sourceMappingURL=atomic-write-BqEykHp9.js.map
+//# sourceMappingURL=atomic-write-4lANmzsO.js.map

package/dist/{backup-DSDhHI5f.js → backup-bdg6dvsb.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 { m as get_plugin_backup_filename, n as get_backup_filename, r as get_backups_dir, t as ensure_directory_exists } from "./paths-6wrIM8yh.js";
+import { s as read_claude_config } from "./config-BhX4eAgg.js";
+import { a as read_claude_settings } from "./settings-CZR8bVfh.js";
+import { n as output } from "./output-BgN9Uuxf.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-bdg6dvsb.js.map

package/dist/{cache-D6kd7qE8.js → cache-CSUcGdZP.js}

@@ -1,5 +1,5 @@
-import { a as list_linked_plugins, c as read_installed_plugins, d as refresh_all_marketplaces, f as scan_all_cache_keys, i as link_local_plugin, n as clear_plugin_caches, p as unlink_local_plugin, r as get_cached_plugins_info, t as clean_orphaned_versions } from "./plugin-cache-Bby9Dxm9.js";
-import { n as output, t as error } from "./output-BchYq0mR.js";
+import { a as list_linked_plugins, c as read_installed_plugins, d as refresh_all_marketplaces, f as scan_all_cache_keys, i as link_local_plugin, n as clear_plugin_caches, p as unlink_local_plugin, r as get_cached_plugins_info, t as clean_orphaned_versions } from "./plugin-cache-DKcW8LGV.js";
+import { n as output, t as error } from "./output-BgN9Uuxf.js";
 import { defineCommand } from "citty";
 var cache_default = defineCommand({
 	meta: {
@@ -223,4 +223,4 @@ var cache_default = defineCommand({
 //#endregion
 export { cache_default as default };
 
-//# sourceMappingURL=cache-D6kd7qE8.js.map
+//# sourceMappingURL=cache-CSUcGdZP.js.map