From 6cdec1e85bb6c464579120eee893b813063e1ad5 Mon Sep 17 00:00:00 2001 From: divyanshujethi Date: Tue, 17 Nov 2026 16:48:07 +0530 Subject: [PATCH] feat(cli): add 1-click MCP registry installer (npx devshelf install ) for Claude, Cursor, and Windsurf --- bin/cli.js | 171 +++++++++++++++- bin/lib/mcp-installer.js | 379 ++++++++++++++++++++++++++++++++++++ tests/mcp-installer.test.ts | 76 ++++++++ 3 files changed, 624 insertions(+), 2 deletions(-) create mode 100644 bin/lib/mcp-installer.js create mode 100644 tests/mcp-installer.test.ts diff --git a/bin/cli.js b/bin/cli.js index 3b2e3be0..4597d8a8 100644 --- a/bin/cli.js +++ b/bin/cli.js @@ -25,8 +25,8 @@ import { refreshCatalog, searchCatalog, } from "./lib/catalog.js"; -import { loadSponsors } from "./lib/sponsors.js"; import { loadNewsletter } from "./lib/newsletter.js"; +import { loadSponsors } from "./lib/sponsors.js"; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); @@ -167,6 +167,9 @@ ${c.bold}USAGE:${c.reset} ${c.green}npx devshelf daily [--quiet]${c.reset} Print today's curated open-source discovery ${c.green}npx devshelf search [options]${c.reset} Fuzzy search tools, APIs, and AI agents ${c.green}npx devshelf explain ${c.reset} Deep-dive tool explainer, install command & Docker + ${c.green}npx devshelf install ${c.reset} 1-Click install MCP server into Claude, Cursor & Windsurf + ${c.green}npx devshelf uninstall ${c.reset} Remove MCP server from client configurations + ${c.green}npx devshelf mcp:list${c.reset} List installed MCP servers across AI coding clients ${c.green}npx devshelf contribute [query]${c.reset} Find repos actively seeking help & starter tasks ${c.green}npx devshelf list [category]${c.reset} List items by category ${c.green}npx devshelf random${c.reset} Discover a random curated resource @@ -184,6 +187,9 @@ ${c.bold}OPTIONS:${c.reset} ${c.cyan}-t, --tag ${c.reset} Filter by semantic tag (e.g. "No Card Required", "mcp") ${c.cyan}--free-tier-storage, --storage ${c.reset} Filter by free-tier storage threshold (e.g. "500mb", "1gb") ${c.cyan}-c, --category ${c.reset} Filter by category (e.g. "ai", "apis", "database") + ${c.cyan}--target ${c.reset} Target specific clients: claude, cursor, windsurf + ${c.cyan}--workspace, -w${c.reset} Write Cursor config to local .cursor/mcp.json + ${c.cyan}--dry-run${c.reset} Preview configuration changes without writing ${c.cyan}-q, --quiet${c.reset} Ultra-compact output for .zshrc / .bashrc execution ${c.cyan}--json${c.reset} Output raw JSON results for piping ${c.cyan}--open${c.reset} Open first result in browser @@ -192,6 +198,9 @@ ${c.bold}OPTIONS:${c.reset} ${c.bold}EXAMPLES:${c.reset} ${c.gray}$${c.reset} npx devshelf search "postgres" --free-tier-storage 500mb + ${c.gray}$${c.reset} npx devshelf install filesystem + ${c.gray}$${c.reset} npx devshelf install sqlite --target claude,cursor + ${c.gray}$${c.reset} npx devshelf mcp:list ${c.gray}$${c.reset} npx devshelf search "agent" --tag "mcp" ${c.gray}$${c.reset} npx devshelf search "postman" ${c.gray}$${c.reset} npx devshelf daily --quiet @@ -638,7 +647,15 @@ async function main() { const a = args[i]; if (a.startsWith("-")) { if ( - ["-t", "--tag", "--free-tier-storage", "--storage", "-c", "--category"].includes(a) && + [ + "-t", + "--tag", + "--free-tier-storage", + "--storage", + "-c", + "--category", + "--target", + ].includes(a) && i + 1 < args.length && !args[i + 1].startsWith("-") ) { @@ -1281,6 +1298,156 @@ async function main() { return; } + if (command === "install" || command === "add") { + const toolSlug = cleanArgs[1]; + const targetOption = getOption("--target"); + const dryRun = args.includes("--dry-run"); + const workspace = args.includes("--workspace") || args.includes("-w"); + + const { installMcpServer, VERIFIED_MCP_REGISTRY } = await import("./lib/mcp-installer.js"); + + if (!toolSlug) { + printHeader(); + console.log(`\n ${c.bold}⚡ 1-Click MCP Registry Installer${c.reset}`); + console.log( + ` ${c.gray}Writes verified MCP server configs directly into Claude Desktop, Cursor & Windsurf.${c.reset}\n`, + ); + console.log( + ` ${c.amber}Usage:${c.reset} ${c.green}npx devshelf install [options]${c.reset}\n`, + ); + console.log(` ${c.cyan}Popular Verified MCP Tools:${c.reset}`); + for (const [slug, meta] of Object.entries(VERIFIED_MCP_REGISTRY)) { + console.log( + ` • ${c.bold}${c.green}${slug.padEnd(16)}${c.reset} ${c.gray}${meta.description}${c.reset}`, + ); + } + console.log( + `\n ${c.gray}Options: --target claude,cursor,windsurf | --workspace | --dry-run${c.reset}\n`, + ); + return; + } + + const result = installMcpServer(toolSlug, { + target: targetOption, + dryRun, + workspace, + }); + + if (isJson) { + console.log(JSON.stringify(result, null, 2)); + return; + } + + printHeader(); + console.log(`\n ${c.bold}⚡ 1-Click MCP Registry Installer${c.reset}`); + console.log( + ` Configuring: ${c.bold}${c.green}${result.definition.name}${c.reset} (${c.cyan}${result.definition.serverKey}${c.reset})`, + ); + console.log( + ` Command: ${c.gray}${result.definition.config.command} ${result.definition.config.args.join(" ")}${c.reset}\n`, + ); + + for (const res of result.results) { + const clientLabel = + res.client === "claude" + ? "Claude Desktop" + : res.client === "cursor" + ? "Cursor" + : "Windsurf"; + if (res.success) { + const actionLabel = + res.action === "dry-run" + ? "[dry-run]" + : res.action === "updated" + ? "Updated" + : "Installed"; + console.log( + ` ${c.green}✔${c.reset} ${c.bold}${clientLabel.padEnd(16)}${c.reset} ${c.green}${actionLabel}${c.reset} → ${c.gray}${res.path}${c.reset}`, + ); + } else { + console.log( + ` ${c.red}✖${c.reset} ${c.bold}${clientLabel.padEnd(16)}${c.reset} ${c.red}Failed${c.reset} (${res.error})`, + ); + } + } + + console.log( + `\n ${c.purple}✨ Done! Restart your AI client (Claude, Cursor, or Windsurf) to activate.${c.reset}\n`, + ); + return; + } + + if (command === "uninstall" || command === "remove") { + const toolSlug = cleanArgs[1]; + if (!toolSlug) { + console.error( + `${c.red}Error:${c.reset} Please specify tool slug to uninstall. Example: npx devshelf uninstall filesystem`, + ); + process.exit(1); + } + const { uninstallMcpServer } = await import("./lib/mcp-installer.js"); + const targetOption = getOption("--target"); + const workspace = args.includes("--workspace") || args.includes("-w"); + const res = uninstallMcpServer(toolSlug, { target: targetOption, workspace }); + + if (isJson) { + console.log(JSON.stringify(res, null, 2)); + return; + } + + printHeader(); + console.log( + `\n ${c.bold}🗑️ MCP Server Uninstaller${c.reset}: ${c.amber}${toolSlug}${c.reset}\n`, + ); + for (const r of res.results) { + const clientLabel = + r.client === "claude" ? "Claude Desktop" : r.client === "cursor" ? "Cursor" : "Windsurf"; + if (r.action === "removed") { + console.log( + ` ${c.green}✔${c.reset} ${c.bold}${clientLabel.padEnd(16)}${c.reset} Removed from ${c.gray}${r.path}${c.reset}`, + ); + } else { + console.log( + ` ${c.gray}•${c.reset} ${c.bold}${clientLabel.padEnd(16)}${c.reset} Not found in ${c.gray}${r.path}${c.reset}`, + ); + } + } + console.log(`\n ${c.green}✨ Uninstallation complete.${c.reset}\n`); + return; + } + + if (command === "mcp:list" || command === "mcp:installed") { + const { listInstalledMcpServers } = await import("./lib/mcp-installer.js"); + const workspace = args.includes("--workspace") || args.includes("-w"); + const installed = listInstalledMcpServers({ workspace }); + + if (isJson) { + console.log(JSON.stringify(installed, null, 2)); + return; + } + + printHeader(); + console.log(`\n ${c.bold}🔌 Installed MCP Servers Across AI Clients${c.reset}\n`); + for (const [client, data] of Object.entries(installed)) { + const clientLabel = + client === "claude" ? "Claude Desktop" : client === "cursor" ? "Cursor" : "Windsurf"; + const serverNames = Object.keys(data.servers); + console.log(` ${c.bold}${c.cyan}${clientLabel}${c.reset} ${c.gray}(${data.path})${c.reset}`); + if (serverNames.length === 0) { + console.log(` ${c.gray}No MCP servers configured.${c.reset}`); + } else { + for (const name of serverNames) { + const cfg = data.servers[name]; + console.log( + ` • ${c.green}${c.bold}${name.padEnd(16)}${c.reset} ${c.gray}${cfg.command || "npx"} ${(cfg.args || []).join(" ")}${c.reset}`, + ); + } + } + console.log(); + } + return; + } + // Fallback: assume search const matches = searchItems(resources, command); printHeader(); diff --git a/bin/lib/mcp-installer.js b/bin/lib/mcp-installer.js new file mode 100644 index 00000000..fade863d --- /dev/null +++ b/bin/lib/mcp-installer.js @@ -0,0 +1,379 @@ +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; + +/** + * Pre-verified known MCP servers registry + */ +export const VERIFIED_MCP_REGISTRY = { + devshelf: { + name: "DevShelf Directory MCP", + command: "npx", + args: ["-y", "@ritualdev-lab/devshelf", "mcp"], + description: + "Official DevShelf MCP Server providing instant search across 575+ developer tools.", + }, + agentshield: { + name: "AgentShield Runtime Defense", + command: "npx", + args: ["-y", "@ritualdev-lab/agentshield", "mcp"], + description: + "Linux eBPF kernel sandbox and zero-leak environment defense for autonomous agents.", + }, + dbshield: { + name: "DBShield Database Proxy", + command: "npx", + args: ["-y", "@ritualdev-lab/dbshield", "mcp"], + description: "Wire-level SQL dry-run defense with instant rollback and PII masking.", + }, + skillprism: { + name: "SkillPrism FinOps Gateway", + command: "npx", + args: ["-y", "@ritualdev-lab/skillprism", "mcp"], + description: "JIT prompt token compaction (98%+ reduction) with OpenTelemetry FinOps metrics.", + }, + mockforge: { + name: "MockForge Relational Synth", + command: "npx", + args: ["-y", "@ritualdev-lab/mockforge", "mcp"], + description: "Relational mock database engine with circular foreign key auto-resolution.", + }, + "web-sec-auditor": { + name: "WebSecAuditor AST Scanner", + command: "npx", + args: ["-y", "@ritualdev-lab/web-sec-auditor", "mcp"], + description: "AST taint-flow security auditor and automated vulnerability gate.", + }, + filesystem: { + name: "Official Filesystem Server", + command: "npx", + args: ["-y", "@modelcontextprotocol/server-filesystem", process.cwd()], + description: "Model Context Protocol official filesystem read/write server.", + }, + github: { + name: "Official GitHub MCP Server", + command: "npx", + args: ["-y", "@modelcontextprotocol/server-github"], + env: { GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}" }, + description: "Model Context Protocol official GitHub repository and issues server.", + }, + postgres: { + name: "Official Postgres MCP Server", + command: "npx", + args: ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"], + description: "Model Context Protocol PostgreSQL database query server.", + }, + sqlite: { + name: "Official SQLite MCP Server", + command: "npx", + args: ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./test.db"], + description: "Model Context Protocol SQLite database server.", + }, + "brave-search": { + name: "Official Brave Search MCP", + command: "npx", + args: ["-y", "@modelcontextprotocol/server-brave-search"], + env: { BRAVE_API_KEY: "${BRAVE_API_KEY}" }, + description: "Model Context Protocol official web search server.", + }, + fetch: { + name: "Official HTTP Fetch MCP", + command: "npx", + args: ["-y", "@modelcontextprotocol/server-fetch"], + description: "Model Context Protocol web page and API content fetcher.", + }, + slack: { + name: "Official Slack MCP Server", + command: "npx", + args: ["-y", "@modelcontextprotocol/server-slack"], + env: { SLACK_BOT_TOKEN: "${SLACK_BOT_TOKEN}", SLACK_TEAM_ID: "${SLACK_TEAM_ID}" }, + description: "Model Context Protocol Slack communication server.", + }, + memory: { + name: "Knowledge Graph Memory MCP", + command: "npx", + args: ["-y", "@modelcontextprotocol/server-memory"], + description: "Model Context Protocol persistent knowledge-graph memory server.", + }, + puppeteer: { + name: "Puppeteer Headless Browser", + command: "npx", + args: ["-y", "@modelcontextprotocol/server-puppeteer"], + description: "Model Context Protocol headless web automation server.", + }, + git: { + name: "Official Git MCP Server", + command: "npx", + args: ["-y", "@modelcontextprotocol/server-git"], + description: "Model Context Protocol local git repository operations.", + }, + docker: { + name: "Docker Engine MCP", + command: "npx", + args: ["-y", "@modelcontextprotocol/server-docker"], + description: "Model Context Protocol container management server.", + }, + everything: { + name: "Reference Everything MCP", + command: "npx", + args: ["-y", "@modelcontextprotocol/server-everything"], + description: "Model Context Protocol reference test server.", + }, +}; + +/** + * Resolves standard configuration file paths for AI clients across platforms + */ +export function getClientConfigPaths(options = {}) { + const home = os.homedir(); + const platform = process.platform; + + let claudePath = ""; + if (platform === "win32") { + const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming"); + claudePath = path.join(appData, "Claude", "claude_desktop_config.json"); + } else if (platform === "darwin") { + claudePath = path.join( + home, + "Library", + "Application Support", + "Claude", + "claude_desktop_config.json", + ); + } else { + claudePath = path.join(home, ".config", "Claude", "claude_desktop_config.json"); + } + + const cursorPath = options.workspace + ? path.join(process.cwd(), ".cursor", "mcp.json") + : path.join(home, ".cursor", "mcp.json"); + + const windsurfPath = path.join(home, ".codeium", "windsurf", "mcp_config.json"); + + return { + claude: claudePath, + cursor: cursorPath, + windsurf: windsurfPath, + }; +} + +/** + * Resolves an MCP server definition from verified registry or generic npm package + */ +export function resolveMcpServerDefinition(toolSlug, customArgs = [], customEnv = {}) { + const cleanSlug = toolSlug.toLowerCase().trim(); + const verified = VERIFIED_MCP_REGISTRY[cleanSlug]; + + if (verified) { + const args = customArgs.length > 0 ? customArgs : [...verified.args]; + const env = + Object.keys(customEnv).length > 0 ? { ...(verified.env || {}), ...customEnv } : verified.env; + + const res = { + serverKey: cleanSlug, + name: verified.name, + description: verified.description, + config: { + command: verified.command, + args, + }, + }; + if (env && Object.keys(env).length > 0) { + res.config.env = env; + } + return res; + } + + // Generic npm package or scoped tool + const serverKey = cleanSlug.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/^-+|-+$/g, ""); + const args = customArgs.length > 0 ? customArgs : ["-y", toolSlug]; + const res = { + serverKey: serverKey || "custom-mcp-server", + name: toolSlug, + description: `Community MCP Server for ${toolSlug}`, + config: { + command: "npx", + args, + }, + }; + if (Object.keys(customEnv).length > 0) { + res.config.env = customEnv; + } + return res; +} + +/** + * Safely reads existing MCP configuration JSON file + */ +export function readMcpConfig(filePath) { + try { + if (fs.existsSync(filePath)) { + const content = fs.readFileSync(filePath, "utf8").trim(); + if (!content) { + return { mcpServers: {} }; + } + const parsed = JSON.parse(content); + if (!parsed.mcpServers || typeof parsed.mcpServers !== "object") { + parsed.mcpServers = {}; + } + return parsed; + } + } catch (err) { + // If parse error or corrupted, backup existing + try { + if (fs.existsSync(filePath)) { + fs.copyFileSync(filePath, `${filePath}.bak.${Date.now()}`); + } + } catch {} + } + return { mcpServers: {} }; +} + +/** + * Writes configuration back to disk with proper directory creation + */ +export function writeMcpConfig(filePath, config) { + const dir = path.dirname(filePath); + if (!fs.existsSync(dir)) { + fs.mkdirSync(dir, { recursive: true }); + } + fs.writeFileSync(filePath, JSON.stringify(config, null, 2), "utf8"); +} + +/** + * Installs an MCP server into target client configurations + */ +export function installMcpServer(toolSlug, options = {}) { + const definition = resolveMcpServerDefinition(toolSlug, options.args, options.env); + const paths = getClientConfigPaths(options); + + // Determine target clients + const requestedTargets = options.target + ? options.target.split(",").map((t) => t.trim().toLowerCase()) + : ["claude", "cursor", "windsurf"]; + + const results = []; + + for (const client of requestedTargets) { + const configPath = paths[client]; + if (!configPath) { + results.push({ client, success: false, error: `Unknown client target: ${client}` }); + continue; + } + + if (options.dryRun) { + results.push({ + client, + path: configPath, + success: true, + action: "dry-run", + serverKey: definition.serverKey, + payload: definition.config, + }); + continue; + } + + try { + const config = readMcpConfig(configPath); + const isUpdate = Boolean(config.mcpServers[definition.serverKey]); + + config.mcpServers[definition.serverKey] = definition.config; + writeMcpConfig(configPath, config); + + results.push({ + client, + path: configPath, + success: true, + action: isUpdate ? "updated" : "added", + serverKey: definition.serverKey, + payload: definition.config, + }); + } catch (err) { + results.push({ + client, + path: configPath, + success: false, + error: err.message, + }); + } + } + + return { + toolSlug, + definition, + results, + }; +} + +/** + * Uninstalls an MCP server from client configurations + */ +export function uninstallMcpServer(toolSlug, options = {}) { + const cleanSlug = toolSlug.toLowerCase().trim(); + const paths = getClientConfigPaths(options); + const requestedTargets = options.target + ? options.target.split(",").map((t) => t.trim().toLowerCase()) + : ["claude", "cursor", "windsurf"]; + + const results = []; + + for (const client of requestedTargets) { + const configPath = paths[client]; + if (!configPath) continue; + + if (!fs.existsSync(configPath)) { + results.push({ client, path: configPath, success: true, action: "not-found" }); + continue; + } + + try { + const config = readMcpConfig(configPath); + if (config.mcpServers[cleanSlug]) { + delete config.mcpServers[cleanSlug]; + writeMcpConfig(configPath, config); + results.push({ + client, + path: configPath, + success: true, + action: "removed", + serverKey: cleanSlug, + }); + } else { + results.push({ + client, + path: configPath, + success: true, + action: "not-found", + serverKey: cleanSlug, + }); + } + } catch (err) { + results.push({ client, path: configPath, success: false, error: err.message }); + } + } + + return { toolSlug: cleanSlug, results }; +} + +/** + * Lists installed MCP servers across clients + */ +export function listInstalledMcpServers(options = {}) { + const paths = getClientConfigPaths(options); + const installed = {}; + + for (const [client, configPath] of Object.entries(paths)) { + installed[client] = { + path: configPath, + exists: fs.existsSync(configPath), + servers: {}, + }; + + if (installed[client].exists) { + const config = readMcpConfig(configPath); + installed[client].servers = config.mcpServers || {}; + } + } + + return installed; +} diff --git a/tests/mcp-installer.test.ts b/tests/mcp-installer.test.ts new file mode 100644 index 00000000..4b31609b --- /dev/null +++ b/tests/mcp-installer.test.ts @@ -0,0 +1,76 @@ +import assert from "node:assert"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import test from "node:test"; +import { + VERIFIED_MCP_REGISTRY, + getClientConfigPaths, + installMcpServer, + listInstalledMcpServers, + readMcpConfig, + resolveMcpServerDefinition, + uninstallMcpServer, + writeMcpConfig, +} from "../bin/lib/mcp-installer.js"; + +test("1-Click MCP Registry Installer Suite", async (t) => { + await t.test("Resolves pre-verified MCP servers accurately", () => { + const devshelf = resolveMcpServerDefinition("devshelf"); + assert.strictEqual(devshelf.serverKey, "devshelf"); + assert.strictEqual(devshelf.config.command, "npx"); + assert.ok(devshelf.config.args.includes("@ritualdev-lab/devshelf")); + + const agentshield = resolveMcpServerDefinition("agentshield"); + assert.strictEqual(agentshield.serverKey, "agentshield"); + assert.ok(agentshield.config.args.includes("@ritualdev-lab/agentshield")); + + const fsServer = resolveMcpServerDefinition("filesystem"); + assert.strictEqual(fsServer.serverKey, "filesystem"); + assert.ok(fsServer.config.args.includes("@modelcontextprotocol/server-filesystem")); + }); + + await t.test("Resolves custom community tool slugs", () => { + const custom = resolveMcpServerDefinition("@myorg/cool-mcp"); + assert.strictEqual(custom.serverKey, "myorg-cool-mcp"); + assert.strictEqual(custom.config.command, "npx"); + assert.deepStrictEqual(custom.config.args, ["-y", "@myorg/cool-mcp"]); + }); + + await t.test("Resolves client configuration paths across Claude, Cursor, and Windsurf", () => { + const paths = getClientConfigPaths(); + assert.ok(paths.claude.includes("claude_desktop_config.json")); + assert.ok(paths.cursor.includes("mcp.json")); + assert.ok(paths.windsurf.includes("mcp_config.json")); + + const wsPaths = getClientConfigPaths({ workspace: true }); + assert.ok(wsPaths.cursor.startsWith(process.cwd())); + }); + + await t.test("Performs dry-run without writing to disk", () => { + const res = installMcpServer("sqlite", { dryRun: true }); + assert.strictEqual(res.toolSlug, "sqlite"); + assert.strictEqual(res.results.length, 3); + for (const r of res.results) { + assert.strictEqual(r.action, "dry-run"); + assert.strictEqual(r.success, true); + } + }); + + await t.test("Reads and writes configuration file with directory creation", () => { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "devshelf-mcp-test-")); + const tmpConfigFile = path.join(tmpDir, "nested", "mcp.json"); + + const initial = readMcpConfig(tmpConfigFile); + assert.deepStrictEqual(initial, { mcpServers: {} }); + + initial.mcpServers["test-tool"] = { command: "node", args: ["server.js"] }; + writeMcpConfig(tmpConfigFile, initial); + + assert.ok(fs.existsSync(tmpConfigFile)); + const reloaded = readMcpConfig(tmpConfigFile); + assert.strictEqual(reloaded.mcpServers["test-tool"].command, "node"); + + fs.rmSync(tmpDir, { recursive: true, force: true }); + }); +});