start-vibing-stacks 1.0.0 → 1.1.0

package/dist/index.js

@@ -12,6 +12,7 @@ import * as ui from './ui.js';
 import { detectProject, detectPhpFramework, detectNodeFramework } from './detector.js';
 import { autoInstall, installComposer, installClaudeCode } from './installer.js';
 import { loadStackConfig, setupProject } from './setup.js';
+import { selectMcpServers, installMcpServers } from './mcp.js';
 // =============================================================================
 // CLI Arguments
 // =============================================================================
@@ -19,6 +20,7 @@ const args = process.argv.slice(2);
 const FLAGS = {
     force: args.includes('--force'),
     noClaude: args.includes('--no-claude'),
+    noMcp: args.includes('--no-mcp'),
     noInstall: args.includes('--no-install'),
     help: args.includes('--help') || args.includes('-h'),
     version: args.includes('--version') || args.includes('-v'),
@@ -36,6 +38,7 @@ if (FLAGS.help) {
   ${chalk.bold('Options:')}
     --force           Overwrite existing configuration
     --no-claude       Skip Claude Code installation
+    --no-mcp          Skip MCP server selection
     --no-install      Skip dependency installation
     --help, -h        Show this help
     --version, -v     Show version
@@ -155,6 +158,8 @@ async function main() {
             })),
         },
     ]);
