mcpick 0.0.9 → 0.0.11

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # mcpick
 
+## 0.0.11
+
+### Patch Changes
+
+- 7ec3323: feat: add plugin install, uninstall, and update commands
+  via Claude CLI
+- 99b2bf3: feat: add plugin install, uninstall, and update to
+  interactive menu
+- 9b1c6d7: feat: add plugin support to backup, restore, and profiles
+
+## 0.0.10
+
+### Patch Changes
+
+- ffe29b3: Add non-interactive CLI mode with citty for scripting and
+  LLM usage
+- fff6c0d: add plugin cache management with staleness detection and
+  cleanup
+
 ## 0.0.9
 
 ### Patch Changes

package/README.md

@@ -1,8 +1,8 @@
 # McPick
 
-A CLI tool for dynamically managing MCP server configurations in
-Claude Code. Enable and disable MCP servers on-demand to optimize
-context usage and performance.
+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.
 
 ## Installation
 
@@ -51,10 +51,15 @@ This can lead to:
 
 ## The Solution
 
-McPick provides an intuitive CLI menu to:
+McPick provides an intuitive CLI menu and non-interactive subcommands
+to:
 
 - ✅ **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,
@@ -71,6 +76,8 @@ McPick provides an intuitive CLI menu to:
 │
 ◆  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
@@ -162,6 +169,104 @@ Or use full format with `mcpServers` wrapper:
 }
 ```
 
+### 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.
+
+#### 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
+
+```bash
+# Show cache status for all plugins
+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
+
+Install, update, and toggle Claude Code marketplace plugins:
+
+```bash
+# List all plugins and their status
+npx mcpick plugins list
+npx mcpick plugins list --json
+
+# Install/uninstall a plugin (wraps claude plugin CLI)
+npx mcpick plugins install plugin-name@marketplace
+npx mcpick plugins uninstall plugin-name@marketplace
+
+# Update a plugin to latest version
+npx mcpick plugins update plugin-name@marketplace
+
+# Enable/disable a plugin
+npx mcpick plugins enable plugin-name@marketplace
+npx mcpick plugins disable plugin-name@marketplace
+```
+
+All plugin commands support `--scope` (user, project, local) and
+`--json` flags.
+
+### CLI Subcommands
+
+McPick supports both an interactive menu (default) and non-interactive
+CLI subcommands for scripting and LLM tool use:
+
+```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
+```
+
+All subcommands support `--json` for machine-readable output.
+
 ### Typical Workflow
 
 1. **Before a coding session**: Run `mcpick -p <profile>` or use the
@@ -209,6 +314,11 @@ MCPick works with the standard Claude Code configuration format:
   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
 

package/dist/cli/commands/add.js

