alita-mcp

Name	alita-mcp JSON
Version	0.1.19 JSON
	download
home_page	None
Summary	ELITEA MCP Client
upload_time	2025-07-09 20:29:38
maintainer	None
docs_url	None
author	None
requires_python	>=3.10
license	None
keywords	client mcp alita
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Alita MCP Client

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![PyPI version](https://badge.fury.io/py/alita-mcp.svg)](https://badge.fury.io/py/alita-mcp)

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

| Feature | CLI Mode | Tray Mode | Daemon Mode |
|---------|----------|-----------|-------------|
| Server Management | ✅ Manual | ✅ GUI Controls | ✅ Background |
| Configuration | ✅ Bootstrap CMD | ✅ File/Wizard | ✅ File-based |
| User Interface | 💻 Terminal | 🖥️ System Tray | 🔄 Background |
| Auto-start | ❌ Manual | ✅ OS Integration | ✅ Service Mode |
| Resource Usage | 💾 On-demand | 💾 Minimal | 💾 Continuous |
| Best For | Development | Daily Use | Production |

## 🚀 Quick Start

### Installation

#### Using pipx (Recommended)

```bash
# Install pipx if not already installed
pip install pipx

# Install alita-mcp
pipx install alita-mcp
```

#### Using pip

```bash
pip install alita-mcp
```

### Configuration

```bash
# 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

```bash
# Launch the system tray application
alita-mcp tray

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

### Example Usage

```bash
# 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](#installation)
- [System Tray Application](#system-tray-application)
- [Command Line Usage](#command-line-usage)
- [Configuration](#configuration)
- [Server Management](#server-management)
- [Platform-Specific Notes](#platform-specific-notes)
- [Development](#development)
- [Documentation](#documentation)
- [Contributing](#contributing)

## 💻 Installation

### Prerequisites

- Python 3.10 or higher
- pip or pipx package manager

### Method 1: Using pipx (Recommended)

[pipx](https://pypa.github.io/pipx/) installs the package in an isolated environment while making CLI commands globally available.

#### macOS

```bash
# 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

```bash
# 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

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

# Install alita-mcp
pipx install alita-mcp
```

### Method 2: Using pip

```bash
pip install alita-mcp
```

### Method 3: From Source

```bash
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

```bash
# 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
```bash
# 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
```bash
# Add to autostart
mkdir -p ~/.config/autostart
cp scripts/alita-mcp-tray.desktop ~/.config/autostart/
```

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

## 💻 Command Line Usage

### Available Commands

```bash
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

```bash
# 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

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

#### Transport Options

```bash
# 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

```bash
# 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

```bash
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

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

### Configuration File Structure

```json
{
  "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

```json
{
  "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

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

### Daemon Mode

Run servers in the background for continuous operation:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](docs/TRAY_APPLICATION.md)** - Complete tray app guide
- **[TRAY_SETUP_GUIDE.md](docs/TRAY_SETUP_GUIDE.md)** - Platform-specific setup
- **[STATEFUL_SESSIONS.md](docs/STATEFUL_SESSIONS.md)** - Server session management
- **[MACOS_FORK_SAFETY_FIX.md](docs/MACOS_FORK_SAFETY_FIX.md)** - macOS compatibility
- **[DAEMON_MODE_SUMMARY.md](docs/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](LICENSE) file for details.

## 🆘 Support

- **Documentation**: Check the `docs/` directory for detailed guides
- **Issues**: Report bugs and request features on [GitHub Issues](https://github.com/ProjectAlita/alita-mcp-client/issues)
- **Discussions**: Join community discussions on [GitHub Discussions](https://github.com/ProjectAlita/alita-mcp-client/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:
```bash
# 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
```bash
# 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](https://github.com/ProjectAlita/alita-mcp-client/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](#alita-mcp-client)**

Made with ❤️ by the Project Alita Team


            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "alita-mcp",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": "Aliaksei Breilian <Aliaksei_Breilian@epam.com>, Mikalai Biazruchka <Mikalai_Biazruchka@epam.com>",
    "keywords": "client, mcp, alita",
    "author": null,
    "author_email": "Artem Rozumenko <artyom.rozumenko@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/d5/22/71e71affef495d591fbb175556138971d19f4f486bb7ff49eeb75bfed62d/alita_mcp-0.1.19.tar.gz",
    "platform": null,
    "description": "# Alita MCP Client\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![PyPI version](https://badge.fury.io/py/alita-mcp.svg)](https://badge.fury.io/py/alita-mcp)\n\nA 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.\n\n## \u2728 Features\n\n- \ud83d\udda5\ufe0f **System Tray Application** - Easy-to-use GUI with cross-platform support\n- \ud83d\ude80 **Command Line Interface** - Full-featured CLI for developers and automation\n- \ud83d\udd27 **Interactive Bootstrap** - Step-by-step configuration wizard\n- \ud83c\udf10 **Multiple Transports** - Support for stdio and SSE (Server-Sent Events)\n- \ud83d\udd04 **Stateful & Stateless Sessions** - Flexible server connection modes\n- \ud83d\udc27 **Cross-Platform** - Works on Windows, macOS, and Linux\n- \ud83d\udce6 **Easy Installation** - Available via PyPI with pipx support\n- \ud83d\udee1\ufe0f **Production Ready** - Comprehensive error handling and logging\n\n### Feature Comparison\n\n| Feature | CLI Mode | Tray Mode | Daemon Mode |\n|---------|----------|-----------|-------------|\n| Server Management | \u2705 Manual | \u2705 GUI Controls | \u2705 Background |\n| Configuration | \u2705 Bootstrap CMD | \u2705 File/Wizard | \u2705 File-based |\n| User Interface | \ud83d\udcbb Terminal | \ud83d\udda5\ufe0f System Tray | \ud83d\udd04 Background |\n| Auto-start | \u274c Manual | \u2705 OS Integration | \u2705 Service Mode |\n| Resource Usage | \ud83d\udcbe On-demand | \ud83d\udcbe Minimal | \ud83d\udcbe Continuous |\n| Best For | Development | Daily Use | Production |\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n#### Using pipx (Recommended)\n\n```bash\n# Install pipx if not already installed\npip install pipx\n\n# Install alita-mcp\npipx install alita-mcp\n```\n\n#### Using pip\n\n```bash\npip install alita-mcp\n```\n\n### Configuration\n\n```bash\n# Interactive configuration\nalita-mcp bootstrap\n\n# Or with command line parameters\nalita-mcp bootstrap --deployment_url https://api.example.com --auth_token YOUR_TOKEN\n```\n\n### Start System Tray Application\n\n```bash\n# Launch the system tray application\nalita-mcp tray\n\n# Or run in background (daemon mode)\nalita-mcp tray --daemon\n```\n\n### Example Usage\n\n```bash\n# 1. Configure the client\nalita-mcp bootstrap --deployment_url https://api.elitea.com --auth_token your_token_here\n\n# 2. Run with a specific project\nalita-mcp run --project_id 123\n\n# 3. Or start the tray app for GUI management\nalita-mcp tray\n```\n\n## \ud83d\udccb Table of Contents\n\n- [Installation](#installation)\n- [System Tray Application](#system-tray-application)\n- [Command Line Usage](#command-line-usage)\n- [Configuration](#configuration)\n- [Server Management](#server-management)\n- [Platform-Specific Notes](#platform-specific-notes)\n- [Development](#development)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n\n## \ud83d\udcbb Installation\n\n### Prerequisites\n\n- Python 3.10 or higher\n- pip or pipx package manager\n\n### Method 1: Using pipx (Recommended)\n\n[pipx](https://pypa.github.io/pipx/) installs the package in an isolated environment while making CLI commands globally available.\n\n#### macOS\n\n```bash\n# Install pipx\nbrew install pipx\npipx ensurepath\n\n# Install alita-mcp\npipx install alita-mcp\n\n# Add to shell profile (if needed)\necho 'export PATH=\"$PATH:$HOME/.local/bin\"' >> ~/.zprofile\nsource ~/.zprofile\n```\n\n#### Linux\n\n```bash\n# Install pipx\nsudo apt install pipx  # Ubuntu/Debian\n# or\nsudo dnf install pipx  # Fedora\n# or\npip install --user pipx\n\n# Ensure PATH\npipx ensurepath\n\n# Install alita-mcp\npipx install alita-mcp\n```\n\n#### Windows\n\n```powershell\n# Install pipx\npip install --user pipx\npython -m pipx ensurepath\n\n# Install alita-mcp\npipx install alita-mcp\n```\n\n### Method 2: Using pip\n\n```bash\npip install alita-mcp\n```\n\n### Method 3: From Source\n\n```bash\ngit clone https://github.com/ProjectAlita/alita-mcp-client.git\ncd alita-mcp-client\npip install -e .\n```\n\n## \ud83c\udfae System Tray Application\n\nThe system tray application provides an intuitive GUI for managing your MCP client without requiring terminal knowledge.\n\n### Features\n\n- **\ud83d\udda5\ufe0f System Tray Integration** - Minimalist icon in your system tray\n- **\ud83d\udcc1 Configuration Management** - Open config files, run bootstrap wizard\n- **\ud83d\udd04 Server Control** - Start/stop MCP servers with different modes\n- **\ud83d\udcca Real-time Status** - Visual feedback for server operations\n- **\ud83c\udf0d Cross-Platform** - Windows, macOS, and Linux support\n- **\ud83d\udeab No GUI Dependencies** - Works in all environments\n\n### Starting the Tray App\n\n```bash\n# Launch tray application\nalita-mcp tray\n\n# Run in background (daemon mode)\nalita-mcp tray --daemon\n\n# Using launch scripts (platform-specific)\n./scripts/launch-tray-macos.sh      # macOS\n./scripts/launch-tray-windows.bat   # Windows\n```\n\n### Tray Menu Options\n\nRight-click the tray icon to access:\n\n#### Server Control\n- **Start MCP Server (Embedded)** - Run servers within the tray process\n- **Start MCP Server (Daemon)** - Run servers as background daemon\n- **Stop MCP Server** - Stop running servers (shows current mode)\n- **Restart MCP Server** - Reload configuration by stopping and starting servers\n\n#### Configuration\n- **Open Config File** - Edit JSON configuration in default text editor\n- **Open Config Folder** - Open configuration directory in file manager\n- **Bootstrap (Terminal)** - Run interactive configuration setup\n- **View Current Config** - Display current settings via system notification\n\n#### Application\n- **About** - Application information and version\n- **Quit** - Exit the tray application\n\n### Auto-Start Setup\n\n#### macOS\n```bash\n# Copy launch script to Applications\ncp scripts/launch-tray-macos.sh ~/Applications/\n\n# Add to Login Items in System Preferences\n# or create a Launch Agent (see docs/TRAY_SETUP_GUIDE.md)\n```\n\n#### Linux\n```bash\n# Add to autostart\nmkdir -p ~/.config/autostart\ncp scripts/alita-mcp-tray.desktop ~/.config/autostart/\n```\n\n#### Windows\n```powershell\n# Copy to Startup folder\n# Press Win+R, type shell:startup, then copy launch-tray-windows.bat\n```\n\n## \ud83d\udcbb Command Line Usage\n\n### Available Commands\n\n```bash\nalita-mcp --help                    # Show all available commands\nalita-mcp bootstrap                 # Configure deployment URL and auth token\nalita-mcp run                       # Run MCP client with specific project/app\nalita-mcp serve                     # Start MCP servers in background\nalita-mcp tray                      # Launch system tray application\n```\n\n### Running MCP Client\n\n#### With Specific Application\n\n```bash\n# Run with specific project and application\nalita-mcp run --project_id YOUR_PROJECT_ID --app_id YOUR_APP_ID\n\n# Include version (optional)\nalita-mcp run --project_id YOUR_PROJECT_ID --app_id YOUR_APP_ID --version_id YOUR_VERSION_ID\n```\n\n#### With All Project Agents\n\n```bash\n# Use all available agents in a project\nalita-mcp run --project_id YOUR_PROJECT_ID\n```\n\n#### Transport Options\n\n```bash\n# Default: stdio transport\nalita-mcp run --project_id YOUR_PROJECT_ID\n\n# SSE transport for web applications\nalita-mcp run --project_id YOUR_PROJECT_ID --transport sse --port 8000\n```\n\n### Server Management\n\n```bash\n# Start servers in background\nalita-mcp serve --daemon\n\n# Custom PID and log files\nalita-mcp serve --daemon --pid-file /path/to/app.pid --log-file /path/to/app.log\n\n# View running servers\nps aux | grep alita-mcp\n```\n\n## \u2699\ufe0f Configuration\n\n### Configuration Locations\n\nThe client stores configuration in your OS's standard app data directory:\n\n- **Windows**: `%APPDATA%\\alita-mcp-client`\n- **macOS**: `~/Library/Application Support/alita-mcp-client`\n- **Linux**: `~/.config/alita-mcp-client`\n\n### Bootstrap Configuration\n\n#### Interactive Mode\n\n```bash\nalita-mcp bootstrap\n```\n\nThis launches an interactive wizard that guides you through:\n1. **Deployment URL** - Your ELITEA platform endpoint\n2. **Authentication Token** - Your API authentication token\n3. **Server Configuration** - Host and port settings\n4. **MCP Server Setup** - Configure available MCP servers\n   - When prompted for **Args**, enter all arguments in a single line separated\n     by spaces. They will be stored as a list in the configuration file.\n\n#### Command Line Mode\n\n```bash\nalita-mcp bootstrap \\\n  --deployment_url https://api.example.com \\\n  --auth_token YOUR_TOKEN \\\n  --host 0.0.0.0 \\\n  --port 8000\n```\n\n### Configuration File Structure\n\n```json\n{\n  \"deployment_url\": \"https://api.example.com\",\n  \"auth_token\": \"your-auth-token\",\n  \"host\": \"0.0.0.0\",\n  \"port\": 8000,\n  \"servers\": {\n    \"server1\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp_server\"],\n      \"env\": {},\n      \"stateful\": false\n    }\n  }\n}\n```\n\n## \ud83d\udd04 Server Management\n\n### Stateful vs Stateless Sessions\n\n#### Stateless (Default)\n- Each tool call creates a fresh connection\n- Server state resets between calls\n- Best for: File operations, API calls, simple commands\n\n```json\n{\n  \"servers\": {\n    \"api_server\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"api_mcp_server\"],\n      \"stateful\": false\n    }\n  }\n}\n```\n\n#### Stateful\n- Maintains persistent connections\n- Server state persists between calls\n- Best for: Browser automation, database connections, complex workflows\n\n```json\n{\n  \"servers\": {\n    \"browser_server\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"playwright_mcp_server\"],\n      \"stateful\": true\n    }\n  }\n}\n```\n\n### Daemon Mode\n\nRun servers in the background for continuous operation:\n\n```bash\n# Start daemon\nalita-mcp serve --daemon\n\n# Check status\nps aux | grep \"alita-mcp serve\"\n\n# Stop daemon (find PID and kill)\nkill $(cat ~/.local/var/run/alita-mcp/alita-mcp-serve.pid)\n```\n\n## \ud83d\udda5\ufe0f Platform-Specific Notes\n\n### macOS\n- **Fork Safety**: Automatic handling of GUI framework compatibility\n- **Dock Integration**: Tray app automatically hides from dock\n- **Launch Agents**: Support for automatic startup\n- **Homebrew**: Easy installation via pipx\n\n### Linux\n- **Desktop Entry**: Autostart support via `.desktop` files\n- **System Tray**: Compatible with GNOME, KDE, and other desktop environments\n- **Package Managers**: Works with apt, dnf, pacman via pip/pipx\n\n### Windows\n- **System Tray**: Native Windows system tray integration\n- **Startup Folder**: Easy auto-start setup\n- **PowerShell**: Full PowerShell compatibility\n\n## \ud83d\udee0\ufe0f Development\n\n### Setup Development Environment\n\n```bash\n# Clone repository\ngit clone https://github.com/ProjectAlita/alita-mcp-client.git\ncd alita-mcp-client\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install in editable mode\npip install -e .\n\n# Install development dependencies\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npython -m pytest\n\n# Run with coverage\npython -m pytest --cov=alita_mcp\n\n# Run specific test file\npython -m pytest tests/test_fork_safety.py -v\n```\n\n### Building and Publishing\n\n```bash\n# Install build tools\npip install build twine\n\n# Build the package\npython -m build\n\n# Upload to PyPI (requires authentication)\ntwine upload dist/*\n```\n\n## \ud83d\udcda Documentation\n\nComprehensive documentation is available in the `docs/` directory:\n\n- **[TRAY_APPLICATION.md](docs/TRAY_APPLICATION.md)** - Complete tray app guide\n- **[TRAY_SETUP_GUIDE.md](docs/TRAY_SETUP_GUIDE.md)** - Platform-specific setup\n- **[STATEFUL_SESSIONS.md](docs/STATEFUL_SESSIONS.md)** - Server session management\n- **[MACOS_FORK_SAFETY_FIX.md](docs/MACOS_FORK_SAFETY_FIX.md)** - macOS compatibility\n- **[DAEMON_MODE_SUMMARY.md](docs/DAEMON_MODE_SUMMARY.md)** - Background operations\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Commit** your changes (`git commit -m 'Add amazing feature'`)\n4. **Push** to the branch (`git push origin feature/amazing-feature`)\n5. **Open** a Pull Request\n\n### Development Guidelines\n\n- Follow PEP 8 style guidelines\n- Add tests for new features\n- Update documentation as needed\n- Ensure cross-platform compatibility\n\n## \ud83d\udcdd License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## \ud83c\udd98 Support\n\n- **Documentation**: Check the `docs/` directory for detailed guides\n- **Issues**: Report bugs and request features on [GitHub Issues](https://github.com/ProjectAlita/alita-mcp-client/issues)\n- **Discussions**: Join community discussions on [GitHub Discussions](https://github.com/ProjectAlita/alita-mcp-client/discussions)\n\n## \ud83d\udd27 Troubleshooting\n\n### Common Issues\n\n#### macOS: \"Fork Safety\" Errors\nIf 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.\n\n#### Tray Icon Not Appearing\n- **Linux**: Ensure your desktop environment supports system tray icons\n- **Windows**: Check if system tray icons are enabled in taskbar settings\n- **macOS**: The icon should appear in the menu bar (top-right area)\n\n#### Command Not Found\nIf `alita-mcp` command is not found:\n```bash\n# For pipx installations\npipx ensurepath\nsource ~/.bashrc  # or ~/.zprofile for zsh\n\n# For pip installations\npip install --user alita-mcp\nexport PATH=\"$PATH:$HOME/.local/bin\"\n```\n\n#### Configuration Issues\n```bash\n# Reset configuration\nrm -rf ~/.config/alita-mcp-client  # Linux\nrm -rf ~/Library/Application\\ Support/alita-mcp-client  # macOS\n# Then run: alita-mcp bootstrap\n```\n\n### Getting Help\n\n1. Check the relevant documentation in `docs/`\n2. Search existing [GitHub Issues](https://github.com/ProjectAlita/alita-mcp-client/issues)\n3. Create a new issue with:\n   - Your operating system and version\n   - Python version (`python --version`)\n   - Full error message and traceback\n   - Steps to reproduce the issue\n\n## \ud83d\udd04 Changelog\n\n### Version 0.1.10 (Latest)\n\n- \u2705 **System Tray Application** - Complete GUI interface with context menus\n- \u2705 **macOS Fork Safety Fix** - Resolved all macOS GUI compatibility issues\n- \u2705 **Daemon Mode** - Background server operation with PID management\n- \u2705 **Cross-Platform Support** - Full Windows, macOS, and Linux compatibility\n- \u2705 **Auto-Start Integration** - System-level startup scripts and services\n- \u2705 **Enhanced Error Handling** - Comprehensive logging and recovery mechanisms\n- \u2705 **Configuration Management** - File-based config with GUI and CLI access\n- \u2705 **Production Ready** - Stable release with comprehensive testing\n\n### Previous Versions\n\n- **0.1.9** - Added basic tray functionality\n- **0.1.8** - Improved server management\n- **0.1.7** - Enhanced CLI interface\n- **0.1.6** - Initial PyPI release\n\n---\n\n**[\u2b06 Back to Top](#alita-mcp-client)**\n\nMade with \u2764\ufe0f by the Project Alita Team\n\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "ELITEA MCP Client",
    "version": "0.1.19",
    "project_urls": {
        "Documentation": "https://github.com/ProjectAlita/alita-mcp-client#readme",
        "Homepage": "https://github.com/ProjectAlita/alita-mcp-client",
        "Issues": "https://github.com/ProjectAlita/alita-mcp-client/issues",
        "Repository": "https://github.com/ProjectAlita/alita-mcp-client.git"
    },
    "split_keywords": [
        "client",
        " mcp",
        " alita"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "b91ce009a2779960ff75c7deb152e78c8c36c4ed260a18ca884a1c97d7c4b0f7",
                "md5": "1b8370de3d6962b2290451556af79def",
                "sha256": "50d14988e0e796bfaa303107415c4bfbd8855ee79d6705e57eb465b99bf4f026"
            },
            "downloads": -1,
            "filename": "alita_mcp-0.1.19-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "1b8370de3d6962b2290451556af79def",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 47282,
            "upload_time": "2025-07-09T20:29:37",
            "upload_time_iso_8601": "2025-07-09T20:29:37.329570Z",
            "url": "https://files.pythonhosted.org/packages/b9/1c/e009a2779960ff75c7deb152e78c8c36c4ed260a18ca884a1c97d7c4b0f7/alita_mcp-0.1.19-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "d52271e71affef495d591fbb175556138971d19f4f486bb7ff49eeb75bfed62d",
                "md5": "36dc6691fc513bfbbdcfdf2fd2e5283c",
                "sha256": "c360d42cf740726f2c71e329ee9152f1b15e75491b5079f849e8beacdc59345c"
            },
            "downloads": -1,
            "filename": "alita_mcp-0.1.19.tar.gz",
            "has_sig": false,
            "md5_digest": "36dc6691fc513bfbbdcfdf2fd2e5283c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 61208,
            "upload_time": "2025-07-09T20:29:38",
            "upload_time_iso_8601": "2025-07-09T20:29:38.928526Z",
            "url": "https://files.pythonhosted.org/packages/d5/22/71e71affef495d591fbb175556138971d19f4f486bb7ff49eeb75bfed62d/alita_mcp-0.1.19.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-09 20:29:38",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "ProjectAlita",
    "github_project": "alita-mcp-client#readme",
    "github_not_found": true,
    "lcname": "alita-mcp"
}