mcpick 0.0.20 → 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,19 +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
+
 ## 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,366 +1,206 @@
-# McPick
+# MCPick
 
-A CLI tool for managing MCP servers, plugins, and plugin caches in
-Claude Code. Toggle servers and plugins on/off, manage stale plugin
-caches, and optimise context usage and performance.
+[![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)
 
-## Installation
+Vendor-neutral MCP configuration manager with first-class Claude Code
+support.
 
-### One-time Usage (recommended)
+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.
 
-```bash
-pnpx mcpick
-# or
-pnpm dlx mcpick
-# or
-npx mcpick
-```
-
-### Global Installation
+## Install
 
 ```bash
-pnpm install -g mcpick
-# or
 npm install -g mcpick
+# or run without installing
+npx mcpick --help
 ```
 
-## The Problem
-
-Using the Claude Code `/doctor` command you may see something like
-this if you have many MCP servers configured:
-
-```bash
- Context Usage Warnings
- └ ⚠ Large MCP tools context (~66,687 tokens > 25,000)
-   └ MCP servers:
-     └ mcp-omnisearch-testing: 20 tools (~10,494 tokens)
-     └ mcp-omnisearch: 20 tools (~10,454 tokens)
-     └ mcp-sqlite-tools-testing: 19 tools (~9,910 tokens)
-     └ mcp-sqlite-tools: 19 tools (~9,872 tokens)
-     └ playwright: 21 tools (~9,804 tokens)
-     └ (7 more servers)
-```
-
-Claude Code loads **all** MCP servers from your `.claude.json` file at
-startup, regardless of whether you need them for your current task.
-This can lead to:
+Requirements:
 
-- 🐌 Slower Claude Code startup times
-- 💾 High context token usage
-- 🧠 Cognitive overload from too many available tools
-
-## The Solution
+- 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 provides an intuitive CLI menu and non-interactive subcommands
-to:
+## Agent-first CLI
 
-- ✅ **Toggle servers on/off** - Enable only the MCP servers you need
-  for your current task
-- 🔌 **Toggle plugins on/off** - Enable or disable Claude Code
-  marketplace plugins
-- 🗑️ **Manage plugin cache** - Detect stale plugins, clear caches,
-  clean orphaned versions, refresh marketplaces
-- 📁 **Manage server registry** - Keep a database of all your
-  available MCP servers
-- 🔄 **Safe configuration** - Only modifies the `mcpServers` section,
-  preserving other Claude Code settings
-- 💾 **Backup & restore** - Create focused backups of your MCP server
-  configurations
+In non-TTY environments, MCPick shows help instead of launching the
+interactive TUI. This makes it safer for prompts like:
 
-## Features
+> “Use mcpick to work out how to enable this MCP server.”
 
-### Interactive Menu
+Start with:
 
 ```bash
-┌  McPick - MCP Server Configuration Manager
-│
-◆  What would you like to do?
-│  ● Enable / Disable MCP servers (Toggle MCP servers on/off)
-│  ○ Enable / Disable plugins (Toggle Claude Code plugins on/off)
-│  ○ Manage plugin cache (View, clear, or refresh plugin caches)
-│  ○ Backup config
-│  ○ Add MCP server
-│  ○ Restore from backup
-│  ○ Load profile
-│  ○ Save profile
-│  ○ Exit
-└
+npx mcpick --help
+npx mcpick clients
+npx mcpick list --json
 ```
 
-### Scope Support
+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.
 
-MCPick supports the three MCP server scopes used by Claude Code:
+## MCP clients
 
-| Scope       | Description                          | Storage Location                              |
-| ----------- | ------------------------------------ | --------------------------------------------- |
-| **Local**   | Project-specific servers (default)   | `~/.claude.json` → `projects[cwd].mcpServers` |
-| **Project** | Shared via `.mcp.json` in repository | `.mcp.json` in project root                   |
-| **User**    | Global servers for all projects      | `~/.claude.json` → `mcpServers`               |
+Supported client adapters:
 
-When you select "Enable / Disable MCP servers", MCPick will:
+| 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`            |
 
-1. Ask which scope you want to edit
-2. Show servers already enabled for that scope (pre-checked)
-3. Use `claude mcp add/remove` CLI commands for Local and Project
-   scopes
+Show known config locations:
 
-This integration ensures your changes are correctly applied to the
-right configuration location.
-
-### Smart Server Management
+```bash
+npx mcpick clients
+npx mcpick clients --json
+```
 
-- **Auto-discovery**: Automatically imports servers from your existing
-  `.claude.json`
-- **Registry sync**: Maintains a registry of available servers for
-  quick selection
-- **Selective enabling**: Choose exactly which servers to enable via
-  multiselect
-- **Configuration safety**: Preserves all non-MCP settings in your
-  Claude Code config
+## MCP server commands
 
-### Backup System
+```bash
+# List Claude Code registry/status
+npx mcpick list
+npx mcpick list --json
+
+# List another client
+npx mcpick list --client pi --scope user --json
+npx mcpick list --client opencode --scope project
+
+# 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>
+```
 
-- **Focused backups**: Only backs up MCP server configurations (not
-  the entire 30k+ line config)
-- **Automatic cleanup**: Keeps last 10 backups to prevent storage
-  bloat
-- **Easy restoration**: Restore from any previous backup with a simple
-  menu
+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.
 
-### Profiles
+## Portable skills
 
-Load predefined sets of MCP servers instantly:
+MCPick delegates portable SKILL.md management to the external `skills`
+CLI.
 
 ```bash
-# Apply a profile
-mcpick --profile database
-mcpick -p database
+# List installed skills for a client
+npx mcpick skills list --agent pi --json
 
-# Save current config as a profile
-mcpick --save-profile mysetup
-mcpick -s mysetup
+# See available skills from a source without installing
+npx mcpick skills add spences10/skills --list
 
-# List available profiles
-mcpick --list-profiles
-mcpick -l
-```
-
-Profiles are stored in `~/.claude/mcpick/profiles/`. You can also
-create them manually:
-
-```json
-// ~/.claude/mcpick/profiles/database.json
-{
-	"mcp-sqlite-tools": {
-		"type": "stdio",
-		"command": "npx",
-		"args": ["-y", "mcp-sqlite-tools"]
-	}
-}
-```
+# Install one skill
+npx mcpick skills add spences10/skills --agent pi --skill svelte-runes --yes
 
-Or use full format with `mcpServers` wrapper:
+# Install all skills for a client globally
+npx mcpick skills add spences10/skills --agent opencode --skill '*' --global --yes
 
-```json
-{
-  "mcpServers": {
-    "server-name": { ... }
-  }
-}
+# Update/remove
+npx mcpick skills update --global --yes
+npx mcpick skills remove svelte-runes --agent pi --yes
 ```
 
-### Plugin Cache Management
-
-Claude Code caches marketplace plugins at `~/.claude/plugins/cache/`.
-When marketplace authors update plugins, your cached versions can go
-stale. McPick detects this and lets you fix it.
+## Claude Code-specific tools
 
-#### Interactive
-
-Select "Manage plugin cache" from the main menu to:
-
-- **View cache status** - See all cached plugins with staleness
-  indicators (version mismatch, commits behind, orphaned versions)
-- **Clear plugin caches** - Refreshes the marketplace and clears
-  selected caches so they rebuild with the latest version
-- **Clean orphaned versions** - Remove old version directories marked
-  as orphaned
-- **Refresh marketplaces** - Git pull all marketplace clones to get
-  latest plugin listings
-
-#### CLI Subcommands
+These commands wrap Claude Code concepts and are intentionally
+client-specific:
 
 ```bash
-# Show cache status for all plugins
+# 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 status --json
-
-# Clear a specific plugin cache (refreshes marketplace first)
-npx mcpick cache clear plugin-name@marketplace
-npx mcpick cache clear --all
-
-# Remove orphaned version directories
-npx mcpick cache clean-orphaned
-
-# Refresh all marketplace clones
 npx mcpick cache refresh
 ```
 
-### Plugin Management
+## Profiles and backups
 
-Install, update, and toggle Claude Code marketplace plugins:
+Profiles and backups currently preserve MCP server and Claude Code
+plugin state.
 
 ```bash
-# List all plugins and their status
-npx mcpick plugins list
-npx mcpick plugins list --json
+npx mcpick --profile database
+npx mcpick --save-profile mysetup
+npx mcpick --list-profiles
+
+npx mcpick backup
+npx mcpick restore [file]
+```
+
+## Interactive TUI
 
-# Install/uninstall a plugin (wraps claude plugin CLI)
-npx mcpick plugins install plugin-name@marketplace
-npx mcpick plugins uninstall plugin-name@marketplace
+Running `npx mcpick` in a terminal launches the human-facing menu:
 
-# Update a plugin to latest version
-npx mcpick plugins update plugin-name@marketplace
+```text
+MCPick - MCP Configuration Manager
 
-# Enable/disable a plugin
-npx mcpick plugins enable plugin-name@marketplace
-npx mcpick plugins disable plugin-name@marketplace
+What would you like to do?
+  Enable / Disable MCP servers
+  Skills
+  Client-specific tools
+  Load profile
+  Save profile
+  Backup config
+  Restore from backup
+  Exit
 ```
 
-All plugin commands support `--scope` (user, project, local) and
-`--json` flags.
+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”.
 
-### CLI Subcommands
+## Config locations
 
-McPick supports both an interactive menu (default) and non-interactive
-CLI subcommands for scripting and LLM tool use:
+MCPick reads the standard locations used by each client adapter.
+Common paths include:
 
-```bash
-# MCP server management
-npx mcpick list                    # List servers
-npx mcpick enable <server>         # Enable a server
-npx mcpick disable <server>        # Disable a server
-npx mcpick add --name <n> ...      # Add a server
-npx mcpick remove <server>         # Remove a server
-
-# Backups and profiles
-npx mcpick backup                  # Create backup
-npx mcpick restore [file]          # Restore from backup
-npx mcpick profile list            # List profiles
-npx mcpick profile load <name>     # Load a profile
-npx mcpick profile save <name>     # Save current config
-
-# Plugin management
-npx mcpick plugins list            # List plugins
-npx mcpick plugins enable <key>    # Enable plugin
-npx mcpick plugins disable <key>   # Disable plugin
-npx mcpick plugins install <key>   # Install from marketplace
-npx mcpick plugins uninstall <key> # Remove plugin
-npx mcpick plugins update <key>    # Update to latest version
-
-# Cache management
-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
-```
+| 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                             |
 
-All subcommands support `--json` for machine-readable output.
-
-### Typical Workflow
-
-1. **Before a coding session**: Run `mcpick -p <profile>` or use the
-   interactive menu to enable relevant servers
-2. **Launch Claude Code**: Run `claude` to start with your configured
-   servers
-3. **Switch contexts**: Run `mcpick -p <other-profile>` to quickly
-   switch server sets
-
-### Adding New Servers
-
-1. Select "Add MCP server"
-2. Provide server details:
-   - Name (e.g., "mcp-sqlite-tools")
-   - Command (e.g., "npx")
-   - Arguments (e.g., "-y", "mcp-sqlite-tools")
-   - Description (optional)
-   - Environment variables (optional)
-
-## Configuration
-
-MCPick works with the standard Claude Code configuration format:
-
-```json
-{
-	"mcpServers": {
-		"server-name": {
-			"command": "npx",
-			"args": ["-y", "mcp-server-package"],
-			"env": {
-				"API_KEY": "your-key"
-			}
-		}
-	}
-}
-```
+MCPick-owned state lives under `~/.claude/mcpick/` for historical
+compatibility.
 
-### File Locations
-
-- **Claude Config**: `~/.claude.json` (your main Claude Code
-  configuration)
-- **Project Config**: `.mcp.json` (project-specific shared config,
-  committed to git)
-- **MCPick Registry**: `~/.claude/mcpick/servers.json` (MCPick's
-  server database)
-- **Backups**: `~/.claude/mcpick/backups/` (MCP configuration backups)
-- **Profiles**: `~/.claude/mcpick/profiles/` (predefined server sets)
-- **Plugin Cache**: `~/.claude/plugins/cache/` (cached plugin files)
-- **Installed Plugins**: `~/.claude/plugins/installed_plugins.json`
-  (plugin install registry)
-- **Marketplaces**: `~/.claude/plugins/marketplaces/` (marketplace git
-  clones)
-
-#### MCP Server Storage by Scope
-
-| Scope   | Location                                                     | Use Case                           |
-| ------- | ------------------------------------------------------------ | ---------------------------------- |
-| Local   | `~/.claude.json` → `projects["/path/to/project"].mcpServers` | Personal project config            |
-| Project | `.mcp.json` in project root                                  | Shared team config (commit to git) |
-| User    | `~/.claude.json` → `mcpServers`                              | Global servers for all projects    |
-
-> **Note**: MCPick automatically detects servers in parent
-> directories. If you have local servers configured at
-> `/Users/you/projects` and run MCPick from
-> `/Users/you/projects/myapp`, it will find and display them.
-
-## Safety Features
-
-- **Non-destructive**: Only modifies the `mcpServers` section of your
-  Claude Code config
-- **Backup integration**: Automatically creates backups before major
-  changes
-- **Validation**: Ensures all server configurations are valid before
-  writing
-- **Error handling**: Graceful failure modes with helpful error
-  messages
-
-## Future Features
-
-McPick is actively being developed with new features planned. See the
-[roadmap](./docs/ROADMAP.md) for details on:
-
-- **Settings Validation** - Validate your Claude Code settings files
-  using the
-  [claude-code-settings-schema](https://github.com/spences10/claude-code-settings-schema)
-- **Permissions Management** - Interactive tool permission
-  configuration with presets (Safe Mode, Dev Mode, Review Mode)
-
-Have ideas for other features?
-[Open an issue](https://github.com/spences10/mcpick/issues) or check
-out the [contribution guide](./docs/ROADMAP.md)!
-
-## Requirements
+## Development
 
-- Node.js 22+
-- Claude Code installed and configured
-- pnpm (for building from source)
+```bash
+pnpm install
+pnpm test
+pnpm run check
+pnpm build
+```
+
+See `docs/VENDOR_NEUTRAL_ARCHITECTURE.md` for architecture notes.