@l4yercak3/cli 1.2.8 → 1.2.10

package/.claude/settings.local.json

@@ -17,7 +17,9 @@
       "Bash(git push:*)",
       "Bash(session\" errors when trying to use features.\n\nNow the login command validates the session with the backend first.\nIf validation fails, it clears the local session and prompts for\nfresh login, avoiding the confusing loop.\n\n🤖 Generated with [Claude Code]\\(https://claude.com/claude-code\\)\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")",
       "Bash(npm run build:*)",
-      "Bash(npm version:*)"
+      "Bash(npm version:*)",
+      "Bash(npm run lint:fix:*)",
+      "Bash(cat:*)"
     ]
   }
 }

package/bin/cli.js

@@ -17,6 +17,7 @@ const spreadCommand = require('../src/commands/spread');
 const apiKeysCommand = require('../src/commands/api-keys');
 const upgradeCommand = require('../src/commands/upgrade');
 const mcpServerCommand = require('../src/commands/mcp-server');
+const mcpSetupCommand = require('../src/commands/mcp-setup');
 
 // Create CLI program
 const program = new Command();
@@ -72,6 +73,11 @@ program
   .description(mcpServerCommand.description)
   .action(mcpServerCommand.handler);
 
+program
+  .command(mcpSetupCommand.command)
+  .description(mcpSetupCommand.description)
+  .action(mcpSetupCommand.handler);
+
 // Show logo and welcome message if no command provided
 if (process.argv.length === 2) {
   console.log(''); // initial spacing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@l4yercak3/cli",
-  "version": "1.2.8",
+  "version": "1.2.10",
   "description": "Icing on the L4yercak3 - The sweet finishing touch for your Layer Cake integration",
   "main": "src/index.js",
   "bin": {

package/src/commands/mcp-server.js

@@ -15,13 +15,66 @@
 
 const { startServer } = require('../mcp/server');
 
+/**
+ * Check if running in interactive terminal (manual invocation)
+ * vs being called by an MCP client (piped stdin/stdout)
+ */
+function isInteractiveTerminal() {
+  return process.stdin.isTTY && process.stdout.isTTY;
+}
+
+/**
+ * Show setup instructions when run manually
+ */
+function showManualInvocationHelp() {
+  // Use stderr since stdout is reserved for MCP protocol
+  console.error('');
+  console.error('╔══════════════════════════════════════════════════════════════╗');
+  console.error('║              L4YERCAK3 MCP Server - Setup Guide              ║');
+  console.error('╚══════════════════════════════════════════════════════════════╝');
+  console.error('');
+  console.error('This command starts the MCP server for AI assistant integration.');
+  console.error('It\'s typically called by your MCP client, not run directly.');
+  console.error('');
+  console.error('📦 Claude Code (CLI):');
+  console.error('   l4yercak3 mcp-setup');
+  console.error('   # or manually:');
+  console.error('   claude mcp add l4yercak3 -- npx @l4yercak3/cli mcp-server');
+  console.error('');
+  console.error('🖥️  Claude Desktop:');
+  console.error('   Add to ~/Library/Application Support/Claude/claude_desktop_config.json:');
+  console.error('   {');
+  console.error('     "mcpServers": {');
+  console.error('       "l4yercak3": {');
+  console.error('         "command": "npx",');
+  console.error('         "args": ["@l4yercak3/cli", "mcp-server"]');
+  console.error('       }');
+  console.error('     }');
+  console.error('   }');
+  console.error('');
+  console.error('🔌 Other MCP Clients (Cursor, Cody, Continue, etc.):');
+  console.error('   Command: npx @l4yercak3/cli mcp-server');
+  console.error('   Transport: stdio');
+  console.error('');
+  console.error('💡 Requirements:');
+  console.error('   • Logged in to L4YERCAK3 (l4yercak3 login)');
+  console.error('');
+}
+
 module.exports = {
   command: 'mcp-server',
-  description: 'Start the MCP server for Claude Code integration',
+  description: 'Start the MCP server for AI assistant integration',
   handler: async () => {
     // Note: All output goes to stderr because stdout is used for MCP protocol
     // console.error is used intentionally here
 
+    // If running in an interactive terminal (not piped), show help
+    if (isInteractiveTerminal()) {
+      showManualInvocationHelp();
+      console.error('Starting server anyway (press Ctrl+C to exit)...');
+      console.error('');
+    }
+
     try {
       await startServer();
     } catch (error) {

package/src/commands/mcp-setup.js

@@ -0,0 +1,510 @@
+/**
+ * MCP Setup Command
+ *
+ * Configures MCP clients to use the L4YERCAK3 MCP server.
+ * Supports Claude Code CLI, Claude Desktop, and other MCP-compatible clients.
+ *
+ * @module commands/mcp-setup
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const configManager = require('../config/config-manager');
+
+/**
+ * Check if Claude CLI is installed
+ */
+function isClaudeInstalled() {
+  try {
+    execSync('claude --version', { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if MCP server is already configured in Claude
+ */
+function isMcpConfigured() {
+  try {
+    const result = execSync('claude mcp list', {
+      stdio: 'pipe',
+      encoding: 'utf8'
+    });
+    return result.includes('l4yercak3');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Configure Claude MCP with l4yercak3 server
+ */
+async function configureMcp(scope = 'user') {
+  const scopeFlag = scope === 'project' ? '--scope project' : '';
+  const command = `claude mcp add l4yercak3 ${scopeFlag} -- npx @l4yercak3/cli mcp-server`.trim();
+
+  try {
+    execSync(command, { stdio: 'inherit' });
+    return true;
+  } catch (error) {
+    console.error(chalk.red(`Failed to configure MCP: ${error.message}`));
+    return false;
+  }
+}
+
+/**
+ * Remove existing MCP configuration from Claude Code
+ */
+function removeMcpConfig() {
+  try {
+    execSync('claude mcp remove l4yercak3', { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get Claude Desktop config path based on platform
+ */
+function getClaudeDesktopConfigPath() {
+  const platform = os.platform();
+  const home = os.homedir();
+
+  if (platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  } else if (platform === 'win32') {
+    return path.join(process.env.APPDATA || home, 'Claude', 'claude_desktop_config.json');
+  } else {
+    // Linux
+    return path.join(home, '.config', 'Claude', 'claude_desktop_config.json');
+  }
+}
+
+/**
+ * Get the full path to npx executable
+ * Claude Desktop needs absolute paths since it doesn't inherit shell PATH
+ */
+function getNpxPath() {
+  try {
+    const npxPath = execSync('which npx', { stdio: 'pipe', encoding: 'utf8' }).trim();
+    return npxPath || 'npx';
+  } catch {
+    // Fallback to common locations
+    const commonPaths = [
+      '/usr/local/bin/npx',
+      '/opt/homebrew/bin/npx',
+      '/usr/bin/npx',
+      path.join(os.homedir(), '.nvm/versions/node', 'current', 'bin', 'npx'),
+    ];
+
+    for (const p of commonPaths) {
+      if (fs.existsSync(p)) {
+        return p;
+      }
+    }
+
+    return 'npx'; // Last resort fallback
+  }
+}
+
+/**
+ * Get the full path to l4yercak3 CLI if globally installed
+ * Returns null if not found
+ */
+function getL4yercak3Path() {
+  try {
+    const cliPath = execSync('which l4yercak3', { stdio: 'pipe', encoding: 'utf8' }).trim();
+    return cliPath || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the best command configuration for Claude Desktop
+ * Prefers globally installed l4yercak3 over npx for reliability
+ */
+function getClaudeDesktopCommand() {
+  const l4yercak3Path = getL4yercak3Path();
+
+  if (l4yercak3Path) {
+    // Use globally installed CLI directly (more reliable)
+    return {
+      command: l4yercak3Path,
+      args: ['mcp-server'],
+      description: `${l4yercak3Path} mcp-server`
+    };
+  }
+
+  // Fall back to npx
+  const npxPath = getNpxPath();
+  return {
+    command: npxPath,
+    args: ['@l4yercak3/cli', 'mcp-server'],
+    description: `${npxPath} @l4yercak3/cli mcp-server`
+  };
+}
+
+/**
+ * Check if Claude Desktop config exists
+ */
+function hasClaudeDesktopConfig() {
+  return fs.existsSync(getClaudeDesktopConfigPath());
+}
+
+/**
+ * Configure Claude Desktop with l4yercak3 MCP server
+ */
+function configureClaudeDesktop() {
+  const configPath = getClaudeDesktopConfigPath();
+  let config = { mcpServers: {} };
+
+  // Read existing config if it exists
+  if (fs.existsSync(configPath)) {
+    try {
+      const content = fs.readFileSync(configPath, 'utf8');
+      config = JSON.parse(content);
+      if (!config.mcpServers) {
+        config.mcpServers = {};
+      }
+    } catch {
+      // If parsing fails, start fresh but preserve the file structure
+      config = { mcpServers: {} };
+    }
+  } else {
+    // Ensure directory exists
+    const configDir = path.dirname(configPath);
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+  }
+
+  // Add l4yercak3 server with full path
+  // Claude Desktop doesn't inherit shell PATH, so we need absolute paths
+  const cmdConfig = getClaudeDesktopCommand();
+
+  config.mcpServers.l4yercak3 = {
+    command: cmdConfig.command,
+    args: cmdConfig.args
+  };
+
+  // Write config
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+  return { configPath, commandDescription: cmdConfig.description };
+}
+
+/**
+ * Remove l4yercak3 from Claude Desktop config
+ */
+function removeClaudeDesktopConfig() {
+  const configPath = getClaudeDesktopConfigPath();
+
+  if (!fs.existsSync(configPath)) {
+    return false;
+  }
+
+  try {
+    const content = fs.readFileSync(configPath, 'utf8');
+    const config = JSON.parse(content);
+
+    if (config.mcpServers && config.mcpServers.l4yercak3) {
+      delete config.mcpServers.l4yercak3;
+      fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+      return true;
+    }
+  } catch {
+    return false;
+  }
+
+  return false;
+}
+
+/**
+ * Check if l4yercak3 is configured in Claude Desktop
+ */
+function isClaudeDesktopConfigured() {
+  const configPath = getClaudeDesktopConfigPath();
+
+  if (!fs.existsSync(configPath)) {
+    return false;
+  }
+
+  try {
+    const content = fs.readFileSync(configPath, 'utf8');
+    const config = JSON.parse(content);
+    return config.mcpServers && config.mcpServers.l4yercak3;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  command: 'mcp-setup',
+  description: 'Configure MCP clients to use the L4YERCAK3 server',
+  handler: async () => {
+    console.log('');
+    console.log(chalk.bold.hex('#9F7AEA')('🔧 L4YERCAK3 MCP Setup\n'));
+
+    // Check if logged in
+    const session = configManager.getSession();
+    if (!session) {
+      console.log(chalk.yellow('⚠️  Not logged in to L4YERCAK3'));
+      console.log(chalk.gray('   Run `l4yercak3 login` first to authenticate.\n'));
+      console.log(chalk.gray('   The MCP server needs your session to access L4YERCAK3 features.'));
+      process.exit(1);
+    }
+
+    console.log(chalk.green('✓ Logged in as: ') + chalk.white(session.email || session.userId));
+    console.log('');
+
+    // Detect available clients
+    const hasClaudeCli = isClaudeInstalled();
+    const hasClaudeDesktop = hasClaudeDesktopConfig() || fs.existsSync(path.dirname(getClaudeDesktopConfigPath()));
+
+    // Build client choices
+    const clientChoices = [];
+
+    if (hasClaudeCli) {
+      const configured = isMcpConfigured();
+      clientChoices.push({
+        name: `Claude Code (CLI)${configured ? chalk.gray(' - already configured') : ''}`,
+        value: 'claude-code',
+        configured
+      });
+    }
+
+    clientChoices.push({
+      name: `Claude Desktop${isClaudeDesktopConfigured() ? chalk.gray(' - already configured') : ''}`,
+      value: 'claude-desktop',
+      configured: isClaudeDesktopConfigured()
+    });
+
+    clientChoices.push({
+      name: 'Other MCP client (show manual instructions)',
+      value: 'other'
+    });
+
+    // Ask which client to configure
+    const { client } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'client',
+        message: 'Which MCP client would you like to configure?',
+        choices: clientChoices,
+      },
+    ]);
+
+    console.log('');
+
+    if (client === 'claude-code') {
+      await setupClaudeCode();
+    } else if (client === 'claude-desktop') {
+      await setupClaudeDesktop();
+    } else {
+      showOtherClientInstructions();
+    }
+  },
+};
+
+/**
+ * Setup Claude Code CLI
+ */
+async function setupClaudeCode() {
+  const alreadyConfigured = isMcpConfigured();
+
+  if (alreadyConfigured) {
+    const { action } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'action',
+        message: 'L4YERCAK3 is already configured. What would you like to do?',
+        choices: [
+          { name: 'Keep existing configuration', value: 'keep' },
+          { name: 'Reconfigure (remove and re-add)', value: 'reconfigure' },
+          { name: 'Remove configuration', value: 'remove' },
+        ],
+      },
+    ]);
+
+    if (action === 'keep') {
+      console.log(chalk.gray('\nKeeping existing configuration.'));
+      showUsageInstructions('Claude Code');
+      return;
+    }
+
+    if (action === 'remove') {
+      removeMcpConfig();
+      console.log(chalk.green('\n✓ L4YERCAK3 MCP server removed from Claude Code'));
+      return;
+    }
+
+    removeMcpConfig();
+    console.log(chalk.gray('Removed existing configuration...'));
+  }
+
+  // Ask for scope
+  const { scope } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'scope',
+      message: 'Where should the MCP server be configured?',
+      choices: [
+        { name: 'User (global) - Available in all projects', value: 'user' },
+        { name: 'Project - Only for current directory', value: 'project' },
+      ],
+      default: 'user',
+    },
+  ]);
+
+  console.log('');
+  console.log(chalk.gray('Configuring Claude Code...'));
+
+  const success = await configureMcp(scope);
+
+  if (success) {
+    console.log('');
+    console.log(chalk.green.bold('✓ L4YERCAK3 MCP server configured for Claude Code!\n'));
+    showUsageInstructions('Claude Code');
+  } else {
+    console.log('');
+    console.log(chalk.red('Failed to configure MCP server.'));
+    console.log(chalk.gray('\nYou can try manual configuration:'));
+    console.log(chalk.cyan('  claude mcp add l4yercak3 -- npx @l4yercak3/cli mcp-server'));
+  }
+}
+
+/**
+ * Setup Claude Desktop
+ */
+async function setupClaudeDesktop() {
+  const alreadyConfigured = isClaudeDesktopConfigured();
+
+  if (alreadyConfigured) {
+    const { action } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'action',
+        message: 'L4YERCAK3 is already configured. What would you like to do?',
+        choices: [
+          { name: 'Keep existing configuration', value: 'keep' },
+          { name: 'Reconfigure', value: 'reconfigure' },
+          { name: 'Remove configuration', value: 'remove' },
+        ],
+      },
+    ]);
+
+    if (action === 'keep') {
+      console.log(chalk.gray('\nKeeping existing configuration.'));
+      showUsageInstructions('Claude Desktop');
+      return;
+    }
+
+    if (action === 'remove') {
+      removeClaudeDesktopConfig();
+      console.log(chalk.green('\n✓ L4YERCAK3 MCP server removed from Claude Desktop'));
+      console.log(chalk.gray('  Restart Claude Desktop for changes to take effect.'));
+      return;
+    }
+  }
+
+  console.log(chalk.gray('Configuring Claude Desktop...'));
+
+  try {
+    const { configPath, commandDescription } = configureClaudeDesktop();
+    console.log('');
+    console.log(chalk.green.bold('✓ L4YERCAK3 MCP server configured for Claude Desktop!\n'));
+    console.log(chalk.gray(`  Config:  ${configPath}`));
+    console.log(chalk.gray(`  Command: ${commandDescription}`));
+    console.log(chalk.yellow('\n  ⚠️  Restart Claude Desktop for changes to take effect.'));
+    console.log(chalk.gray('  (Using absolute path since Claude Desktop doesn\'t inherit your shell PATH)\n'));
+    showUsageInstructions('Claude Desktop');
+  } catch (error) {
+    console.log('');
+    console.log(chalk.red(`Failed to configure Claude Desktop: ${error.message}`));
+    showClaudeDesktopManualInstructions();
+  }
+}
+
+/**
+ * Show manual instructions for Claude Desktop
+ */
+function showClaudeDesktopManualInstructions() {
+  const configPath = getClaudeDesktopConfigPath();
+  const cmdConfig = getClaudeDesktopCommand();
+
+  console.log(chalk.gray('\nManual configuration:'));
+  console.log(chalk.gray(`  Edit: ${configPath}`));
+  console.log('');
+  console.log(chalk.white('  Add to mcpServers (use absolute paths):'));
+  console.log(chalk.cyan('  {'));
+  console.log(chalk.cyan('    "mcpServers": {'));
+  console.log(chalk.cyan('      "l4yercak3": {'));
+  console.log(chalk.cyan(`        "command": "${cmdConfig.command}",`));
+  console.log(chalk.cyan(`        "args": ${JSON.stringify(cmdConfig.args)}`));
+  console.log(chalk.cyan('      }'));
+  console.log(chalk.cyan('    }'));
+  console.log(chalk.cyan('  }'));
+  console.log('');
+  console.log(chalk.gray('  Note: Claude Desktop doesn\'t inherit your shell PATH.'));
+  console.log(chalk.gray(`  Find paths with: ${chalk.cyan('which l4yercak3')} or ${chalk.cyan('which npx')}`));
+  console.log('');
+}
+
+/**
+ * Show instructions for other MCP clients
+ */
+function showOtherClientInstructions() {
+  console.log(chalk.bold('🔌 Manual MCP Configuration\n'));
+
+  console.log(chalk.white('  Server command:'));
+  console.log(chalk.cyan('    npx @l4yercak3/cli mcp-server\n'));
+
+  console.log(chalk.white('  Transport: ') + chalk.cyan('stdio\n'));
+
+  console.log(chalk.white('  Compatible clients include:'));
+  console.log(chalk.gray('    • Cursor'));
+  console.log(chalk.gray('    • Cody (Sourcegraph)'));
+  console.log(chalk.gray('    • Continue'));
+  console.log(chalk.gray('    • Zed'));
+  console.log(chalk.gray('    • Any MCP-compatible AI assistant'));
+  console.log('');
+
+  console.log(chalk.white('  JSON configuration format:'));
+  console.log(chalk.cyan('  {'));
+  console.log(chalk.cyan('    "command": "npx",'));
+  console.log(chalk.cyan('    "args": ["@l4yercak3/cli", "mcp-server"],'));
+  console.log(chalk.cyan('    "transport": "stdio"'));
+  console.log(chalk.cyan('  }'));
+  console.log('');
+
+  console.log(chalk.gray('  Refer to your client\'s documentation for where to add this config.\n'));
+}
+
+/**
+ * Show usage instructions after setup
+ */
+function showUsageInstructions(clientName = 'your AI assistant') {
+  console.log(chalk.bold('📖 How to use:\n'));
+
+  console.log(chalk.white(`  In ${clientName}, you can now:`));
+  console.log(chalk.gray('  • Ask Claude to list your L4YERCAK3 contacts, projects, or invoices'));
+  console.log(chalk.gray('  • Create or update CRM records through natural language'));
+  console.log(chalk.gray('  • Get project integration help with context from your L4YERCAK3 data'));
+  console.log('');
+
+  console.log(chalk.white('  Example prompts:'));
+  console.log(chalk.cyan('  "Show me my recent contacts in L4YERCAK3"'));
+  console.log(chalk.cyan('  "Create a new project called Website Redesign"'));
+  console.log(chalk.cyan('  "What invoices are pending?"'));
+  console.log('');
+
+  console.log(chalk.gray('  The MCP server runs automatically when needed.'));
+  console.log(chalk.gray('  Your session stays active until you run `l4yercak3 logout`.\n'));
+}

package/src/commands/spread.js

@@ -522,6 +522,8 @@ async function handleSpread() {
             githubRepo: detection.github.isGitHub ? `${detection.github.owner}/${detection.github.repo}` : undefined,
             githubBranch: detection.github.branch || 'main',
           },
+          // Don't generate a new API key if user already has one configured
+          skipApiKeyGeneration: apiKey === null,
         };
 
         const registrationResult = await backendClient.registerApplication(registrationData);
@@ -583,9 +585,9 @@ async function handleSpread() {
         applicationId = registrationResult.applicationId;
         console.log(chalk.green(`  ✅ Application registered with L4YERCAK3\n`));
 
-        // If backend returned a new API key, use it
+        // Show API key if backend generated one
         if (registrationResult.apiKey && registrationResult.apiKey.key) {
-          console.log(chalk.gray(`     API key generated: ${registrationResult.apiKey.prefix}`));
+          console.log(chalk.gray(`     API key: ${registrationResult.apiKey.prefix}`));
         }
       }
     } catch (regError) {

package/src/mcp/registry/domains/applications.js

@@ -464,11 +464,11 @@ Looks at database schemas, types, and common patterns.`,
         },
       },
       requiresAuth: true,
-      handler: async (params, authContext) => {
+      handler: async (params, authContext) => 
         // This tool provides suggestions based on common patterns
         // In a real implementation, it would analyze actual project files
 
-        return {
+         ({
           suggestions: [
             {
               localModel: 'User',
@@ -509,8 +509,8 @@ Looks at database schemas, types, and common patterns.`,
             'Use l4yercak3_add_model_mapping to add mappings you want',
             'Customize field mappings as needed for your schema',
           ],
-        };
-      },
+        })
+      ,
     },
   ],
 };

package/src/mcp/registry/domains/core.js

@@ -195,8 +195,7 @@ Use this when the user needs to login but hasn't yet.`,
         properties: {},
       },
       requiresAuth: false,
-      handler: async () => {
-        return {
+      handler: async () => ({
           instructions: [
             '1. Open a terminal in this project directory',
             '2. Run: l4yercak3 login',
@@ -209,8 +208,7 @@ Use this when the user needs to login but hasn't yet.`,
             '2. Then run: l4yercak3 login',
           ],
           documentation: 'https://docs.l4yercak3.com/cli/authentication',
-        };
-      },
+        }),
     },
 
     // ========================================