@@ -0,0 +1,135 @@
+import { defineCommand } from 'citty';
+import { add_server_to_registry } from '../../core/registry.js';
+import { validate_mcp_server } from '../../core/validation.js';
+import { add_mcp_via_cli } from '../../utils/claude-cli.js';
+import { error, output } from '../output.js';
+export 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',
+        },
+        scope: {
+            type: 'string',
+            description: 'Scope: local, project, or user (default: local)',
+            default: 'local',
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const scope = args.scope;
+        if (!['local', 'project', 'user'].includes(scope)) {
+            error(`Invalid scope: ${scope}. Use local, project, or user.`);
+        }
+        const transport = args.type;
+        if (!['stdio', 'sse', 'http'].includes(transport)) {
+            error(`Invalid type: ${transport}. Use stdio, sse, or http.`);
+        }
+        // Build server object
+        const server_data = {
+            name: args.name,
+        };
+        if (transport === 'stdio') {
+            if (!args.command) {
+                error('--command is required for stdio transport');
+            }
+            server_data.command = args.command;
+            if (args.args) {
+                server_data.args = args.args.split(',');
+            }
+        }
+        else {
+            if (!args.url) {
+                error(`--url is required for ${transport} transport`);
+            }
+            server_data.type = transport;
+            server_data.url = args.url;
+            if (args.headers) {
+                server_data.headers = parse_key_value_pairs(args.headers);
+            }
+        }
+        if (args.env) {
+            server_data.env = parse_key_value_pairs(args.env);
+        }
+        if (args.description) {
+            server_data.description = args.description;
+        }
+        // Validate
+        let server;
+        try {
+            server = validate_mcp_server(server_data);
+        }
+        catch (err) {
+            error(`Invalid server config: ${err instanceof Error ? err.message : 'validation failed'}`);
+        }
+        // Add to registry
+        await add_server_to_registry(server);
+        // Enable via CLI
+        const result = await add_mcp_via_cli(server, scope);
+        if (args.json) {
+            output({
+                added: server.name,
+                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 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;
+}
+//# sourceMappingURL=add.js.map

package/dist/cli/commands/backup.js

@@ -0,0 +1,83 @@
+import { defineCommand } from 'citty';
+import { readdir, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { read_claude_config } from '../../core/config.js';
+import { read_claude_settings } from '../../core/settings.js';
+import { ensure_directory_exists, get_backup_filename, get_backups_dir, get_plugin_backup_filename, } from '../../utils/paths.js';
+import { output } from '../output.js';
+const MAX_BACKUPS = 10;
+async function cleanup_old_backups(prefix) {
+    try {
+        const backups_dir = get_backups_dir();
+        const files = await readdir(backups_dir);
+        const backup_files = files
+            .filter((f) => f.startsWith(prefix) && f.endsWith('.json'))
+            .sort()
+            .reverse();
+        if (backup_files.length > MAX_BACKUPS) {
+            for (const file of backup_files.slice(MAX_BACKUPS)) {
+                await unlink(join(backups_dir, file));
+            }
+        }
+    }
+    catch {
+        // Cleanup is best-effort
+    }
+}
+export default defineCommand({
+    meta: {
+        name: 'backup',
+        description: 'Create a timestamped backup of MCP servers and plugins',
+    },
+    args: {
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const current_config = await read_claude_config();
+        const current_settings = await read_claude_settings();
+        const backups_dir = get_backups_dir();
+        await ensure_directory_exists(backups_dir);
+        // Backup MCP servers
+        const mcp_filename = get_backup_filename();
+        const mcp_path = join(backups_dir, mcp_filename);
+        const mcp_backup = {
+            mcpServers: current_config.mcpServers || {},
+        };
+        await writeFile(mcp_path, JSON.stringify(mcp_backup, null, 2), 'utf-8');
+        // Backup plugins
+        const plugins = current_settings.enabledPlugins || {};
+        const plugin_count = Object.keys(plugins).length;
+        let plugin_path = null;
+        if (plugin_count > 0) {
+            const plugin_filename = get_plugin_backup_filename();
+            plugin_path = join(backups_dir, plugin_filename);
+            const plugin_backup = { enabledPlugins: plugins };
+            await writeFile(plugin_path, JSON.stringify(plugin_backup, null, 2), 'utf-8');
+        }
+        await cleanup_old_backups('mcp-servers-');
+        await cleanup_old_backups('plugins-');
+        const server_count = Object.keys(current_config.mcpServers || {}).length;
+        if (args.json) {
+            output({
+                mcp: { path: mcp_path, servers: server_count },
+                plugins: plugin_path
+                    ? {
+                        path: plugin_path,
+                        plugins: plugin_count,
+                    }
+                    : null,
+            }, true);
+        }
+        else {
+            console.log(`Backup created: ${mcp_path} (${server_count} servers)`);
+            if (plugin_path) {
+                console.log(`Plugin backup: ${plugin_path} (${plugin_count} plugins)`);
+            }
+        }
+    },
+});
+//# sourceMappingURL=backup.js.map

package/dist/cli/commands/cache.js

@@ -0,0 +1,181 @@
+import { defineCommand } from 'citty';
+import { clean_orphaned_versions, clear_plugin_caches, get_cached_plugins_info, read_installed_plugins, refresh_all_marketplaces, } from '../../core/plugin-cache.js';
+import { error, output } from '../output.js';
+const status = defineCommand({
+    meta: {
+        name: 'status',
+        description: 'Show cached plugins with staleness info',
+    },
+    args: {
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const plugins = await get_cached_plugins_info();
+        if (args.json) {
+            output(plugins, true);
+            return;
+        }
+        if (plugins.length === 0) {
+            console.log('No cached plugins found.');
+            return;
+        }
+        for (const p of plugins) {
+            const stale_markers = [];
+            if (p.isVersionStale) {
+                stale_markers.push(`version: ${p.installedVersion} → ${p.latestVersion}`);
+            }
+            if (p.isShaStale) {
+                stale_markers.push('commits behind');
+            }
+            if (p.orphanedVersions.length > 0) {
+                stale_markers.push(`${p.orphanedVersions.length} orphaned`);
+            }
+            const status_str = stale_markers.length > 0
+                ? `  [stale: ${stale_markers.join(', ')}]`
+                : '  [up to date]';
+            console.log(`${p.name}@${p.marketplace}  v${p.installedVersion}${status_str}`);
+        }
+    },
+});
+const clear = defineCommand({
+    meta: {
+        name: 'clear',
+        description: 'Clear plugin caches (refreshes marketplace first)',
+    },
+    args: {
+        plugin: {
+            type: 'positional',
+            description: 'Plugin key (name@marketplace) — omit for all',
+            required: false,
+        },
+        all: {
+            type: 'boolean',
+            description: 'Clear all plugin caches',
+            default: false,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const installed = await read_installed_plugins();
+        const all_keys = Object.keys(installed.plugins);
+        if (all_keys.length === 0) {
+            if (args.json) {
+                output({ cleared: [], errors: [] }, true);
+            }
+            else {
+                console.log('No cached plugins to clear.');
+            }
+            return;
+        }
+        let keys_to_clear;
+        if (args.plugin) {
+            if (!installed.plugins[args.plugin]) {
+                error(`Plugin '${args.plugin}' not found in cache. Run 'mcpick cache status' to see cached plugins.`);
+            }
+            keys_to_clear = [args.plugin];
+        }
+        else if (args.all) {
+            keys_to_clear = all_keys;
+        }
+        else {
+            error('Specify a plugin key or use --all. Run "mcpick cache status" to see cached plugins.');
+        }
+        const result = await clear_plugin_caches(keys_to_clear);
+        if (args.json) {
+            output(result, true);
+        }
+        else {
+            for (const key of result.cleared) {
+                console.log(`Cleared: ${key}`);
+            }
+            for (const err of result.errors) {
+                console.error(`Error: ${err}`);
+            }
+            if (result.cleared.length > 0) {
+                console.log('\nRun /reload-plugins in Claude Code or restart your session.');
+            }
+        }
+    },
+});
+const clean_orphaned = defineCommand({
+    meta: {
+        name: 'clean-orphaned',
+        description: 'Remove orphaned plugin version directories',
+    },
+    args: {
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const result = await clean_orphaned_versions();
+        if (args.json) {
+            output(result, true);
+        }
+        else if (result.cleaned === 0) {
+            console.log('No orphaned versions found.');
+        }
+        else {
+            for (const p of result.paths) {
+                console.log(`Removed: ${p}`);
+            }
+            console.log(`\nCleaned ${result.cleaned} orphaned version(s).`);
+        }
+    },
+});
+const refresh = defineCommand({
+    meta: {
+        name: 'refresh',
+        description: 'Refresh all marketplace clones (git pull)',
+    },
+    args: {
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const results = await refresh_all_marketplaces();
+        if (args.json) {
+            const data = Object.fromEntries(results);
+            output(data, true);
+            return;
+        }
+        if (results.size === 0) {
+            console.log('No marketplaces configured.');
+            return;
+        }
+        for (const [name, result] of results) {
+            if (result.success) {
+                console.log(`${name}  refreshed`);
+            }
+            else {
+                console.error(`${name}  failed: ${result.error}`);
+            }
+        }
+    },
+});
+export default defineCommand({
+    meta: {
+        name: 'cache',
+        description: 'Manage plugin cache',
+    },
+    subCommands: {
+        status,
+        clear,
+        'clean-orphaned': clean_orphaned,
+        refresh,
+    },
+});
+//# sourceMappingURL=cache.js.map

package/dist/cli/commands/disable.js

@@ -0,0 +1,33 @@
+import { defineCommand } from 'citty';
+import { remove_mcp_via_cli } from '../../utils/claude-cli.js';
+import { error } from '../output.js';
+export default defineCommand({
+    meta: {
+        name: 'disable',
+        description: 'Disable an MCP server',
+    },
+    args: {
+        server: {
+            type: 'positional',
+            description: 'Server name to disable',
+            required: true,
+        },
+        scope: {
+            type: 'string',
+            description: 'Scope: local, project, or user (default: local)',
+            default: 'local',
+        },
+    },
+    async run({ args }) {
+        const scope = args.scope;
+        if (!['local', 'project', 'user'].includes(scope)) {
+            error(`Invalid scope: ${scope}. Use local, project, or user.`);
+        }
+        const result = await remove_mcp_via_cli(args.server);
+        if (!result.success) {
+            error(result.error || 'Failed to disable server');
+        }
+        console.log(`Disabled '${args.server}' (scope: ${scope})`);
+    },
+});
+//# sourceMappingURL=disable.js.map

package/dist/cli/commands/enable.js

@@ -0,0 +1,39 @@
+import { defineCommand } from 'citty';
+import { get_all_available_servers } from '../../core/registry.js';
+import { add_mcp_via_cli } from '../../utils/claude-cli.js';
+import { error } from '../output.js';
+export default defineCommand({
+    meta: {
+        name: 'enable',
+        description: 'Enable an MCP server',
+    },
+    args: {
+        server: {
+            type: 'positional',
+            description: 'Server name to enable',
+            required: true,
+        },
+        scope: {
+            type: 'string',
+            description: 'Scope: local, project, or user (default: local)',
+            default: 'local',
+        },
+    },
+    async run({ args }) {
+        const scope = args.scope;
+        if (!['local', 'project', 'user'].includes(scope)) {
+            error(`Invalid scope: ${scope}. Use local, project, or user.`);
+        }
+        const all_servers = await get_all_available_servers();
+        const server = all_servers.find((s) => s.name === args.server);
+        if (!server) {
+            error(`Server '${args.server}' not found in registry. Run 'mcpick list' to see available servers.`);
+        }
+        const result = await add_mcp_via_cli(server, scope);
+        if (!result.success) {
+            error(result.error || 'Failed to enable server');
+        }
+        console.log(`Enabled '${server.name}' (scope: ${scope})`);
+    },
+});
+//# sourceMappingURL=enable.js.map