Alita MCP Client

A powerful and user-friendly MCP (Model Context Protocol) client with both command-line interface and system tray application. Provides seamless integration with the ELITEA platform for managing MCP servers and AI agents.

✨ Features

• 🖥️ System Tray Application - Easy-to-use GUI with cross-platform support
• 🚀 Command Line Interface - Full-featured CLI for developers and automation
• 🔧 Interactive Bootstrap - Step-by-step configuration wizard
• 🌐 Multiple Transports - Support for stdio and SSE (Server-Sent Events)
• 🔄 Stateful & Stateless Sessions - Flexible server connection modes
• 🐧 Cross-Platform - Works on Windows, macOS, and Linux
• 📦 Easy Installation - Available via PyPI with pipx support
• 🛡️ Production Ready - Comprehensive error handling and logging

Feature Comparison

🚀 Quick Start

Installation

Using pipx (Recommended)

# Install pipx if not already installed
pip install pipx

# Install alita-mcp
pipx install alita-mcp

Using pip

pip install alita-mcp

Configuration

# Interactive configuration
alita-mcp bootstrap

# Or with command line parameters
alita-mcp bootstrap --deployment_url https://api.example.com --auth_token YOUR_TOKEN

Start System Tray Application

# Launch the system tray application
alita-mcp tray

# Or run in background (daemon mode)
alita-mcp tray --daemon

Example Usage

# 1. Configure the client
alita-mcp bootstrap --deployment_url https://api.elitea.com --auth_token your_token_here

# 2. Run with a specific project
alita-mcp run --project_id 123

# 3. Or start the tray app for GUI management
alita-mcp tray

📋 Table of Contents

• Installation
• System Tray Application
• Command Line Usage
• Configuration
• Server Management
• Platform-Specific Notes
• Development
• Documentation
• Contributing

💻 Installation

Prerequisites

• Python 3.10 or higher
• pip or pipx package manager

Method 1: Using pipx (Recommended)

pipx installs the package in an isolated environment while making CLI commands globally available.

macOS

# Install pipx
brew install pipx
pipx ensurepath

# Install alita-mcp
pipx install alita-mcp

# Add to shell profile (if needed)
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zprofile
source ~/.zprofile

Linux

# Install pipx
sudo apt install pipx  # Ubuntu/Debian
# or
sudo dnf install pipx  # Fedora
# or
pip install --user pipx

# Ensure PATH
pipx ensurepath

# Install alita-mcp
pipx install alita-mcp

Windows

# Install pipx
pip install --user pipx
python -m pipx ensurepath

# Install alita-mcp
pipx install alita-mcp

Method 2: Using pip

pip install alita-mcp

Method 3: From Source

git clone https://github.com/ProjectAlita/alita-mcp-client.git
cd alita-mcp-client
pip install -e .

🎮 System Tray Application

The system tray application provides an intuitive GUI for managing your MCP client without requiring terminal knowledge.

Features

• 🖥️ System Tray Integration - Minimalist icon in your system tray
• 📁 Configuration Management - Open config files, run bootstrap wizard
• 🔄 Server Control - Start/stop MCP servers with different modes
• 📊 Real-time Status - Visual feedback for server operations
• 🌍 Cross-Platform - Windows, macOS, and Linux support
• 🚫 No GUI Dependencies - Works in all environments

Starting the Tray App

# Launch tray application
alita-mcp tray

# Run in background (daemon mode)
alita-mcp tray --daemon

# Using launch scripts (platform-specific)
./scripts/launch-tray-macos.sh      # macOS
./scripts/launch-tray-windows.bat   # Windows

Tray Menu Options

Right-click the tray icon to access:

Server Control

• Start MCP Server (Embedded) - Run servers within the tray process
• Start MCP Server (Daemon) - Run servers as background daemon
• Stop MCP Server - Stop running servers (shows current mode)
• Restart MCP Server - Reload configuration by stopping and starting servers

