node-server-orchestrator

Node Server Orchestrator

A powerful MCP (Model Context Protocol) server 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
• MCP Standard - Full compliance with Model Context Protocol
• Extensible - Easy to configure new projects and server types
• Cross-Platform - Works on Windows, macOS, and Linux

📋 Available Tools

• start_server - Start a specific project server
• stop_server - Stop a running server
• get_server_status - Get detailed server status with uptime
• list_servers - List all configured servers
• start_all_servers - Start all servers simultaneously

🛠️ 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

# Start the MCP server
node-server-orchestrator mcp

# 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

Integration with AI Agents

When integrated with an AI agent (like Claude), the MCP server provides tools that can be called programmatically:

// Example agent usage
const result = await mcpClient.callTool('start_server', {
  server_id: 'my-backend'
});
console.log(result.content[0].text);

Example Workflow

• List available servers:

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

• Start a server:

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

• 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

AI Agent Automation

• Let AI assistants manage development servers
• Automated testing and deployment workflows
• Multi-project development coordination

🔌 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.

🚨 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.

🙏 Acknowledgments

Built with the Model Context Protocol SDK.