Metadata-Version: 2.4
Name: server-ops-mcp
Version: 0.1.7
Summary: MCP server for VPS management — SSH, Docker, services, GitHub, deployments, monitoring
Project-URL: Homepage, https://github.com/TECH-SAVVY-PI/devops-mcp
Project-URL: Repository, https://github.com/TECH-SAVVY-PI/devops-mcp
Project-URL: Issues, https://github.com/TECH-SAVVY-PI/devops-mcp/issues
Author: Tech
License-Expression: MIT
Keywords: devops,docker,mcp,server-management,ssh
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: asyncssh>=2.14
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25.0
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: docker
Requires-Dist: aiodocker>=0.22; extra == 'docker'
Description-Content-Type: text/markdown

# server-ops-mcp

MCP server for VPS management — SSH commands, Docker containers, service management, GitHub integration, deployments, and monitoring.

Uses **lazy category loading** — only meta-tools are registered at startup. The agent enables categories on demand.

## Quick Start

### 1. Install

```bash
pip install server-ops-mcp
```

### 2. Setup your VPS (one-time)

```bash
server-ops-mcp setup --host 1.2.3.4
```

This will:
- Prompt for your sudo password (hidden input, never stored)
- Create a `mcp-agent` user on the VPS
- Configure NOPASSWD sudo for service commands
- Generate an Ed25519 SSH keypair
- Save the private key to `~/.ssh/server-ops-<name>`
- Update `~/.config/devops-mcp/config.json`

### 3. Add to your MCP client

```json
{
  "mcpServers": {
    "server-ops": {
      "command": "server-ops-mcp"
    }
  }
}
```

### 4. Use it

Just talk to your agent:
- "Check disk usage on my server"
- "Restart nginx"
- "Deploy latest code"

The agent discovers and enables tool categories automatically.

## Commands

```bash
server-ops-mcp                          # Start MCP server (default)
server-ops-mcp setup --host <ip>        # One-time VPS provisioning
server-ops-mcp info                     # Show setup info and management guide
server-ops-mcp info --name my-vps       # Info for a specific host
```

## Configuration

### Setup (Recommended)

Use `server-ops-mcp setup` — handles everything automatically.

### Manual Config

Create `~/.config/devops-mcp/config.json`:

```json
{
  "hosts": {
    "my-server": {
      "host": "1.2.3.4",
      "username": "mcp-agent",
      "port": 22,
      "key_path": "~/.ssh/server-ops-my-server"
    }
  },
  "default_host": "my-server",
  "enabled_categories": ["ssh", "docker", "utility"],
  "github": {
    "token": "ghp_..."
  }
}
```

### Environment Variables

```bash
export DEVOPS_MCP_HOST=1.2.3.4
export DEVOPS_MCP_USER=root
export DEVOPS_MCP_KEY=~/.ssh/id_ed25519
export DEVOPS_MCP_GITHUB_TOKEN=ghp_...
```

## MCP Client Setup

### opencode

```json
{
  "mcpServers": {
    "server-ops": {
      "command": "server-ops-mcp"
    }
  }
}
```

### Claude Desktop

```json
{
  "mcpServers": {
    "server-ops": {
      "command": "server-ops-mcp"
    }
  }
}
```

### Cursor

```json
{
  "mcpServers": {
    "server-ops": {
      "command": "server-ops-mcp"
    }
  }
}
```

## Security

### How it works

1. `server-ops-mcp setup` runs once in your terminal (not in the agent)
2. Creates a dedicated `mcp-agent` user on your VPS
3. Configures NOPASSWD sudo for service commands only
4. Generates SSH keypair — private key stays on your machine
5. Password is never stored or passed to the agent

### Remove access

```bash
# On the VPS
sudo userdel -r mcp-agent
sudo rm /etc/sudoers.d/mcp-agent
```

### Add password to user (if needed later)

```bash
# On the VPS
sudo passwd mcp-agent
```

### Rotate SSH key

```bash
# On your machine
server-ops-mcp setup --host 1.2.3.4 --name my-vps
```

## Tools (48 total)

### Meta-tools (always loaded)

| Tool | Description |
|------|-------------|
| `list_categories` | List available tool categories and their status |
| `enable_category` | Enable a category, registering its tools |
| `disable_category` | Disable a category, removing its tools |
| `search_tools` | Search across all categories (including disabled) |

### SSH (9 tools)

| Tool | Description |
|------|-------------|
| `ssh_exec` | Run a command on the remote host |
| `ssh_upload` | Upload file content via SFTP |
| `ssh_download` | Download a file via SFTP |
| `ssh_file_read` | Read a remote file (with offset/limit) |
| `ssh_file_write` | Write a remote file (overwrite) |
| `ssh_file_edit` | Edit a remote file (exact string replacement) |
| `ssh_provision_user` | Create Linux user + push SSH key |
| `ssh_unlock_admin` | Unlock sudo session (15-min TTL) |
| `ssh_lock_admin` | Lock sudo session |

### Docker (6 tools)

| Tool | Description |
|------|-------------|
| `docker_exec_cmd` | Run command in a container |
| `docker_logs_cmd` | Get container logs |
| `docker_ps_cmd` | List containers |
| `docker_start_cmd` | Start a container |
| `docker_stop_cmd` | Stop a container |
| `docker_restart_cmd` | Restart a container |

### Services (7 tools)

| Tool | Description |
|------|-------------|
| `service_status` | Get systemd service status |
| `service_start` | Start a systemd service |
| `service_stop` | Stop a systemd service |
| `service_restart` | Restart a systemd service |
| `service_logs` | Get service logs via journalctl |
| `nginx_test` | Test nginx configuration |
| `nginx_reload` | Reload nginx (tests config first) |

### Monitoring (6 tools)

| Tool | Description |
|------|-------------|
| `health_check_http` | HTTP health check from remote host |
| `health_check_tcp` | TCP connectivity check from remote host |
| `tail_logs` | Tail logs from journalctl or file |
| `disk_usage` | Get disk usage (df -h) |
| `memory_usage` | Get memory usage (free -m) |
| `process_list` | Get top processes by CPU |

### GitHub (7 tools)

| Tool | Description |
|------|-------------|
| `github_list_issues` | List issues in a repo |
| `github_get_issue` | Get issue details with comments |
| `github_comment_issue` | Comment on an issue |
| `github_close_issue` | Close an issue |
| `github_list_pulls` | List pull requests |
| `github_create_deployment` | Create a GitHub deployment |
| `github_create_deployment_status` | Create deployment status |

### Deploy (5 tools)

| Tool | Description |
|------|-------------|
| `deploy_git_pull` | Deploy by pulling latest code |
| `deploy_docker_compose` | Deploy with docker compose |
| `deploy_status` | Check current deployed version |
| `rollback_git` | Rollback to previous git commit |
| `rollback_docker_compose` | Rollback docker compose deployment |

### Utility (4 tools)

| Tool | Description |
|------|-------------|
| `server_info` | OS, uptime, kernel info |
| `list_hosts` | List configured SSH hosts |
| `add_host` | Add a new SSH host |
| `remove_host` | Remove an SSH host |

## Development

```bash
pip install -e ".[dev]"
ruff check src/
pytest
```

## License

MIT
