ShingWong/node-server-orchestrator

Node Server Orchestrator

A CLI tool for orchestrating Node.js development servers across multiple projects. Start, stop, and monitor backend, frontend, database, and other Node.js-based development servers with a unified interface.

🚀 Features

• Multi-Project Support - Manage servers across different projects

• Health Monitoring - Real-time status checks with uptime tracking

• Error Handling - Startup failure detection and clear error messages

• Extensible - Easy to configure new projects and server types

• Cross-Platform - Works on Windows, macOS, and Linux

📋 Available Commands

• start <server-id> - Start a specific project server
• stop <server-id> - Stop a running server
• status <server-id> - Get detailed server status with uptime
• list - List all configured servers
• start-all - Start all servers simultaneously
• stop-all - Stop all running servers

🛠️ Installation

npm install -g node-server-orchestrator

Or use directly:

npx node-server-orchestrator

⚙️ Configuration

Create a configuration file at ~/.config/node-server-orchestrator/config.json:

{
  "projects": {
    "my-backend": {
      "name": "My Backend API",
      "type": "backend",
      "command": ["npm", "run", "dev"],
      "cwd": "/path/to/my-project",
      "port": 3000,
      "healthPath": "/health",
      "startupTimeout": 10000,
      "description": "My project backend server"
    },
    "my-frontend": {
      "name": "My Frontend App",
      "type": "frontend", 
      "command": ["npm", "start"],
      "cwd": "/path/to/my-project/frontend",
      "port": 3001,
      "healthPath": "/",
      "startupTimeout": 15000,
      "description": "My project frontend development server"
    }
  }
}

🔧 Usage

CLI Usage

# List all available servers
node-server-orchestrator list

# Start a specific server
node-server-orchestrator start example-backend

# Stop a specific server  
node-server-orchestrator stop example-backend

# Check server status
node-server-orchestrator status example-backend

# Start all servers
node-server-orchestrator start-all

# Stop all servers
node-server-orchestrator stop-all

# Show help
node-server-orchestrator --help

Example Workflow

1. List available servers:

   📋 Available Servers:
   My Backend API (my-backend) - My project backend server
   My Frontend App (my-frontend) - My project frontend development server
   

2. Start a server:

   ✅ My Backend API started successfully
   📊 PID: 12345
   🌐 Port: 3000
   ⏰ Started: 2:30:45 PM
   

3. Check status:

   🟢 My Backend API is running
   📊 PID: 12345
   🌐 Port: 3000
   ⏰ Started: 2:30:45 PM
   ⏱️  Uptime: 5m 23s
   

🎯 Use Cases

Development Workflows

• Start all project servers with one command
• Monitor server health during development
• Automatically restart servers on changes

CI/CD Integration

• Start test environments programmatically
• Verify server health before deployments
• Manage multiple microservices

🔌 API Reference

Server Configuration

Each server configuration supports:

• name: Human-readable server name
• type: Server type (backend, frontend, database, etc.)
• command: Command array to start the server
• cwd: Working directory for the server
• port: Port number for health checks
• healthPath: HTTP path for health checks
• startupTimeout: Maximum startup wait time in milliseconds
• description: Server description

Health Check Protocol

Servers are considered healthy when they respond with HTTP 200/304 on the specified port and health path.

🔒 Security Features

The CLI tool includes comprehensive security measures:

Input Validation

• Server ID Validation: Only alphanumeric characters, hyphens, and underscores allowed
• Command Whitelist: Only pre-approved commands (npm, node, yarn, pnpm, bun) can be executed
• Port Validation: Port numbers must be between 1-65535
• Path Validation: Working directories must be absolute paths
• Timeout Limits: Startup timeouts capped at 60 seconds maximum

Command Injection Protection

• Shell Execution: All commands run with shell: false to prevent command injection
• Command Array: Commands must be provided as arrays, not strings

Path Traversal Prevention

• Config Path Sanitization: Prevents ../ directory traversal in configuration files
• Absolute Paths: All working directories must be absolute paths

Error Information Protection

• Error Sanitization: Sensitive paths and IP addresses are redacted from error messages
• Limited Information: Error messages provide only necessary information

🚨 Error Handling

The MCP server provides clear error messages for:

• Port conflicts - When a server is already running
• Startup failures - When servers fail to start within timeout
• Process crashes - When managed processes terminate unexpectedly
• Configuration errors - Invalid server configurations

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

Development Setup

git clone https://github.com/swong-fcsllc/node-server-orchestrator.git
cd node-server-orchestrator
npm install
npm run build
npm test

📄 License

MIT License - see LICENSE file for details.