Configuration

• Open Config File - Edit JSON configuration in default text editor
• Open Config Folder - Open configuration directory in file manager
• Bootstrap (Terminal) - Run interactive configuration setup
• View Current Config - Display current settings via system notification

Application

• About - Application information and version
• Quit - Exit the tray application

Auto-Start Setup

macOS

# Copy launch script to Applications
cp scripts/launch-tray-macos.sh ~/Applications/

# Add to Login Items in System Preferences
# or create a Launch Agent (see docs/TRAY_SETUP_GUIDE.md)

Linux

# Add to autostart
mkdir -p ~/.config/autostart
cp scripts/alita-mcp-tray.desktop ~/.config/autostart/

Windows

# Copy to Startup folder
# Press Win+R, type shell:startup, then copy launch-tray-windows.bat

💻 Command Line Usage

Available Commands

alita-mcp --help                    # Show all available commands
alita-mcp bootstrap                 # Configure deployment URL and auth token
alita-mcp run                       # Run MCP client with specific project/app
alita-mcp serve                     # Start MCP servers in background
alita-mcp tray                      # Launch system tray application

Running MCP Client

With Specific Application

# Run with specific project and application
alita-mcp run --project_id YOUR_PROJECT_ID --app_id YOUR_APP_ID

# Include version (optional)
alita-mcp run --project_id YOUR_PROJECT_ID --app_id YOUR_APP_ID --version_id YOUR_VERSION_ID

With All Project Agents

# Use all available agents in a project
alita-mcp run --project_id YOUR_PROJECT_ID

Transport Options

# Default: stdio transport
alita-mcp run --project_id YOUR_PROJECT_ID

# SSE transport for web applications
alita-mcp run --project_id YOUR_PROJECT_ID --transport sse --port 8000

Server Management

# Start servers in background
alita-mcp serve --daemon

# Custom PID and log files
alita-mcp serve --daemon --pid-file /path/to/app.pid --log-file /path/to/app.log

# View running servers
ps aux | grep alita-mcp

⚙️ Configuration

Configuration Locations

The client stores configuration in your OS's standard app data directory:

• Windows: %APPDATA%\alita-mcp-client
• macOS: ~/Library/Application Support/alita-mcp-client
• Linux: ~/.config/alita-mcp-client

Bootstrap Configuration

Interactive Mode

alita-mcp bootstrap

This launches an interactive wizard that guides you through:

1. Deployment URL - Your ELITEA platform endpoint
2. Authentication Token - Your API authentication token
3. Server Configuration - Host and port settings
4. MCP Server Setup - Configure available MCP servers
   • When prompted for Args, enter all arguments in a single line separated by spaces. They will be stored as a list in the configuration file.

Command Line Mode

alita-mcp bootstrap \
  --deployment_url https://api.example.com \
  --auth_token YOUR_TOKEN \
  --host 0.0.0.0 \
  --port 8000

Configuration File Structure

{
  "deployment_url": "https://api.example.com",
  "auth_token": "your-auth-token",
  "host": "0.0.0.0",
  "port": 8000,
  "servers": {
    "server1": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "env": {},
      "stateful": false
    }
  }
}

🔄 Server Management

Stateful vs Stateless Sessions

Stateless (Default)

• Each tool call creates a fresh connection
• Server state resets between calls
• Best for: File operations, API calls, simple commands

{
  "servers": {
    "api_server": {
      "command": "python",
      "args": ["-m", "api_mcp_server"],
      "stateful": false
    }
  }
}

Stateful

• Maintains persistent connections
• Server state persists between calls
• Best for: Browser automation, database connections, complex workflows

{
  "servers": {
    "browser_server": {
      "command": "python",
      "args": ["-m", "playwright_mcp_server"],
      "stateful": true
    }
  }
}

Daemon Mode

Run servers in the background for continuous operation:

# Start daemon
alita-mcp serve --daemon

