# MCP Manager

A comprehensive full-stack application for managing Model Context Protocol (MCP) servers for Claude Desktop with intelligent setup, auto-scanning, enhanced error handling, and a modern web interface.

## ✨ Features

### **🖥️ Full-Stack Architecture**
- **CLI Tool**: Enhanced command-line interface with setup wizard and auto-scanning
- **Web Interface**: Modern React frontend with real-time server management
- **REST API**: FastAPI backend with comprehensive endpoints
- **Cross-Platform**: Works on Windows, macOS, and Linux

### **🚀 Core Functionality**
- **Server Discovery**: Automatically finds available MCP servers from multiple sources
- **Easy Installation**: Install servers with automatic dependency management
- **Configuration Management**: Safely manage Claude Desktop configuration with atomic operations
- **Backup & Restoration**: Built-in backup and restore functionality
- **Real-time Monitoring**: Live server status and health monitoring
- **Web Dashboard**: Beautiful, responsive web interface for all operations

### **🔧 Enhanced Features**
- **🧙‍♂️ Setup Wizard**: Interactive guided onboarding for new users
- **🔍 Auto-Scanning**: Automatic discovery of new MCP servers and updates
- **🛠️ Smart Error Handling**: Auto-fix suggestions and intelligent recovery
- **📢 Notification System**: Stay informed about updates and recommendations
- **💊 Health Monitoring**: System diagnostics and dependency checking
- **🎯 Personalized Recommendations**: Intelligent server suggestions
- **⭐ GitHub Integration**: Support for awesome-mcp-servers repositories

## 🏗️ Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web Frontend  │    │   REST API      │    │   CLI Tool      │
│   (React)       │────│   (FastAPI)     │────│   (Python)      │
│   Port 3001     │    │   Port 8001     │    │   Direct Access │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  Core Services  │
                    │                 │
                    │ • Config Mgmt   │
                    │ • Server Sources│
                    │ • Notifications │
                    │ • Health Monitor│
                    │ • GitHub Parser │
                    │ • Error Handler │
                    └─────────────────┘
```

## 🚀 Quick Start

### **Option 1: Web Interface (Recommended)**

1. **Start the Backend API:**
   ```bash
   cd backend
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload
   ```

2. **Start the Frontend:**
   ```bash
   cd frontend
   npm install
   npm run dev
   ```

3. **Access the Web Interface:**
   Open http://localhost:3001 in your browser

### **Option 2: CLI Tool**

```bash
# Clone and set up
git clone <your-repo-url>
cd mcp-manager
chmod +x mcp-manager

# Run interactive setup (recommended for first-time users)
./mcp-manager setup
```

## 📱 Web Interface Features

### **🎛️ Dashboard**
- Server installation status overview
- System health monitoring
- Quick access to common operations
- Real-time connection status

### **🔧 Server Management**
- Browse 60+ available MCP servers
- Install/uninstall servers with one click
- View detailed server information
- Category and tag-based filtering

### **📊 System Monitoring**
- Health score and system diagnostics
- Dependency status checking
- Configuration validation
- Performance metrics

### **⚙️ Configuration**
- Visual Claude Desktop config management
- Backup and restore operations
- Environment settings
- API configuration

### **📢 Notifications**
- Real-time alerts and updates
- Priority-based notification system
- Action items with one-click solutions
- Notification history and management

## 📋 CLI Commands

### **Core Commands**
```bash
# Server Management
./mcp-manager list                    # Show installed servers
./mcp-manager available              # Show available servers
./mcp-manager backup                 # Create configuration backup

