mcpick 0.0.13 → 0.0.14

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # mcpick
 
+## 0.0.14
+
+### Patch Changes
+
+- 0170ea0: Add local dev workflow: mcpick dev + cache link/unlink
+
 ## 0.0.13
 
 ### Patch Changes

package/dist/cli/commands/cache.js

@@ -1,5 +1,5 @@
 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 { clean_orphaned_versions, clear_plugin_caches, get_cached_plugins_info, link_local_plugin, list_linked_plugins, read_installed_plugins, refresh_all_marketplaces, unlink_local_plugin, } from '../../core/plugin-cache.js';
 import { error, output } from '../output.js';
 const status = defineCommand({
     meta: {
@@ -166,6 +166,111 @@ const refresh = defineCommand({
         }
     },
 });
+const link = defineCommand({
+    meta: {
+        name: 'link',
+        description: 'Symlink a local directory into the plugin cache for dev',
+    },
+    args: {
+        path: {
+            type: 'positional',
+            description: 'Local path to the plugin/marketplace directory',
+            required: true,
+        },
+        as: {
+            type: 'string',
+            description: 'Plugin key (name@marketplace) for the cache entry',
+            required: true,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        if (!args.as) {
+            error('--as is required. Specify plugin key as name@marketplace.');
+        }
+        if (!args.as.includes('@')) {
+            error('Plugin key must be in name@marketplace format (e.g. my-plugin@my-marketplace)');
+        }
+        const result = await link_local_plugin(args.path, args.as);
+        if (args.json) {
+            output(result, true);
+        }
+        else if (result.success) {
+            console.log(`Linked: ${result.key}`);
+            console.log(`  ${result.symlinkPath} → ${result.targetPath}`);
+            console.log('\nRun /reload-plugins in Claude Code or restart your session.');
+        }
+        else {
+            error(result.error || 'Unknown error');
+        }
+    },
+});
+const unlink = defineCommand({
+    meta: {
+        name: 'unlink',
+        description: 'Remove a symlink from the plugin cache',
+    },
+    args: {
+        key: {
+            type: 'positional',
+            description: 'Plugin key (name@marketplace)',
+            required: true,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const result = await unlink_local_plugin(args.key);
+        if (args.json) {
+            output(result, true);
+        }
+        else if (result.success) {
+            console.log(`Unlinked: ${args.key}`);
+            if (result.restored) {
+                console.log('  Original cache directory restored from backup.');
+            }
+            console.log('\nRun /reload-plugins in Claude Code or restart your session.');
+        }
+        else {
+            error(result.error || 'Unknown error');
+        }
+    },
+});
+const links = defineCommand({
+    meta: {
+        name: 'links',
+        description: 'List all symlinked plugin cache entries',
+    },
+    args: {
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const linked = await list_linked_plugins();
+        if (args.json) {
+            output(linked, true);
+            return;
+        }
+        if (linked.length === 0) {
+            console.log('No linked plugins.');
+            return;
+        }
+        for (const l of linked) {
+            console.log(`${l.key}`);
+            console.log(`  ${l.symlinkPath} → ${l.targetPath}`);
+        }
+    },
+});
 export default defineCommand({
     meta: {
         name: 'cache',
@@ -176,6 +281,9 @@ export default defineCommand({
         clear,
         'clean-orphaned': clean_orphaned,
         refresh,
+        link,
+        unlink,
+        links,
     },
 });
 //# sourceMappingURL=cache.js.map

package/dist/cli/commands/dev.js

@@ -0,0 +1,162 @@
+import { defineCommand } from 'citty';
+import { apply_dev_override, list_dev_overrides, restore_all_dev_overrides, restore_dev_override, } from '../../core/dev-override.js';
+import { error, output } from '../output.js';
+const apply = defineCommand({
+    meta: {
+        name: 'apply',
+        description: 'Override an MCP server with a local dev command',
+    },
+    args: {
+        name: {
+            type: 'positional',
+            description: 'Server name to override',
+            required: true,
+        },
+        command: {
+            type: 'string',
+            description: 'Local command to run',
+            required: true,
+        },
+        args: {
+            type: 'string',
+            description: 'Comma-separated arguments',
+        },
+        scope: {
+            type: 'string',
+            description: 'Scope to search: local, project, or user (default: auto-detect)',
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const scope = args.scope;
+        if (scope && !['local', 'project', 'user'].includes(scope)) {
+            error(`Invalid scope: ${scope}. Use local, project, or user.`);
+        }
+        const cmd_args = args.args
+            ? args.args.split(',')
+            : [];
+        const result = await apply_dev_override(args.name, args.command, cmd_args, scope);
+        if (args.json) {
+            output(result, true);
+        }
+        else if (result.success) {
+            console.log(`Dev override applied for '${args.name}' (scope: ${result.scope})`);
+            console.log(`  command: ${args.command}${cmd_args.length > 0 ? ` ${cmd_args.join(' ')}` : ''}`);
+            console.log('\nRestart Claude Code or run /reload-plugins to pick up changes.');
+        }
+        else {
+            error(result.error || 'Unknown error');
+        }
+    },
+});
+const restore = defineCommand({
+    meta: {
+        name: 'restore',
+        description: 'Restore original server config from dev override',
+    },
+    args: {
+        name: {
+            type: 'positional',
+            description: 'Server name to restore (omit with --all to restore all)',
+            required: false,
+        },
+        all: {
+            type: 'boolean',
+            description: 'Restore all dev overrides',
+            default: false,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        if (args.all) {
+            const result = await restore_all_dev_overrides();
+            if (args.json) {
+                output(result, true);
+            }
+            else {
+                if (result.restored.length === 0 && result.errors.length === 0) {
+                    console.log('No dev overrides to restore.');
+                }
+                else {
+                    for (const name of result.restored) {
+                        console.log(`Restored: ${name}`);
+                    }
+                    for (const err of result.errors) {
+                        console.error(`Error: ${err}`);
+                    }
+                }
+            }
+            return;
+        }
+        if (!args.name) {
+            error('Specify a server name or use --all. Run "mcpick dev list" to see active overrides.');
+        }
+        const result = await restore_dev_override(args.name);
+        if (args.json) {
+            output(result, true);
+        }
+        else if (result.success) {
+            console.log(`Restored original config for '${args.name}'`);
+            console.log('\nRestart Claude Code or run /reload-plugins to pick up changes.');
+        }
+        else {
+            error(result.error || 'Unknown error');
+        }
+    },
+});
+const list = defineCommand({
+    meta: {
+        name: 'list',
+        description: 'List active dev overrides',
+    },
+    args: {
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const overrides = await list_dev_overrides();
+        if (args.json) {
+            output(overrides, true);
+            return;
+        }
+        if (overrides.length === 0) {
+            console.log('No active dev overrides.');
+            return;
+        }
+        for (const o of overrides) {
+            const orig = o.original;
+            const dev = o.dev;
+            const original_cmd = orig.command
+                ? `${orig.command}${orig.args ? ' ' + orig.args.join(' ') : ''}`
+                : orig.url || '?';
+            const dev_cmd = `${dev.command}${dev.args ? ' ' + dev.args.join(' ') : ''}`;
+            console.log(`${o.name}  (scope: ${o.scope})`);
+            console.log(`  original: ${original_cmd}`);
+            console.log(`  dev:      ${dev_cmd}`);
+            console.log(`  since:    ${o.createdAt}`);
+        }
+    },
+});
+export default defineCommand({
+    meta: {
+        name: 'dev',
+        description: 'MCP server local development workflow',
+    },
+    subCommands: {
+        apply,
+        restore,
+        list,
+    },
+});
+//# sourceMappingURL=dev.js.map

package/dist/cli/index.js

@@ -15,6 +15,7 @@ const main = defineCommand({
         profile: () => import('./commands/profile.js').then((m) => m.default),
         plugins: () => import('./commands/plugins.js').then((m) => m.default),
         cache: () => import('./commands/cache.js').then((m) => m.default),
+        dev: () => import('./commands/dev.js').then((m) => m.default),
     },
 });
 export const run = () => runMain(main);

package/dist/core/dev-override.js

@@ -0,0 +1,210 @@
+import { access, readFile } from 'node:fs/promises';
+import { atomic_json_write } from '../utils/atomic-write.js';
+import { get_claude_config_path, get_current_project_path, get_dev_overrides_path, get_project_mcp_json_path, } from '../utils/paths.js';
+const EMPTY_OVERRIDES = {
+    version: 1,
+    overrides: {},
+};
+export async function read_dev_overrides() {
+    try {
+        const content = await readFile(get_dev_overrides_path(), 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return { ...EMPTY_OVERRIDES, overrides: {} };
+    }
+}
+async function write_dev_overrides(data) {
+    await atomic_json_write(get_dev_overrides_path(), () => data);
+}
+/**
+ * Read full config for a given scope and return the server entry if found.
+ * Returns { config, server, scope } or null.
+ */
+async function find_server_in_scope(name, scope) {
+    if (scope === 'user' || scope === 'local') {
+        const config_path = get_claude_config_path();
+        try {
+            await access(config_path);
+            const content = await readFile(config_path, 'utf-8');
+            const parsed = JSON.parse(content);
+            if (scope === 'user') {
+                const server = parsed.mcpServers?.[name];
+                if (server)
+                    return { server, scope: 'user' };
+            }
+            else {
+                // local scope: projects[cwd].mcpServers
+                const cwd = get_current_project_path();
+                const server = parsed.projects?.[cwd]?.mcpServers?.[name];
+                if (server)
+                    return { server, scope: 'local' };
+            }
+        }
+        catch {
+            // File doesn't exist
+        }
+    }
+    else if (scope === 'project') {
+        const mcp_path = get_project_mcp_json_path();
+        try {
+            await access(mcp_path);
+            const content = await readFile(mcp_path, 'utf-8');
+            const parsed = JSON.parse(content);
+            const server = parsed.mcpServers?.[name];
+            if (server)
+                return { server, scope: 'project' };
+        }
+        catch {
+            // File doesn't exist
+        }
+    }
+    return null;
+}
+/**
+ * Auto-detect which scope a server lives in.
+ * Searches local → project → user.
+ */
+async function detect_server_scope(name) {
+    for (const scope of ['local', 'project', 'user']) {
+        const result = await find_server_in_scope(name, scope);
+        if (result)
+            return result;
+    }
+    return null;
+}
+/**
+ * Write a server config into the appropriate scope config file.
+ */
+async function write_server_to_scope(name, server, scope) {
+    if (scope === 'user') {
+        await atomic_json_write(get_claude_config_path(), (existing) => {
+            if (!existing.mcpServers) {
+                existing.mcpServers = {};
+            }
+            existing.mcpServers[name] =
+                server;
+            return existing;
+        });
+    }
+    else if (scope === 'local') {
+        const cwd = get_current_project_path();
+        await atomic_json_write(get_claude_config_path(), (existing) => {
+            if (!existing.projects) {
+                existing.projects = {};
+            }
+            const projects = existing.projects;
+            if (!projects[cwd]) {
+                projects[cwd] = {};
+            }
+            if (!projects[cwd].mcpServers) {
+                projects[cwd].mcpServers = {};
+            }
+            projects[cwd].mcpServers[name] = server;
+            return existing;
+        });
+    }
+    else if (scope === 'project') {
+        await atomic_json_write(get_project_mcp_json_path(), (existing) => {
+            if (!existing.mcpServers) {
+                existing.mcpServers = {};
+            }
+            existing.mcpServers[name] =
+                server;
+            return existing;
+        });
+    }
+}
+/**
+ * Apply a dev override: store original config, swap in local dev command.
+ */
+export async function apply_dev_override(name, command, args, scope) {
+    // Find the server
+    let found;
+    if (scope) {
+        found = await find_server_in_scope(name, scope);
+    }
+    else {
+        found = await detect_server_scope(name);
+    }
+    if (!found) {
+        return {
+            success: false,
+            scope: scope || 'local',
+            error: `Server '${name}' not found${scope ? ` in ${scope} scope` : ' in any scope'}`,
+        };
+    }
+    // Check not already overridden
+    const overrides = await read_dev_overrides();
+    if (overrides.overrides[name]) {
+        return {
+            success: false,
+            scope: found.scope,
+            error: `Server '${name}' already has a dev override. Run 'mcpick dev --restore ${name}' first.`,
+        };
+    }
+    // Build dev server config
+    const dev_server = {
+        command,
+        ...(args.length > 0 ? { args } : {}),
+    };
+    // Store original
+    overrides.overrides[name] = {
+        original: found.server,
+        dev: dev_server,
+        scope: found.scope,
+        createdAt: new Date().toISOString(),
+    };
+    await write_dev_overrides(overrides);
+    // Write dev config
+    await write_server_to_scope(name, dev_server, found.scope);
+    return { success: true, scope: found.scope };
+}
+/**
+ * Restore original server config from dev override.
+ */
+export async function restore_dev_override(name) {
+    const overrides = await read_dev_overrides();
+    const entry = overrides.overrides[name];
+    if (!entry) {
+        return {
+            success: false,
+            error: `No dev override found for '${name}'`,
+        };
+    }
+    // Write original config back
+    await write_server_to_scope(name, entry.original, entry.scope);
+    // Remove override entry
+    delete overrides.overrides[name];
+    await write_dev_overrides(overrides);
+    return { success: true };
+}
+/**
+ * Restore all dev overrides.
+ */
+export async function restore_all_dev_overrides() {
+    const overrides = await read_dev_overrides();
+    const restored = [];
+    const errors = [];
+    for (const name of Object.keys(overrides.overrides)) {
+        const result = await restore_dev_override(name);
+        if (result.success) {
+            restored.push(name);
+        }
+        else {
+            errors.push(`${name}: ${result.error}`);
+        }
+    }
+    return { restored, errors };
+}
+/**
+ * List all active dev overrides.
+ */
+export async function list_dev_overrides() {
+    const overrides = await read_dev_overrides();
+    return Object.entries(overrides.overrides).map(([name, entry]) => ({
+        name,
+        ...entry,
+    }));
+}
+//# sourceMappingURL=dev-override.js.map

package/dist/core/plugin-cache.js

@@ -1,9 +1,9 @@
 import { exec } from 'node:child_process';
-import { readdir, readFile, rm } from 'node:fs/promises';
+import { lstat, readdir, readFile, readlink, rename, rm, symlink } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { promisify } from 'node:util';
 import { atomic_json_write } from '../utils/atomic-write.js';
-import { get_installed_plugins_path, get_known_marketplaces_path, get_marketplace_manifest_path, get_plugin_cache_dir, } from '../utils/paths.js';
+import { ensure_directory_exists, get_installed_plugins_path, get_known_marketplaces_path, get_marketplace_manifest_path, get_plugin_cache_dir, } from '../utils/paths.js';
 const execAsync = promisify(exec);
 const EMPTY_INSTALLED = {
     version: 2,
@@ -99,7 +99,7 @@ async function find_orphaned_versions(marketplace, plugin_name) {
     return orphaned;
 }
 // --- Staleness analysis ---
-function parse_plugin_key(key) {
+export function parse_plugin_key(key) {
     const at_index = key.lastIndexOf('@');
     return {
         name: at_index > 0 ? key.substring(0, at_index) : key,
@@ -257,4 +257,160 @@ export async function clean_orphaned_versions() {
     }
     return { cleaned: cleaned_paths.length, paths: cleaned_paths };
 }
+// --- Cache linking ---
+/**
+ * Symlink a local directory into the plugin cache.
+ * Backs up existing cache directory if present.
+ */
+export async function link_local_plugin(local_path, key) {
+    const resolved_path = resolve(local_path);
+    const { name, marketplace } = parse_plugin_key(key);
+    // Validate local path exists
+    try {
+        const stat = await lstat(resolved_path);
+        if (!stat.isDirectory()) {
+            return {
+                success: false,
+                key,
+                symlinkPath: '',
+                targetPath: resolved_path,
+                error: `Path is not a directory: ${resolved_path}`,
+            };
+        }
+    }
+    catch {
+        return {
+            success: false,
+            key,
+            symlinkPath: '',
+            targetPath: resolved_path,
+            error: `Path does not exist: ${resolved_path}`,
+        };
+    }
+    const cache_dir = get_plugin_cache_dir();
+    const plugin_dir = join(cache_dir, marketplace, name);
+    // Ensure parent directory exists
+    await ensure_directory_exists(join(cache_dir, marketplace));
+    // If plugin_dir exists and is not a symlink, back it up
+    try {
+        const stat = await lstat(plugin_dir);
+        if (stat.isSymbolicLink()) {
+            // Already a symlink — remove it
+            await rm(plugin_dir);
+        }
+        else if (stat.isDirectory()) {
+            // Back up existing directory
+            const backup_path = `${plugin_dir}.backup`;
+            await rename(plugin_dir, backup_path);
+        }
+    }
+    catch {
+        // Doesn't exist — fine
+    }
+    // Create symlink
+    try {
+        await symlink(resolved_path, plugin_dir, 'dir');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        return {
+            success: false,
+            key,
+            symlinkPath: plugin_dir,
+            targetPath: resolved_path,
+            error: `Failed to create symlink: ${msg}`,
+        };
+    }
+    return {
+        success: true,
+        key,
+        symlinkPath: plugin_dir,
+        targetPath: resolved_path,
+    };
+}
+/**
+ * Remove a symlink from the plugin cache and restore backup if present.
+ */
+export async function unlink_local_plugin(key) {
+    const { name, marketplace } = parse_plugin_key(key);
+    const cache_dir = get_plugin_cache_dir();
+    const plugin_dir = join(cache_dir, marketplace, name);
+    // Verify it's actually a symlink
+    try {
+        const stat = await lstat(plugin_dir);
+        if (!stat.isSymbolicLink()) {
+            return {
+                success: false,
+                key,
+                restored: false,
+                error: `'${key}' is not a symlink — nothing to unlink`,
+            };
+        }
+    }
+    catch {
+        return {
+            success: false,
+            key,
+            restored: false,
+            error: `'${key}' not found in cache`,
+        };
+    }
+    // Remove symlink
+    await rm(plugin_dir);
+    // Restore backup if present
+    const backup_path = `${plugin_dir}.backup`;
+    let restored = false;
+    try {
+        await lstat(backup_path);
+        await rename(backup_path, plugin_dir);
+        restored = true;
+    }
+    catch {
+        // No backup to restore
+    }
+    return { success: true, key, restored };
+}
+/**
+ * List all symlinked entries in the plugin cache.
+ */
+export async function list_linked_plugins() {
+    const cache_dir = get_plugin_cache_dir();
+    const links = [];
+    try {
+        const marketplaces = await readdir(cache_dir, { withFileTypes: true });
+        for (const mkt of marketplaces) {
+            if (!mkt.isDirectory() && !mkt.isSymbolicLink())
+                continue;
+            const mkt_path = join(cache_dir, mkt.name);
+            let entries;
+            try {
+                entries = await readdir(mkt_path, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                const entry_path = join(mkt_path, entry.name);
+                try {
+                    const stat = await lstat(entry_path);
+                    if (stat.isSymbolicLink()) {
+                        const target = await readlink(entry_path);
+                        links.push({
+                            key: `${entry.name}@${mkt.name}`,
+                            symlinkPath: entry_path,
+                            targetPath: resolve(join(cache_dir, mkt.name), target),
+                        });
+                    }
+                }
+                catch {
+                    // Skip on error
+                }
+            }
+        }
+    }
+    catch {
+        // Cache dir doesn't exist
+    }
+    return links;
+}
 //# sourceMappingURL=plugin-cache.js.map

package/dist/index.js

@@ -281,6 +281,7 @@ const SUBCOMMANDS = new Set([
     'profile',
     'plugins',
     'cache',
+    'dev',
 ]);
 const arg = process.argv[2];
 if ((arg && SUBCOMMANDS.has(arg)) ||

package/dist/utils/paths.js

@@ -31,6 +31,9 @@ export function get_claude_settings_path() {
 export function get_mcpick_dir() {
     return join(get_base_dir().baseDir, 'mcpick');
 }
+export function get_dev_overrides_path() {
+    return join(get_mcpick_dir(), 'dev-overrides.json');
+}
 export function get_server_registry_path() {
     return join(get_mcpick_dir(), 'servers.json');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpick",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "Dynamic MCP server and plugin configuration manager for Claude Code",
   "type": "module",
   "main": "./dist/index.js",