# Check status
ps aux | grep "alita-mcp serve"

# Stop daemon (find PID and kill)
kill $(cat ~/.local/var/run/alita-mcp/alita-mcp-serve.pid)

🖥️ Platform-Specific Notes

macOS

• Fork Safety: Automatic handling of GUI framework compatibility
• Dock Integration: Tray app automatically hides from dock
• Launch Agents: Support for automatic startup
• Homebrew: Easy installation via pipx

Linux

• Desktop Entry: Autostart support via .desktop files
• System Tray: Compatible with GNOME, KDE, and other desktop environments
• Package Managers: Works with apt, dnf, pacman via pip/pipx

Windows

• System Tray: Native Windows system tray integration
• Startup Folder: Easy auto-start setup
• PowerShell: Full PowerShell compatibility

🛠️ Development

Setup Development Environment

# Clone repository
git clone https://github.com/ProjectAlita/alita-mcp-client.git
cd alita-mcp-client

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode
pip install -e .

# Install development dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=alita_mcp

# Run specific test file
python -m pytest tests/test_fork_safety.py -v

Building and Publishing

# Install build tools
pip install build twine

# Build the package
python -m build

# Upload to PyPI (requires authentication)
twine upload dist/*

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

• TRAY_APPLICATION.md - Complete tray app guide
• TRAY_SETUP_GUIDE.md - Platform-specific setup
• STATEFUL_SESSIONS.md - Server session management
• MACOS_FORK_SAFETY_FIX.md - macOS compatibility
• DAEMON_MODE_SUMMARY.md - Background operations

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guidelines
• Add tests for new features
• Update documentation as needed
• Ensure cross-platform compatibility

📝 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🆘 Support

• Documentation: Check the docs/ directory for detailed guides
• Issues: Report bugs and request features on GitHub Issues
• Discussions: Join community discussions on GitHub Discussions

🔧 Troubleshooting

Common Issues

macOS: "Fork Safety" Errors

If you encounter fork safety errors on macOS, they have been automatically resolved in version 0.1.10+. The client now uses fork-safe daemon mode for GUI applications.

Tray Icon Not Appearing

• Linux: Ensure your desktop environment supports system tray icons
• Windows: Check if system tray icons are enabled in taskbar settings
• macOS: The icon should appear in the menu bar (top-right area)

Command Not Found

If alita-mcp command is not found:

# For pipx installations
pipx ensurepath
source ~/.bashrc  # or ~/.zprofile for zsh

# For pip installations
pip install --user alita-mcp
export PATH="$PATH:$HOME/.local/bin"

Configuration Issues

# Reset configuration
rm -rf ~/.config/alita-mcp-client  # Linux
rm -rf ~/Library/Application\ Support/alita-mcp-client  # macOS
# Then run: alita-mcp bootstrap

Getting Help

1. Check the relevant documentation in docs/
2. Search existing GitHub Issues
3. Create a new issue with:
   • Your operating system and version
   • Python version (python --version)
   • Full error message and traceback
   • Steps to reproduce the issue

🔄 Changelog

Version 0.1.10 (Latest)

• ✅ System Tray Application - Complete GUI interface with context menus
• ✅ macOS Fork Safety Fix - Resolved all macOS GUI compatibility issues
• ✅ Daemon Mode - Background server operation with PID management
• ✅ Cross-Platform Support - Full Windows, macOS, and Linux compatibility
• ✅ Auto-Start Integration - System-level startup scripts and services
• ✅ Enhanced Error Handling - Comprehensive logging and recovery mechanisms
• ✅ Configuration Management - File-based config with GUI and CLI access
• ✅ Production Ready - Stable release with comprehensive testing

Previous Versions

• 0.1.9 - Added basic tray functionality
• 0.1.8 - Improved server management
• 0.1.7 - Enhanced CLI interface
• 0.1.6 - Initial PyPI release

⬆ Back to Top

Made with ❤️ by the Project Alita Team