+    // ─── Step 6b: MCP Servers ────────────────────────────────────────────
+    const selectedMcps = FLAGS.noMcp ? [] : await selectMcpServers(stackId, database);
     // ─── Step 7: Show Summary & Confirm ────────────────────────────────────
     const config = {
         name: projectName,
@@ -180,6 +185,7 @@ async function main() {
         'Skills': `${stackConfig.skills.length} stack + shared`,
         'Hooks': 'stop-validator + prompt-inject',
         'Gates': stackConfig.qualityGates.map((g) => g.name).join(' → '),
+        'MCPs': selectedMcps.length > 0 ? `${selectedMcps.length} servers` : 'None',
     });
     const { confirmed } = await inquirer.prompt([
         {
@@ -218,7 +224,11 @@ async function main() {
         ui.error('Setup failed.');
         process.exit(1);
     }
-    // ─── Step 10: Install Claude Code ──────────────────────────────────────
+    // ─── Step 10: Install MCP Servers ───────────────────────────────────
+    if (selectedMcps.length > 0) {
+        await installMcpServers(selectedMcps, projectDir);
+    }
+    // ─── Step 11: Install Claude Code ──────────────────────────────────────
     if (!FLAGS.noClaude) {
         console.log('');
         installClaudeCode();

package/dist/mcp.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Start Vibing Stacks — MCP Server Manager
+ *
+ * Discovers, selects, and configures MCP servers based on stack.
+ */
+/**
+ * Interactive MCP selection
+ */
+export declare function selectMcpServers(stackId: string, database: string): Promise<string[]>;
+/**
+ * Install selected MCP servers
+ */
+export declare function installMcpServers(selectedIds: string[], projectDir: string): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,165 @@
+/**
+ * Start Vibing Stacks — MCP Server Manager
+ *
+ * Discovers, selects, and configures MCP servers based on stack.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+import inquirer from 'inquirer';
+import ora from 'ora';
+import chalk from 'chalk';
+import * as ui from './ui.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_ROOT = resolve(__dirname, '..');
+/**
+ * Load MCP server registry
+ */
+function loadRegistry() {
+    const registryPath = join(PACKAGE_ROOT, 'stacks', '_shared', 'config', 'mcp-servers.json');
+    return JSON.parse(readFileSync(registryPath, 'utf8'));
+}
+/**
+ * Get servers compatible with a stack + database
+ */
+function getCompatibleServers(registry, stackId, database) {
+    const results = [];
+    for (const [id, server] of Object.entries(registry.servers)) {
+        if (!server.stacks.includes(stackId))
+            continue;
+        // Filter DB-specific MCPs
+        if (id === 'mongodb' && database !== 'mongodb')
+            continue;
+        if (id === 'mysql' && database !== 'mysql')
+            continue;
+        if (id === 'postgres' && database !== 'postgresql')
+            continue;
+        if (id === 'nextjs-devtools' && stackId !== 'nodejs')
+            continue;
+        const recommended = server.tier === 'core' ||
+            (id === 'mongodb' && database === 'mongodb') ||
+            (id === 'mysql' && database === 'mysql') ||
+            (id === 'postgres' && database === 'postgresql');
+        results.push({ id, server, recommended });
+    }
+    // Sort: core first, then stack-specific, then productivity
+    const tierOrder = { core: 0, 'stack-specific': 1, productivity: 2 };
+    results.sort((a, b) => {
+        const aOrder = tierOrder[a.server.tier] ?? 3;
+        const bOrder = tierOrder[b.server.tier] ?? 3;
+        return aOrder - bOrder;
+    });
+    return results;
+}
+/**
+ * Interactive MCP selection
+ */
+export async function selectMcpServers(stackId, database) {
+    const registry = loadRegistry();
+    const compatible = getCompatibleServers(registry, stackId, database);
+    if (compatible.length === 0) {
+        ui.info('No MCP servers available for this stack');
+        return [];
+    }
+    ui.header('🔌 MCP Servers');
+    console.log(chalk.dim('  Model Context Protocol — extend Claude Code capabilities\n'));
+    const { selectedMcps } = await inquirer.prompt([
+        {
+            type: 'checkbox',
+            name: 'selectedMcps',
+            message: 'Select MCP servers to install:',
+            choices: compatible.map((c) => {
+                const envNote = c.server.envVars.length > 0
+                    ? chalk.dim(` (needs: ${c.server.envVars.join(', ')})`)
+                    : '';
+                const tierLabel = c.server.tier === 'core'
+                    ? chalk.green(' [core]')
+                    : c.server.tier === 'stack-specific'
+                        ? chalk.yellow(' [stack]')
+                        : chalk.dim(' [optional]');
+                return {
+                    name: `${c.server.icon}  ${c.server.name} — ${c.server.description}${tierLabel}${envNote}`,
+                    value: c.id,
+                    checked: c.recommended,
+                };
+            }),
+        },
+    ]);
+    return selectedMcps;
+}
+/**
+ * Install selected MCP servers
+ */
+export async function installMcpServers(selectedIds, projectDir) {
+    if (selectedIds.length === 0)
+        return;
+    const registry = loadRegistry();
+    const spinner = ora('Configuring MCP servers...').start();
+    // Build Claude Code MCP config
+    const mcpConfig = {};
+    for (const id of selectedIds) {
+        const server = registry.servers[id];
+        if (!server)
+            continue;
+        mcpConfig[id] = server.config;
+        // Try to install stdio-based servers
+        if (server.install && server.config.command) {
+            spinner.text = `Pre-caching ${server.name}...`;
+            try {
+                execSync(`${server.install} --help 2>/dev/null || true`, {
+                    stdio: 'pipe',
+                    timeout: 30000,
+                });
+            }
+            catch {
+                // Non-critical — Claude Code will install on first use
+            }
+        }
+    }
+    // Write MCP config to .claude/config/
+    const configDir = join(projectDir, '.claude', 'config');
+    mkdirSync(configDir, { recursive: true });
+    writeFileSync(join(configDir, 'mcp-active.json'), JSON.stringify({ mcpServers: mcpConfig }, null, 2));
+    // Also write to Claude Code's settings if exists
+    const claudeSettingsPath = join(projectDir, '.claude', 'settings.json');
+    if (existsSync(claudeSettingsPath)) {
+        try {
+            const settings = JSON.parse(readFileSync(claudeSettingsPath, 'utf8'));
+            settings.mcpServers = mcpConfig;
+            writeFileSync(claudeSettingsPath, JSON.stringify(settings, null, '\t'));
+        }
+        catch { }
+    }
+    // Create .env.example with required env vars
+    const envVars = [];
+    for (const id of selectedIds) {
+        const server = registry.servers[id];
+        if (server?.envVars.length) {
+            for (const v of server.envVars) {
+                envVars.push(`# ${server.name}\n${v}=`);
+            }
+        }
+    }
+    if (envVars.length > 0) {
+        const envExamplePath = join(projectDir, '.env.mcp.example');
+        writeFileSync(envExamplePath, `# MCP Server Environment Variables\n# Copy to .env and fill in values\n\n${envVars.join('\n\n')}\n`);
+        spinner.text = 'Created .env.mcp.example for required API keys';
+    }
+    spinner.succeed(`${selectedIds.length} MCP servers configured`);
+    // Show env var warnings
+    const needsEnv = selectedIds.filter((id) => {
+        const server = registry.servers[id];
+        return server?.envVars.length > 0;
+    });
+    if (needsEnv.length > 0) {
+        console.log('');
+        ui.warn('Some MCPs need environment variables:');
+        for (const id of needsEnv) {
+            const server = registry.servers[id];
+            console.log(chalk.dim(`    ${server.icon}  ${server.name}: ${server.envVars.join(', ')}`));
+        }
+        ui.info('See .env.mcp.example for details');
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/config/mcp-servers.json

@@ -0,0 +1,191 @@
+{
+  "$comment": "MCP Server Registry — available servers for all stacks",
+  "servers": {
+    "context7": {
+      "name": "Context7",
+      "description": "Real-time library documentation",
+      "icon": "📚",
+      "tier": "core",
+      "stacks": ["php", "nodejs", "python", "go", "rust"],
+      "install": "npx -y @upstash/context7-mcp@latest",
+      "config": {
+        "command": "npx",
+        "args": ["-y", "@upstash/context7-mcp@latest"]
+      },
+      "envVars": [],
+      "publisher": "upstash"
+    },
+    "sequential-thinking": {
+      "name": "Sequential Thinking",
+      "description": "Structured reasoning for complex problems",
+      "icon": "🧠",
+      "tier": "core",
+      "stacks": ["php", "nodejs", "python", "go", "rust"],
+      "install": "npx -y @modelcontextprotocol/server-sequential-thinking",
+      "config": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+      },
+      "envVars": [],
+      "publisher": "modelcontextprotocol"
+    },
+    "playwright": {
+      "name": "Playwright",
+      "description": "Browser automation & E2E testing",
+      "icon": "🎭",
+      "tier": "core",
+      "stacks": ["php", "nodejs", "python"],
+      "install": "npx -y @playwright/mcp@latest",
+      "config": {
+        "command": "npx",
+        "args": ["-y", "@playwright/mcp@latest", "--user-data-dir", "./.playwright-data"]
+      },
+      "envVars": [],
+      "publisher": "microsoft"
+    },
+    "memory": {
+      "name": "Memory",
+      "description": "Persistent knowledge graph across sessions",
+      "icon": "💾",
+      "tier": "core",
+      "stacks": ["php", "nodejs", "python", "go", "rust"],
+      "install": "npx -y @modelcontextprotocol/server-memory",
+      "config": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-memory"]
+      },
+      "envVars": [],
+      "publisher": "modelcontextprotocol"
+    },
+    "github": {
+      "name": "GitHub",
+      "description": "Repository management, issues, PRs, CI/CD",
+      "icon": "🐙",
+      "tier": "core",
+      "stacks": ["php", "nodejs", "python", "go", "rust"],
+      "install": null,
+      "config": {
+        "remote": {
+          "url": "https://api.githubcopilot.com/mcp/"
+        }
+      },
+      "envVars": ["GITHUB_PERSONAL_ACCESS_TOKEN"],
+      "publisher": "github"
+    },
+    "brave-search": {
+      "name": "Brave Search",
+      "description": "Privacy-first web search",
+      "icon": "🔍",
+      "tier": "productivity",
+      "stacks": ["php", "nodejs", "python", "go", "rust"],
+      "install": "npx -y @modelcontextprotocol/server-brave-search",
+      "config": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-brave-search"]
+      },
+      "envVars": ["BRAVE_API_KEY"],
+      "publisher": "modelcontextprotocol"
+    },
+    "nextjs-devtools": {
+      "name": "Next.js DevTools",
+      "description": "Next.js 16+ error detection and live state",
+      "icon": "▲",
+      "tier": "stack-specific",
+      "stacks": ["nodejs"],
+      "install": "npx -y next-devtools-mcp@latest",
+      "config": {
+        "command": "npx",
+        "args": ["-y", "next-devtools-mcp@latest"]
+      },
+      "envVars": [],
+      "publisher": "vercel"
+    },
+    "mongodb": {
+      "name": "MongoDB",
+      "description": "MongoDB database operations",
+      "icon": "🍃",
+      "tier": "stack-specific",
+      "stacks": ["php", "nodejs", "python"],
+      "install": "npx -y @mongodb-js/mongodb-mcp-server",
+      "config": {
+        "command": "npx",
+        "args": ["-y", "@mongodb-js/mongodb-mcp-server"]
+      },
+      "envVars": ["MONGODB_URI"],
+      "publisher": "mongodb-js"
+    },
+    "mysql": {
+      "name": "MySQL",
+      "description": "MySQL/MariaDB database operations",
+      "icon": "🐬",
+      "tier": "stack-specific",
+      "stacks": ["php", "nodejs", "python"],
+      "install": "npx -y @benborla29/mcp-server-mysql",
+      "config": {
+        "command": "npx",
+        "args": ["-y", "@benborla29/mcp-server-mysql"]
+      },
+      "envVars": ["MYSQL_HOST", "MYSQL_USER", "MYSQL_PASSWORD", "MYSQL_DATABASE"],
+      "publisher": "benborla29"
+    },
+    "postgres": {
+      "name": "PostgreSQL",
+      "description": "PostgreSQL database operations",
+      "icon": "🐘",
+      "tier": "stack-specific",
+      "stacks": ["php", "nodejs", "python"],
+      "install": "npx -y @modelcontextprotocol/server-postgres",
+      "config": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-postgres"]
+      },
+      "envVars": ["POSTGRES_CONNECTION_STRING"],
+      "publisher": "modelcontextprotocol"
+    },
+    "sentry": {
+      "name": "Sentry",
+      "description": "Error tracking & AI-powered debugging",
+      "icon": "🐛",
+      "tier": "productivity",
+      "stacks": ["php", "nodejs", "python"],
+      "install": null,
+      "config": {
+        "url": "https://mcp.sentry.dev/mcp"
+      },
+      "envVars": [],
+      "publisher": "getsentry"
+    },
+    "figma": {
+      "name": "Figma",
+      "description": "Design-to-code workflows",
+      "icon": "🎨",
+      "tier": "productivity",
+      "stacks": ["php", "nodejs"],
+      "install": null,
+      "config": {
+        "url": "https://mcp.figma.com/mcp"
+      },
+      "envVars": [],
+      "publisher": "figma"
+    },
+    "fetch": {
+      "name": "Fetch",
+      "description": "HTTP requests and web content retrieval",
+      "icon": "🌐",
+      "tier": "productivity",
+      "stacks": ["php", "nodejs", "python", "go", "rust"],
+      "install": "uvx mcp-server-fetch",
+      "config": {
+        "command": "uvx",
+        "args": ["mcp-server-fetch"]
+      },
+      "envVars": [],
+      "publisher": "modelcontextprotocol"
+    }
+  },
+  "tiers": {
+    "core": "Essential for daily development — recommended for all",
+    "stack-specific": "Depends on your stack and database choice",
+    "productivity": "Enhanced productivity — optional"
+  }
+}