@deriv-com/fe-mcp-servers 0.0.8 → 0.0.10

package/README.md

@@ -4,6 +4,7 @@ A collection of Front-End Model Context Protocol (MCP) servers for reusability a
 
 ## 🏗️ Project Structure
 
+### Source Structure (Development)
 ```
 mcps/
 ├── shift-ai/                  # Individual MCP server
@@ -30,14 +31,43 @@ mcps/
 npm install -g @deriv-com/fe-mcp-servers
 ```
 
-### Get Your Configuration Path
-Copy and run this command to get the exact path for your MCP configuration:
+### CLI Commands
+
+After installation, use the `fe-mcp` CLI to manage MCP servers:
+
+```bash
+# List all available MCP servers
+fe-mcp list
+
+# Interactive config generator - creates file & opens it for copy-paste
+fe-mcp code
+
+# Show detailed info about a specific server
+fe-mcp info shift-ai
+
+# Output MCP client configuration JSON
+fe-mcp config shift-ai
+
+# Show help
+fe-mcp help
+
+# Show version
+fe-mcp --version
+```
+
+### Quick Setup (Recommended)
+
+The easiest way to get your MCP config:
 
 ```bash
-echo "$(npm root -g)/@deriv-com/fe-mcp-servers/dist/SERVER_NAME/mcp-server.js"
+fe-mcp code
 ```
 
-Replace `SERVER_NAME` with the specific server you want (e.g., `shift-ai`).
+This will:
+1. Show you a list of available MCP servers
+2. Ask you to select one
+3. Generate the configuration JSON with the correct path
+4. Save it to a file and auto-open it for easy copy-paste
 
 ### MCP Configuration Template
 ```json
@@ -45,7 +75,7 @@ Replace `SERVER_NAME` with the specific server you want (e.g., `shift-ai`).
   "mcpServers": {
     "server-name": {
       "command": "node",
-      "args": ["<PASTE_PATH_FROM_ABOVE>"]
+      "args": ["<PATH_FROM_FE-MCP>"]
     }
   }
 }
@@ -66,11 +96,14 @@ Replace `SERVER_NAME` with the specific server you want (e.g., `shift-ai`).
 ## 🛠️ Development
 
 ### Building the Package
+The build process bundles all dependencies into standalone executables:
 ```bash
 cd mcps
 npm run build
 ```
 
+This creates bundled files in `dist/` with all dependencies included.
+
 ### Running Tests
 ```bash
 npm run test
@@ -79,64 +112,35 @@ npm run test
 ### Adding New MCP Servers
 
 1. Create a new directory in `mcps/`
-2. Add the required structure:
+2. Add the required **source structure**:
    ```
    your-server/
    ├── src/
-   │   ├── mcp-server.js    # Required: Main MCP server
-   │   ├── your-logic.js    # Your server logic
-   │   └── test-mcp.js      # Optional: Tests
-   └── README.md            # Required: Documentation
+   │   ├── mcp-server.js     # Main server implementation (entry point)
+   │   └── mcp.js           # Core functionality
+   └── README.md            # Server documentation
    ```
-3. Use standard npm imports (dependencies are resolved from mcps root)
-4. The build script will automatically include it
+3. Implement your MCP server logic in the `src/` files
+4. The build process will automatically bundle everything into `dist/your-server/mcp-server.js`
+5. Users will reference the **bundled file** (not the source) in their MCP configuration
 
-## Available MCP Servers
-
-### 🚀 shift-ai
-AI code generation and analysis server that provides intelligent code suggestions, analysis, and automated code generation capabilities.
-
-**Status**: ✅ Active
-**Location**: `shift-ai/`
-
-### 🐙 github-mcp
-GitHub integration server for repository management, issue tracking, and pull request automation.
-
-**Status**: 🚧 Planned
-**Location**: `github-mcp/`
-
-### 💬 slack-mcp
-Slack workspace automation server for communication workflows and bot integrations.
-
-**Status**: 🚧 Planned
-**Location**: `slack-mcp/`
-
-### 🗄️ database-mcp
-Database query and schema management server supporting multiple database systems.
-
-**Status**: 🚧 Planned
-**Location**: `database-mcp/`
-
-## 📦 Distribution
-
-This package is published to npm as part of the @deriv/ai-tools collection with all dependencies bundled for easy installation and usage.
-
-## 🔧 Standards
+### Requirements for New Servers
 
 Each MCP server must:
