mcpick 0.0.18 → 0.0.20

package/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: package.json
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm run build
+
+      - run: pnpm run test

package/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+	"editor.defaultFormatter": "oxc.oxc-vscode",
+	"editor.formatOnSave": true,
+	"oxc.fmt.configPath": "./vite.config.ts"
+}

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # mcpick
 
+## 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
+
+## 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
+
 ## 0.0.18
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Spence
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/add-BDyaBew0.js

@@ -0,0 +1,113 @@
+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 { 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"
+		},
+		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.`);
+		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;
+		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 (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;
+}
+//#endregion
+export { add_default as default };
+
+//# sourceMappingURL=add-BDyaBew0.js.map

package/dist/add-json-BjgzdeG-.js

@@ -0,0 +1,58 @@
+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 { 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
+		},
+		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.`);
+		try {
+			JSON.parse(args.config);
+		} catch {
+			error("Invalid JSON configuration. Provide a valid JSON string.");
+		}
+		const result = await mcp_add_json_via_cli(args.name, args.config, scope);
+		if (args.json) output({
+			added: args.name,
+			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");
+	}
+});
+//#endregion
+export { add_json_default as default };
+
+//# sourceMappingURL=add-json-BjgzdeG-.js.map

package/dist/atomic-write-BqEykHp9.js

@@ -0,0 +1,26 @@
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+//#region src/utils/atomic-write.ts
+/**
+* Atomically write a JSON file with fresh-read merging.
+*
+* 1. Re-reads the file right before writing to pick up concurrent changes
+* 2. Applies the merge function to the freshest data
+* 3. Writes to a temp file, then renames (atomic on same filesystem)
+*/
+async function atomic_json_write(file_path, merge) {
+	let existing = {};
+	try {
+		const content = await readFile(file_path, "utf-8");
+		existing = JSON.parse(content);
+	} catch {}
+	const merged = merge(existing);
+	const content = JSON.stringify(merged, null, 2);
+	const tmp_path = join(dirname(file_path), `.${Date.now()}.tmp`);
+	await writeFile(tmp_path, content, "utf-8");
+	await rename(tmp_path, file_path);
+}
+//#endregion
+export { atomic_json_write as t };
+
+//# sourceMappingURL=atomic-write-BqEykHp9.js.map

package/dist/backup-DSDhHI5f.js

@@ -0,0 +1,64 @@
+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 { readdir, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { defineCommand } from "citty";
+//#region src/cli/commands/backup.ts
+const MAX_BACKUPS = 10;
+async function cleanup_old_backups(prefix) {
+	try {
+		const backups_dir = get_backups_dir();
+		const backup_files = (await readdir(backups_dir)).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 {}
+}
+var backup_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);
+		const mcp_path = join(backups_dir, get_backup_filename());
+		const mcp_backup = { mcpServers: current_config.mcpServers || {} };
+		await writeFile(mcp_path, JSON.stringify(mcp_backup, null, 2), "utf-8");
+		const plugins = current_settings.enabledPlugins || {};
+		const plugin_count = Object.keys(plugins).length;
+		let plugin_path = null;
+		if (plugin_count > 0) {
+			plugin_path = join(backups_dir, get_plugin_backup_filename());
+			await writeFile(plugin_path, JSON.stringify({ enabledPlugins: plugins }, 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)`);
+		}
+	}
+});
+//#endregion
+export { backup_default as default };
+
+//# sourceMappingURL=backup-DSDhHI5f.js.map

package/dist/cache-D6kd7qE8.js

@@ -0,0 +1,226 @@
+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 { defineCommand } from "citty";
+var cache_default = defineCommand({
+	meta: {
+		name: "cache",
+		description: "Manage plugin cache"
+	},
+	subCommands: {
+		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}`);
+				}
+			}
+		}),
+		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 installed_keys = Object.keys(installed.plugins);
+				const scanned_keys = args.all ? await scan_all_cache_keys() : [];
+				const all_keys = [...new Set([...installed_keys, ...scanned_keys])];
+				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] && !scanned_keys.includes(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.");
+				}
+			}
+		}),
+		"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).`);
+				}
+			}
+		}),
+		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) {
+					output(Object.fromEntries(results), 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}`);
+			}
+		}),
+		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");
+			}
+		}),
+		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");
+			}
+		}),
+		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}`);
+				}
+			}
+		})
+	}
+});
+//#endregion
+export { cache_default as default };
+
+//# sourceMappingURL=cache-D6kd7qE8.js.map