# auto-om - Linux Automation Operations Management MCP Server

[![Version](https://img.shields.io/badge/version-0.8.0-blue.svg)](https://github.com/atoncooper/auto-om)
[![Python](https://img.shields.io/badge/python-3.11+-green.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE)

[English](README.md) | [简体中文](docs/README_CN.md)

A comprehensive Model Context Protocol (MCP) server for Linux automation operations management. This MCP server provides 74+ tools across 8 categories for efficient Linux server management through SSH connections.

## Features

### Tool Categories (88 tools total)

| Category | Tools Count | Status |
|----------|-------------|--------|
| 📁 File & Directory Management | 12 | ✅ Complete |
| 📝 Text Processing & Analysis | 11 | ✅ Complete |
| 📊 System Monitoring | 11 | ✅ Complete |
| ⚙️ Process Management | 10 | ✅ Complete |
| 👤 User & Permissions | 0 | ⏳ Pending |
| 🌐 Network Operations | 14 | ✅ Complete |
| 📦 Compression & Archive | 8 | ✅ Complete |
| 🔄 Package Management | 7 | ✅ Complete |

### Key Capabilities

- **File Operations**: Create, copy, move, delete files and directories
- **Text Processing**: View, search, transform text files with regex support
- **System Monitoring**: CPU, memory, disk, process monitoring in real-time
- **Process Control**: Kill, signal, and manage process priorities
- **Network Diagnostics**: Ping, traceroute, DNS, HTTP testing, port scanning
- **Compression**: Create and extract tar, zip, gzip, bzip2, xz archives
- **Package Management**: Install, remove, update packages (apt, yum, dnf)

## Installation

### Prerequisites

- Python 3.11 or higher
- pip and pipenv
- Linux servers with SSH access

### Setup from Source

```bash
# Clone the repository
git clone https://github.com/atoncooper/auto-om.git
cd auto-om

# Install dependencies with pipenv
pipenv install

# Activate virtual environment
pipenv shell

# Or install with pip directly
pip install -r requirements.txt
```

### Using Docker

```bash
# Build the Docker image
docker build -t auto-om:latest .

# Or use docker-compose
docker-compose up -d
```

## Configuration

Create an `application.yaml` file:

```yaml
# Transport mode: "stdio" or "http"
transport:
  mode: http

# HTTP settings (for http mode)
http:
  host: 0.0.0.0
  port: 8000

# SSH connection pool
ssh_pool:
  default_timeout: 30
  max_retries: 3
  connection_timeout: 10
  retry_delay: 5
  max_connections: 10

  # Add your Linux servers
  servers:
    - host: "192.168.1.100"
      port: 22
      username: "your_username"
      password: "your_password"
      alias: "server1"
```

**⚠️ Security Warning**: Use environment variables for sensitive data in production:

```bash
export SSH_PASSWORD="your_password"
```

Then reference it in YAML:
```yaml
servers:
  - host: "192.168.1.100"
    username: "your_username"
    password: "${SSH_PASSWORD}"
```

## Usage

### Start the Server

```bash
# Run in stdio mode (default, for MCP clients)
python main.py

# Run in HTTP mode
python main.py --mode http

# Run with custom host/port
python main.py --mode http --host 127.0.0.1 --port 9000

# Using custom config
python main.py --config /path/to/config.yaml
```

### Docker Usage

```bash
# Run with docker-compose
docker-compose up

# Run with docker
docker run -p 8000:8000 \
  -v $(pwd)/application.yaml:/app/application.yaml \
  auto-om:latest
```

### Documentation

Complete documentation for integrating with various AI development tools:

| Tool | Documentation | Use Case |
|------|---------------|----------|
| **Claude Code** | [Claude Code Guide](docs/claude-code-guide.md) | CLI-based AI development assistant |
| **Cursor** | [Cursor Guide](docs/cursor-guide.md) | AI-powered IDE for coding |
| **Trae** | [Trae Guide](docs/trae-guide.md) | Mobile/terminal AI assistant |

### Quick Start with AI Tools

#### Claude Code (CLI)
```bash
# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Configure in ~/.config/Claude/claude_desktop_config.json
# Then use: claude-code "Check server status on server1"
```

#### Cursor (IDE)
1. Open Cursor Settings
2. Navigate to MCP section
3. Add server: `http://localhost:8000/sse`
4. Start using tools in Cursor's AI chat

#### Trae (Mobile)
1. Install Trae app (iOS/Android)
2. Add MCP server: `http://your-server-ip:8000/sse`
3. Use voice or text commands for server management

### Quick Start

Use the provided scripts:

```bash
# Linux/macOS
./scripts/start.sh

# Windows
scripts\start.bat
```

## MCP Client Integration

#### Using Postman MCP

1. Install Postman MCP Client
2. Add MCP Server: `http://your-server:8000/sse`
3. Tools will be automatically discovered

#### Using Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "auto-om": {
      "command": "python",
      "args": ["/path/to/auto-om/main.py"],
      "env": {
        "PYTHONPATH": "/path/to/auto-om"
      }
    }
  }
}
```

## Tool Examples

### File Management

```json
{
  "host": "server1",
  "path": "/home/user/documents"
}
```

### System Monitoring

```json
{
  "host": "server1",
  "human_readable": true
}
```

### Process Control

```json
{
  "host": "server1",
  "pid": 1234,
  "signal": "TERM"
}
```

### Network Diagnostics

```json
{
  "host": "server1",
  "destination": "google.com",
  "count": 5
}
```

### Package Management

```json
{
  "host": "server1",
  "packages": "nginx",
  "dry_run": true
}
```

## Architecture

```
auto-om/
├── main.py                 # Entry point
├── application.yaml        # Configuration file
├── requirements.txt        # Python dependencies
├── Dockerfile             # Container definition
├── docker-compose.yml     # Multi-container setup
├── src/
│   ├── core/              # Core MCP functionality
│   │   ├── server.py      # MCP server implementation
│   │   └── ssh_client.py  # SSH connection pool
│   └── tools/             # Tool implementations
│       ├── file_mgr.py        # File management (12 tools)
│       ├── text_proc.py        # Text processing (11 tools)
│       ├── system_monitor.py   # System monitoring (11 tools)
│       ├── process_mgr.py      # Process management (10 tools)
│       ├── network_ops.py      # Network operations (14 tools)
│       ├── compress_ops.py     # Compression (8 tools)
│       └── package_mgr.py      # Package management (7 tools)
├── VERSION.md             # Version history
└── README.md              # This file
```

## Security Features

- **Non-root Operations**: All operations designed for non-root users
- **Path Validation**: Prohibited operations on system directories
- **Command Validation**: Dangerous commands are blocked
- **Dry-run Mode**: Preview destructive operations before executing
- **Connection Pooling**: Secure SSH connection management
- **Output Limits**: Prevent overwhelming responses

## Supported Linux Distributions

- Debian 10+
- Ubuntu 18.04+
- CentOS 7+
- RHEL 7+
- Fedora 30+

## Dependencies

- Python 3.11+
- paramiko 3.5.0 (SSH2 protocol)
- mcp 1.25.0 (Model Context Protocol)
- pyyaml 6.0.3 (YAML configuration)

## Development

```bash
# Install development dependencies
pipenv install --dev

# Run tests (when available)
pytest tests/

# Format code
black src/

# Type checking
mypy src/
```

## Version History

See [VERSION.md](VERSION.md) for detailed version history.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## License

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

## Support

For issues and questions:
- GitHub Issues: https://github.com/atoncooper/auto-om/issues
- Documentation: [VERSION.md](VERSION.md)

## Acknowledgments

- Built with [MCP Python SDK](https://github.com/anthropics/python-mcp-sdk)
- Inspired by common Linux automation tools