-- Have `src/mcp-server.js` as the main entry point
-- Use standard npm package imports
-- Include comprehensive `README.md` documentation
-- Follow consistent coding patterns
-- Include test coverage where applicable
+- Have `src/mcp-server.js` as the main entry point (source file)  
+- Follow the MCP protocol specification
+- Include comprehensive documentation in README.md
+- The build process will bundle everything into a single executable `dist/server-name/mcp-server.js` file
 
 ## 🏗️ Architecture
 
-- **Monorepo Structure**: All servers in one package for easy distribution
-- **Shared Dependencies**: Common dependencies bundled at mcps level
-- **Automatic Discovery**: Build system automatically finds and includes servers
-- **Global Installation**: Zero-configuration setup via npm global install
-- **Standardized Structure**: Consistent patterns across all servers
-- **Protocol**: [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
-- **Runtime**: Node.js
-- **Build System**: Automated packaging and distribution 
+### Build Process
+- **Input**: Source files in `src/` directories
+- **Process**: esbuild bundles all dependencies
+- **Output**: Single executable files in `dist/` directories
+- **Distribution**: npm package contains only the `dist/` directory
+
+### Dependency Management
+- All dependencies are bundled into the final executable
+- No external dependency resolution required at runtime
+- Standalone files that work in any Node.js environment 

package/bin/fe-mcp.js

@@ -0,0 +1,424 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execSync, spawn } from 'child_process';
+import readline from 'readline';
+import os from 'os';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(__dirname, '..');
+const distDir = path.join(packageRoot, 'dist');
+const srcDir = packageRoot;
+
+// Read package.json for version
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+
+// ANSI colors
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  red: '\x1b[31m',
+};
+
+const c = (color, text) => `${colors[color]}${text}${colors.reset}`;
+
+/**
+ * Get all available MCP servers
+ */
+function getMcpServers() {
+  const servers = [];
+  
+  // Check dist directory for built servers
+  if (fs.existsSync(distDir)) {
+    const entries = fs.readdirSync(distDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const mcpServerPath = path.join(distDir, entry.name, 'mcp-server.js');
+        const readmePath = path.join(distDir, entry.name, 'README.md');
+        
+        if (fs.existsSync(mcpServerPath)) {
+          const server = {
+            name: entry.name,
+            path: mcpServerPath,
+            hasReadme: fs.existsSync(readmePath),
+            readmePath: readmePath,
+            built: true,
+          };
+          
+          // Try to extract description from README
+          if (server.hasReadme) {
+            const readme = fs.readFileSync(readmePath, 'utf-8');
+            const descMatch = readme.match(/^#[^\n]+\n+([^\n#]+)/);
+            if (descMatch) {
+              server.description = descMatch[1].trim();
+            }
+          }
+          
+          servers.push(server);
+        }
+      }
+    }
+  }
+  
+  // Also check source directories for unbuilt servers
+  const srcEntries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of srcEntries) {
+    if (entry.isDirectory() && 
+        !['dist', 'bin', 'node_modules', 'scripts'].includes(entry.name) &&
+        !entry.name.startsWith('.')) {
+      const srcMcpPath = path.join(srcDir, entry.name, 'src', 'mcp-server.js');
+      
+      if (fs.existsSync(srcMcpPath)) {
+        // Check if already in servers list (built version)
+        const existing = servers.find(s => s.name === entry.name);
+        if (!existing) {
+          const readmePath = path.join(srcDir, entry.name, 'README.md');
+          const server = {
+            name: entry.name,
+            path: srcMcpPath,
+            hasReadme: fs.existsSync(readmePath),
+            readmePath: readmePath,
+            built: false,
+          };
+          
+          if (server.hasReadme) {
+            const readme = fs.readFileSync(readmePath, 'utf-8');
+            const descMatch = readme.match(/^#[^\n]+\n+([^\n#]+)/);
+            if (descMatch) {
+              server.description = descMatch[1].trim();
+            }
+          }
+          
+          servers.push(server);
+        }
+      }
+    }
+  }
+  
+  return servers;
+}
+
+/**
+ * List all available MCP servers
+ */
+function listServers() {
+  const servers = getMcpServers();
+  
+  if (servers.length === 0) {
+    console.log(c('yellow', '\n⚠️  No MCP servers found.'));
+    console.log(c('dim', '   Run "npm run build" to build the servers first.\n'));
+    return;
+  }
+  
+  console.log(c('bright', '\n📦 Available MCP Servers\n'));
+  console.log(c('dim', '─'.repeat(60)));
+  
+  for (const server of servers) {
+    const status = server.built 
+      ? c('green', '● built') 
+      : c('yellow', '○ source only');
+    
+    console.log(`\n  ${c('cyan', server.name)} ${c('dim', `(${status})`)}`);
+    
+    if (server.description) {
+      console.log(`  ${c('dim', server.description)}`);
+    }
+  }
+  
+  console.log(c('dim', '\n─'.repeat(60)));
+  console.log(c('dim', `\nTotal: ${servers.length} server(s)`));
+  console.log(c('dim', `\nUse "${c('cyan', 'fe-mcp info <name>')}" for details`));
+  console.log(c('dim', `Use "${c('cyan', 'fe-mcp path <name>')}" to get the executable path\n`));
+}
+
+/**
+ * Show detailed info about a specific MCP server
+ */
+function showInfo(serverName) {
+  const servers = getMcpServers();
+  const server = servers.find(s => s.name === serverName);
+  
+  if (!server) {
+    console.log(c('red', `\n❌ MCP server "${serverName}" not found.\n`));
+    console.log(c('dim', 'Available servers:'));
+    servers.forEach(s => console.log(c('dim', `  - ${s.name}`)));
+    console.log();
+    process.exit(1);
+  }
+  
+  console.log(c('bright', `\n📦 ${server.name}\n`));
+  console.log(c('dim', '─'.repeat(60)));
+  
+  if (server.description) {
+    console.log(`\n${c('bright', 'Description:')}`);
+    console.log(`  ${server.description}`);
+  }
+  
+  console.log(`\n${c('bright', 'Status:')} ${server.built ? c('green', 'Built ✓') : c('yellow', 'Not built')}`);
+  console.log(`${c('bright', 'Path:')} ${server.path}`);
+  
+  if (server.built) {
+    console.log(`\n${c('bright', 'MCP Configuration:')}`);
+    console.log(c('dim', '  Add this to your MCP client config:\n'));
+    
+    const config = {
+      [server.name]: {
+        command: 'node',
+        args: [server.path]
+      }
+    };
+    
+    console.log(c('cyan', JSON.stringify({ mcpServers: config }, null, 2)));
+  }
+  
+  if (server.hasReadme) {
+    console.log(`\n${c('bright', 'Documentation:')} ${server.readmePath}`);
+  }
+  
+  console.log(c('dim', '\n─'.repeat(60) + '\n'));
+}
+
+/**
+ * Show help
+ */
+function showHelp() {
+  console.log(`
+${c('bright', '@deriv-com/fe-mcp-servers CLI')}
+
+${c('bright', 'Usage:')}
+  fe-mcp <command> [options]
+
+${c('bright', 'Commands:')}
+  ${c('cyan', 'list')}              List all available MCP servers
+  ${c('cyan', 'code')}              Interactive config generator (creates file & opens it)
+  ${c('cyan', 'info <name>')}       Show detailed info about a specific server
+  ${c('cyan', 'config <name>')}     Output MCP client configuration JSON
+  ${c('cyan', 'help')}              Show this help message
+  ${c('cyan', '-v, --version')}     Show version number
+
+${c('bright', 'Examples:')}
+  fe-mcp list
+  fe-mcp code
+  fe-mcp info shift-ai
+  fe-mcp config shift-ai
+
+${c('bright', 'Global Installation:')}
+  npm install -g @deriv-com/fe-mcp-servers
+  fe-mcp list
+`);
+}
+
+/**
+ * Output MCP config JSON for a server
+ */
+function outputConfig(serverName) {
+  const servers = getMcpServers();
+  const server = servers.find(s => s.name === serverName);
+  
+  if (!server) {
+    console.error(c('red', `MCP server "${serverName}" not found.`));
+    process.exit(1);
+  }
+  
+  if (!server.built) {
+    console.error(c('red', `MCP server "${serverName}" is not built yet.`));
+    console.error(c('dim', 'Run "npm run build" first.'));
+    process.exit(1);
+  }
+  
+  const config = {
+    [server.name]: {
+      command: 'node',
+      args: [server.path]
+    }
+  };
+  
+  console.log(JSON.stringify(config, null, 2));
+}
+
+/**
+ * Get global npm root path
+ */
+function getGlobalNpmRoot() {
+  try {
+    return execSync('npm root -g', { encoding: 'utf-8' }).trim();
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Open a file with the default application
+ */
+function openFile(filePath) {
+  const platform = os.platform();
+  let command;
+  
+  if (platform === 'darwin') {
+    command = 'open';
+  } else if (platform === 'win32') {
+    command = 'start';
+  } else {
+    command = 'xdg-open';
+  }
+  
+  try {
+    spawn(command, [filePath], { detached: true, stdio: 'ignore' }).unref();
+  } catch (error) {
+    console.log(c('yellow', `\n⚠️  Could not auto-open file. Please open manually:`));
+    console.log(c('cyan', `   ${filePath}\n`));
+  }
+}
+
+/**
+ * Prompt user to select from a list
+ */
+function promptSelect(question, options) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    
+    console.log(c('bright', `\n${question}\n`));
+    
+    options.forEach((opt, i) => {
+      console.log(`  ${c('cyan', `[${i + 1}]`)} ${opt.name}${opt.description ? c('dim', ` - ${opt.description.substring(0, 50)}...`) : ''}`);
+    });
+    
+    console.log();
+    
+    rl.question(c('bright', 'Enter number: '), (answer) => {
+      rl.close();
+      const index = parseInt(answer, 10) - 1;
+      if (index >= 0 && index < options.length) {
+        resolve(options[index]);
+      } else {
+        console.log(c('red', '\n❌ Invalid selection.\n'));
+        process.exit(1);
+      }
+    });
+  });
+}
+
+/**
+ * Generate MCP config file and open it
+ */
+async function generateConfigFile() {
+  const servers = getMcpServers().filter(s => s.built);
+  
+  if (servers.length === 0) {
+    console.log(c('yellow', '\n⚠️  No built MCP servers found.'));
+    console.log(c('dim', '   Run "npm run build" to build the servers first.\n'));
+    process.exit(1);
+  }
+  
+  console.log(c('bright', '\n🔧 MCP Configuration Generator\n'));
+  console.log(c('dim', '─'.repeat(50)));
+  
+  // Let user select a server
+  const selected = await promptSelect('Select an MCP server:', servers);
+  
+  // Get the global npm path
+  const globalRoot = getGlobalNpmRoot();
+  let serverPath;
+  
+  if (globalRoot) {
+    // Use global path for installed package
+    serverPath = `${globalRoot}/@deriv-com/fe-mcp-servers/dist/${selected.name}/mcp-server.js`;
+  } else {
+    // Fallback to local path
+    serverPath = selected.path;
+  }
+  
+  // Generate config
+  const config = {
+    mcpServers: {
+      [selected.name]: {
+        command: 'node',
+        args: [serverPath]
+      }
+    }
+  };
+  
+  const configJson = JSON.stringify(config, null, 2);
+  
+  // Create temp file
+  const tempDir = os.tmpdir();
+  const fileName = 'fe-mcp-config.txt';
+  const filePath = path.join(tempDir, fileName);
+  
+  // Write config to file
+  fs.writeFileSync(filePath, configJson, 'utf-8');
+  
+  console.log(c('green', `\n✅ Configuration generated for ${c('cyan', selected.name)}`));
+  console.log(c('dim', '─'.repeat(50)));
+  console.log(c('bright', '\nConfiguration:\n'));
+  console.log(c('cyan', configJson));
+  console.log(c('dim', '\n─'.repeat(50)));
+  console.log(c('dim', `\nFile saved to: ${filePath}`));
+  console.log(c('bright', '\n📂 Opening file for copy-paste...\n'));
+  
+  // Open the file
+  openFile(filePath);
+}
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const command = args[0];
+
+switch (command) {
+  case 'list':
+  case 'ls':
+  case undefined:
+    listServers();
+    break;
+  
+  case 'code':
+    generateConfigFile();
+    break;
+    
+  case 'info':
+  case 'show':
+    if (!args[1]) {
+      console.log(c('red', '\n❌ Please specify a server name.'));
+      console.log(c('dim', '   Example: fe-mcp info shift-ai\n'));
+      process.exit(1);
+    }
+    showInfo(args[1]);
+    break;
+    
+  case 'config':
+    if (!args[1]) {
+      console.log(c('red', '\n❌ Please specify a server name.'));
+      console.log(c('dim', '   Example: fe-mcp config shift-ai\n'));
+      process.exit(1);
+    }
+    outputConfig(args[1]);
+    break;
+    
+  case 'help':
+  case '--help':
+  case '-h':
+    showHelp();
+    break;
+  
+  case 'version':
+  case '--version':
+  case '-v':
+    console.log(`${packageJson.name} v${packageJson.version}`);
+    break;
+    
+  default:
+    console.log(c('red', `\n❌ Unknown command: ${command}`));
+    showHelp();
+    process.exit(1);
+}