# Enhanced Commands
./mcp-manager setup                  # 🆕 Interactive setup wizard
./mcp-manager scan                   # 🆕 Scan for updates and new servers
./mcp-manager diagnose               # 🆕 Run system health check
./mcp-manager notifications          # 🆕 View alerts and updates
./mcp-manager status                 # Enhanced with notifications
```

### **Command Options**
```bash
--config-path <path>     # Override default config location
--verbose                # Detailed output
--json                   # Output in JSON format
--no-cache              # Skip cache for fresh data
--force                 # Skip confirmation prompts
```

## 🛠️ Development Setup

### **Prerequisites**
- **Python 3.8+** (required)
- **Node.js 16+** and npm (for frontend)
- **Git** (for version control)

### **Full Development Environment**

1. **Clone the Repository:**
   ```bash
   git clone <your-repo-url>
   cd mcp-manager
   ```

2. **Backend Setup:**
   ```bash
   cd backend
   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate
   pip install -r requirements.txt
   uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload
   ```

3. **Frontend Setup:**
   ```bash
   cd frontend
   npm install
   npm run dev
   ```

4. **CLI Setup:**
   ```bash
   # Make CLI executable
   chmod +x mcp-manager
   
   # Run setup wizard
   ./mcp-manager setup
   ```

### **Available Scripts**

#### Backend
```bash
uvicorn app.main:app --reload          # Development server
uvicorn app.main:app --host 0.0.0.0    # Production server
python -m pytest                       # Run tests
```

#### Frontend
```bash
npm run dev         # Development server
npm run build       # Production build
npm run preview     # Preview production build
npm run lint        # Lint code
```

## 🌐 API Endpoints

The FastAPI backend provides comprehensive REST endpoints:

- **`GET /api/health`**: Health check
- **`GET /api/servers/available`**: List available servers
- **`GET /api/servers/installed`**: List installed servers
- **`POST /api/servers/install`**: Install a server
- **`DELETE /api/servers/{name}`**: Uninstall a server
- **`GET /api/system/status`**: System health status
- **`POST /api/system/scan`**: Run system scan
- **`GET /api/notifications/`**: Get notifications
- **`GET /api/analytics/overview`**: Analytics dashboard

Full API documentation available at: http://localhost:8001/docs

## 🔧 Configuration

MCP Manager automatically discovers your Claude Desktop configuration:

- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

### Configuration Schema
```json
{
  "mcpServers": {
    "server-name": {
      "command": "executable-path",
      "args": ["arg1", "arg2"],
      "env": {
        "KEY": "value"
      }
    }
  }
}
```

## 🛡️ Safety Features

### **Atomic Operations**
- All configuration changes use atomic file operations
- Temporary files prevent corruption during writes
- Automatic rollback on any failure

### **Automatic Backups**
- Backups created before any destructive operation
- Timestamped backup files for easy identification
- Easy restoration through web interface or CLI

### **Comprehensive Validation**
- JSON schema validation for all configuration changes
- Server name validation (alphanumeric with hyphens/underscores)
- Environment variable validation
- Pre-flight checks before operations

## 🚨 Troubleshooting

### **Common Issues**

| Issue | Solution |
|-------|----------|
| "No configuration found" | Run setup wizard or ensure Claude Desktop has been run once |
| "Backend connection failed" | Ensure backend is running on port 8001 |
| "npm not available" | Install Node.js from https://nodejs.org/ |
| "pip not available" | Install Python from https://python.org/ |
| "Permission denied" | Check file permissions or run with appropriate privileges |

### **Getting Help**
```bash
# CLI Diagnostics
./mcp-manager diagnose
./mcp-manager status --verbose
./mcp-manager notifications --all

# Web Interface
# Visit http://localhost:3001/system for health dashboard
# Check browser console for frontend errors
# Review backend logs for API issues
```

### **Emergency Recovery**
If your configuration becomes corrupted:
```bash
# List available backups
ls ~/.config/Claude/mcp_manager_backups/

# CLI recovery
./mcp-manager status --verbose

# Web interface recovery
# Navigate to System > Configuration for backup restore
```

## 🏢 Technology Stack

### **Frontend**
- **React 18** with TypeScript
- **Vite** for fast development and building
- **TailwindCSS** for modern styling
- **Tanstack Query** for API state management
- **React Router** for navigation

### **Backend**
- **FastAPI** for modern Python API development
- **Pydantic** for data validation
- **Uvicorn** for ASGI server
- **Requests** for HTTP client functionality

### **CLI Tool**
- **Python 3.8+** with cross-platform support
- **Rich** for beautiful terminal output
- **Click** for CLI framework
- **GitPython** for repository operations

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Commit changes (`git commit -m 'Add amazing feature'`)
7. Push to branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## ⭐ Key Benefits

- **Zero Learning Curve**: Setup wizard eliminates configuration complexity
- **Modern Interface**: Beautiful web UI alongside powerful CLI
- **Stay Current**: Never miss important updates or useful new servers
- **Reduce Errors**: Automatic error detection and intelligent recovery
- **Save Time**: Smart recommendations and one-click solutions
- **Production Ready**: Comprehensive safety features and error handling
- **Cross-Platform**: Works seamlessly on Windows, Mac, and Linux

---

**Ready to get started?** 

- **Web Interface**: Run the backend and frontend, then visit http://localhost:3001
- **CLI Tool**: Run `./mcp-manager setup` for a guided setup experience!