claude-cli-advanced-starter-pack 1.0.0

package/src/commands/explore-mcp/claude-md-updater.js

@@ -0,0 +1,252 @@
+/**
+ * CLAUDE.md Updater
+ *
+ * Updates CLAUDE.md with MCP server documentation.
+ * Adds tool references and usage examples for installed MCPs.
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * MCP section marker
+ */
+const MCP_SECTION_START = '<!-- MCP-SERVERS-START -->';
+const MCP_SECTION_END = '<!-- MCP-SERVERS-END -->';
+
+/**
+ * Generate MCP documentation section
+ *
+ * @param {Array} installedMcps - Array of installed MCP definitions
+ * @returns {string} Markdown documentation
+ */
+export function generateMcpDocumentation(installedMcps) {
+  if (installedMcps.length === 0) {
+    return `
+${MCP_SECTION_START}
+## MCP Servers
+
+No MCP servers configured. Run \`gtask explore-mcp\` to discover and install MCP servers.
+${MCP_SECTION_END}
+`;
+  }
+
+  const sections = installedMcps.map((mcp) => {
+    const tools = mcp.tools?.slice(0, 5).join(', ') || 'See documentation';
+    const hasMoreTools = mcp.tools?.length > 5;
+
+    return `### ${mcp.name}
+
+**ID:** \`${mcp.id}\`
+**Category:** ${mcp.category}
+
+${mcp.description}
+
+**Key Tools:** ${tools}${hasMoreTools ? ` (+${mcp.tools.length - 5} more)` : ''}
+
+${mcp.note ? `> **Note:** ${mcp.note}` : ''}`;
+  });
+
+  // Group by category
+  const byCategory = {};
+  for (const mcp of installedMcps) {
+    const cat = mcp.category || 'other';
+    if (!byCategory[cat]) byCategory[cat] = [];
+    byCategory[cat].push(mcp);
+  }
+
+  const categorySections = Object.entries(byCategory)
+    .map(([category, mcps]) => {
+      const categoryName = category.charAt(0).toUpperCase() + category.slice(1);
+      const mcpDocs = mcps
+        .map((mcp) => {
+          const tools = mcp.tools?.slice(0, 3).join(', ') || 'See docs';
+          return `| ${mcp.name} | \`${mcp.id}\` | ${tools} |`;
+        })
+        .join('\n');
+
+      return `### ${categoryName}
+
+| Server | ID | Key Tools |
+|--------|----|-----------|
+${mcpDocs}`;
+    })
+    .join('\n\n');
+
+  return `
+${MCP_SECTION_START}
+## MCP Servers
+
+MCP (Model Context Protocol) servers extend Claude's capabilities. These are configured in \`.mcp.json\`.
+
+${categorySections}
+
+### Usage
+
+MCP tools are accessed via the \`ToolSearch\` tool or directly if loaded:
+
+\`\`\`
+# Search for MCP tools
+ToolSearch query: "playwright screenshot"
+
+# Use directly (after loading)
+mcp__playwright__browser_screenshot
+\`\`\`
+
+### Restart Required
+
+After modifying \`.mcp.json\`, restart Claude Code for changes to take effect:
+
+\`\`\`bash
+# Exit and re-enter the project
+cd .. && cd your-project
+\`\`\`
+
+*Generated by gtask explore-mcp*
+${MCP_SECTION_END}
+`;
+}
+
+/**
+ * Load CLAUDE.md content
+ */
+export function loadClaudeMd(cwd = process.cwd()) {
+  const claudeMdPath = join(cwd, 'CLAUDE.md');
+
+  if (existsSync(claudeMdPath)) {
+    return readFileSync(claudeMdPath, 'utf8');
+  }
+
+  return null;
+}
+
+/**
+ * Update CLAUDE.md with MCP documentation
+ *
+ * @param {Array} installedMcps - Array of installed MCP definitions
+ * @param {Object} options - Options
+ * @returns {Object} Update result
+ */
+export async function updateClaudeMd(installedMcps, options = {}) {
+  const spinner = ora('Updating CLAUDE.md...').start();
+  const cwd = options.cwd || process.cwd();
+  const claudeMdPath = join(cwd, 'CLAUDE.md');
+
+  try {
+    // Generate new MCP section
+    const mcpSection = generateMcpDocumentation(installedMcps);
+
+    let content = loadClaudeMd(cwd);
+
+    if (!content) {
+      // No CLAUDE.md exists - create minimal one with MCP section
+      spinner.text = 'Creating CLAUDE.md...';
+      content = `# Project
+
+<!-- Project-specific instructions for Claude Code -->
+
+${mcpSection}
+`;
+      writeFileSync(claudeMdPath, content, 'utf8');
+      spinner.succeed('Created CLAUDE.md with MCP documentation');
+      return {
+        success: true,
+        action: 'created',
+        path: claudeMdPath,
+      };
+    }
+
+    // Check if MCP section exists
+    const hasStartMarker = content.includes(MCP_SECTION_START);
+    const hasEndMarker = content.includes(MCP_SECTION_END);
+
+    if (hasStartMarker && hasEndMarker) {
+      // Replace existing section
+      spinner.text = 'Replacing existing MCP section...';
+      const regex = new RegExp(
+        `${MCP_SECTION_START}[\\s\\S]*?${MCP_SECTION_END}`,
+        'g'
+      );
+      content = content.replace(regex, mcpSection.trim());
+    } else {
+      // Append to end
+      spinner.text = 'Appending MCP section...';
+
+      // Find good insertion point (before any existing sections like "---" at end)
+      const lines = content.split('\n');
+      let insertIndex = lines.length;
+
+      // Look for common ending patterns
+      for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (line === '---' || line.startsWith('*Generated') || line.startsWith('<!-- ')) {
+          insertIndex = i;
+        } else if (line.length > 0) {
+          break;
+        }
+      }
+
+      lines.splice(insertIndex, 0, '', mcpSection.trim(), '');
+      content = lines.join('\n');
+    }
+
+    writeFileSync(claudeMdPath, content, 'utf8');
+    spinner.succeed('Updated CLAUDE.md with MCP documentation');
+
+    return {
+      success: true,
+      action: hasStartMarker ? 'updated' : 'appended',
+      path: claudeMdPath,
+    };
+  } catch (error) {
+    spinner.fail(`Failed to update CLAUDE.md: ${error.message}`);
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Remove MCP section from CLAUDE.md
+ */
+export function removeMcpSection(cwd = process.cwd()) {
+  const claudeMdPath = join(cwd, 'CLAUDE.md');
+
+  if (!existsSync(claudeMdPath)) {
+    return false;
+  }
+
+  let content = readFileSync(claudeMdPath, 'utf8');
+
+  const hasStartMarker = content.includes(MCP_SECTION_START);
+  const hasEndMarker = content.includes(MCP_SECTION_END);
+
+  if (hasStartMarker && hasEndMarker) {
+    const regex = new RegExp(
+      `\\n?${MCP_SECTION_START}[\\s\\S]*?${MCP_SECTION_END}\\n?`,
+      'g'
+    );
+    content = content.replace(regex, '\n');
+    writeFileSync(claudeMdPath, content, 'utf8');
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Generate a quick-reference comment for MCP tools
+ */
+export function generateMcpQuickRef(installedMcps) {
+  const lines = ['<!-- MCP Quick Reference'];
+
+  for (const mcp of installedMcps) {
+    lines.push(`  ${mcp.id}: ${mcp.tools?.slice(0, 3).join(', ') || 'see docs'}`);
+  }
+
+  lines.push('-->');
+  return lines.join('\n');
+}

package/src/commands/explore-mcp/mcp-installer.js

@@ -0,0 +1,346 @@
+/**
+ * MCP Installer
+ *
+ * Handles installation of MCP servers:
+ * - Generates .mcp.json configuration
+ * - Updates .claude/settings.json permissions
+ * - Supports Windows (cmd /c wrapper)
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+import inquirer from 'inquirer';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+
+/**
+ * Check if running on Windows
+ */
+export function isWindows() {
+  return process.platform === 'win32';
+}
+
+/**
+ * Generate MCP server configuration for .mcp.json
+ *
+ * @param {Object} mcp - MCP server definition from registry
+ * @param {Object} envValues - Environment variable values provided by user
+ * @returns {Object} Server configuration object
+ */
+export function generateMcpConfig(mcp, envValues = {}) {
+  const config = {
+    env: { ...envValues },
+  };
+
+  // Handle different command types
+  if (mcp.command === 'uvx') {
+    // Python-based MCP (like claude-mem)
+    config.command = 'uvx';
+    config.args = [...(mcp.args || [])];
+  } else if (mcp.npmPackage) {
+    // NPM-based MCP
+    if (isWindows()) {
+      config.command = 'cmd';
+      config.args = ['/c', 'npx', '-y', mcp.npmPackage];
+    } else {
+      config.command = 'npx';
+      config.args = ['-y', mcp.npmPackage];
+    }
+
+    // Add any additional args
+    if (mcp.args) {
+      config.args.push(...mcp.args);
+    }
+  }
+
+  return config;
+}
+
+/**
+ * Load existing .mcp.json or create empty structure
+ */
+export function loadMcpJson(cwd = process.cwd()) {
+  const mcpPath = join(cwd, '.mcp.json');
+
+  if (existsSync(mcpPath)) {
+    try {
+      const content = readFileSync(mcpPath, 'utf8');
+      return JSON.parse(content);
+    } catch {
+      return { mcpServers: {} };
+    }
+  }
+
+  return { mcpServers: {} };
+}
+
+/**
+ * Save .mcp.json
+ */
+export function saveMcpJson(config, cwd = process.cwd()) {
+  const mcpPath = join(cwd, '.mcp.json');
+  const content = JSON.stringify(config, null, 2);
+  writeFileSync(mcpPath, content, 'utf8');
+  return mcpPath;
+}
+
+/**
+ * Load existing .claude/settings.json or create empty structure
+ */
+export function loadClaudeSettings(cwd = process.cwd()) {
+  const settingsPath = join(cwd, '.claude', 'settings.json');
+
+  if (existsSync(settingsPath)) {
+    try {
+      const content = readFileSync(settingsPath, 'utf8');
+      return JSON.parse(content);
+    } catch {
+      return { permissions: { allow: [], deny: [] } };
+    }
+  }
+
+  return { permissions: { allow: [], deny: [] } };
+}
+
+/**
+ * Save .claude/settings.json
+ */
+export function saveClaudeSettings(settings, cwd = process.cwd()) {
+  const claudeDir = join(cwd, '.claude');
+  const settingsPath = join(claudeDir, 'settings.json');
+
+  if (!existsSync(claudeDir)) {
+    mkdirSync(claudeDir, { recursive: true });
+  }
+
+  const content = JSON.stringify(settings, null, 2);
+  writeFileSync(settingsPath, content, 'utf8');
+  return settingsPath;
+}
+
+/**
+ * Add MCP permission to settings
+ */
+export function addMcpPermission(settings, mcpId) {
+  if (!settings.permissions) {
+    settings.permissions = { allow: [], deny: [] };
+  }
+
+  if (!settings.permissions.allow) {
+    settings.permissions.allow = [];
+  }
+
+  const permission = `MCP(${mcpId}:*)`;
+
+  if (!settings.permissions.allow.includes(permission)) {
+    settings.permissions.allow.push(permission);
+  }
+
+  return settings;
+}
+
+/**
+ * Enable MCP server in settings
+ */
+export function enableMcpServer(settings, mcpId) {
+  if (!settings.enableAllProjectMcpServers) {
+    if (!settings.enabledMcpjsonServers) {
+      settings.enabledMcpjsonServers = [];
+    }
+
+    if (!settings.enabledMcpjsonServers.includes(mcpId)) {
+      settings.enabledMcpjsonServers.push(mcpId);
+    }
+  }
+
+  return settings;
+}
+
+/**
+ * Prompt user for required environment variables
+ */
+export async function promptForEnvVars(mcp) {
+  const envValues = {};
+  const required = mcp.requiredEnv || {};
+  const optional = mcp.optionalEnv || {};
+
+  // Prompt for required vars
+  for (const [key, info] of Object.entries(required)) {
+    const { value } = await inquirer.prompt([
+      {
+        type: 'password',
+        name: 'value',
+        message: `${key} (${info.description}):`,
+        mask: '*',
+        validate: (input) => input.length > 0 || 'This field is required',
+      },
+    ]);
+    envValues[key] = value;
+  }
+
+  // Ask about optional vars
+  if (Object.keys(optional).length > 0) {
+    const { configureOptional } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'configureOptional',
+        message: 'Configure optional settings?',
+        default: false,
+      },
+    ]);
+
+    if (configureOptional) {
+      for (const [key, info] of Object.entries(optional)) {
+        const { value } = await inquirer.prompt([
+          {
+            type: 'input',
+            name: 'value',
+            message: `${key} (${info.description}):`,
+            default: info.default || '',
+          },
+        ]);
+        if (value) {
+          envValues[key] = value;
+        }
+      }
+    }
+  }
+
+  return envValues;
+}
+
+/**
+ * Install a single MCP server
+ *
+ * @param {Object} mcp - MCP definition from registry
+ * @param {Object} options - Installation options
+ * @returns {Object} Installation result
+ */
+export async function installMcp(mcp, options = {}) {
+  const spinner = ora(`Installing ${mcp.name}...`).start();
+  const cwd = options.cwd || process.cwd();
+
+  try {
+    // 1. Get environment variables
+    spinner.text = 'Configuring environment variables...';
+    let envValues = options.envValues || {};
+
+    if (!options.skipEnvPrompt && Object.keys(mcp.requiredEnv || {}).length > 0) {
+      spinner.stop();
+      envValues = await promptForEnvVars(mcp);
+      spinner.start();
+    }
+
+    // 2. Generate MCP config
+    spinner.text = 'Generating configuration...';
+    const mcpConfig = generateMcpConfig(mcp, envValues);
+
+    // 3. Update .mcp.json
+    spinner.text = 'Updating .mcp.json...';
+    const mcpJson = loadMcpJson(cwd);
+    mcpJson.mcpServers = mcpJson.mcpServers || {};
+    mcpJson.mcpServers[mcp.id] = mcpConfig;
+
+    // Add helpful note
+    if (!mcpJson._NOTE) {
+      mcpJson._NOTE = 'MCP servers configured by gtask explore-mcp';
+    }
+
+    const mcpPath = saveMcpJson(mcpJson, cwd);
+
+    // 4. Update .claude/settings.json
+    spinner.text = 'Updating Claude settings...';
+    const settings = loadClaudeSettings(cwd);
+    addMcpPermission(settings, mcp.id);
+    enableMcpServer(settings, mcp.id);
+    const settingsPath = saveClaudeSettings(settings, cwd);
+
+    spinner.succeed(`Installed ${mcp.name}`);
+
+    return {
+      success: true,
+      mcp,
+      files: {
+        mcpJson: mcpPath,
+        settings: settingsPath,
+      },
+      config: mcpConfig,
+    };
+  } catch (error) {
+    spinner.fail(`Failed to install ${mcp.name}: ${error.message}`);
+    return {
+      success: false,
+      mcp,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Install multiple MCPs
+ */
+export async function installMultipleMcps(mcps, options = {}) {
+  const results = [];
+
+  for (const mcp of mcps) {
+    const result = await installMcp(mcp, options);
+    results.push(result);
+  }
+
+  return results;
+}
+
+/**
+ * Check if an MCP is already installed
+ */
+export function isMcpInstalled(mcpId, cwd = process.cwd()) {
+  const mcpJson = loadMcpJson(cwd);
+  return mcpJson.mcpServers && mcpId in mcpJson.mcpServers;
+}
+
+/**
+ * Get list of installed MCPs
+ */
+export function getInstalledMcps(cwd = process.cwd()) {
+  const mcpJson = loadMcpJson(cwd);
+  return Object.keys(mcpJson.mcpServers || {});
+}
+
+/**
+ * Remove an MCP
+ */
+export function removeMcp(mcpId, cwd = process.cwd()) {
+  // Remove from .mcp.json
+  const mcpJson = loadMcpJson(cwd);
+  if (mcpJson.mcpServers && mcpId in mcpJson.mcpServers) {
+    delete mcpJson.mcpServers[mcpId];
+    saveMcpJson(mcpJson, cwd);
+  }
+
+  // Remove from settings
+  const settings = loadClaudeSettings(cwd);
+  if (settings.enabledMcpjsonServers) {
+    settings.enabledMcpjsonServers = settings.enabledMcpjsonServers.filter(
+      (id) => id !== mcpId
+    );
+    saveClaudeSettings(settings, cwd);
+  }
+
+  return true;
+}
+
+/**
+ * Verify MCP installation by checking npm package exists
+ */
+export async function verifyMcpPackage(npmPackage) {
+  try {
+    execSync(`npm view ${npmPackage.split('@')[0]} --json`, {
+      stdio: 'pipe',
+      encoding: 'utf8',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}